This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Text/Thesaurus/ISO, Next: Text/Tmpl, Prev: Text/Template, Up: Module List A class to handle ISO thesaurii ******************************* NAME ==== Text::Thesaurus::ISO - A class to handle ISO thesaurii SYNOPSIS ======== use Text::Thesaurus::ISO; $thes = new Text::Thesaurus::ISO; $thes->open("myisothesfile"); $thes->reopen("myisothesfile"); %entry = $thes->terminfo("dumpy"); @broaderterms = $thes->broader("dumpy"); @narrowerterms = $thes->narrower("dumpy"); $dateentered = $thes->dateentered("dumpy"); $datechanged = $thes->datechanged("dumpy"); @alternatives = $thes->alternatives("dumpy"); @sources = $thes->sources("dumpy"); @links = $thes->links("dumpy"); @scopenotes = $thes->scopenote("dumpy"); @historynotes = $thes->history("dumpy"); DESCRIPTION =========== This module defines an abstract ROADS Thesaurus object and a number of methods that operate on these objects. These methods allow new Thesaurus objects to be created, specify what Thesaurus file to use, retrieve all the information from the thesaurus concerning a given term, find broader terms for a given term and find narrower terms for a given term. METHODS ======= new --- This creates a new (empty) thesaurus object. open ---- Opens an ISO thesaurus file specified by its single parameter. It also checks if the backend database exists for this file and if not, creates it. reopen ------ Opens an ISO thesaurus file specified by its single parameter. This method always reindexes the ISO thesaurus file, and so should be called if the ISO thesaurus file has been changed since the last time the index was generated. Note that this call can be quite time consuming, especially on a large thesaurus file, so its probably best avoided in interactive systems (have a batch script that periodically updates the thesaurus indexes behind the scenes instead). terminfo -------- Takes a term (a word or phrase) and returns all the information for that term from its thesaurus record. The information is returned in a hash array keyed on the attribute name in the ISO thesaurus record (ie BT, TERM, UF, etc). broader ------- Takes a term and returns a list of all the broader terms for it. narrower -------- Takes a term and returns a list of all the narrower terms for it. dateentered ----------- Takes a thesaurus term as a parameter and returns the date that the term's record was entered into the thesaurus file. Returns an undef value if the term does not exist in the thesaurus file or if there is no entry date recorded. datechanged ----------- Takes a thesaurus term as a parameter and returns the date that the term's record was last changed in the thesaurus file. Returns an undef value if the term does not exist in the thesaurus file or if there is no changed date recorded. alternatives ------------ Takes a thesaurus term as a parameter and returns an array of alternative terms based on that. sources ------- Takes a thesaurus term as a parameter and returns an array of source statements that detail where the term was extracted from. links ----- Takes a thesaurus term as a parameter and returns an array of links to other terms in the thesaurus. scopenote --------- Takes a thesaurus term as a parameter and returns an array of scope notes applying to that term. The scope notes often provide human readable descriptions of the term and the its limits. history ------- Takes a thesaurus term as a parameter and returns an array of historical notes. These are usually human readable comments made when major changes have been made to the thesaurus that effect the specified term's entry. BUGS ==== None known of as yet. It is intended that more methods will be added in the future to specifically retreive various parts of the thesaurus record which will hopefully make the terminfo method obsolete. Also note that this version has only been tested against a single ISO thesaurus file (a demonstration version of the Art and Architecture Thesaurus) - feedback of bugs with other thesaurii are most welcome. COPYRIGHT ========= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. It was developed by the Department of Computer Studies at Loughborough University of Technology, as part of the ROADS project. ROADS is funded under the UK Electronic Libraries Programme (eLib), and the European Commission Telematics for Research Programme. AUTHOR ====== Jon Knight Martin Hamilton  File: pm.info, Node: Text/Tmpl, Next: Text/TreeFile, Prev: Text/Thesaurus/ISO, Up: Module List Templating system perl library ****************************** NAME ==== Text::Tmpl - Templating system perl library SYNOPSIS ======== *use Text::Tmpl;* $context = *new Text::Tmpl*; $return = $context->set_delimiters($opentag, $closetag); $return = $context->register_simple($name, $coderef); $return = $context->register_pair($isnamed, $open_name, $close_name, $coderef); $return = $context->alias_simple($old_name, $new_name); $return = $context->alias_pair($old_open_name, $old_close_name, $new_open_name, $new_close_name); $context->set_debug($to_debug_or_not_to_debug); $context->set_strip($to_strip_or_not_to_strip); $return = $context->set_dir($directory); $return = $context->set_value($name, $value); $return = $context->set_values($hashref); $subcontext = $context->loop_iteration($loop_name); $output = $context->parse_file($template_filename); $output = $context->parse_string($template); $errno = Text::Tmpl::errno(); $errstr = Text::Tmpl::strerror(); DESCRIPTION =========== Design goals ------------ simplicity, reusability, speed, complete separation of logic from formatting. Feature set ----------- variables, loops, conditionals, extensibility of tags, includes, arbitrary delimiters. Usage ----- For starters, make sure you 'use Text::Tmpl'. Each function is described below: new This function initializes the library. It allocates and returns the "global" context structure, and also configures all of the default tag behavior. set_delimiters This function lets you change the delimiters marking the beginning and end of a tag (by default, these are ""), for the specified context. set_value This function stores the name=value pair in the current context. set_values This function dumps the name=value pairs from a hash reference into the current context. set_debug This function turns debugging output on or off. Note that debugging output hasn't been written yet - this is just a placeholder. set_strip This function enables or disables the newline stripping feature. If enabled, the parser removes a single newline (if present) from after any tag. set_dir This function sets the directory where templates will be sought, both by parse_file and by the include tag. Search order is always current directory then this searched directory. loop_iteration This function adds an iteration to the loop named loop_name, and returns a unique context for that loop iteration. parse_file This function opens $template_filename, and parses the contents of that file as a template, returning the output. parse_string This function parses template directly, in the same way that Text::Tmpl::parse_file does. register_simple This function registers a new simple tag named $name, which when encountered will cause the parser to call $coderef. See template_extend(1) for the gory details. register_pair This function registers a new tag pair $open_name/$close_name, which when encountered will cause the parser to call $coderef. See template_extend for the gory details. alias_simple This function copies the definition of a simple tag, previously registered as $old_name, to also be called by $new_name. alias_pair This function copies the definition of a tag pair, previously registered as $old_open_name/$old_close_name, to also be called by $new_open_name/$new_close_name. errno This function returns the error number of the last error - see the RETURN VALUES section below. strerror This function returns a string describing the last error - see the RETURN VALUES section below. RETURN VALUES ============= All of the above functions which return numeric values will return 0 if they fail, or 1 otherwise. The ones which return contexts will return undef if they fail, or a valid pointer otherwise. A function which fails will also set a global error number, which you can read using the errno() or strerror() package functions. BUGS ==== Hopefully none. AUTHOR ====== J. David Lowe, dlowe@pootpoot.com SEE ALSO ======== libtmpl(1), template_syntax(1), template_extend(1)  File: pm.info, Node: Text/TreeFile, Next: Text/TreeFile/details, Prev: Text/Tmpl, Up: Module List Reads a tree of text strings into a data structure ************************************************** NAME ==== Text::TreeFile - Reads a tree of text strings into a data structure SYNOPSIS ======== use Text::TreeFile; # need to set $filename, e.g.: my $filename='treetest.tre'; my $treeref=Text::TreeFile->new($filename); # or other option: my $treeref=Text::TreeFile->new($filename,'mult'); die "TreeFile constructor failed to read file $filename\n" unless defined $treeref; my $topref=$treeref->{top}; # scalar or array for top-level tree(s) showlines($topref,0); # see EXAMPLE, below REQUIRES ======== *TreeFile* uses modules: FileHandle, Exporter and *Autoloader*. DESCRIPTION =========== The `TreeFile.pm' module supports a simple ASCII text file format for representing tree structures. It loads the contents of such a file into a tree (or array of trees) of two-element array nodes, where the first element of each node is a text string and the second is an array of child nodes. It supports comments, continuation lines and include files, and uses a strict (two-space-per-level) indentation scheme in the file to indicate hierarchical nesting. OPTIONS ======= TreeFile implements an option between single or multiple top-level trees per file. The option is exercised by the presence or absence of a second argument to new(), as demonstrated in the *"SYNOPSIS"* section, above (the two lines where "my $treeref=" occurs). (default case) If the new() constructor is not given a second argument, the default option occurs: A single top-level tree is read, per file. This leaves the remainder of each file's contents available for some other facility to use. In this case new() returns (a reference to) the top-level tree (node). (optional case) If the new() constructor is given a second argument, multiple top-level trees are read from each file (and the entire file needs to conform to the TreeFile syntax). In this case new() returns (a reference to) an array containing (references to) the top-level trees. EXAMPLE ======= use Text::TreeFile; sub showlines; # set $filename string and $wantmult boolean # my $filename='treetest.tre'; # my $wantmult=1; # or: =0; # or: omit from new() constructor; my $treeref; $treeref=Text::TreeFile->new($filename) if not $wantmult; $treeref=Text::TreeFile->new($filename,'mult') if $wantmult; die "TreeFile constructor returned undef\n" unless defined $treeref; my $topref=$treeref->{top}; # node or array of nodes for top-level tree(s) showlines($topref,0); sub showlines { my ($spec,$level)=@_; if(ref($$spec[0]) eq 'ARRAY') { # want-mult case for my $item (@$spec) { print(' 'x$level);print("$$item[0]\n"); for(@{$$item[1]}) { showlines $_,$level; } } } else { # spec[0] is the top-level string: no-want-mult case print(' 'x$level);print("$$spec[0]\n"); for(@{$$spec[1]}) { showlines $_,$level+1; } } } FILE FORMAT =========== The file format supported relies upon indentation of text strings, to indicate hierarchical nesting for the tree structure. Strict indentation (of two space characters per nesting level) is used to represent parent-child structure. Comments -------- A line consisting exclusively of whitespace, or a line beginning with either the pound-sign ("#"), the semicolon (";"), or the forward slash ("/") character will be ignored as a comment. In the very first line of a file, the initial characters, "exec ", will indicate a comment line. Continuation Lines ------------------ A line beginning with whitespace followed by three period (".") characters, will be concatenated to the previous line, as a continuation. The preceding end-of-line, the initial whitespace and the ellipsis ("...") will be removed and otherwise ignored, to allow long strings to be represented within line-length constraints. As a rule, it's probably a good idea to make sure any line that is continued with a continuation line have no trailing spaces, and that any spaces that are desired in the resulting concatenation occur between the ellipsis ("...") and the remainder of the continuation line. Perhaps a later version of the module will remove trailing spaces on each line, to further reduce surprises. Include Files ------------- In addition, any line consisting of indentation followed by "include" will be interpreted as a file-include request. In this case, succeeding whitespace followed by a file specification will cause the contents of the named file to be substituted at that point in the tree. The remainder of the include-file line is ignored as commentary. AUTHOR ====== John Kirk <`johnkirk@dystanhays.com'> COPYRIGHT ========= Copyright (c) 2000 John Kirk. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== `Text::TreeFile::details(3pm)' in this node - for precise definition of syntax, `Text::TreeFile::internals(3pm)' in this node - for implementation commentary, and `http://perl.dystanhays.com/jnk' - for related material.  File: pm.info, Node: Text/TreeFile/details, Next: Text/TreeFile/internals, Prev: Text/TreeFile, Up: Module List precise usage specifications **************************** NAME ==== Text::TreeFile::details - precise usage specifications SYNOPSIS ======== use Text::TreeFile; my $filename='demodata/treetest.tre'; # read in single-tree mode my $tf=Text::TreeFile->new($filename); my $treeref=$$tf{top}; print "The string content of the top-level tree node is:\n\n"; print " $$treeref[0]\n\n"; print "It has ",scalar @{$$treeref[1]}," second-level child nodes\n"; DESCRIPTION =========== First, each public function is described. Then, a test script. After that, a few more details. CONSTRUCTOR: new [ filename, [ *endq* ] ] ========================================= The constructor (function new()) for module *Text::TreeFile* can be invoked with zero, one or two parameters. The first is a filename to be read into an internal tree structure of strings; the second, a single/multiple tree flag. If no parameters are specified, an object (a blessed reference to a hash) will be returned with only the prototype entries present. In this case, one might create a tree by other external means and put it into the hash. Parameter: filename ------------------- If at least one parameter is specified, the first will be taken to be the name of the tree file to be read. If it contains a slash ("/") character, the leading path up to the final file name will be remembered (under key, "*idir*") and used as a prefix for all include files named in the course of reading the tree(s). The filename is remembered under key, "*iname*" in the blessed hash created. Parameter: *endq* ----------------- If two parameters are specified in the call to new(), the second will be interpreted as an indicator whether reading the file should stop at the end of the first full top-level tree. If present, the string specified in this parameter is copied into the blessed hash under the key, "*endq*". This will indicate multiple-tree mode, in which case the entire file will be read and interpreted as a tree of text strings. If unspecified, or specified as undef, the default of single-tree mode will be used for reading the file. Single-tree Reading Mode ------------------------ In the default file reading mode, only a single (the first, if there are more than one) top-level tree will be read from the file. The element of the module's blessed hash with key, "top", will have as value a reference to this tree (node). (To access file data following the first tree in the file, refer to the `internals' in this node documentation file.) Multiple-tree Reading Mode -------------------------- If the *endq* parameter is specified to new(), the entire file must conform to proper tree file syntax, and will be read into a data structure consisting of an array of top-level trees (tree nodes). In this case the element of the blessed hash with key, "top", will have as its value a reference to this array instead of a reference to just a single top-level tree (node). FUNCTION: *showlines* ===================== *showlines()* is called with a reference to a tree data structure as its first parameter and, optionally, an initial (integer) level number as its second parameter. It recursively prints the contents of the tree. FUNCTION: *showglobals* ======================= *showglobals()* is called with no parameters, and shows the contents of the blessed hash which is taken to contain global variables., TEST SCRIPT: test.pl ==================== The test.pl script conducts some tests of the module. EXPORTS ======= Nothing is exported by default. Functions *showlines()* and *showglobals()* may be imported on request. The module's new() function returns a blessed reference to a hash containing a number of data items, notably one with key, "top" which is the (top node of) the resulting tree of text strings read from the file. Key: "top" ---------- The tree structure of text strings returned by this module is remembered under the key, "top", in the object hash whose blessed reference is returned by new(). Nodes ----- Each node of the tree of text strings created by this module is an array of two elements, the first being a text string which is the content of this node, and the second being a reference to an array of references to the child nodes of the current node. EXCEPTIONS ========== The new() function will return the undef value if *_loadtree()* returns false. The *_loadtree()* function prints a warning to STDOUT and returns the undef value if an internal error allows it to be called with no input filename specified at the top file nesting level. The module should not allow this to occur. As a separate case, the prior paragraph's description applies, with a slightly different warning message, below the top file nesting level. If a filename is specified, but *_loadtree()* is unsuccessful in opening the file, a warning is printed to STDOUT and the undef value is returned. If *_readspec()* finds a line without an indent of an exact multiple of two space characters, it issues a *die()* call with a warning message. BUGS ==== The module doesn't use the *Carp(3pm)* module for warnings, calls *die()* in some exceptional cases, uses "`print STDOUT'" for warnings, and returns special values in most exceptional cases. It should use *Carp(3pm)* to issue warnings and then return special values, for all exceptions.  File: pm.info, Node: Text/TreeFile/internals, Next: Text/Trie, Prev: Text/TreeFile/details, Up: Module List implementation details ********************** NAME ==== Text::TreeFiles::internals - implementation details SYNOPSIS ======== use Text::TreeFile; sub _loadtree; sub _readspec; DESCRIPTION =========== (Nothing written, yet.)  File: pm.info, Node: Text/Trie, Next: Text/Unaccent, Prev: Text/TreeFile/internals, Up: Module List Name ==== Text::Trie Usage ----- use Text::Trie qw(Trie walkTrie); @trie = Trie 'abc', 'ab', 'ad'; walkTrie sub {print("[",shift,"]")}, sub {print(shift)}, sub {print "->"}, sub {print ","}, sub {print "("}, sub {print ")"}, @trie; `Trie' Given list of strings returns an array that consists of common heads and tails of strings. Element of an array is a string or an array reference. Each element corresponds to a group of arguments. Arguments are split into groups according to the first letter. If group consists of one element, it results in the string element in the output array. If group consists of several elements, then the corresponding element of output array looks like [$head, ...] where $head is the common head of the group, the rest is the result of recursive application of `Trie' to tails of elements of the group. `walkTrie' Takes 6 references to subroutines and an array as arguments. Array is interpreted as output of `Trie', the routine walks over the tree depth-first. If element of the array is a reference to array, it is interpreted as a node, and the `walkTrie' is applied to the corresponding array (without the first element) recursively. Otherwise the element is interpreted as a leaf of the tree. Subroutines are executed when (in the order of arguments of `walkTrie'): * a leaf of the tree is met, argument is the corresponding element of array; * a node is met, argument is the first element of the corresponding array; * a node that is not-empty is met, argument is the reference to the corresponding array; is called after the previous one; * between two sibling nodes or leafs, argument is the next node or leaf; * before executing any other code for a node, argument is the node; * after executing any other code for a node, argument is the node; Any one of the first six arguments can be undef instead of being a reference to a subroutine. Exports ------- None by default, `Trie' and `walkTrie' are @EXPORTABLE. Configuration ------------- Variable $Text::Trie::step can be set to a value bigger than 1 to set the length of smallest units arguments can be broken into. AUTHOR ====== Contact Ilya Zakharevich, *ilya@math.ohio-state.edu*.  File: pm.info, Node: Text/Unaccent, Next: Text/Vpp, Prev: Text/Trie, Up: Module List Remove accents from a string **************************** NAME ==== Text::Unaccent - Remove accents from a string SYNOPSIS ======== use Text::Unaccent; $unaccented = unac_string($charset, $string); $unaccented = unac_string_utf16($string); DESCRIPTION =========== Text::Unaccent is a module that remove accents from a string. `unac_string' converts the input string from the specified charset to UTF-16 and call `unac_string_utf16' to return the unaccented equivalent. The conversion from and to UTF-16 is done with iconv(1). METHODS ======= $unaccented = unac_string($charset, $string) Return the unaccented equivalent of the string $string. The character set of $string is specified by the $charset argument. The returned string is coded using the same character set. Valid values for the $charset argument are character sets known by iconv(1). Under GNU/Linux try `iconv --list' for a complete list. $unaccented = unac_string_utf16($string) Return the unaccented equivalent of the string $string. The character set of $string must be UTF-16. AUTHOR ====== Loic Dachary (loic@senga.org) http://www.sourceforge.net/projects/unac/ SEE ALSO ======== iconv(1).  File: pm.info, Node: Text/Vpp, Next: Text/Wrap, Prev: Text/Unaccent, Up: Module List Perl extension for a versatile text pre-processor ************************************************* 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 @EVAL 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; 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-2000 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).  File: pm.info, Node: Text/Wrap, Next: Text/WrapProp, Prev: Text/Vpp, Up: Module List line wrapping to form simple paragraphs *************************************** NAME ==== Text::Wrap - line wrapping to form simple paragraphs SYNOPSIS ======== use Text::Wrap print wrap($initial_tab, $subsequent_tab, @text); print fill($initial_tab, $subsequent_tab, @text); use Text::Wrap qw(wrap $columns $huge); $columns = 132; $huge = 'die'; $huge = 'wrap'; DESCRIPTION =========== Text::Wrap::wrap() is a very simple paragraph formatter. It formats a single paragraph at a time by breaking lines at word boundaries. Indentation is controlled for the first line ($initial_tab) and all subsequent lines ($subsequent_tab) independently. Lines are wrapped at $Text::Wrap::columns columns. $Text::Wrap::columns should be set to the full width of your output device. When words that are longer than $columns are encountered, they are broken up. Previous versions of wrap() die()ed instead. To restore the old (dying) behavior, set $Text::Wrap::huge to 'die'. Text::Wrap::fill() is a simple multi-paragraph formatter. It formats each paragraph separately and then joins them together when it's done. It will destroy any whitespace in the original text. It breaks text into paragraphs by looking for whitespace after a newline. In other respects it acts like wrap(). EXAMPLE ======= print wrap("\t","","This is a bit of text that forms a normal book-style paragraph"); AUTHOR ====== David Muir Sharnoff with help from Tim Pierce and many many others.  File: pm.info, Node: Text/WrapProp, Next: Text/Wrapper, Prev: Text/Wrap, Up: Module List proportional line wrapping to form simple paragraphs **************************************************** NAME ==== Text::WrapProp - proportional line wrapping to form simple paragraphs SYNOPSIS ======== use Text::WrapProp print wrap_prop($text, $width, $ref_width_table); use Text::WrapProp qw(wrap_prop); DESCRIPTION =========== Text::WrapProp::wrap_prop() is a very simple paragraph formatter for proportional text. It formats a single paragraph at a time by breaking lines at word boundries. You must supply the column width in floating point units which should be set to the full width of your output device. A reference to a character width table must also be supplied. The width units can be any metric you choose, as long as the column width and the width table use the same metric. Proportional wrapping is most commonly used in the publishing industry. In the HTML age, custom proportional wrapping is less often performed as the browser performs the calculations automatically. EXAMPLE ======= my @width_table = (0.05) x 256; print wrap_prop("This is a bit of text that forms a normal book-style paragraph. Supercajafrajalisticexpialadocious!", 4.00, \@width_table); BUGS ==== It's not clear what the correct behavior should be when WrapProp() is presented with a word that is longer than a line. The previous behavior was to die. Now the word is split at line-length. AUTHOR ====== James Briggs <71022.3700@compuserve.com>, styled after Text::Wrap.  File: pm.info, Node: Text/Wrapper, Next: Text/libtmpl, Prev: Text/WrapProp, Up: Module List Simple word wrapping routine **************************** NAME ==== Text::Wrapper - Simple word wrapping routine SYNOPSIS ======== require Text::Wrapper; $wrapper = Text::Wrapper->new(columns => 60, body_start => ' '); print $wrapper->wrap($text); DESCRIPTION =========== *Text::Wrapper* provides simple word wrapping. It breaks long lines, but does not alter spacing or remove existing line breaks. If you're looking for more sophisticated text formatting, try the *Text::Format* module. Reasons to use *Text::Wrapper* instead of *Text::Format*: * *Text::Wrapper* is significantly smaller. * It does not alter existing whitespace or combine short lines. It only breaks long lines. Again, if *Text::Wrapper* doesn't meet your needs, try *Text::Format*. Methods ------- $wrapper = Text::Wrapper->new( [options] ) Constructs a new *Text::Wrapper* object. The options are specified by key and value. The keys are: body_start The text that begins the second and following lines of a paragraph. (Default '') columns The number of columns to use. This includes any text in body_start or par_start. (Default 70) par_start The text that begins the first line of each paragraph. (Default '') $wrapper->body_start( [$value] ) $wrapper->columns( [$value] ) $wrapper->par_start( [$value] ) If $value is supplied, sets the option and returns the previous value. If omitted, just returns the current value. $wrapper->wrap($text) Returns a word wrapped copy of $text. The original is not altered. BUGS ==== Does not handle tabs (they're treated just like spaces). Does not break words that can't fit on one line. AUTHOR ====== Christopher J. Madsen <`chris_madsen@geocities.com'>  File: pm.info, Node: Text/libtmpl, Next: Text/template_extend, Prev: Text/Wrapper, Up: Module List Templating system C library *************************** NAME ==== libtmpl - Templating system C library SYNOPSIS ======== *#include "template.h"* context_p template_init(void) int template_set_delimiters(context_p ctx, char *opentag, char *closetag) int template_register_simple(context_p ctx, char *name, void (*function)(context_p, char **, int, char**)) int template_register_pair(context_p ctx, char named_context, char *open_name, char *close_name, void (*function)(context_p, int, char**)) int template_alias_simple(context_p ctx, char *old_name, char *new_name) int template_alias_pair(context_p ctx, char *old_open_name, char *old_close_name, char *new_open_name, char *new_close_name) int template_set_value(context_p ctx, char *name, char *value) void template_set_debug(context_p ctx, int debug) void template_set_strip(context_p ctx, int strip) int template_set_dir(context_p ctx, char *directory) void template_destroy(context_p ctx) context_p template_loop_iteration(context_p ctx, char *loop_name) int template_parse_file(context_p ctx, char *template_filename, char **output) int template_parse_string(context_p ctx, char *template, char **output) extern int template_errno char * template_strerror(void) DESCRIPTION =========== Design goals ------------ simplicity, reusability, speed, complete separation of logic from formatting. Feature set ----------- variables, loops, conditionals, extensibility of tags, includes, arbitrary delimiters. Usage ----- For starters, make sure you #include "template.h" and link against libtmpl.a. Each function is described below: template_init This function initializes the library. It allocates and returns the "global" context structure, and also configures all of the default tag behavior. template_init() can fail with TMPL_EMALLOC. template_set_delimiters This function lets you change the delimiters marking the beginning and end of a tag (by default, these are "" in the given context. template_set_delimiters() can fail with TMPL_ENULLARG. template_set_value This function stores the name=value pair in the current context. template_set_value() can fail with TMPL_ENULLARG. template_set_debug This function turns debugging output on or off. Note that debugging output hasn't been written yet - this is just a placeholder. template_set_strip This function enables or disables the newline stripping feature. If enabled, the parser removes a single newline (if present) from after any tag. template_set_dir This function sets the directory where templates will be sought, both by parse_file and by the include tag. Search order is always current directory then this searched directory. template_set_dir() can fail with TMPL_ENULLARG. template_loop_iteration This function adds an iteration to the loop named loop_name, and returns a unique context for that loop iteration. template_loop_iteration() can fail with TMPL_ENULLARG, TMPL_EMALLOC. template_parse_file This function opens template_filename, and parses the contents of that file as a template, placing the output into *output. It allocates all the memory for you, but it is up to the programmer to free *output! template_parse_file() can fail with TMPL_ENULLARG, TMPL_ENOTFOUND, TMPL_EFOPEN, TMPL_EMALLOC or TMPL_EPARSE. template_parse_string This function parses template directly, in the same way that template_parse_file does. template_parse_string() can fail with TMPL_ENULLARG, TMPL_EMALLOC or TMPL_EPARSE. template_register_simple This function registers a new simple tag named name, which when encountered will cause the parser to call function. See template_extend(1) for the gory details. template_register_simple() can fail with TMPL_ENULLARG, TMPL_EMALLOC. template_register_pair This function registers a new tag pair open_name/close_name, which when encountered will cause the parser to call function. See template_extend for the gory details. template_register_pair() can fail with TMPL_ENULLARG, TMPL_EMALLOC. template_alias_simple This function copies the definition of a simple tag, previously registered as old_name, to also be called by new_name. template_alias_simple() can fail with TMPL_ENULLARG, TMPL_EMALLOC. template_alias_pair This function copies the definition of a tag pair, previously registered as old_open_name/old_close_name, to also be called by new_open_name/new_close_name. template_alias_pair() can fail with TMPL_ENULLARG, TMPL_EMALLOC. template_destroy This function blows away all of the memory allocated within the given context. You should really *only* call this on the context returned by template_init, and only at the end of your code. template_errno This is a global variable containing the error number of the last error - see the RETURN VALUES section below. template_strerror This function returns a string describing the last error - see the RETURN VALUES section below. RETURN VALUES ============= All of the above functions which return int values will return 0 if they fail, or 1 otherwise. The ones which return context_p pointers will return NULL if they fail, or a valid pointer otherwise. A function which fails will also set a global error number, which you can read or use template_strerror() to describe. BUGS ==== Hopefully none. AUTHOR ====== J. David Lowe, dlowe@pootpoot.com SEE ALSO ======== Text::Tmpl(1), template_syntax(1), template_extend(1)  File: pm.info, Node: Text/template_extend, Next: Text/template_syntax, Prev: Text/libtmpl, Up: Module List how to extend the Text::Tmpl template library (with C or Perl). *************************************************************** NAME ==== template_extend - how to extend the Text::Tmpl template library (with C or Perl). SYNOPSIS ======== Perl: $context->register_simple("name", \&simple_handler); sub simple_handler { my($context, $name, @args) = @_; # do stuff to build a return string return "result string!"; } $context->register_pair($is_named, "open", "close", \&pair_handler); sub pair_handler { my($context, $name, @args) = @_; # do stuff to the context return; } $subctx = Text::Tmpl::context_get_anonymous_child($ctx); $subctx = Text::Tmpl::context_get_named_child($ctx, $name); $peerctx = Text::Tmpl::context_add_peer($ctx); $return = Text::Tmpl::context_set_named_child($ctx, $name); Text::Tmpl::context_output_contents($ctx, $output); C: int template_register_simple(context_p ctx, char *name, void (*function)(context_p, char **, int, char**)) void simple_handler(context_p ctx, char **output, int argc, char **argv) { char *returnstring; /* do stuff to build a return string */ *output = (char *)calloc(1, strlen(returnstring)); strncpy(*output, returnstring, strlen(returnstring)); return; } int template_register_pair(context_p ctx, char named_context, char *open_name, char *close_name, void (*function)(context_p, int, char**)) void pair_handler(context_p ctx, int argc, char **argv) { /* do stuff to the context */ return; } context_p context_get_anonymous_child(context_p ctx); context_p context_get_named_child(context_p ctx, char *name); int context_set_named_child(context_p ctx, char *name); context_p context_add_peer(context_p ctx); void context_output_contents(context_p ctx, char output_contents); DESCRIPTION =========== Creating new tags in this templating system is pretty easy, despite the somewhat daunting API. The perl and C APIs are virtually identical in both usage and effects, so I'm going to be discussing the process in a (hopefully) language independent way. Note that tags are global in scope - a tag can be registered at any point before the parsing stage and will be visible to the entire template. This may change in future versions, if there seems to be a demand for scoped tags. Tag Argument Passing -------------------- Arguments to any tag are passed into the tag function as an argc/argv pair in the C API, or a list in the Perl API. Either way, element 0 of the argument list will be the tag name, so the first argument is actually element 1. Simple Tags ----------- Simple tags are lone tags which generate a string for inclusion in the parsed output. A perl simple tag function simply returns a string, whereas a C simple tag function has to allocate a new string (which the caller will free() after use.) The echo tag function in C looks like: void simple_tag_echo(context_p ctx, char **output, int argc, char **argv) { int size; if (argc < 1) { *output = NULL; return; } size = strlen(argv[1]); *output = (char *)calloc(1, size + 1); strncpy(*output, argv[1], size); (*output)[size] = '\0'; return; } This illustrates a couple of things: errors from simple tags should be indicated by making *output a NULL pointer, and don't forget to null-terminate *output. In perl, you would duplicate this by: sub simple_tag_echo { my $context = shift || return undef; my $name = shift || return undef; my $string = shift || return undef; return $string; } It should also be pointed out that all of the argument parsing, including variable interpolation, has already happened by this point. Simple tags are called with the context in which they are found. They can make changes to the context, but the results may be unexpected - for example, attempting to disable the output of the entire surrounding context will not work. The output string from a single tag will (if not NULL) be run through the parser. This means that a simple tag can output a template fragment. So, for example, if you wanted to implement an "else" tag, you could: sub simple_tag_else { my $context = shift || return undef; my $name = shift || return undef; return ""; } Tag Pairs --------- Tag pairs are more complicated. As the name implies, tag pairs have a beginning and an end, denoted by two distinct tags. When a beginning tag is found, the parser scans forward to find the matching closing tag, and then parses everything in between in the context of the tag function. There are two kinds of tag pairs - those with named contexts, and those with anonymous contexts. A named context is used for tag pairs which allow the programmer to pre-build some (or all) of the context structure before parsing takes place, such as the loop tag. An anonymous context is used when the context is constructed completely at parse time, such as the comment tag. The actual name of the context, in a named context tag pair, is the first argument to the opening tag (for example retrieves the named context "foo" from the parent context). The tag function is called before parsing of the context begins, so it gets to completely set up the context beforehand. So the comment tag, for example, simply disables output of the context: void tag_pair_comment(context_p ctx, int argc, char **argv) { context_output_contents(ctx, 0); return; } The contents of the context are never even parsed, since the parser knows that it won't be output. The context_* functions ----------------------- This group of functions is used to manipulate context structures in ways the main template API doesn't allow. Before we dive into it, some understanding of the context structure will be required. Contexts are quite simple, really. They contain a list of variables and a flag which determines whether the contents of the context should be output. Each context can also know about a number of other contexts internally: its parent, its peer(s) - each peer representing a loop iteration - and its named children. A context may have zero or more of each of these. For example, the initial context returned from template_init has no parent, no peers and no named children initially. If you call template_loop_iteration, the main context will gain a single named child context, which in turn will have the main context as a parent, no peers (yet) and no named children. If you call template_loop_iteration on the main context with the same name again, the named child will gain a peer context. And so on, and so forth... In summary: the parent context provides nested scopes, peers represent iterations over the same chunk of the template, and named children are contexts which can be fetched by name both at preparation time and parse time. context_get_anonymous_child Creates and returns an unnamed context with the parent set to the current context (i.e. a new context within the scope of the current context). context_get_named_child This function returns a named context within the scope of the current context, if it exists. context_set_named_child This function creates a new named context within the scope of the current context. context_add_peer This function adds a peer context to the context passed in, and initializes it. context_output_contents This function sets the output_contents flag in the current context. RETURN VALUES ============= Functions which return context_p pointers will return NULL if there is any problem at all. Functions which return integers return 0 on failure and 1 on success. BUGS ==== Hopefully none. AUTHOR ====== J. David Lowe, dlowe@pootpoot.com SEE ALSO ======== libtmpl(1), Text::Tmpl(1), template_syntax(1)