Parse::Template - Processeur de templates contenant des expressions Perl (0.32)
use Parse::Template; my %template = ( 'TOP' => q!Text before %%$self->eval('DATA')%% text after!, 'DATA' => q!Insert data: ! . q!1. List: %%"@list$N"%%! . q!2. Hash: %%"$hash{'key_value'}$N"%%! . q!3. File content: %%print <FH>%%! . q!4. Sub: %%&SUB()$N%%! ); my $tmplt = new Parse::Template (%template); open FH, "< foo"; $tmplt->env('var' => '(value!)'); $tmplt->env('list' => [1, 2, 10], 'N' => "\n", 'FH' => \*FH, 'SUB' => sub { "->content generated by a sub<-" }, 'hash' => { 'key_value' => q!It\'s an hash value! }); print $tmplt->eval('TOP'), "\n";
La classe Parse::Template permet d'évaluer des expressions Perl placées dans un texte. Cette classe peut être utilisée comme générateur de code, ou de documents appartenant à un format documentaire quelconque (HTML, XML, RTF, etc.).
Parse::Template
Le principe de la génération de texte à partir d'un template est simple. Un template est constitué d'un texte qui comporte des expressions à évaluer en des endroits balisés. L'interprétation de ces expressions génère des fragments de textes qui viennent se substituer aux expressions.
L'évaluation a lieu dans un environnement dans lequel on peut, par exemple, placer des structures de données qui serviront à générer les parties à compléter.
TEMPLATE Texte + Expression Perl | +-----> Evaluation ----> Texte (document ou programme) | Subs + Structures de données ENVIRONNEMENT
La classe Parse::Template permet de décomposer un template en parties. Ces parties sont définies par un tableau associatif passé en argument au constructeur de la classe : Parse::Template->new('someKey', '... text with expressions to evaluate ...'). Au sein d'une partie, l'inclusion d'une sous-partie se fait au moyen d'une expression de la forme :
Parse::Template-
new('someKey', '... text with expressions to evaluate ...')
$self->eval('SUB_PART_NAME')
$self désigne l'instance de la classe Parse::Template.
$self
Vous pouvez vous contenter de ne mentionner que le nom de la partie. Dans ce cas une routine du nom de cette partie est générée dynamiquement. Dans l'exemple du synopsis l'insertion de la partie TOP peut ainsi se réécrire comme suit :
TOP
'TOP' => q!Text before %%DATA()%% text after!
DATA() est placée entre %% et est de fait traiter comme une expression a évaluer.
DATA()
%%
Les routines acceptent des arguments. Un argument peut être par exemple utilisé pour contrôler la profondeur des appels récursifs d'un template :
print Parse::Template->new( 'TOP' => q!%%$_[0] < 10 ? '[' . TOP($_[0] + 1) . ']' : ''%%! )->eval('TOP', 0);
Dans une expression vous pouvez utiliser les variables $self et $part. La première désigne l'instance template, la seconde le nom de la partie dans laquelle se trouve l'expression.
$part
La méthode env() permet de construire l'environnement requis pour l'évaluation d'un template. Chaque entrée à définir dans cet environnement doit être spécifiée au moyen d'une clé du nom du symbole à créer, associée à une référence dont le type est celui de l'entrée à créer dans cette environnement (par exemple, une référence à un tableau pour créer un tableau). Un variable scalaire est définie en associant le nom de la variable à sa valeur. Une variable scalaire contenant une référence est définie en écrivant 'var'=>\$variable, avec $variable une variable à portée lexicale qui contient la référence.
env()
'var'=
\$variable
$variable
Chaque instance de Parse::Template est définie dans une classe spécifique, sous-classe de Parse::Template. La sous-classe contient l'environnement spécifique au template et hérite des méthodes de la classe Parse::Template.
En cas d'erreur de syntaxe dans l'évaluation d'une expression Parse::Template essaie d'indiquer la partie du template et l'expression à incriminer. Si la variable $Parse::Template::CONFESS contient une valeur VRAIE la pile des évaluations est imprimée.
$Parse::Template::CONFESS
Constructeur de la classe. HASH est un tableau associatif qui définit le texte du template.
HASH
Exemple.
use Parse::Template; $t = new Parse::Template('key' => 'associated text');
Permet de définir l'environnement spécifique à un template.
env(SYMBOL) retourne la référence assocée au symbole ou undef si le symbole n'est pas défini. La référence retournée est du type indiqué par le caractère (&, $, %, @, *) qui préfixe le symbole.
env(SYMBOL)
undef
&, $, %, @, *
Exemples.
$tmplt->env('LIST' => [1, 2, 3])} Définition d'une liste @{$tmplt->env('*LIST')} Retourne la liste @{$tmplt->env('@LIST')} Idem
Evalue le partie du template désignée par PART_NAME. Retourne la chaîne de caractères résultant de cette évaluation.
PART_NAME
Retourne la partie désignée du template.
Pré-processe une expression régulière de manière à pouvoir l'insérer dans un template où le délimiteur d'expression régulière est un "/", ou un "!".
setPart() permet de définir une nouvelle entrée dans le hash qui définit le contenu du template.
setPart()
La classe Parse::Template permet de se livrer à toutes sortes de facéties. En voici quelques illustrations.
Le premier exemple montre comment générer un document HTML en exploitant une structure de données placée dans l'environnement d'évaluation. Le template comporter deux partie DOC et SECTION. La partie SECTION est appelée au sein de la partie DOC pour générer autant de sections qu'il y a d'élément dans le tableau section_content.
DOC
SECTION
section_content
my %template = ('DOC' => <<'END_OF_DOC;', 'SECTION' => <<'END_OF_SECTION;'); <html> <head></head> <body> %% my $content; for (my $i = 0; $i <= $#section_content; $i++) { $content .= SECTION($i); } $content; %% </body> </html> END_OF_DOC; %% $section_content[$_[0]]->{Content} =~ s/^/<p>/mg; join '', '<H1>', $section_content[$_[0]]->{Title}, '</H1>', $section_content[$_[0]]->{Content}; %% END_OF_SECTION; my $tmplt = new Parse::Template (%template); $tmplt->env('section_content' => [ { Title => 'First Section', Content => 'Nothing to write' }, { Title => 'Second section', Content => 'Nothing else to write' } ] ); print $tmplt->eval('DOC'), "\n";
Le second exemple montre comment générer un document HTML à partir d'une notation fonctionnelle, c'est-à-dire obtenir le texte :
<P><B>text in bold</B><I>text in italic</I></P>
à partir de
P(B("text in bold"), I("text in italic"))
L'expression Perl permettant de produire ce genre de structure est très simple et se réduit à :
join '', @_
Le contenu à évaluer est le même quel que soit la balise et peut donc être placé dans une variable. Nous obtenons donc le template suivant :
my $ELT_CONTENT = q!%%join '', @_%%!; my $HTML_T1 = new Parse::Template( 'DOC' => '%%P(B("text in bold"), I("text in italic"))%%', 'P' => qq!<P>$ELT_CONTENT</P>!, 'B' => qq!<B>$ELT_CONTENT</B>!, 'I' => qq!<I>$ELT_CONTENT</I>!, ); print $HTML_T1->eval('DOC'), "\n";
Nous pouvons aller plus loin en exploitant la variable $part qui est définie par défaut dans l'environnement d'évaluation du template :
$ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!; $HTML_T2 = new Parse::Template( 'DOC' => '%%P(B("text in bold"), I("text in italic"))%%', 'P' => qq!$ELT_CONTENT!, 'B' => qq!$ELT_CONTENT!, 'I' => qq!$ELT_CONTENT!, ); print $HTML_T2->eval('DOC'), "\n";
Voyons une autre étape qui automatise la production des expressions :
$DOC = q!P(B("text in bold"), I("text in italic"))!; $ELT_CONTENT = q!%%"<$part>" . join('', @_) . "</$part>"%%!; $HTML_T3 = new Parse::Template( 'DOC' => qq!%%$DOC%%!, map { $_ => $ELT_CONTENT } qw(P B I) ); print $HTML_T3->eval('DOC'), "\n";
Moyennant une dernière transformation il est possible d'utiliser une notation invocation de méthode pour procéder à la génération :
$ELT_CONTENT = q!%%shift(@_); "<$part>" . join('', @_) . "</$part>"%%!; $HTML_T4 = new Parse::Template( map { $_ => $ELT_CONTENT } qw(P B I) ); print $HTML_T4->P( $HTML_T4->B("text in bold"), $HTML_T4->I("text in italic") ), "\n";
Parse::Template a été initialement créée pour servir de générateur de code à la classe Parse::Lex. Vous trouverez d'autres exemples d'utilisation dans les classes Parse::Lex, Parse::CLex et Parse::Token.
Parse::Lex
Parse::CLex
Parse::Token
Il s'agit d'un module expérimental. Je suis très intéressé par vos remarques et suggestions.
Les instances ne sont pas détruites. Donc n'utilisez pas cette classe pour créer un grand nombre d'instances.
Philippe Verdret avec l'aide d'Ocrat pour la traduction de la documentation en anglais.
Copyright (c) 1995-1999 Philippe Verdret. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'd'évaluer'. Assuming CP1252
To install Parse::Lex, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Parse::Lex
CPAN shell
perl -MCPAN -e shell install Parse::Lex
For more information on module installation, please visit the detailed CPAN module installation guide.