/tags/rel-1-3-25/SWIG/Examples/perl5/variables/index.html

# · HTML · 65 lines · 50 code · 15 blank · 0 comment · 0 complexity · 41b5653827514565f443cc719105f48e MD5 · raw file 

    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>SWIG:Examples:perl5:variables</title>
    4. 

  4. </head>
    5. 

  5. 

  6. <body bgcolor="#ffffff">
    7. 

  7. 

  8. <tt>SWIG/Examples/perl5/variables/</tt>
    9. 

  9. <hr>
    10. 

  10. 

  11. <H2>Wrapping C Global Variables</H2>
    12. 

  12. 

  13. <tt>$Header$</tt><br>
    14. 

  14. 

  15. <p>
    16. 

  16. When a C global variable appears in an interface file, SWIG tries to
    17. 

  17. wrap it using a technique known as "variable linking."  The idea is
    18. 

  18. pretty simple---we try to create a Perl variable that magically
    19. 

  19. retrieves or updates the value of the underlying C variable when it is
    20. 

  20. accessed.  Click <a href="example.i">here</a> to see a SWIG interface with some variable
    21. 

  21. declarations in it.
    22. 

  22. 

  23. <h2>Manipulating Variables from Perl</h2>
    24. 

  24. 

  25. Accessing a C global variable from Perl is easy---just reference it like a normal Perl variable.
    26. 

  26. Click <a href="runme.pl">here</a> to see a script that updates and prints some global variables.
    27. 

  27. 

  28. <h2>Creating read-only variables</h2>
    29. 

  29. 

  30. The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to
    31. 

  31. specify a collection of read-only variables.  For example:
    32. 

  32. 

  33. <blockquote>
    34. 

  34. <pre>
    35. 

  35. %immutable;
    36. 

  36. int    status;
    37. 

  37. double blah;
    38. 

  38. ...
    39. 

  39. %mutable;
    40. 

  40. </pre>
    41. 

  41. </blockquote>
    42. 

  42. 

  43. The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled
    44. 

  44. using the <tt>%mutable</tt> directive.
    45. 

  45. 

  46. 

  47. <h2>Notes:</h2>
    48. 

  48. 

  49. <ul>
    50. 

  50. <li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character
    51. 

  51. string.   However, whenever the value of such a variable is set from Perl, the old
    52. 

  52. value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends
    53. 

  53. on whether or not SWIG was run with the -c++ option).
    54. 

  54. <li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers.
    55. 

  55. <li>String array variables such as '<tt>char name[256]</tt>' are managed as Perl strings, but
    56. 

  56. when setting the value, the result is truncated to the maximum length of the array.  Furthermore, the string is assumed to be null-terminated.
    57. 

  57. <li>When structures and classes are used as global variables, they are mapped into pointers.
    58. 

  58. Getting the "value" returns a pointer to the global variable.  Setting the value of a structure results in a memory copy from a pointer to the global.
    59. 

  59. <li>Variables are linked using Perl's magic mechanism.  Take a look at the Advanced Perl Programming book to 
    60. 

  60. find out more about this feature.
    61. 

  61. </ul>
    62. 

  62. 

  63. </body>
    64. 

  64. </html>
    65. 

  65. <hr>
    66.