The third beta of Embperl 2.0 is now available from
ftp://ftp.dev.ecos.de/pub/perl/embperl/HTML-Embperl-2.0b3.tar.gz
This version mainly contains bugfixes. Since the first and second beta I
have fixed a lot of bugs and use it now in production environment on my own.
But be carefull this release may still contain bugs.Documentation is not yet
updated to reflect the changes in 2.0, everything that has changed is
documented in README.v2.
The current stable release is Embperl 1.3.3
Embperl is a system for building dynamic websites with Perl.
It gives you the power to embed Perl code in your HTML documents
and the ability to build your Web site out of small reusable objects in
an object-oriented style. You can also take advantage of all the
usual Perl modules, (including DBI for database access) use their
functionality and easily include their output in your web pages.
Embperl has several features which are especially useful for creating
HTML, including dynamic tables, form field processing, URL
escaping/unescaping, session handling, and more.
See http://perl.apache.org/embperl/ (english) or
http://www.ecos.de/embperl/ (german) for more information.
For all Embperl 1.x users here is a sumary of the difference of Embperl
2.0:
Hints for using Embperl 2.x
---------------------------
Embperl 2 has a totaly rewritten core. It contains nearly 7500 lines
new (mostly C-) code. Also I have done a lot of testing, there may
be still undiscovered bugs!
Please report any weired behaviour to the embperl mailing list, but
be sure to read this whole README to understand what can't work so far.
The Embperl core now works in a totaly different way. It is divided into
smaller steps:
1 reading the source
2 parseing
3 compiling
4 executing
5 outputing
Further version will allow to replace every single step of this pipeline
with custom modules. Also it will be possible to cascade multiple
processors. This allows for example to have Embperl and SSI in one file
and to parse the file only once, feeding it first to the SSI processor and
afterwards to the Embperl processor. Also the parser will be exchangeable
in future version to allow for example to use an XML parser and an
XSLT stylesheet processor.
These new execution scheme is also faster, because html tags and
metacommands
are parsed only once (Perl code was also (and is still) cached in 1.x)
My first benchmarks show 50%-100% faster execution under mod_perl for pages
longer then 20K (For short pages ( < 5K ouput) you won't see such a great
difference)
and without any external database access.
Another new feature is that the syntax of the Embperl parser is defined
within the module HTML::Embperl::Syntax and can be modified as nessecary.
Embperl comes with a set syntax definitons which can be extened modified by
the user. So far there are syntaxdefinitions for SSI, Text only, Perl only,
ASP and a Mail taglib. You can tell Embperl which syntax to use either in
the configuration via EMBPERL_SYNTAX, or with the syntax parameter of
Execute or you change the syntax dynamicly inside the page via the
[$syntax $] command. You also could specify more then one syntax at the
same
time e.g. [$syntax Embperl SSI $] to mix Embperl tags and SSI tags in the
same
page.
If you like to create your own syntax read
perldoc HTML::Embperl::Syntax
and look at the files under Embperl/Syntax/ for examples how to do it.
Also new is the possibility to cache (parts of) the output. See
for the new configuration directives below
Debugging
---------
Starting with 2.0b2 Embperl files can debugged via the interavtive debugger.
The debugger shows the Embperl page source along with the correct
linenumbers.
You can do anything you can do inside a normal Perl programm via the
debugger,
e.g. show variables, modify variables, single step, set breakpoints etc.
You can use the Perl interacive command line debugger via
perl -d embpexec.pl file.epl
or if you prefer a graphical debugger, try ddd
(http://www.gnu.org/software/ddd/)
it's a great tool, also for debugging any other perl script:
ddd --debugger 'perl -d embpexec.pl file.epl'
NOTE: embpexec.pl could be found in the Embperl source directory
If you want to debug your pages, while running under mod_perl, Apache::DB is
the
right thing. Apache::DB is available from CPAN.
The following difference to Embperl 1.x apply:
------------------------------------------------------
- The following options can currently only set from the httpd.conf:
optRawInput, optKeepSpaces
- The following options are currently not supported:
optDisableHtmlScan, optDisableTableScan,
optDisableInputScan, optDisableMetaScan
optDisableHtmlScan can be replaced by switching the syntax e.g.
[$syntax EmbperlBlocks $] # same as [- $optDisableHtmlScan = 1 -]
here goes your code, Embperl will not interpret any html tags here
[$syntax Embperl $] # same as [- $optDisableHtmlScan = 0 -]
- Nesting must be properly. I.e. you cannot put a <table> tag (for an
dynamic table) inside an if and the </table> inside another if.
(That still works for static tables)
- optUndefToEmptyValue is always set and cannot be disabled.
- [$ foreach $x (@x) $] requires now the brackets around the
array (like Perl)
- [+ +] blocks must now contain a valid Perl expression. Embperl 1.x
allows you to put multiple statements into such a block. For performance
reasons this is not possible anymore. Also the expression must _not_
terminated with a semikolon. To let old code work, just wrap it into a do
e.g. [.+ do { my $a = $b + 5 ; $a } +]
The following things are not fully tested/working yet:
------------------------------------------------------
- [- exit -]
- safe namespaces
- print to OUT does not work correctly inside of loops
Embperl 1.x compatibility flag
------------------------------
If you don't have a separate computer to make the test setup, you can
include
PerlSetEnv EMBPERL_EP1COMPAT 1
at the top level of your httpd.conf, then Embperl will behave just the same
like Embperl 1.3b7. In the directories where you make your tests, you
include a
PerlSetEnv EMBPERL_EP1COMPAT 0
to enable the new engine.
but _DON'T_ use this one a production machine. While this compatibility mode
is tested and shows no problems for me, it's not so hard tested as 1.3b7
itself!
Addtional Config directives
---------------------------
Caching parameter
-----------------
execute parameter / httpd.conf environment variable / name inside page (must
set inside [! !])
cache_key / EMBPERL_CACHE_KEY / $CACHE_KEY
literal string that is appended to the cache key
cache_key_options / EMBPERL_CACHE_KEY_OPTIONS / $CACHE_KEY_OPTIONS
ckoptCarryOver = 1, use result from CacheKeyFunc of preivious step
if any
ckoptPathInfo = 2, include the PathInfo into CacheKey
ckoptQueryInfo = 4, include the QueryInfo into CacheKey
ckoptDontCachePost = 8, don't cache POST requests (not yet implemented)
Default: all options set
expired_func / EMBPERL_EXPIRES_FUNC / &EXPIRES
function that should be called when build a cache key. The result is
appended to the cache key.
cache_key_func / EMBPERL_CACHE_KEY_FUNC / &CACHE_KEY
function that is called everytime before data is taken from the cache.
If this funtion returns true, the data from the cache isn't used anymore,
but rebuild.
Function could be either a coderef (when passed to Execute), a name of a
subroutine or a string starting with "sub " in which case it is compiled
as anoymous subroutine.
expires_in / EMBPERL_EXPIRES_IN / $EXPIRES
Time in seconds that the output schould be cached. (0 = never, -1 = forever)
Syntax switching
----------------
syntax / EMBPERL_SYNTAX / [$ syntax $]
Used to tell Embperl which syntax to use inside a page. Embperl comes with
the following syntaxes:
- EmbperlHTML # all the HTML tag that Embperl recognizes by
default
- EmbperlBlocks # all the [ ] blocks that Embperl supports
- Embperl # (default; contains EmbperlHtml and EmbperlBlocks)
- ASP # <% %> and <%= %>, see perldoc
HTML::Embperl::Syntax::ASP
- SSI # Server Side Includes, see perldoc
HTML::Embperl::Syntax::SSI
- Perl # File contains pure Perl (similar to
Apache::Registry), but
# can be used inside EmbperlObject
- Text # File contains only Text, no actions is taken on
the Text
- Mail # Defines the <mail:send> 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
You can get a description for each syntax if you type
perldoc HTML::Embperl::Syntax::xxx
where xxx is the name of the syntax.
You can also specify multiple syntaxes e.g.
PerlSetEnv EMBPERL_SYNTAX "Embperl SSI"
Execute ({inputfile => '*', syntax => 'Embperl ASP'}) ;
The syntax metacommand allows to switch the syntax or to
add or subtract syntaxes e.g.
[$ syntax + Mail $]
will add the Mail taglib so the <mail:send> tag is available after
this line.
[$ syntax - Mail $]
now the <mail:send> tag is unknown again
[$ syntax SSI $]
now you can only use SSI commands inside your page.
-------------------
Changes since 2.0b2:
- correct package handling in EP1COMPAT mode
- compiles now with sun-cc. Patches from Michael Stevens.
- fixed several bugs that caused weired behaviour with nested subs
and tables.
- fixed a bug that caused Embperl to stop when it sees a checkbox
inside a loop, for which no value is in %fdat.
- fixed a bug that caused Embperl alias a value in %fdat and %idat
- Execute work now also on the very first line of a file. Spotted
by Michael Smith.
- [- -] can now contain Perl comments. Spotted by Michael Stevens.
- [- -] can now start with =pod. Spotted by Jonny Cavell.
- fixed a parser error so <[+ $foo +]> generates the correct result.
Spotted by Michael Stevens.
- fixed bug in Node_insertAfter which may cause a single Execute
on the second line of a file to loop endless. Spotted by
Janny Cavell.
- Embperl doesn't search for attributes inside of quotes inside of
html tags anymore. Spotted by Ian Van der Poel.
- type=checkbox|radio is now case insensitiv as it should. Spotted
by Jonny Cavell.
- print OUT and Execute now works together. Spotted by Jonny Cavell.
- Embperl doesn't insert a linefeed after an Execute anymore.
- Embperl now keeps single or double quote the same as in the source
file. Requested by Jonny Cavell.
- [$hidden$] works now correctly inside of loops. Spotted by Jonny
Cavell.
- The parser now checks for the correct end of an html tag. Spotted
by Jonny Cavell.
- Added RTF syntax. This allows you for example to create serial letters
with your favorite word processing program, save them as RTF and
process
them with Embperl. See HTML::Embperl::Syntax::RTF for docs.
-------------------
Enjoy
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: announce-unsubscribe@perl.apache.org
For additional commands, e-mail: announce-help@perl.apache.org
ftp://ftp.dev.ecos.de/pub/perl/embperl/HTML-Embperl-2.0b3.tar.gz
This version mainly contains bugfixes. Since the first and second beta I
have fixed a lot of bugs and use it now in production environment on my own.
But be carefull this release may still contain bugs.Documentation is not yet
updated to reflect the changes in 2.0, everything that has changed is
documented in README.v2.
The current stable release is Embperl 1.3.3
Embperl is a system for building dynamic websites with Perl.
It gives you the power to embed Perl code in your HTML documents
and the ability to build your Web site out of small reusable objects in
an object-oriented style. You can also take advantage of all the
usual Perl modules, (including DBI for database access) use their
functionality and easily include their output in your web pages.
Embperl has several features which are especially useful for creating
HTML, including dynamic tables, form field processing, URL
escaping/unescaping, session handling, and more.
See http://perl.apache.org/embperl/ (english) or
http://www.ecos.de/embperl/ (german) for more information.
For all Embperl 1.x users here is a sumary of the difference of Embperl
2.0:
Hints for using Embperl 2.x
---------------------------
Embperl 2 has a totaly rewritten core. It contains nearly 7500 lines
new (mostly C-) code. Also I have done a lot of testing, there may
be still undiscovered bugs!
Please report any weired behaviour to the embperl mailing list, but
be sure to read this whole README to understand what can't work so far.
The Embperl core now works in a totaly different way. It is divided into
smaller steps:
1 reading the source
2 parseing
3 compiling
4 executing
5 outputing
Further version will allow to replace every single step of this pipeline
with custom modules. Also it will be possible to cascade multiple
processors. This allows for example to have Embperl and SSI in one file
and to parse the file only once, feeding it first to the SSI processor and
afterwards to the Embperl processor. Also the parser will be exchangeable
in future version to allow for example to use an XML parser and an
XSLT stylesheet processor.
These new execution scheme is also faster, because html tags and
metacommands
are parsed only once (Perl code was also (and is still) cached in 1.x)
My first benchmarks show 50%-100% faster execution under mod_perl for pages
longer then 20K (For short pages ( < 5K ouput) you won't see such a great
difference)
and without any external database access.
Another new feature is that the syntax of the Embperl parser is defined
within the module HTML::Embperl::Syntax and can be modified as nessecary.
Embperl comes with a set syntax definitons which can be extened modified by
the user. So far there are syntaxdefinitions for SSI, Text only, Perl only,
ASP and a Mail taglib. You can tell Embperl which syntax to use either in
the configuration via EMBPERL_SYNTAX, or with the syntax parameter of
Execute or you change the syntax dynamicly inside the page via the
[$syntax $] command. You also could specify more then one syntax at the
same
time e.g. [$syntax Embperl SSI $] to mix Embperl tags and SSI tags in the
same
page.
If you like to create your own syntax read
perldoc HTML::Embperl::Syntax
and look at the files under Embperl/Syntax/ for examples how to do it.
Also new is the possibility to cache (parts of) the output. See
for the new configuration directives below
Debugging
---------
Starting with 2.0b2 Embperl files can debugged via the interavtive debugger.
The debugger shows the Embperl page source along with the correct
linenumbers.
You can do anything you can do inside a normal Perl programm via the
debugger,
e.g. show variables, modify variables, single step, set breakpoints etc.
You can use the Perl interacive command line debugger via
perl -d embpexec.pl file.epl
or if you prefer a graphical debugger, try ddd
(http://www.gnu.org/software/ddd/)
it's a great tool, also for debugging any other perl script:
ddd --debugger 'perl -d embpexec.pl file.epl'
NOTE: embpexec.pl could be found in the Embperl source directory
If you want to debug your pages, while running under mod_perl, Apache::DB is
the
right thing. Apache::DB is available from CPAN.
The following difference to Embperl 1.x apply:
------------------------------------------------------
- The following options can currently only set from the httpd.conf:
optRawInput, optKeepSpaces
- The following options are currently not supported:
optDisableHtmlScan, optDisableTableScan,
optDisableInputScan, optDisableMetaScan
optDisableHtmlScan can be replaced by switching the syntax e.g.
[$syntax EmbperlBlocks $] # same as [- $optDisableHtmlScan = 1 -]
here goes your code, Embperl will not interpret any html tags here
[$syntax Embperl $] # same as [- $optDisableHtmlScan = 0 -]
- Nesting must be properly. I.e. you cannot put a <table> tag (for an
dynamic table) inside an if and the </table> inside another if.
(That still works for static tables)
- optUndefToEmptyValue is always set and cannot be disabled.
- [$ foreach $x (@x) $] requires now the brackets around the
array (like Perl)
- [+ +] blocks must now contain a valid Perl expression. Embperl 1.x
allows you to put multiple statements into such a block. For performance
reasons this is not possible anymore. Also the expression must _not_
terminated with a semikolon. To let old code work, just wrap it into a do
e.g. [.+ do { my $a = $b + 5 ; $a } +]
The following things are not fully tested/working yet:
------------------------------------------------------
- [- exit -]
- safe namespaces
- print to OUT does not work correctly inside of loops
Embperl 1.x compatibility flag
------------------------------
If you don't have a separate computer to make the test setup, you can
include
PerlSetEnv EMBPERL_EP1COMPAT 1
at the top level of your httpd.conf, then Embperl will behave just the same
like Embperl 1.3b7. In the directories where you make your tests, you
include a
PerlSetEnv EMBPERL_EP1COMPAT 0
to enable the new engine.
but _DON'T_ use this one a production machine. While this compatibility mode
is tested and shows no problems for me, it's not so hard tested as 1.3b7
itself!
Addtional Config directives
---------------------------
Caching parameter
-----------------
execute parameter / httpd.conf environment variable / name inside page (must
set inside [! !])
cache_key / EMBPERL_CACHE_KEY / $CACHE_KEY
literal string that is appended to the cache key
cache_key_options / EMBPERL_CACHE_KEY_OPTIONS / $CACHE_KEY_OPTIONS
ckoptCarryOver = 1, use result from CacheKeyFunc of preivious step
if any
ckoptPathInfo = 2, include the PathInfo into CacheKey
ckoptQueryInfo = 4, include the QueryInfo into CacheKey
ckoptDontCachePost = 8, don't cache POST requests (not yet implemented)
Default: all options set
expired_func / EMBPERL_EXPIRES_FUNC / &EXPIRES
function that should be called when build a cache key. The result is
appended to the cache key.
cache_key_func / EMBPERL_CACHE_KEY_FUNC / &CACHE_KEY
function that is called everytime before data is taken from the cache.
If this funtion returns true, the data from the cache isn't used anymore,
but rebuild.
Function could be either a coderef (when passed to Execute), a name of a
subroutine or a string starting with "sub " in which case it is compiled
as anoymous subroutine.
expires_in / EMBPERL_EXPIRES_IN / $EXPIRES
Time in seconds that the output schould be cached. (0 = never, -1 = forever)
Syntax switching
----------------
syntax / EMBPERL_SYNTAX / [$ syntax $]
Used to tell Embperl which syntax to use inside a page. Embperl comes with
the following syntaxes:
- EmbperlHTML # all the HTML tag that Embperl recognizes by
default
- EmbperlBlocks # all the [ ] blocks that Embperl supports
- Embperl # (default; contains EmbperlHtml and EmbperlBlocks)
- ASP # <% %> and <%= %>, see perldoc
HTML::Embperl::Syntax::ASP
- SSI # Server Side Includes, see perldoc
HTML::Embperl::Syntax::SSI
- Perl # File contains pure Perl (similar to
Apache::Registry), but
# can be used inside EmbperlObject
- Text # File contains only Text, no actions is taken on
the Text
- Mail # Defines the <mail:send> 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
You can get a description for each syntax if you type
perldoc HTML::Embperl::Syntax::xxx
where xxx is the name of the syntax.
You can also specify multiple syntaxes e.g.
PerlSetEnv EMBPERL_SYNTAX "Embperl SSI"
Execute ({inputfile => '*', syntax => 'Embperl ASP'}) ;
The syntax metacommand allows to switch the syntax or to
add or subtract syntaxes e.g.
[$ syntax + Mail $]
will add the Mail taglib so the <mail:send> tag is available after
this line.
[$ syntax - Mail $]
now the <mail:send> tag is unknown again
[$ syntax SSI $]
now you can only use SSI commands inside your page.
-------------------
Changes since 2.0b2:
- correct package handling in EP1COMPAT mode
- compiles now with sun-cc. Patches from Michael Stevens.
- fixed several bugs that caused weired behaviour with nested subs
and tables.
- fixed a bug that caused Embperl to stop when it sees a checkbox
inside a loop, for which no value is in %fdat.
- fixed a bug that caused Embperl alias a value in %fdat and %idat
- Execute work now also on the very first line of a file. Spotted
by Michael Smith.
- [- -] can now contain Perl comments. Spotted by Michael Stevens.
- [- -] can now start with =pod. Spotted by Jonny Cavell.
- fixed a parser error so <[+ $foo +]> generates the correct result.
Spotted by Michael Stevens.
- fixed bug in Node_insertAfter which may cause a single Execute
on the second line of a file to loop endless. Spotted by
Janny Cavell.
- Embperl doesn't search for attributes inside of quotes inside of
html tags anymore. Spotted by Ian Van der Poel.
- type=checkbox|radio is now case insensitiv as it should. Spotted
by Jonny Cavell.
- print OUT and Execute now works together. Spotted by Jonny Cavell.
- Embperl doesn't insert a linefeed after an Execute anymore.
- Embperl now keeps single or double quote the same as in the source
file. Requested by Jonny Cavell.
- [$hidden$] works now correctly inside of loops. Spotted by Jonny
Cavell.
- The parser now checks for the correct end of an html tag. Spotted
by Jonny Cavell.
- Added RTF syntax. This allows you for example to create serial letters
with your favorite word processing program, save them as RTF and
process
them with Embperl. See HTML::Embperl::Syntax::RTF for docs.
-------------------
Enjoy
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: announce-unsubscribe@perl.apache.org
For additional commands, e-mail: announce-help@perl.apache.org