HTML :: Phl module for processing HTML documents containing Perl code instructions

The article provides the HTML :: Phl module specification for working with HTML documents containing Perl programming language code.



The task of the HTML :: Phl module is to select a perl-code from a HTML-formatted text document, perform some manipulations on it and the rest of the code, combine the resulting perl code and “feed” all this ' eval ', resulting in a generated HTML page that is rendered by a web browser.

')



The article is written for informational purposes, the development of the module is conceptual in nature, and its reliable use requires additional testing.

---

Table of contents:

PHL Specification

• Pointers

• Separators

• Keys

• Functions

• Expansion modules

• Configuration Settings

Distribution PHL

PHL specification ^

In an HTML document, the perl code is placed using peculiar instructions. Each such instruction has a beginning and an end to identify the perl code in the document.

The PHL specification defines three options for writing instructions:



1. Linear instruction:



% pl [keys] [perl code]



2. Instruction in the form of a single-line block:



<% pl [(: | =) [name]] [keys] [perl code] %>



3. Multi-line block:



<% pl [(: | =) [name]] [keys]

[perl code]

%>



Where



' % pl ', ' <% pl ', ' %> ' - instruction pointers (define the beginning and end of Perl code);



[name] is the name of the block (used when identifying blocks, mainly in parallel programming);



' : ' or ' = ' - separators (on the one hand, they are separators between instruction pointers and the block name, on the other hand, they have a number of additional functional features);



[keys] - control keys (allow you to modify the Perl code enclosed in the instruction before passing it to the interpreter for execution);



[perl code] - Perl code.





The controls [name] and [keys] are not used as often, and you can successfully do without them, but their use is very convenient.

  <%pl:f1 -fork #    my $f = "   f1"; sleep 1; return $f; %> <%pl -join=f1 #    f1 print $phl_join{f1}; %> 

To the standard Perl functions in PHL there is additionally added the function ' include () '), implemented for the possibility of building a document from several files.

  %pl include($file_name); <%pl include("$file_name", "socket"); %> <%pl my $result = include("$file_name", "open decode"); %> 

Pointers ^

By default, pointers look like: ' <% pl ', ' %> ' and ' % pl '.



Pointers can be overridden in the settings of the ' Phl.pm ' file or in the configuration file ' config.phl '. As a result, you can write <% ... code perl ...%> or [... code perl ...] or even so ¦ ... code perl ... ¦ .



If you wish, you can define your own (optional) instruction pointers. This is implemented using specially designed modules.



For example, using the module ' HTML :: Phl :: Php ', in addition to the instruction pointer ' <% pl ', the pointer ' <% php ' is added, allowing you to execute simple PHP programming language code.

  1 %pl -ev use HTML::Phl::Php; 2 3 <%php 4 echo "PHP >> <b>OK</b><br>"; 5 echo date('H:i:s dmY'); 6 %> 

Separators ^

The delimiter task is to separate the instruction pointer from the block name.



Unlike the separator ' : ', the separator ' = ' changes the interpretation of the code in the analyzer. At the same time, the result of using the delimiter ' = ' in single-line and multi-line blocks differ.

  1 %pl my $test = "<b></b>"; 2 3 1.  '<%pl= $test %>'   . 4 <br><br> 5 6 <%pl=name1 7 2.  '$test'  8   '<b>$phl_blok[1]</b>' ( '='). 9 %> 10 <br><br> 11 12 <%pl:name2 13 print "3.  '$test'"; 14 print "   '<b>$phl_blok[2]</b>' ( ':')."; 15 %> 

Keys ^

The keys allow you to modify the perl code placed in the instructions. They can be specified in full or in abbreviated form:



-begin

-end

-perl_all

-eval

-fork

-thread

-join

• The keys ' -begin ' [' -bg '] and ' -end '

When using the ' -begin ' key, the analyzer takes the perl code contained in the instruction and wraps it in a ' BEGIN {} ' block.



The same thing happens when using the ' -end ' key - the perl code is placed in the ' END {} ' block.



Source:

  1 1.  HTML<br> 2 <%pl -end 3 print "2.  end<br>"; 4 %> 5 3.  HTML<br> 6 7 <%pl -begin 8 print "4.  begin<br>"; 9 %> 10 5.  HTML<br> 11 12 <%pl -end 13 print "6.  end<br>"; 14 %> 15 7.  HTML<br> 16 17 <%pl -bg 18 print "8.  begin<br>"; 19 %> 20 9.  HTML<br> 

• Key ' -perl_all ' [' -pl ']

When using this key, there is no need to limit the perl code to instruction directives. The analyzer will interpret the entire text of the document as Perl code.

  1 %pl -pl 2 3 use CGI; 4 5 print "Content-type: text/html; charset=utf-8\n\n"; 6 7 my $test = ""; 8 my $q = new CGI; 9 10 print $q -> h4("$test   CGI"); 11 print ("<H4>$test  Phl</H4>"); 

• Key ' -eval ' [' -ev ']

The key allows you to execute code enclosed within an instruction, during the operation of the analyzer (before its execution by eval ).



For example, we will try using this key to change the pointers ' <% pl ', etc., by placing the following instruction in the code:

  1 <%pl -eval 2 $phl{lt} = '['; 3 $phl{rt} = ']'; 4 $phl{ln} = '~'; 5 $phl{sh} = ''; 6 %> 

The instruction pointers have taken on a completely different look. Now the instruction can be written like this:

  1 [= 2   3 ] 

or so

  1 [ print " " ] 

or so

  1 ~ print " " 

• Key ' -fork ' [' -fk ']

Code enclosed within an instruction is executed in a parallel child process created as a result of fork () running.

  1 <%pl:f1 -fork 2 #      f1 3 my $f; 4 sleep 1; #     f1 5 return $f; 6 %> 

• Key ' -thread ' [' -td ']

The code enclosed within the instruction is executed in a parallel thread (“thread”, “thread” of the process) created by the standard ' threads ' module within one process.

  1 <%pl:t1 -thread 2 #     t1 3 my $t; 4 sleep 1; #     t1 5 return $t; 6 %> 

• Key ' -join ' [' -jn ']

The key allows you to get the results of the execution of child processes and threads.



The results are placed in the % phl_join hash, the keys of which are the names of the created processes / threads. If, when applying for the result, the necessary parallel processes have not yet completed, the program waits for them to complete.

  1 <%pl -join 2 #        3 foreach my $key(keys(%phl_join)) { 4 if (ref $phl_join{$key}) { #   -  5 my @result = @{$phl_join{$key}}; 6 print " '$key' -    '$result[0]'"; 7 } else { 8 print " '$key' -  '$phl_join{$key}'"; 9 } 10 } 11 %> 

• Additional keys

If you wish, you can define your own (additional) keys or override existing ones. This is implemented using specially designed modules.



So, for example, using the module ' HTML :: Phl :: Utilit ' and the key ' -import ' [' -im '] you can view a list of all the pointers, keys and parameters currently available to the program.

  1 %pl -ev use HTML::Phl::Utilit; 2 3 %pl -import 

Functions ^

Only one ' include () ' function has been added to the PHL, implemented to be able to assemble a document from several files containing HTML (TXT) or PHL markup.



The function ' include () ' is similar to the standard Perl function ' open () ', with the difference that the first argument is the name of the file to be included in the document, and the second is one or more special control parameters.

  1 %pl include($file_name); 2 3 <%pl include("$file_name", "socket"); %> 4 5 <%pl 6 my $result = include($file_name, "open decode"); 7 %> 

In general, writing the function ' include () ' looks like this:



include (" file_name " [, " param " [, " name_process "]]) ;



file_name :

"File_name.phl"

"File_name.cgi"

"File_path / file_name.phl"

"/file_path/file_name.html"

"Https: //domain/file_path/file_name.html"



[param] :

phl , exist , head

abs , no_abs , no_eval

no_strict , open , decode

no_decode , cgi , socket

fork , thread



additional parameters and dependencies:

phl [.phl] <= exist, head, abs, decode

cgi [.cgi] <= require, decode

open <= decode, abs

socket <= exist, head, no_abs, decode, no_decode

fork <= waitpid, no_waitpid

thread <= join, detach



The first argument to ' file_name ' may contain the reserved words " JOIN ", " CONFIG " or " TIMER " in addition to the file name.



If the file ' file_name ' has the extension ' .phl ', then this file is identified as a PHL file. The extension can be changed in the settings using $ phl {pl} .



When the ' include () ' function is called in an undefined context, the result of the Perl code execution is placed in the body of the document inside the print () function. For scalar or list context, the result is returned as the requested value of a variable or list of values, respectively.

  1 <%pl 2 include("file_name.phl"); 3 my $result = include("file_name.phl"); 4 my @result = include("file_name.phl"); 5 %> 

The second argument of the function ' include () ' may contain one or more special control parameters.

• ' phl ' parameter

This parameter indicates to the processor that the code contained in the include file is a PHL format document.



The file data is sent to the analyzer, where it is converted into perl-code and transferred to ' eval '.



The ' phl ' parameter performs similar actions if we simply indicated the extension ' .phl ' in the name of the included file (the extension can be changed in the settings in ' $ phl {pl} ').

  1 <%pl 2 include("file_name.txt", "phl"); 3 my $result = include("file_name.html", "phl decode=utf-8"); 4 my @result = include("file_name", "phl abs"); 5 %> 

• The parameter ' exist ' (' ex ')

Allows you to check the existence of the file.

  1 <%pl 2 my $exist_file = include("$file_name", "exist"); 3 if ($exist_file) { 4 print " $file_name "; 5 } else { 6 print " $file_name  "; 7 } 8 %> 

• ' head ' parameter (' hd ')

Returns a list of 5 elements: Content type, Document length, Modified time, Expires, Server.

  1 <%pl 2 my @head = include("$file_name", "head"); 3 %> 

• Parameter ' abs '

If the parameter ' abs ' is present, the relative references specified in the file are converted to absolute ones.

  %pl include("$file_name", "abs"); 

• Parameter ' no_eval ' (' ne ')

When specifying this parameter, the result of the execution of the included file code is ignored.

  <%pl include("$file_name", "no_eval") %> 

• Parameter ' no_strict ' (' ns ')

If the ' no_strict ' parameter is specified, the action of the ' use strict ' pragma is not applied to the code of the loaded file ' $ file_name '.

  1 <%pl 2 include("$file_name", "ns"); 3 %> 

• Parameter ' open ' (' on ')

Like the ' open () ' function, it is used to open a file and extract any data from it (there is no possibility to write data to a file).

  1 <%pl 2 include("$file_name", "open"); 3 my $result = include("$file_name", "open decode=koi8-r"); 4 my @result = include("$file_name", "on, decode=cp1251, abs"); 5 %> 

• ' decode ' (' dc ') parameter

If the ' decode ' parameter is present , the data from the encoding specified in the parameters (for example, ' decode = cp1251 ') is decoded into the internal Perl format.



If the encoding is not specified or the ' decode ' parameter is missing , then during decoding it is assumed that the encoding of the included file corresponds to the $ phl {encoding_in} specified in the phl.pm settings (or config.phl ).



If the encoding of the resulting document is different from ' utf-8 ', then the data is encoded into the $ phl {encoding_out} encoding specified in the phl.pm settings (or config.phl ).

Encoding and decoding data is carried out using the standard module ' Encode.pm '.

• ' cgi ' parameter

This parameter is intended for connecting cgi-scripts written in Perl.

  1 <%pl 2 include("file_name.cgi"); 3 include("$file_name", "cgi"); 4 include("$file_name", "cgi require"); 5 include("file_name.cgi", "decode=cp866"); 6 %> 

• ' socket ' (' sk ') parameter

Used to load a web document using the standard module ' IO :: Socket :: INET '

  1 <%pl 2 include("file_name.html", "socket"); 3 include("http://domain/"); 4 my $text = include("http://domain/file_path/file_name.html", "decode=cp1251"); 5 my @result = include("$file_name", "decode no_abs"); 6 %> 

If the address of the file included in the document starts with http or ftp, then the ' socket ' parameter is optional.



Additional parameters ' exist ', ' head ', ' no_abs ', ' decode ', ' no_decode ' may be used in conjunction with the ' socket ' parameter.

• optional parameter ' exist ' (' ex ')

Allows you to check the existence of a domain, file, address.

  1 <%pl 2 my @include_name_file = ( 3 'dir1/name_file.html', 4 '/dir2/name_file.php', 5 'http://www.yandex.ru', 6 'http://www.yandex/eklmnfjoeqxngsitwf.html', 7 'http://eklmnfjoeqxngsitwfhoevd.ru' 8 ); 9 10 foreach my $name_file (@include_name_file) { 11 my $ex = include("$name_file", "socket exist"); 12 if ($ex) { 13 print " '$name_file' <br>"; 14 } elsif (!defined $ex) { 15 print " '$name_file'  <br>"; 16 } else { 17 print " '$name_file'  <br>"; 18 } 19 } 20 %> 

• additional parameter ' head ' (' hd ')

Returns the title of the document.

  1 <%pl 2 foreach my $name_file (@test_name_file) { 3 my head = include("$name_file", "socket head"); 4 if ($#head) { 5 print "  '$name_file'  => '@head[0..3]'<br>"; 6 } else { 7 print "  '$name_file'  => '@head'<br>"; 8 } 9 } 10 %> 

• additional parameter ' no_abs ' (' na ')

By default, all relative links are replaced with absolute ones, but if the ' no_abs ' parameter is specified, this does not happen.

  %pl include("$file_name", "socket no_abs"); 

• additional parameter ' decode ' (' dc ')

It is used to decode documents from the encoding specified by the ' decode ' parameter into the internal Perl format and further into the encoding specified in the settings in $ phl {encoding_out} .



If the ' decode ' parameter is used without specifying the source encoding of the requested file, then decoding is performed taking into account the encoding specified in the file header in ' charset ' (if any).



If the ' decode ' parameter is not used, it is assumed by default that our file is utf-8 encoded.



Using the ' no_decode ' parameter (' nd '), no decoding of the data occurs.

  1 <%pl 2 include("http://www.rbc.ru", "decode=utf-8"); 3 include("http://www.mail.ru", "decode"); 4 my $html_text1 = include("http://ru.motorsport.com"); 5 my $html_text2 = include("http://www.google.com", "nd"); 6 %> 

• ' fork ' (' fk ') parameter

The code of the file being loaded is executed in a parallel child process created as a result of the launch of ' fork () '.

  1 <%pl 2 include("$file_name", "fork"); 3 %> 

The result of executing a parallel process can be returned to the parent using the ' return ' in the text of the include file instruction.

  1 <%pl 2 <font color=#646464><I>#    $phl_var{name}</I></font> 3 my $f = " "; 4 sleep 1; 5 return $f; 6 %> 

In the third argument of the function ' include () ' you can specify the unique name of the child process, in order to then look for the result of the execution of the child process “by name”.

  1 <%pl 2 include("$file_name", "fork", "f1"); 3 %> 

• additional parameter ' waitpid ' (' wd ')

In order to return the result of the child process execution to the point of calling the ' include () ' function, it is necessary to specify the ' waitpid ' parameter in addition to the ' fork ' parameter or to specify ' waitpid ' as the third argument to the ' include () ' function.



The result of working out a parallel process can be returned back to the parent process by calling ' include () ' in scalar or list context.

  1 <%pl 2 $result = include("$file_name", "fork waitpid"); 3 @result = include("$file_name", "fork", "waitpid"); 4 %> 

In fact, you can refuse from the ' waitpid ' parameter altogether, both in the second and in the third argument. In this case, the program will still wait for the completion of the child process, and the function ' include () ' will be less cumbersome.

  1 <%pl 2 @result = include("$file_name", "fork", ""); 3 $result = include("$file_name", "fk"); 4 %> 

• additional parameter ' no_waitpid ' (' nw ')

The result of the process can not be returned, unless, try to write something to a file or display it.

  1 <%pl 2 include("$file_name", "fork no_waitpid"); 3 include("$file_name", "fork", "no_waitpid"); 4 %> 

• argument ' JOIN '

To access the result of executing the child process, you can use the function ' include () ', where the first argument is the reserved word ' JOIN ', the second argument is the name or names of the child processes.

  1 <%pl 2 include("$file_name", "fork", "f1"); 3 4 #         5 6 my $rezult = include("JOIN", "f1"); 7 %> 

You can return the results of several or even all parallel processes by referring to the hash, the keys of which are the names of the processes, the values ​​- the results of their execution.

  1 <%pl 2 my %join_2_3 = include("JOIN", "f2 f3"); 3 print "  'f2' = $join_2_3{f2}<br>"; 4 5 my %join_all = include("JOIN"); 6 foreach my $key(keys(%join_all)) { 7 if (ref $join_all{$key}) { 8 my @result = @{$join_all{$key}}; 9 print "  '$key' = '$join_all{$key}' => "; 10 print "     = '$result[0]'<br>"; 11 } else { 12 print "  '$key' = '$join_all{$key}'<br>"; 13 } 14 } 15 %> 

• ' thread ' (' td ') parameter

A so-called “thread” (“thread”) is created - a peculiar branch of the process in which code execution is possible parallel to the code of the process that generated the thread.



To create a thread, the standard ' thread ' module is used (in turn, Perl must be configured to work with threads).

  1 <%pl 2 include("$file_name", "thread"); 3 %> 

As in the case of the fork parameter, when using threads, it is possible to return the result of the created thread, both to the call point of the include () function, and to an arbitrary point of the program, or to “forget” about the result without returning anything.

• additional parameter ' join ' (' jn ')

The result of executing the thread returns to the call point, while the parent process temporarily stops its execution and waits for data (from the created threads).

  1 <%pl 2 $result = include("$file_name", "thread join"); 3 @result = include("$file_name", "thread", "join"); 4 %result = include("$file_name", "thread"); 5 %> 

• additional parameter ' detach ' (' dh ')

The thread is created, but the main thread of the process does not know in it.

  1 <%pl 2 include("$file_name", "thread detach"); 3 include("$file_name", "thread", "detach"); 4 %> 

You can return data to any point of the main branch of the process by assigning a thread a name (by analogy with the child process created by the ' fork ' parameter).

  1 <%pl 2 include("$file_name", "thread", "t1"); 3 include("$file_name", "thread", "t2"); 4 include("$file_name", "thread", "t3"); 5 6 my $rezult = include("JOIN", "t2"); 7 print "  't2' = '$rezult'<br>"; 8 9 my %join = include("JOIN", "t1 t3"); 10 print "  't1' = '$join{t1}'<br>"; 11 print "  't3' = '$join{t3}'<br>"; 12 %> 

• Own parameters

If you wish, you can define your own (optional) parameters or override existing ones. This is implemented using specially designed modules.



So, for example, using the ' HTML :: Phl :: Utilit ' module and the ' analys ' (' as ') parameter, you can view the perl code generated by the analyzer of the included file before its execution by eval .



Example:

  1 %pl -ev use HTML::Phl::Utilit; 2 3 <%pl 4 include("$file_name", "as"); 5 %> 

PHL Expansion Modules

To achieve greater flexibility in working in PHL, the ability to set your own instruction pointers [sh] , keys [keys] , first argument [include] and parameters [param] of the function ' include () ' is implemented.



<% [sh] [keys]

...

include (" [include] ", " [param] ") ;

...

%>



New keys, parameters and pointers are imported into phl.pm from specially written modules for this purpose.



For example, 4 modules are included in the PHL:

  use HTML::Phl::Utilit; use HTML::Phl::Psimple; use HTML::Phl::Php; use HTML::Phl::Ru; 

Modules can be connected both in the file ' phl.pm ' or ' config.phl ', and in the PHL file.

  1 %pl -ev use HTML::Phl::Utilit 2 3 <%pl 4 #  perl 5 %> 

• Module ' HTML :: Phl :: Utilit '

The module exports to the program 5 keys, 2 parameters and 2 arguments for the function ' include () '.



[keys] :

-listing

-analys

-config

-timer

-no_timer



[param] :

listing

analys



[include] :

CONFIG

TIMER The



keys ' -listing '[' -lt '] and' -analys ' [' -as '] and the parameters ' listing ' (' lt ') and' analys ' (' as ') give the opportunity to see the program listing or the perl code generated by the analyzer before its execution by eval .



Key ' -listing ' ['-lt ']

  1  HTML 1 2 <br><br> 3 4 <%pl -lt 5 my $test = " Perl<br>"; 6 print "$test"; 7 %> 8 <br> 9 10  HTML 2 

Key ' -analys ' [' -as ']

  1 %pl -as 2 3 <%pl 4 my $test = " Perl<br>"; 5 print ("$test"); 6 %> 7 8  HTML  <%pl= $test %> 

The key ' -config ' [' -cf '] or the argument ' CONFIG ' of the function ' include () ' prints the hash of % phl configuration variables.

  1 %pl -config 2 3   4 5 <%pl 6 include("CONFIG"); 7 %> 

The keys ' -timer ' [' -tm '] and ' -no_timer ' [' -nt '] allow you to change the mechanism for displaying time intervals for the program components, and using the ' TIMER ' argument of the ' include () ' function you can set your own timer .

  1 <%pl 2 #    3 %pl -timer 4 5 #    6 %pl -nt 7 %> 

  1 <%pl 2 #     3 include("TIMER", " "); 4 %> 

• Module ' HTML :: Phl :: Php '

Exports the ' php ' pointer, turning the instruction pointer ' <% pl ' into ' <% php ', to be able to work with the programming language code PHP;

  1 %pl -ev use HTML::Phl::Php; 2 3 %pl our $pl = 5; 4 5   PERL: $pl = <b>'<%pl= $pl %>'</b>. 6 <br><br> 7 8 <%php 9 echo "  $pl   PHP ($pl -> $php).<br>"; 10 OUT_PERL($pl -> $php); 11 12 echo "<li> $php = $php.</li><br>"; 13 14 echo " PHP   : $php = 2 * $php + 1.5.<br><br>"; 15 $php = 2 * $php + 1.5; 16 17 echo "   $php  PERL ($php -> $pl).<br>"; 18 IN_PERL($php -> $pl); 19 %> 20 21 <li>  PERL: $pl = <b>'<%pl= $pl %>'</b></li>. 

• Module ' HTML :: Phl :: Ru '

Exports the ' rus ' pointer, turning the instruction pointer ' <% pl ' into ' <% rus ', allowing you to work with some functions and operators of Cyrillic writing.

  1 %pl -ev use HTML::Phl::Ru; 2 3 <% 4 my @_ = ( 5 'file_exist.phl', 6 'http://www.pushkinmuseum.ru', 7 'http://www.pushkinmuseum.ru/467899', 8 'http://eklmn12344556778.ru' 9 ); 10 11 foreach my $_ (@_) { 12 my $ = ("$_", "socket exist"); 13  ($) { 14  "'$_' - <B></B><br>"; 15 }   (!defined $) { 16  "'$_' - <B> </B><br>"; 17 }  { 18  ("'$_' - <B> </B><br>"); 19 } 20 } 21 %> 

• Module ' HTML :: Phl :: Psimple '

Exports the parameter ' Simple ' [' sl '] to work with the standard Perl module ' LWP :: Simple ';

Expansion Module Structure

, ( — 'Phl', ' phl.pm ') ' %phl_import ', , .



' %phl_import ' 5 — ' sh ', ' key ', ' param ', ' include ' ' eval '.

  1 our %phl_import = ( 2 key => { 3 tm => \&HTML::Phl::Utilit::key_timer, 4 im => \&HTML::Phl::Utilit::print_import, 5 }, 6 include => { 7 TIMER => \&HTML::Phl::Utilit::my_timer, 8 CONFIG => \&HTML::Phl::Utilit::config, 9 }, 10 param => {lt => \&HTML::Phl::Utilit::open_listing}, 11 sh => {'' => \&HTML::Phl::Ru::ru_perl}, 12 eval => {as => \&HTML::Phl::Utilit::eval_code} 13 ); 

^

' config.phl ' , ' phl.pm '. web-, PHL .



Perl %phl .

---

PHL ^

'HTML::Phl' -, .



Android, SL4A , perl-, -, HTML Perl. - Perl Android PHL .