################################################################################### # # Embperl - Copyright (c) 1997-2008 Gerald Richter / ecos gmbh www.ecos.de # Embperl - Copyright (c) 2008-2014 Gerald Richter # # You may distribute under the terms of either the GNU General Public # License or the Artistic License, as specified in the Perl README file. # # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR # IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED # WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. # # $Id: Syntax.pm 1578075 2014-03-16 14:01:14Z richter $ # ################################################################################### package Embperl::Syntax ; use strict ; use vars qw{@ISA @EXPORT_OK %EXPORT_TAGS %DocumentRoot %Syntax} ; @ISA = qw{Exporter} ; use constant ntypTag => 1 ; use constant ntypStartTag => 1 + 0x20 ; use constant ntypStartEndTag => 1 + 0x80 ; use constant ntypEndTag => 1 + 0x40 ; use constant ntypEndStartTag => 1 + 0x60 ; use constant ntypAttr => 2 ; use constant ntypAttrValue => 2 + 0x20 ; use constant ntypText => 3 ; use constant ntypCDATA => 4 ; use constant ntypEntityRef => 5 ; use constant ntypEntity => 6 ; use constant ntypProcessingInstr => 7 ; use constant ntypComment => 8 ; use constant ntypDocument => 9 ; use constant ntypDocumentType => 10 ; use constant ntypDocumentFraq => 11 ; use constant ntypNotation => 12 ; use constant aflgSingleQuote => 8 ; @EXPORT_OK = qw{ ntypTag ntypStartTag ntypStartEndTag ntypEndTag ntypEndStartTag ntypAttr ntypAttrValue ntypText ntypCDATA ntypEntityRef ntypEntity ntypProcessingInstr ntypComment ntypDocument ntypDocumentType ntypDocumentFraq ntypNotation aflgSingleQuote } ; %EXPORT_TAGS = ( types => \@EXPORT_OK, ) ; ################################################################################### # # Methods # ################################################################################### # --------------------------------------------------------------------------------- # # Create new Syntax Object # # --------------------------------------------------------------------------------- sub new { my $class = shift ; my $self = $class ; if (!ref $class) { $self = { -root => $class -> CloneHash (\%DocumentRoot) , -procinfotype => 'embperl', } ; bless $self, $class ; } return $self ; } # --------------------------------------------------------------------------------- # # Add new elemets to root # # --------------------------------------------------------------------------------- sub AddToRoot { my ($self, $elements) = @_ ; my $root = $self -> {-root} ; while (my ($k, $v) = each (%$elements)) { $root -> {$k} = $v ; } } # --------------------------------------------------------------------------------- # # Adds code that is execute everytime after the compile of a document # start and end of the execution of a document # # --------------------------------------------------------------------------------- sub AddInitCode { my ($self, $compiletimecode, $initcode, $termcode, $procinfo) = @_ ; my $root = $self -> {-root} ; my $ttref ; foreach my $tagtype ('Document', 'DocumentFraq') { die "'$tagtype' unknown" if (!($ttref = $self -> {-root}{$tagtype})) ; my $pinfo = ($ttref -> {'procinfo'}{$self -> {-procinfotype}} ||= {}) ; $pinfo -> {'compiletimeperlcode'} .= $compiletimecode if ($compiletimecode) ; $pinfo -> {'perlcode'} .= $initcode if ($initcode) ; $pinfo -> {'perlcodeend'} .= $termcode if ($termcode) ; if ($procinfo) { while (my ($k, $v) = each (%$procinfo)) { $pinfo -> {$k} = $v ; } } } } # --------------------------------------------------------------------------------- # # Get root # # --------------------------------------------------------------------------------- sub GetRoot { my ($self) = @_ ; return $self -> {-root} ; } # --------------------------------------------------------------------------------- # # Get/create named syntax # # --------------------------------------------------------------------------------- sub GetSyntax { my ($name, $oldname) = @_ ; my %names ; my $op = '' ; if ($name =~ /^(\+|\-)\s*(.*?)$/) { $op = $1 ; $name = $2; } $name = "$oldname $name" if ($op eq '+') ; my @split = split (/\s/, $name) ; if ($op eq '-') { my @mnames = map { /::/?$_:'Embperl::Syntax::'. $_ } @split ; foreach (@mnames) { $names{$_} = 1 ; } @split = split (/\s/, $oldname) ; } my @xnames = map { /::/?$_:'Embperl::Syntax::'. $_ } @split ; my @names ; foreach (@xnames) { push @names, $1 if (!$names{$_} && (/^\s*([a-zA-Z_0-9:]+)\s*$/)) ; $names{$_} = 1 ; } $name = join (' ', @names) ; print Embperl::LOG "[$$]SYNTAX: switch to $name\n" ; return undef if (!$name) ; return $Syntax{$name} if (exists ($Syntax{$name})) ; foreach my $n (@names) { eval "require $n" ; if ($@) { warn $@ ; return undef ; } } my $first = shift @names ; my $self = $first -> new ; foreach my $n (@names) { no strict ; &{"${n}::new"}($self) ; use strict ; } $self -> {-name} = $name ; BuildTokenTable ($self) ; $Syntax{$name} = $self ; return $self ; } # --------------------------------------------------------------------------------- # # Deep clone a hash and make replacements # # --------------------------------------------------------------------------------- sub CloneHash { my ($self, $old, $replace, $seen, $new) = @_ ; $new ||= {} ; $replace ||= {} ; $seen ||= {$old => $new} ; my ($v, $k) ; while (($k, $v) = each (%$old)) { if ($replace -> {$k}) { $new -> {$k} = $replace -> {$k} ; } else { if (ref ($v) eq 'HASH') { if ($seen -> {$v}) { $new -> {$k} = $seen -> {$v} ; } else { my $sub = {} ; $seen -> {$v} = $sub ; $self -> CloneHash ($v, $replace, $seen, $sub) ; $new -> {$k} = $sub ; } } elsif (ref ($v) eq 'ARRAY') { $new -> {$k} = [@$v] ; } else { $new -> {$k} = $v ; } } } return $new ; } ################################################################################### # # Definitions for documents # ################################################################################### %DocumentRoot = ( '-lsearch' => 1, # The document node is generated always and is not parserd, but can be used to include code 'Document' => { 'nodename' => 'Document', 'nodetype' => ntypDocument, 'procinfo' => { embperl => { perlcode => q{ # any initialisation could be put here #$DB::single = 1 ; $maxrow=100;$maxcol=10; }, compiletimeperlcode => q{ use vars ('$_ep_DomTree', '@ISA', '@param') ; *_ep_rp=\\&XML::Embperl::DOM::Node::iReplaceChildWithCDATA; *_ep_rpid=\\&XML::Embperl::DOM::Node::iReplaceChildWithMsgId; *_ep_rpurl=\\&XML::Embperl::DOM::Node::iReplaceChildWithUrlDATA; *_ep_cp=\\&XML::Embperl::DOM::Tree::iCheckpoint; *_ep_dcp=\\&XML::Embperl::DOM::Tree::iDiscardAfterCheckpoint; *_ep_opt=\\&Embperl::Cmd::Option; *_ep_hid=\\&Embperl::Cmd::Hidden; *_ep_ac=\\&XML::Embperl::DOM::Node::iAppendChild; *_ep_sa=\\&XML::Embperl::DOM::Element::iSetAttribut; Embperl::Util::CreateAliases ; }, perlcodeend => q{# Include here any cleanup code $DB::single = 0 ; }, stackname => 'metacmd', stackmatch => 'Document', 'push' => 'Document', mayjump => 1, } }, }, # The document fraq node is generated always and is not parserd, but can be used to include code 'DocumentFraq' => { 'nodename' => 'DocumentFraq', 'nodetype' => ntypDocumentFraq, 'procinfo' => { embperl => { perlcode => q{ #my $_ep_param_save = \@param ; #*param = $Embperl::req -> component -> param -> param || []; }, compiletimeperlcode => q{ use vars ('$_ep_DomTree', '@ISA', '@param') ; *_ep_rp=\\&XML::Embperl::DOM::Node::iReplaceChildWithCDATA; *_ep_rpid=\\&XML::Embperl::DOM::Node::iReplaceChildWithMsgId; *_ep_rpurl=\\&XML::Embperl::DOM::Node::iReplaceChildWithUrlDATA; *_ep_cp=\\&XML::Embperl::DOM::Tree::iCheckpoint; *_ep_dcp=\\&XML::Embperl::DOM::Tree::iDiscardAfterCheckpoint; *_ep_opt=\\&Embperl::Cmd::Option; *_ep_hid=\\&Embperl::Cmd::Hidden; *_ep_ac=\\&XML::Embperl::DOM::Node::iAppendChild; *_ep_sa=\\&XML::Embperl::DOM::Element::iSetAttribut; Embperl::Util::CreateAliases ; }, perlcodeend => q{ #*param = $_ep_param_save ; }, stackname => 'metacmd', stackmatch => 'DocumentFraq', 'push' => 'DocumentFraq', mayjump => 1, } }, }, ) ; 1; __END__ =pod =head1 NAME Embperl::Syntax - base class for defining custom syntaxes =head1 SYNOPSIS =head1 DESCRIPTION Embperl::Syntax provides a base class from which all custom syntaxes should be derived. Currently Embperl comes with the following derived syntaxes: =over 4 =item EmbperlHTML all the HTML tag that Embperl recognizes by default =item EmbperlBlocks all the [ ] blocks that Embperl supports =item Embperl The default syntax; is derived from C and C =item ASP <% %> and <%= %>, see perldoc Embperl::Syntax::ASP =item SSI Server Side Includes, see perldoc Embperl::Syntax::SSI =item Perl File contains pure Perl (similar to Apache::Registry), but can be used inside EmbperlObject =item Text File contains only Text, no actions is taken on the Text =item Mail Defines the tag, for sending mail. This is an example for a taglib, which could be a base for writing your own taglib to extent the number of available tags =item POD Parses POD out of any file and creates a XML tree similar to pod2xml, which can be formatted by XSLT afterwards. =back You can choose which syntax is used inside your page, either by the C configuration directive, the C, parameter to C or the C<[$ syntax $]> metacommand. You can also specify multiple syntaxes e.g. PerlSetEnv EMBPERL_SYNTAX "Embperl SSI" Execute ({inputfile => '*', syntax => 'Embperl ASP'}) ; The syntax metacommand allows you to switch the syntax or to add or subtract syntaxes e.g. [$ syntax + Mail $] will add the Mail taglib so the tag is available after this line. [$ syntax - Mail $] now the tag is unknown again [$ syntax SSI $] now you can only use SSI commands inside your page. =head1 Defining your own Syntax If you want to define your own syntax, you have to derive a new class from one of the existing ones and extent it with new tags/functionality. The best thing is to take a look at the syntax classes that comes with Embperl. (inside the directory Embperl/Syntax/). For example if you want to add new html tags, derive from I, if you want to add new metacommands derive from I. Some of the classes define addtionaly methods to easily add new tags. See the respective pod file, which methods are available for a certain class. I defines the basic methods to create a syntax: =head1 Methods =head2 Embperl::Syntax -> new / $self -> new Create a new syntax class. This method should only be called inside a constructor of a derived class. =head2 $self -> AddToRoot ($elements) This adds a new element to the root of the parser tree. C<$elements> must be a hashref. See I for an example. =head2 $self -> AddInitCode ($compiletimecode, $initcode, $termcode, $procinfo) This gives you the possibility to add some Perl code, that is always executed at the beginning of a document (C<$initcode>), at the end of the document (C<$termcode>) or at compile time (C<$compiletimecode>). The three strings must be valid Perl code. See I for an example. C<$procinfo> is a hashref that can consits of addtional processor infos (see below) for the document. =head2 $self -> GetRoot Returns the root of the parser tree. =head2 Embperl::Syntax::GetSyntax ($name, $oldname) Returns a syntax object which is build form the syntaxes named in C<$name>. If C<$oldname> is given, C<$name> can start with a C<+> or C<-> to add or subtract a syntax. This is normally only needed by Embperl itself or to implement a syntax switch statement (see I for an example.) =head2 $self -> CloneHash ($old, $replace) Clones a hash which is given as hashref in C<$old>, optional replace the tags given in the hashref C<$replace> and return a hashref to the new hash. =head1 Syntax Structure and Parameter Internaly the syntax object builds a data structure which serve as base for the parser. This structure consists of a list of tokens and options, which starts with a dash: =head2 Tokens =over 4 =item '-lsearch' => 1 Do an linear serach instead of a binary search. This is necessary if the tokens can't clearly separated. =item '-defnodetype' => ntypText, Defines the default type for text nodes. Without any specification the type is CDATA, which mean no escaping takes places. With C all special characters are escaped. =item '-rootnode' Name for a root node to insert always. =item => \%tokendescription All items which does not start with a slash are treated as names. The name of a token is only descriptive and is used in error messages. The item must contain a hashref which describes the token. =back =head2 Tokendescription Each token can have the following members: =over 4 =item 'text' => '<' Start text =item 'end' => '>' End text =item 'matchall' when set to 1 new token starts at next character, when set to -1 new token starts at next character, but only if it is the first token inside another one. =item 'nodename' Text that should be outputed when node is stringifyed. Defaults to text. If the first character is a ':' you can specify the sourounding delimiters for this tag with ::::. Example: ':{:}:NAME' . If the nodename starts with a '!' a unique internal id is generated, so two or more nodename of the same text, can have different meaning in different contexts. =item 'contains' => 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_0123456789' Token consists of the following characters. Either C and C B C could be specified. NOTE: If a item that only specfifies contains but no text should be compiled, you must specfify a nodname. =item 'unescape' => 1 If C isn't set unescape the data of the inside the node =item 'nodetype' => ntypEndTag Type of the node =item 'cdatatype' => ntypAttrValue Type of nodes for data (which is not matched by 'inside' definitions) inside this node. Set to zero to not generate any nodes for text inside of this node, other then these that are matched by a 'inside' definition. =item 'endtag' Name of the tag that marks the end of a block. This is used by the parser to track correct nesting. =item 'follow' => \%tokenlist Hashref that specifices one or more tokens that must follow this token. =item 'inside' => \%tokenlist Hashref that specifices one or more tokens that could occur inside a node that is started with this token. =item exitinside when the token found, the parser stop searching in the current level and continues with the tokens that are defined in the hash from there the current one was "called" via inside =item donteat set to 1 to don't eat the start text, so it will be matched again, by any tokens set under C. Set 2 to don't the end text. Set to 3 for both. =item 'procinfo' => Processor info. Hashref with information how to process this token. =back =head2 Processor info The processor info gives information how to compile this token to valid code that can be executed later on by the processor. There could be information for multiple processors. At the moment only the I processor is defined. Normaly you must not worry about different processor, because the syntax object knows inside that all procinfo is for the I processor. I is a parameter to many methods, it is a hashref and can take the following items: =over 4 =item perlcode => or Code to generate. You can also specify a arrayref of strings. The first string which contains matching attributes are used. The following special strings are replaced: =over 4 =item %#% Text of childnode number (starting with zero) =item %>% Text of sibling node number . 0 gives the current node, > 0 gives the Nth next node, < 0 gives the Nth previous node. =item %&% Value of attribute . =item %^% Stringvalue of given stack =item %?% Set if stackvalue was used =item %$n% Source Dom Tree, Index of current node. =item %$t% Source Dom Tree =item %$x% Index of current node =item %$l% Index of last node =item %$c% Sets the current node Index, if not already done =item %$q% Index of source Dom Tree =item %$p% Number of current checkpoint =item %% Gives a single % =back All of the above special values (expect those start with $) allows the following modifiers: =over 4 =item %B<*>% Attribute/Child etc. must exist. =item %B% Attribute/Child etc. must not exist. =item %B<=>:||% Attribute/Child etc. must have the value = or etc. =item %B<~>:||% Attribute/Child etc. must contain the substring or etc. and a non alphanum character must follow the substring. =back writing a minus sign (-) after * ! = or ~ will cause the child/attribute not to be included, but the condition is evaluated. Writing an ' will cause the value to be quoted. =item perlcodeend => Code to generate at the end of the block. =item compiletimeperlcode => or Code that is executed at compile time. You can also specify a arrayref of string. The first string which contains matching attributes are used. The same special strings are replaced as in C. C<$_[0]> contains the Embperl request object. The method C can be used to get or set the perl code that should be generated by this node. If the code begins with #!- all newlines are removed in the code. This is basically useful to keep all code on the same line, so the line number in error reporting matches the line in the source. =item compiletimeperlcodeend => Code that is executed at compile time, but at the end of the tag. The same special strings are replaced as in C. C<$_[0]> contains the Embperl request object. The method C can be used to get or set the perl code that should be generated by this node. If the code begins with #!- all newlines are removed in the code. This is basically useful to keep all code on the same line, so the linenumber in error reporting matches the line in the source. =item perlcoderemove => 0/1 Remove perlcode if perlcodeend condition is not met. =item removenode => Remove node after compiling. could be one of the following, values could be added: =over 4 =item 1 Remove this node only =item 2 Remove next node if it consists of only white spaces and optKeepSpaces isn't set. =item 3 Replace next node with one space if next node consists only of white spaces and optKeepSpaces isn't set. =item 4 Set this node to ignore for output. =item 5 Remove all child nodes =item 6 Set all child nodes to ignore for output. =item 7 Calculate Attributes values of this node also for nodes that are set to ignore for output (makes only sense if 8 is also set). =back =item removespaces => Remove spaces before or after tag. =over 4 =item 1 Remove all white spaces before tag =item 2 Remove all white spaces after tag =item 3 Remove spaces and tabs before tag =item 4 Remove spaces and tabs after tag =item 5 Remove all spaces and tabs but one before tag =item 6 Remove all whihe space after text inside of tag =item 7 Remove spaces and tabs after text inside of tag =back =item mayjump => 0/1 If set, tells the compiler that this code may jump to another program location. (e.g. if, while, goto etc.). Could also be a condition as described under perlcode. =item compilechilds => 0/1 Compile child nodes. Default: 1 =item stackname => Name of stack for C, C =item stackname2 => Name of stack for C =item push => Push value on stack which name is given with C. Value could include the same specical values as C =item push2 => Push value on stack which name is given with C. Value could include the same specical values as C =item stackmatch => Check if value on stack which name is given with C is the same as the given value. If not give a error message about tag mismatch. Value could include the same specical values as C =item switchcodetype => <1/2> 1 means put the following code into normal code which is executed everytime the page is requested 2 means put the following code put into code which is executed direct after compilation. This is mainly for defining subs, or using modules etc. =item addflags =item cdatatype =item forcetype =item insidemustexist =item matchall =item exitinside =item addfirstchild =item starttag =item endtag =item parsetimeperlcode =item contains =back