/ 
HTML-Expander-2.1
River stage zero No dependents
/ HTML::Expander

NAME

HTML::Expander - html tag expander with inheritable tag definitions (styles)

SYNOPSIS

 use HTML::Expander;

 # get new HTML::Expander object;
 my $ex = new HTML::Expander;
 
 # load style (tags) definitions
 $ex->style_load( "/path/to/style.def.txt" );

 # define some more tags
 $ex->define_tag( 'main', '<name>',  '<h1><font color=%c>' );
 $ex->define_tag( 'main', '</name>', '</font></h1>' );
 
 # copy `main' into `new' style
 $ex->style_copy( 'new', 'main' );
 
 # define one more tag
 $ex->define_tag( 'new', '<h1>',  '<p><h1>' );
 $ex->define_tag( 'new', '<box>',  '<pre>' );
 $ex->define_tag( 'new', '</box>',  '</pre>' );
 
 # expand!
 print $ex->expand( "<style name=new>
                       (current style is '<var name=!STYLE>') 
                       <name c=#fff>This is me</name>
                     </style>
                       (cyrrent style is '<var name=!STYLE>') 
                       <name>empty</name>
                     1.<var name=TEST>
                     2.<var name=TEST set=opala! echo>
                     3.<var name=TEST>
                     \n" );
 # the result will be:
 #                     <pre>(current style is 'new')</pre>
 #                     <p><h1><font color=#fff>This is me</font></h1>
 #                   
 #                     <box>(cyrrent style is 'main')</box>
 #                     <h1><font color=>empty</font></h1>
 #                   1.
 #                   2.opala!
 #                   3.opala!
 
 # this should print current date
 print $ex->expand( '<exec cmd=date>' ), "\n";
 
 # add include paths
 $ex->{ 'INC' }{ '.' } = 1;
 $ex->{ 'INC' }{ '/usr/html/inc' } = 1;
 $ex->{ 'INC' }{ '/opt/test' } = 1;
 
 # remove path
 delete $ex->{ 'INC' }{ '/usr/html/inc' };
 
 # include some file (avoiding recursion if required)
 print $ex->expand( '<inc file=test.pl>' ), "\n";

DESCRIPTION

HTML::Expander replaces html tags with other text (more tags, so it 'expands':)) with optional arguments. HTML::Expander uses tag tables which are called styles. Styles can inherit other styles (several ones if needed). The goal is to have as simple input html document as you need and have multiple different outputs. For example you may want <box> tag to render either as <pre> or as <table><tr><td> in two separated styles.

Essentially HTML::Expander works as preprocessor.

The style file syntax is:

 tag   tag-replacement-string

 STYLE: style-name: inherited-styles-list

 tag   tag-replacement-string

 etc...

inherited-styles-list is comma or semicolon-separated list of styles that should be copied (inherited) in this style

The style file example:

 ### begin style

 # top-level style is called `main' and is silently defined by default
 # style: main

 <head1>   <h1>
 </head1>  </h1>

 <head2>   <h1><font color=#ff0000>
 </head2>  </h1></font>

 STYLE: page: main

 <head2>   <h1><font color=#00ff00>

 STYLE: edit: page, main
 
 # actually `page' inherits `main' so it is not really
 # required here to list `main'

 <head2>   <h1><font color=#0000ff><u>

This is not exhaustive example but it is just for example...

TAG ARGUMENTS

Inside the tag you can define arguments that can be used later during the interpolation or as argument to the special tags etc.

Arguments cannot contain whitespace unless enclosed in " or ':

<mytag arg=value>              # correct
<mytag arg=this is long value> # incorrect!
<mytag arg='the second try'>   # correct
<mytag arg="cade's third try"> # correct

There is no way to mix " and ':

<mytag arg='cade\'s third try'> # incorrect! there is no escape syntax

You can have unary arguments (without value) which, if used, have '1' value.

<mytag echo> is the same as <mytag echo=1>

SPECIAL TAGS

There are several tags with special purposes:

<style name=name>

Sets current style to `name' (saves it on the top of the style stack).

</style>

Removes last used style from the stack (if stack is empty `main' is used). Both <style> and </style> are replaced with empty strings.

<exec cmd=command>

This tag is replaced with `command's output.

<include file=incfile>
or
<inc file=incfile>

This tag is replaced with `incfile' file's content (which will be HTML::Expanded recursively).

VARIABLES/ENVIRONMENT

There is syntax for variables interpolation. Values are taken either from internal environment table or program environment (internal has priority):

(%VARNAME)

All variables are replaced before tag expansion! This helps to handle this:

<tag argument=(%VAR) etc.>

If you need to interpolate variable in the tag expansion process (after the variables interpolation) you need to:

<var name=VARNAME>

If you need to set variable name during tag interpolation you should:

<var name=VARNAME set=VALUE>

If you want to set variable and return its value at the same time you have to use unary 'echo' argument:

<var name=VARNAME set=VALUE echo>

BUGS

Unknown tags are left as-is, this is not bug but if you write non-html tag which is not defined in style tables it will passed into the output text. (see <box> example above for 'main' style)

If you find bug please contact me, thank you.

TODO

<empty>

AUTHOR

 Vladi Belperchinov-Shabanski "Cade"

 <cade@biscom.net> <cade@datamax.bg> <cade@cpan.org>

 http://cade.datamax.bg
 http://play.evrocom.net/cade

VERSION

 $Id: Expander.pm,v 1.12 2004/09/18 00:02:13 cade Exp $