home *** CD-ROM | disk | FTP | other *** search
/ BURKS 2 / BURKS_AUG97.ISO / SLAKWARE / D13 / PERL2.TGZ / perl2.tar / usr / lib / perl5 / pod / perlguts.pod < prev    next >
Text File  |  1996-06-28  |  59KB  |  2,195 lines
  1. =head1 NAME
  2.  
  3. perlguts - Perl's Internal Functions
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. This document attempts to describe some of the internal functions of the
  8. Perl executable.  It is far from complete and probably contains many errors.
  9. Please refer any questions or comments to the author below.
  10.  
  11. =head1 Datatypes
  12.  
  13. Perl has three typedefs that handle Perl's three main data types:
  14.  
  15.     SV  Scalar Value
  16.     AV  Array Value
  17.     HV  Hash Value
  18.  
  19. Each typedef has specific routines that manipulate the various data types.
  20.  
  21. =head2 What is an "IV"?
  22.  
  23. Perl uses a special typedef IV which is large enough to hold either an
  24. integer or a pointer.
  25.  
  26. Perl also uses two special typedefs, I32 and I16, which will always be at
  27. least 32-bits and 16-bits long, respectively.
  28.  
  29. =head2 Working with SV's
  30.  
  31. An SV can be created and loaded with one command.  There are four types of
  32. values that can be loaded: an integer value (IV), a double (NV), a string,
  33. (PV), and another scalar (SV).
  34.  
  35. The four routines are:
  36.  
  37.     SV*  newSViv(IV);
  38.     SV*  newSVnv(double);
  39.     SV*  newSVpv(char*, int);
  40.     SV*  newSVsv(SV*);
  41.  
  42. To change the value of an *already-existing* SV, there are five routines:
  43.  
  44.     void  sv_setiv(SV*, IV);
  45.     void  sv_setnv(SV*, double);
  46.     void  sv_setpvn(SV*, char*, int)
  47.     void  sv_setpv(SV*, char*);
  48.     void  sv_setsv(SV*, SV*);
  49.  
  50. Notice that you can choose to specify the length of the string to be
  51. assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to
  52. calculate the length by using C<sv_setpv> or by specifying 0 as the second
  53. argument to C<newSVpv>.  Be warned, though, that Perl will determine the
  54. string's length by using C<strlen>, which depends on the string terminating
  55. with a NUL character.
  56.  
  57. To access the actual value that an SV points to, you can use the macros:
  58.  
  59.     SvIV(SV*)
  60.     SvNV(SV*)
  61.     SvPV(SV*, STRLEN len)
  62.  
  63. which will automatically coerce the actual scalar type into an IV, double,
  64. or string.
  65.  
  66. In the C<SvPV> macro, the length of the string returned is placed into the
  67. variable C<len> (this is a macro, so you do I<not> use C<&len>).  If you do not
  68. care what the length of the data is, use the global variable C<na>.  Remember,
  69. however, that Perl allows arbitrary strings of data that may both contain
  70. NUL's and not be terminated by a NUL.
  71.  
  72. If you simply want to know if the scalar value is TRUE, you can use:
  73.  
  74.     SvTRUE(SV*)
  75.  
  76. Although Perl will automatically grow strings for you, if you need to force
  77. Perl to allocate more memory for your SV, you can use the macro
  78.  
  79.     SvGROW(SV*, STRLEN newlen)
  80.  
  81. which will determine if more memory needs to be allocated.  If so, it will
  82. call the function C<sv_grow>.  Note that C<SvGROW> can only increase, not
  83. decrease, the allocated memory of an SV.
  84.  
  85. If you have an SV and want to know what kind of data Perl thinks is stored
  86. in it, you can use the following macros to check the type of SV you have.
  87.  
  88.     SvIOK(SV*)
  89.     SvNOK(SV*)
  90.     SvPOK(SV*)
  91.  
  92. You can get and set the current length of the string stored in an SV with
  93. the following macros:
  94.  
  95.     SvCUR(SV*)
  96.     SvCUR_set(SV*, I32 val)
  97.  
  98. You can also get a pointer to the end of the string stored in the SV
  99. with the macro:
  100.  
  101.     SvEND(SV*)
  102.  
  103. But note that these last three macros are valid only if C<SvPOK()> is true.
  104.  
  105. If you want to append something to the end of string stored in an C<SV*>,
  106. you can use the following functions:
  107.  
  108.     void  sv_catpv(SV*, char*);
  109.     void  sv_catpvn(SV*, char*, int);
  110.     void  sv_catsv(SV*, SV*);
  111.  
  112. The first function calculates the length of the string to be appended by
  113. using C<strlen>.  In the second, you specify the length of the string
  114. yourself.  The third function extends the string stored in the first SV
  115. with the string stored in the second SV.  It also forces the second SV to
  116. be interpreted as a string.
  117.  
  118. If you know the name of a scalar variable, you can get a pointer to its SV
  119. by using the following:
  120.  
  121.     SV*  perl_get_sv("varname", FALSE);
  122.  
  123. This returns NULL if the variable does not exist.
  124.  
  125. If you want to know if this variable (or any other SV) is actually C<defined>,
  126. you can call:
  127.  
  128.     SvOK(SV*)
  129.  
  130. The scalar C<undef> value is stored in an SV instance called C<sv_undef>.  Its
  131. address can be used whenever an C<SV*> is needed.
  132.  
  133. There are also the two values C<sv_yes> and C<sv_no>, which contain Boolean
  134. TRUE and FALSE values, respectively.  Like C<sv_undef>, their addresses can
  135. be used whenever an C<SV*> is needed.
  136.  
  137. Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>.
  138. Take this code:
  139.  
  140.     SV* sv = (SV*) 0;
  141.     if (I-am-to-return-a-real-value) {
  142.             sv = sv_2mortal(newSViv(42));
  143.     }
  144.     sv_setsv(ST(0), sv);
  145.  
  146. This code tries to return a new SV (which contains the value 42) if it should
  147. return a real value, or undef otherwise.  Instead it has returned a null
  148. pointer which, somewhere down the line, will cause a segmentation violation,
  149. or just weird results.  Change the zero to C<&sv_undef> in the first line and
  150. all will be well.
  151.  
  152. To free an SV that you've created, call C<SvREFCNT_dec(SV*)>.  Normally this
  153. call is not necessary.  See the section on B<MORTALITY>.
  154.  
  155. =head2 What's Really Stored in an SV?
  156.  
  157. Recall that the usual method of determining the type of scalar you have is
  158. to use C<Sv*OK> macros.  Since a scalar can be both a number and a string,
  159. usually these macros will always return TRUE and calling the C<Sv*V>
  160. macros will do the appropriate conversion of string to integer/double or
  161. integer/double to string.
  162.  
  163. If you I<really> need to know if you have an integer, double, or string
  164. pointer in an SV, you can use the following three macros instead:
  165.  
  166.     SvIOKp(SV*)
  167.     SvNOKp(SV*)
  168.     SvPOKp(SV*)
  169.  
  170. These will tell you if you truly have an integer, double, or string pointer
  171. stored in your SV.  The "p" stands for private.
  172.  
  173. In general, though, it's best to just use the C<Sv*V> macros.
  174.  
  175. =head2 Working with AV's
  176.  
  177. There are two ways to create and load an AV.  The first method just creates
  178. an empty AV:
  179.  
  180.     AV*  newAV();
  181.  
  182. The second method both creates the AV and initially populates it with SV's:
  183.  
  184.     AV*  av_make(I32 num, SV **ptr);
  185.  
  186. The second argument points to an array containing C<num> C<SV*>'s.  Once the
  187. AV has been created, the SV's can be destroyed, if so desired.
  188.  
  189. Once the AV has been created, the following operations are possible on AV's:
  190.  
  191.     void  av_push(AV*, SV*);
  192.     SV*   av_pop(AV*);
  193.     SV*   av_shift(AV*);
  194.     void  av_unshift(AV*, I32 num);
  195.  
  196. These should be familiar operations, with the exception of C<av_unshift>.
  197. This routine adds C<num> elements at the front of the array with the C<undef>
  198. value.  You must then use C<av_store> (described below) to assign values
  199. to these new elements.
  200.  
  201. Here are some other functions:
  202.  
  203.     I32   av_len(AV*); /* Returns highest index value in array */
  204.  
  205.     SV**  av_fetch(AV*, I32 key, I32 lval);
  206.             /* Fetches value at key offset, but it stores an undef value
  207.                at the offset if lval is non-zero */
  208.     SV**  av_store(AV*, I32 key, SV* val);
  209.             /* Stores val at offset key */
  210.  
  211. Take note that C<av_fetch> and C<av_store> return C<SV**>'s, not C<SV*>'s.
  212.  
  213.     void  av_clear(AV*);
  214.             /* Clear out all elements, but leave the array */
  215.     void  av_undef(AV*);
  216.             /* Undefines the array, removing all elements */
  217.     void  av_extend(AV*, I32 key);
  218.             /* Extend the array to a total of key elements */
  219.  
  220. If you know the name of an array variable, you can get a pointer to its AV
  221. by using the following:
  222.  
  223.     AV*  perl_get_av("varname", FALSE);
  224.  
  225. This returns NULL if the variable does not exist.
  226.  
  227. =head2 Working with HV's
  228.  
  229. To create an HV, you use the following routine:
  230.  
  231.     HV*  newHV();
  232.  
  233. Once the HV has been created, the following operations are possible on HV's:
  234.  
  235.     SV**  hv_store(HV*, char* key, U32 klen, SV* val, U32 hash);
  236.     SV**  hv_fetch(HV*, char* key, U32 klen, I32 lval);
  237.  
  238. The C<klen> parameter is the length of the key being passed in.  The C<val>
  239. argument contains the SV pointer to the scalar being stored, and C<hash> is
  240. the pre-computed hash value (zero if you want C<hv_store> to calculate it
  241. for you).  The C<lval> parameter indicates whether this fetch is actually a
  242. part of a store operation.
  243.  
  244. Remember that C<hv_store> and C<hv