NAME

DeltaX::Page - Perl module for parsing pages for masser

     _____
    /     \ _____    ______ ______ ___________
   /  \ /  \\__  \  /  ___//  ___// __ \_  __ \
  /    Y    \/ __ \_\___ \ \___ \\  ___/|  | \/
  \____|__  (____  /____  >____  >\___  >__|
          \/     \/     \/     \/     \/        project

SYNOPSIS

 use DeltaX::Page;

 my $page = new DeltaX::Page('myfile.pg');
 if (!$page->compile()) {
  # write some error
 }
 else {
  my $code = $page->{translated};
 }

FUNCTIONS

new()

Constructor. It has one required parameter - name of file to parse. This name can be prefixed with string: so module it uses as code itself, without reading the file.

Other parameters are in "directive => sub reference" form (see "DIRECTIVES").

You can define values for conditional output as an array reference to _defs argument to new() this way:

 my $page = new DeltaX::Page('somepage.pg', dir1=>\&dir,
  _defs=>['defined1', 'defined2']);

compile()

Tries to compile given file to perl code (which can be evaled). See "FILE SYNTAX" for more information. Returns true in case of success, otherwise returns false.

get_error()

Returns textual representation of error (only valid after compile() call).

FILE SYNTAX

This module is parsing page code for masser (see masser.sourceforge.net) - it's something like perl code embeded in HTML (or XML or other) code. It compiles everything to print statements, except this:

  • everything between <?!- and -!?> is a comment and is ignored

  • everything between <? and ?> is a perl code and is included unchanged

  • <?=token?> is translated to print token; (remember this semicolon!)

  • <?:directive?> is used for conditional and looped output; you can use following:

    if

    for example <?:if defined1?>

    else

    for example:

     <?:if defined1?>
      some output
     <?:else?>
      some other output
     <?:end?>
    end

    end of block for if/else

    for..done

    for example:

     <?:for ...perl foreach syntax...?>
     ...
     <?:done?>
    
     <?:for my $item (@list)?>
     ...
     <?:done?>

    Condition instructions can be embedded.

  • <?!directive [arguments]?> is processed externally (see "DIRECTIVES")

Example:

 Source code:
  <?- this is a test -?>
  <h1>Hi, welcome to <?=$app_name?>!</h1>
  
  It's 
  <?
    my (undef, undef, undef, $day, $mon, $yer) = localtime();
    $mon++; $yer+=1900;
    print sprintf("%02d.%02d.%04d", $day, $mon, $yer);
  ?>
  <br/>
  See you later...
  
 Compiled code:
  print "<h1>Hi, welcome to ";
  print $app_name;
  print "!</h1>";
  print "\n\n";
  print "It's\n";
    my (undef, undef, undef, $day, $mon, $yer) = localtime();
    $mon++; $yer+=1900;
    print sprintf("%02d.%02d.%04d", $day, $mon, $yer);
  print "\n<br/>\nSee you later\n";

  [code was made a little bit readable :-)]

DIRECTIVES

Everything in <?!directive [arguments]?> is a special directive. Module knows these directives:

include

<?!include file?> - includes given file, this means tries to read and compile this file and (in case of success) includes resulting code into actual code.

package

<?!package file?> - works as include

everything other

Every other directive must be defined in new() function and apropriate function will be called (arguments will be given to this function - if there are any). Everything which is returned by this function is included in the code (function must return true value - at least one space, if it returns false, it is detected as an error).

You can define directive in new() for include and package too, but this doesn't change include or package itself, but module expects that called function returns real full path to file to be included. Other returned values are got as additional defines for conditional instructions (see _defs in new()) - but only for included file.

There is special directive definition *, which means 'everything other', so if undefined directive is found, function assigned to it will be called.

Example:

 sub my_include {
  my $filename = shift;
  # only relative path
  return substr($filename, rindex($filename,'/')+1);
 }

 sub my_javascript {
  my $javascript_name = shift;
  # code to give someone know that JavaScript code must be generated...
  return "$cgi->add_javascript('$javascript_name');";
 }

 sub my_other {
        my ($directive, @args) = @_;
        # return code according to $directory
 }
 
 my $page = new DeltaX::Page('test.pg',include=>\&my_include,
  javascript=>\&my_javascript, '*'=>\&my_other);