The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Vpp-1.17
River stage zero No dependents
++
/ Text::Vpp

NAME

Text::Vpp - Perl extension for a versatile text pre-processor

SYNOPSIS

 use Text::Vpp ;

 $fin = Text::Vpp-> new('input_file_name') ;

 $fin->setVar('one_variable_name' => 'value_one', 
              'another_variable_name' => 'value_two') ;

 $res = $fin -> substitute ; # or directly $fin -> substitute('file_out') 

 die "Vpp error ",$fin->getErrors,"\n" unless $res ;

 $fout = $fin->getText ;

 print "Result is : \n\n",join("\n",@$fout) ,"\n";

DESCRIPTION

This class enables to preprocess a file a bit like cpp.

First you create a Vpp object passing the name of the file to process, then you call setvar() to set the variables you need.

Finally you call substitute on the Vpp object.

NON-DESCRIPTION

Note that it's not designed to replace the well known cpp. Note also that if you think of using it to pre-process a perl script, you're likely to shoot yourself in the foot. Perl has a lot of built-in mechanisms so that a pre-processor is not necessary for most cases.

On the other hand some advanced perl users do use Vpp to pre-process their code to gain speed. But in this case you should really think hard about the maintenance of your code. Adding Vpp syntax in your code will make it more difficult to maintain. Even more so if the code maintainer will not be yourself. Furthermore, the build procedure may also be more complex. So please, do consider the trade-off between speed and complexity.

INPUT FILE SYNTAX

Comments

All lines beginning with '#' are skipped. (May be changed with setCommentChar())

When setActionChar() is called with '#' as a parameter, Vpp doesn't skip lines beginning with '#'. In this case, there's no comment possible.

in-line eval

Lines beginning with '@EVAL' (@ being pompously named the 'action char') are evaluated as small perl script. If a line contains (multiple) @@ Perl-Expression @@ constructs these are replaced by the value of that Perl-Expression. You can access all (non-lexically scoped) variables and subroutines from any Perl package iff you use fully qualified names, i.e. for a subroutine foo in package main use ::foo or main::foo To call one of the methods of a Vpp-object, like setActionChar, this has to called as "${self}->setActionChar('@');" Be sure you know what you do, if you call such methods from within an @EVAL line.

Multi-line input

Lines ending with \ are concatenated with the following line.

Variables substitution

You can specify variables in your text beginning with $ (like in perl, but may be changed with setPrefixChar() ) and optionally ending in a Suffix which can be specified by setSuffixChar(). These variables can be set either by the setVar() method, the setVarFromFile() method or by the 'eval' capability of Vpp (See below).

Advanced variables substitution

To use more complicated variables like hash or array accesses you have to use either the 'in-line eval' above or a cheaper and more convenient method. For that you can 'QUOTE' lines like

 @QUOTE
 any lines
 @ENDQUOTE

or

 @QUOTE ( ListPrefix [,ListSeparator] )
 any lines
 @ENDQUOTE

In both cases the lines between the '@QUOTE' and '@ENDQUOTE' are concatenated while keeping the end-of-line character.

In the resulting string all '$' are protected unless $prefix or $suffix or $ListPrefix contains a '$'. Furthermore all '@' are protected unless one of these variables contains a '@'.

Then all variables (defined by $prefix/$suffix) are preprocessed to make them ready for substitution later on. Likewise $ListPrefix (if given) is converted to '@'.

Then this possible multiline construct is quoted by Perl's 'qq' and given to Perl's eval.

Therefore any constructs which interpolate in a double quoted string, will interpolate here too, i.e. variable starting with '$' or '@' (unless protected, see above) and all characters escaped by '\'.

Note the standard trick to interpolate everything within a double quoted string by using the anonymous array construct " @{[expression]} ". The $ListSeparator is used to locally set Perl's variable '$"' (or $LIST_SEPARATOR in module English.pm). You can take any delimiting character but not brackets of any sort to delimit either ListPrefix or ListSeparator .

Note that this feature which raised a lot of discussions between the Vpp contributors should be considered as 'alpha' stage. We may have simpler ideas in the future to implement the same functionnality (hint: all other ideas are welcome). So the interface or the feature itself may be changed. Contact Helmut for further discussions.

Output generation by Perl code

For complex generation of output one can specify one or more Perl subroutines which can be called from within an @PERL statement. To specify the Perl code you say

 @PERL  <<  Termination_Regexp
 any perl source lines not matching 'Termination_Regexp'
 termination line matching 'Termination_Regexp'

Note, that any output have to use the predefined Perl sub Vpp_Out. Note, that the subroutine names should be unique even across included files. To access the variables set by e.g. setVar, you have to use the predefined hash-ref $VAR. Here is an example which generates constants for a C-program which amount to the probability that you draw a specified sequence out of a set.

 @PERL << ^END_OF_PERL$
 sub Chances($$) {
   my ($nseq,$num) = @_;
   # compute the chance to draw a sequence of nseq specific balls
   # out of num balls.
   my $chance;
   if ( $nseq > $num ) {
     $chance= 0;
   } else {
     $chance= 1;
     for (my $k=1; $k <= $nseq; $k++) {
       $chance*= $k/($num-$k);
     }
   }
   Vpp_Out("const double chance_${nseq}_of_$num = $chance;");
 }
 END_OF_PERL

This produces no output by itself. Lateron you can use it as

 @EVAL &Chances(7,49)

to produce the C-statement

 const double chance_7_of_49 = 1.35815917929809e-08;

Output generation by shell code

For complex generation of output one can also specify one or more shell commands which can be called from within an @SHELL statement.

To include the output of the shell command into your text, you can specify: @SHELL [some shell command]

For instance: @SHELL ls Vpp.pm

You can also specify a more complex shell command with: @SHELL << Termination_Regexp any shell code not matching 'Termination_Regexp' termination line matching 'Termination_Regexp'

Unlike the @PERL command, there's no need to call Vpp_Out from the shell code. All the STDOUT of the shell commands will be included in the text.

Setting variables

Lines beginning by @ are 'evaled' using variables defined by setVar() or setVarFromFile(). You can use only scalar variables. This way, you can also define variables in your text which can be used later.

Conditional statements

Text::Vpp understands @IF, @ELSIF, @ENDIF,and so on. @INCLUDE and @IF can be nested.

@IF and @ELSIF are followed by a Perl expression which will be evaled using the variables you have defined (either with setVar(), setVarFromFile() or in an @EVAL line).

Loop statements

Text::Vpp also understands

@FOREACH $MyLoopVar ( Perl-List-Expression ) ... (any) lines which may depend on $MyLoopVar @ENDFOR

These loops may be nested.

Inclusion

Text::Vpp understands @INCLUDE Filename or Perl-Expression @INCLUDE { action => '\\', backslash => 0, file => 'add_on.001' }

The file name may be a bare words if it contains only alphanumeric characters or '-', '.' or '_'. Otherwise, the file name must be quoted.

If the Perl-Expression is a string, it is taken as a filename.

If it is an anonymous hash, it must have a value for the key 'file' and it may have values for 'action', 'comment', 'prefix', 'suffix', 'substitute' and 'backslash'. If given these values will override the current values during the processing of the included file.

Constructor

new(file, optional_var_hash_ref, ...)

The constructor call new(file, optional_var_hash_ref,optional_action_char, optional_comment_char, optional_prefix_char, optional_suffix_char, optional_substitute, optional_backslash_switch);

creates the Vpp object. The file parameter may be a filename or a blessed reference for an object which "can('getline')". The second parameter can be a hash containing all variables needed for the substitute method, the following (optional) parameters specify the corresponding special characters.

Methods

substitute([output_file])

Perform the substitute, inclusion, and so on and write the result in output_file. This maybe a filename or a blessed reference which "can('print')" . Returns 1 on completion, 0 in case of an error.

If output_file is not specified this function stores the substitution result in an internal variable. The result can be retrieved with getText()

 You may prefix the filename with >> to get the output
 appended to an existing file.

rewind()

If method 'substitute' is called more than once, you have to call 'rewind' in between. CAUTION If you have called method 'new' with a blessed reference instead of a filename, you must not call 'rewind' unless your object has a 'seek' method. Otherwise you have to do actions yourself which simulate 'rewind' for your object.

getText()

  Returns an array ref containing the result. You can then get the total
  file with  join "\n",@{VppObj->getText}

getErrors()

Returns an array ref containing the errors.

setVar( key1=> value1, key2 => value2 ,...) or setVar(hash_ref)

Declare variables for the substitute. Note that calling this function clobbers previously stored values.

setVarFromFile( Filename_or_Ref )

Declares a File or an object which can 'getline'. The file must contain a valid Perl expression yielding an anonymous hash, as created e.g. by Data::Dumper Note that calling this function clobbers previously stored values.

setActionChar(char)

Enables the user to use different char as action char. (default @)

Example: setActionChar('#') will enable Vpp to understand #include, #ifdef ..

setCommentChar(char)

Enables the user to use different char as comment char. (default #) This value may be set to undef so that no comments are possible.

setPrefixChar(char)

Enables the user to use different char(s) as prefix char(s), i.e. variables in your text (only) are prefixed by that character(s) instead of the default '$'. If no suffix character(s) has been defined (or set to 'undef') variables may be specified in the form ${variable} where '$' is the current prefix char(s). This form is necessary, if any character which is allowed within a name (regexp '\w') immediately follows the variable. Note, that all variables in 'actions' (like @@ @EVAL @FOREACH @IF) must still be prefixed by '$'.

setSuffixChar(char)

Enables the user to use different char(s) as suffix char(s), i.e. variables in your text (only) are suffixed by that character(s). Note, that all variables in 'actions' (like @@ @EVAL @FOREACH @IF) don't use this.

setSubstitute([prefix,suffix])

Enables the user to specify the prefix and suffix used to mark a Perl expression within the text that will be replaced by its value. The default value is twice the 'action' char as suffix and prefix.

ignoreBackslash()

By default, line ending with '\' are glued to the following line (like in ksh). Once this method is called '\' will be left as is.

CAVEATS

Version 1.0 now requires files included with '@INCLUDE' to be quoted. Version 1.1 now requires calls to method 'rewind' if 'substitute' is called more than once for the same Vpp-object.

AUTHOR

Dominique Dumont Dominique_Dumont@grenoble.hp.com

Copyright (c) 1996-2001 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Additional bugs have been introduced by Helmut Jarausch jarausch@igpm.rwth-aachen.de

SEE ALSO

perl(1),Text::Template(3).