home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _13c6061d36e4ad5debcd04119ff39bf8 < prev    next >
Text File  |  2000-03-23  |  16KB  |  337 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Text::Vpp - Perl extension for a versatile text pre-processor</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Text::Vpp - Perl extension for a versatile text pre-processor</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#nondescription">NON-DESCRIPTION</A></LI>
  26.     <LI><A HREF="#input file syntax">INPUT FILE SYNTAX</A></LI>
  27.     <UL>
  28.  
  29.         <LI><A HREF="#comments">Comments</A></LI>
  30.         <LI><A HREF="#inline eval">in-line eval</A></LI>
  31.         <LI><A HREF="#multiline input">Multi-line input</A></LI>
  32.         <LI><A HREF="#variables substitution">Variables substitution</A></LI>
  33.         <LI><A HREF="#advanced variables substitution">Advanced variables substitution</A></LI>
  34.         <LI><A HREF="#setting variables">Setting variables</A></LI>
  35.         <LI><A HREF="#conditional statements">Conditional statements</A></LI>
  36.         <LI><A HREF="#loop statements">Loop statements</A></LI>
  37.         <LI><A HREF="#inclusion">Inclusion</A></LI>
  38.     </UL>
  39.  
  40.     <LI><A HREF="#constructor">Constructor</A></LI>
  41.     <UL>
  42.  
  43.         <LI><A HREF="#new(file, optional_var_hash_ref, ...)">new(file, optional_var_hash_ref, ...)</A></LI>
  44.     </UL>
  45.  
  46.     <LI><A HREF="#methods">Methods</A></LI>
  47.     <UL>
  48.  
  49.         <LI><A HREF="#substitute([output_file])"><CODE>substitute([output_file])</CODE></A></LI>
  50.         <LI><A HREF="#rewind()"><CODE>rewind()</CODE></A></LI>
  51.         <LI><A HREF="#gettext()"><CODE>getText()</CODE></A></LI>
  52.         <LI><A HREF="#geterrors()"><CODE>getErrors()</CODE></A></LI>
  53.         <LI><A HREF="#setvar( key1=> value1, key2 => value2 ,...) or setvar(hash_ref)">setVar( key1=> value1, key2 => value2 ,...) or <CODE>setVar(hash_ref)</CODE></A></LI>
  54.         <LI><A HREF="#setvarfromfile( filename_or_ref )">setVarFromFile( Filename_or_Ref )</A></LI>
  55.         <LI><A HREF="#setactionchar(char)"><CODE>setActionChar(char)</CODE></A></LI>
  56.         <LI><A HREF="#setcommentchar(char)"><CODE>setCommentChar(char)</CODE></A></LI>
  57.         <LI><A HREF="#setprefixchar(char)"><CODE>setPrefixChar(char)</CODE></A></LI>
  58.         <LI><A HREF="#setsuffixchar(char)"><CODE>setSuffixChar(char)</CODE></A></LI>
  59.         <LI><A HREF="#setsubstitute([prefix,suffix])"><CODE>setSubstitute([prefix,suffix])</CODE></A></LI>
  60.         <LI><A HREF="#ignorebackslash()"><CODE>ignoreBackslash()</CODE></A></LI>
  61.     </UL>
  62.  
  63.     <LI><A HREF="#caveats">CAVEATS</A></LI>
  64.     <LI><A HREF="#author">AUTHOR</A></LI>
  65.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  66. </UL>
  67. <!-- INDEX END -->
  68.  
  69. <HR>
  70. <P>
  71. <H1><A NAME="name">NAME</A></H1>
  72. <P>Text::Vpp - Perl extension for a versatile text pre-processor</P>
  73. <P>
  74. <HR>
  75. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  76. <UL>
  77. <LI>Linux</LI>
  78. <LI>Solaris</LI>
  79. <LI>Windows</LI>
  80. </UL>
  81. <HR>
  82. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  83. <PRE>
  84.  use Text::Vpp ;</PRE>
  85. <PRE>
  86.  $fin = Text::Vpp-> new('input_file_name') ;</PRE>
  87. <PRE>
  88.  $fin->setVar('one_variable_name' => 'value_one', 
  89.               'another_variable_name' => 'value_two') ;</PRE>
  90. <PRE>
  91.  $res = $fin -> substitute ; # or directly $fin -> substitute('file_out')</PRE>
  92. <PRE>
  93.  die "Vpp error ",$fin->getErrors,"\n" unless $res ;</PRE>
  94. <PRE>
  95.  $fout = $fin->getText ;</PRE>
  96. <PRE>
  97.  print "Result is : \n\n",join("\n",@$fout) ,"\n";</PRE>
  98. <P>
  99. <HR>
  100. <H1><A NAME="description">DESCRIPTION</A></H1>
  101. <P>This class enables to preprocess a file a bit like cpp.</P>
  102. <P>First you create a Vpp object passing the name of the file to process, then
  103. you call <CODE>setvar()</CODE> to set the variables you need.</P>
  104. <P>Finally you call substitute on the Vpp object.</P>
  105. <P>
  106. <HR>
  107. <H1><A NAME="nondescription">NON-DESCRIPTION</A></H1>
  108. <P>Note that it's not designed to replace the well known cpp. Note also
  109. that if you think of using it to pre-process a perl script, you're
  110. likely to shoot yourself in the foot. Perl has a lot of built-in
  111. mechanisms so that a pre-processor is not necessary for most cases.</P>
  112. <P>On the other hand some advanced perl users do use Vpp to pre-process their
  113. code to gain speed. But in this case you should really think hard about the
  114. maintenance of your code. Adding Vpp syntax in your code will make it
  115. more difficult to maintain. Even more so if the code maintainer will not
  116. be yourself. Furthermore, the build procedure may also be more complex.
  117. So please, do consider the trade-off between speed and complexity.</P>
  118. <P>
  119. <HR>
  120. <H1><A NAME="input file syntax">INPUT FILE SYNTAX</A></H1>
  121. <P>
  122. <H2><A NAME="comments">Comments</A></H2>
  123. <P>All lines beginning with '#' are skipped. (May be changed with 
  124. <CODE>setCommentChar())</CODE></P>
  125. <P>When <CODE>setActionChar()</CODE> is called with '#' as a parameter, Vpp doesn't 
  126. skip lines beginning with '#'. In this case, there's no comment possible.</P>
  127. <P>
  128. <H2><A NAME="inline eval">in-line eval</A></H2>
  129. <P>Lines beginning with '@EVAL' (@ being pompously named the 'action char') 
  130. are evaluated as small perl script. 
  131. If a line contains (multiple) @@ Perl-Expression @@ constructs these
  132. are replaced by the value of that Perl-Expression.
  133. You can access all (non-lexically scoped) variables and subroutines from
  134. any Perl package iff you use fully qualified names, i.e. for a subroutine
  135. <EM>foo</EM> in package <EM>main</EM>  use  <EM>::foo</EM> or <EM>main::foo</EM>
  136. To call one of the methods of a Vpp-object, like setActionChar, this
  137. has to called as  ``${self}->setActionChar('@');''
  138. Be sure you know what you do, if you call such methods from within
  139. an @EVAL line.</P>
  140. <P>
  141. <H2><A NAME="multiline input">Multi-line input</A></H2>
  142. <P>Lines ending with \ are concatenated with the following line.</P>
  143. <P>
  144. <H2><A NAME="variables substitution">Variables substitution</A></H2>
  145. <P>You can specify variables in your text beginning with $ (like in perl,
  146. but may be changed with <CODE>setPrefixChar()</CODE> ) and optionally ending
  147. in a Suffix which can be specified by setSuffixChar().
  148. These variables can be set either by the <CODE>setVar()</CODE> method, the
  149. <CODE>setVarFromFile()</CODE> method or by the 'eval' capability of Vpp (See below).</P>
  150. <P>
  151. <H2><A NAME="advanced variables substitution">Advanced variables substitution</A></H2>
  152. <P>To use more complicated variables like hash or array accesses you have to
  153. use either the 'in-line eval' above or a cheaper and more convenient
  154. method. For that you can 'QUOTE' lines like</P>
  155. <PRE>
  156.  @QUOTE
  157.  any lines
  158.  @ENDQUOTE</PRE>
  159. <P>or</P>
  160. <PRE>
  161.  @QUOTE ( ListPrefix [,ListSeparator] )
  162.  any lines
  163.  @ENDQUOTE</PRE>
  164. <P>In both cases the lines between the '@QUOTE' and '@ENDQUOTE' are
  165. concatenated while keeping the end-of-line character.</P>
  166. <P>In the resulting string all '$' are protected unless $prefix or $suffix
  167. or $ListPrefix contains a '$'. Furthermore all '@' are protected unless
  168. one of these variables contains a '@'.</P>
  169. <P>Then all variables (defined by $prefix/$suffix) are preprocessed to
  170. make them ready for substitution later on.  Likewise $ListPrefix (if
  171. given) is converted to '@'.</P>
  172. <P>Then this possible multiline construct is quoted by Perl's 'qq' and given
  173. to Perl's eval.</P>
  174. <P>Therefore any constructs which interpolate in a double quoted string,
  175. will interpolate here too, i.e. variable starting with '$' or '@'
  176. (unless protected, see above) and all characters escaped by '\'.</P>
  177. <P>Note the standard trick to interpolate everything within a double
  178. quoted string by using the anonymous array construct `` @{[expression]}
  179. ''.  The $ListSeparator is used to locally set Perl's variable '$``' (or
  180. $LIST_SEPARATOR in module English.pm).  You can take any delimiting
  181. character but not brackets of any sort to delimit either ListPrefix or
  182. ListSeparator .</P>
  183. <P>Note that this feature which raised a lot of discussions between the
  184. Vpp contributors should be considered as 'alpha' stage. We may have
  185. simpler ideas in the future to implement the same functionnality (hint:
  186. all other ideas are welcome). So the interface or the feature itself
  187. may be changed. Contact Helmut for further discussions.</P>
  188. <P>
  189. <H2><A NAME="setting variables">Setting variables</A></H2>
  190. <P>Lines beginning by @ are 'evaled' using variables defined by <CODE>setVar()</CODE>
  191. or setVarFromFile(). You can use only scalar variables. This way, you can
  192. also define variables in your text which can be used later.</P>
  193. <P>
  194. <H2><A NAME="conditional statements">Conditional statements</A></H2>
  195. <P>Text::Vpp understands @IF, @ELSIF, @ENDIF,and so on.  @INCLUDE and @IF
  196. can be nested.</P>
  197. <P>@IF and @ELSIF are followed by a Perl expression which will be evaled using
  198. the variables you have defined (either with setVar(), <CODE>setVarFromFile()</CODE>
  199. or in an @EVAL line).</P>
  200. <P>
  201. <H2><A NAME="loop statements">Loop statements</A></H2>
  202. <P>Text::Vpp also understands</P>
  203. <P>@FOREACH $MyLoopVar ( Perl-List-Expression )
  204. ... (any) lines which may depend on $MyLoopVar
  205. @ENDFOR</P>
  206. <P>These loops may be nested.</P>
  207. <P>
  208. <H2><A NAME="inclusion">Inclusion</A></H2>
  209. <P>Text::Vpp understands
  210. @INCLUDE  Filename or Perl-Expression
  211. @INCLUDE { action => '\\', backslash => 0, file => 'add_on.001' }</P>
  212. <P>The file name may be a bare words if it contains only alphanumeric
  213. characters or '-', '.' or '_'. Otherwise, the file name must be quoted.</P>
  214. <P>If the Perl-Expression is a string, it is taken as a
  215. filename.</P>
  216. <P>If it is an anonymous hash, it must have a value for the key 'file'
  217. and it may have values for 'action', 'comment', 'prefix', 'suffix',
  218. 'substitute' and 'backslash'.  If given these values will override the
  219. current values during the processing of the included file.</P>
  220. <P>
  221. <HR>
  222. <H1><A NAME="constructor">Constructor</A></H1>
  223. <P>
  224. <H2><A NAME="new(file, optional_var_hash_ref, ...)">new(file, optional_var_hash_ref, ...)</A></H2>
  225. <P>The constructor call
  226. <CODE>new(file, optional_var_hash_ref,optional_action_char,</CODE>
  227. <CODE>          optional_comment_char, optional_prefix_char,</CODE>
  228. <CODE>          optional_suffix_char, optional_substitute,</CODE>
  229. <CODE>                             optional_backslash_switch);</CODE></P>
  230. <P>creates the Vpp object. The file parameter may be a filename or
  231. a blessed reference for an object which ``can('getline')''.
  232. The second parameter can be a hash containing all
  233. variables needed for the substitute method, the following (optional)
  234. parameters specify the corresponding special characters.</P>
  235. <P>
  236. <HR>
  237. <H1><A NAME="methods">Methods</A></H1>
  238. <P>
  239. <H2><A NAME="substitute([output_file])"><CODE>substitute([output_file])</CODE></A></H2>
  240. <P>Perform the substitute, inclusion, and so on and write the result in 
  241. <EM>output_file</EM>. This maybe a filename or a blessed reference which
  242. ``can('print')'' .
  243. Returns 1 on completion, 0 in case of an error.</P>
  244. <P>If output_file is not specified this function stores the substitution result
  245. in an internal variable. The result can be retrieved with <CODE>getText()</CODE></P>
  246. <PRE>
  247.  You may prefix the filename with >> to get the output
  248.  appended to an existing file.</PRE>
  249. <P>
  250. <H2><A NAME="rewind()"><CODE>rewind()</CODE></A></H2>
  251. <P>If method 'substitute' is called more than once, you have to call
  252. 'rewind' in between.
  253. CAUTION  If you have called method 'new' with a blessed reference
  254.          instead of a filename, you must not call 'rewind' unless
  255.          your object has a 'seek' method. Otherwise you have to do
  256.          actions yourself which simulate 'rewind' for your object.</P>
  257. <P>
  258. <H2><A NAME="gettext()"><CODE>getText()</CODE></A></H2>
  259. <PRE>
  260.   Returns an array ref containing the result. You can then get the total
  261.   file with  join "\n",@{VppObj->getText}</PRE>
  262. <P>
  263. <H2><A NAME="geterrors()"><CODE>getErrors()</CODE></A></H2>
  264. <P>Returns an array ref containing the errors.</P>
  265. <P>
  266. <H2><A NAME="setvar( key1=> value1, key2 => value2 ,...) or setvar(hash_ref)">setVar( key1=> value1, key2 => value2 ,...) or <CODE>setVar(hash_ref)</CODE></A></H2>
  267. <P>Declare variables for the substitute.
  268. Note that calling this function clobbers previously stored values.</P>
  269. <P>
  270. <H2><A NAME="setvarfromfile( filename_or_ref )">setVarFromFile( Filename_or_Ref )</A></H2>
  271. <P>Declares a File or an object which can 'getline'.
  272. The file must contain a valid Perl expression yielding an
  273. anonymous hash, as created e.g. by Data::Dumper
  274. Note that calling this function clobbers previously stored values.</P>
  275. <P>
  276. <H2><A NAME="setactionchar(char)"><CODE>setActionChar(char)</CODE></A></H2>
  277. <P>Enables the user to use different char as action char. (default @)</P>
  278. <P>Example: <CODE>setActionChar('#')</CODE> will enable Vpp to understand #include, #ifdef ..</P>
  279. <P>
  280. <H2><A NAME="setcommentchar(char)"><CODE>setCommentChar(char)</CODE></A></H2>
  281. <P>Enables the user to use different char as comment char. (default #)
  282. This value may be set to undef so that no comments are possible.</P>
  283. <P>
  284. <H2><A NAME="setprefixchar(char)"><CODE>setPrefixChar(char)</CODE></A></H2>
  285. <P>Enables the user to use different <CODE>char(s)</CODE> as prefix char(s), i.e. variables
  286. in your text (only) are prefixed by that <CODE>character(s)</CODE> instead of the
  287. default '$'. If no suffix <CODE>character(s)</CODE> has been defined (or set to 'undef')
  288. variables may be specified in the form ${variable} where '$' is the
  289. current prefix char(s). This form is necessary, if any character which
  290. is allowed within a name (regexp '\w') immediately follows the variable.
  291. Note, that all variables in 'actions' (like @@ @EVAL @FOREACH @IF)
  292. must still be prefixed by '$'.</P>
  293. <P>
  294. <H2><A NAME="setsuffixchar(char)"><CODE>setSuffixChar(char)</CODE></A></H2>
  295. <P>Enables the user to use different <CODE>char(s)</CODE> as suffix char(s), i.e. variables
  296. in your text (only) are suffixed by that character(s).
  297. Note, that all variables in 'actions' (like @@ @EVAL @FOREACH @IF)
  298. don't use this.</P>
  299. <P>
  300. <H2><A NAME="setsubstitute([prefix,suffix])"><CODE>setSubstitute([prefix,suffix])</CODE></A></H2>
  301. <P>Enables the user to specify the prefix and suffix used to mark
  302. a Perl expression within the text that will be replaced by its
  303. value. The default value is twice the 'action' char as suffix
  304. and prefix.</P>
  305. <P>
  306. <H2><A NAME="ignorebackslash()"><CODE>ignoreBackslash()</CODE></A></H2>
  307. <P>By default, line ending with '\' are glued to the following line (like in
  308. ksh). Once this method is called '\' will be left as is.</P>
  309. <P>
  310. <HR>
  311. <H1><A NAME="caveats">CAVEATS</A></H1>
  312. <P>Version 1.0 now requires files included with '@INCLUDE' to be quoted.
  313. Version 1.1 now requires calls to method 'rewind' if 'substitute' is
  314. called more than once for the same Vpp-object.</P>
  315. <P>
  316. <HR>
  317. <H1><A NAME="author">AUTHOR</A></H1>
  318. <P>Dominique Dumont    <A HREF="mailto:Dominique_Dumont@grenoble.hp.com">Dominique_Dumont@grenoble.hp.com</A></P>
  319. <P>Copyright (c) 1996-1999 Dominique Dumont. All rights reserved.  This
  320. program is free software; you can redistribute it and/or modify it
  321. under the same terms as Perl itself.</P>
  322. <P>Additional bugs have been introduced by
  323. Helmut Jarausch    <A HREF="mailto:jarausch@igpm.rwth-aachen.de">jarausch@igpm.rwth-aachen.de</A></P>
  324. <P>
  325. <HR>
  326. <H1><A NAME="see also">SEE ALSO</A></H1>
  327. <P>perl(1),Text::Template(3).</P>
  328. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  329. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  330. <STRONG><P CLASS=block> Text::Vpp - Perl extension for a versatile text pre-processor</P></STRONG>
  331. </TD></TR>
  332. </TABLE>
  333.  
  334. </BODY>
  335.  
  336. </HTML>
  337.