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.
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 if you use fully qualified names, i.e. for a subroutine foo in package main use ::foo or main::foo
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() ). These variables can be set either by the setVar() method or by the 'eval' capability of Vpp (See below).
Setting variables
Lines beginning by @ are 'evaled' using variables defined by setVar(). 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() or in the text).
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-String-Expression
Note that the file name must be quoted.
Constructor
new(file_name, optional_var_hash_ref, ...)
The constructor call new(file_name, optional_var_hash_ref,optional_action_char, optional_comment_char, optional_prefix_char, optional_backslash_switch);
creates the Vpp object. 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. 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.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.
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 as prefix char, i.e. variables in your text (only) are prefixed by that character instead of the default '$'. Note, that all variables in 'actions' (like @@ @EVAL @FOREACH @IF) must still be prefixed by '$'.
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.
AUTHOR
Dominique Dumont Dominique_Dumont@grenoble.hp.com
Copyright (c) 1996-1998 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
VERSION
Version 1.0
SEE ALSO
perl(1),Text::Template(3).