Gerald Richter wrote:
If you need any help with English documentation cleanup then
let me know which files and I'll have a crack at it.
Thanks for your offer. The main thing I like to do, to check that the old
stuff that is only valid for 1.3 (like optRawInput etc.) is replaced by the
new ones. After this is done, I am happy if you check my english
Sure, just let me know when you are ready, the offer is open.
P.S. If you feel you have some free time, the most important thing for
advocacy of Embperl (other them makeing 2.0 ready), is to update
http://perl.apache.org/docs/tutorials/tmpl/comparison/comparison.html#HTML__
Embperl
And add all the new Embperl::Object and other 2.0 stuff into it...
I don't feel qualified (yet) to write too much about Embperl 2.0, since I don't currently use it
(except for testing the bugs which are currently in play) and I truthfully haven't investigated the
new features too much (e.g. recipes, providers or the new objects).
On a side note, I find some of the new stuff in 2.0 a little obscure. As an application programmer I
can well appreciate the ability to deconstruct the request to the extent that 2.0 appears to allow,
but I honestly cannot see how or why I would personally want to do any of that. Perhaps more
concrete examples of where these new features come in useful would be helpful, both to people like
me and newcomers thinking about using Embperl.
On a philosophical note, I have discovered from personal experience that new ideas are not
necessarily self-evident to other people, they need prompting and examples to bring it all to life
so they can see how it applies to their own situation. There is an "Aha!" moment you're looking for
here, where programmers look at this and see in a flash how it will make their lives easier.
Currently, all I really want out of Embperl is the ability to a) embed Perl code in the HTML
templates, and b) structure my website in a vaguely object-oriented manner through the inheritance
that EmbperlObject (or Embperl::Object) provides. All that is currently satisfactorily supplied by
Embperl 1.x. So to me, the only current perceived benefit of moving to Embperl 2.x is the
performance increase, and this is certainly outweighed by the lingering bugs and continuing
almost-but-not-quite compatibility with 1.x. I'll continue to test my codeset under 2.x, but I am
fearful of putting it up live on the production server because it's almost impossible for me to test
every little case - it's a lot of code (over 50,000 lines in crazyguyonabike) and there's a lot of
community input, which I don't want to risk breaking.
On the new feature front - Why exactly would I write a new recipe or rearrange the providers? No
doubt there are good examples, if someone would be good enough to provide these then they could form
some of the foundation for the Cookbook.
I decided to take another look at the README.v2 and correct the English grammar/spelling issues that
I could find. I am attaching this for you to look at, I hope it's useful as a start.
I will investigate, as time allows, the different Wiki toolkits that are available out there and see
if there is anything that looks like being a good fit here. I agree that perhaps making this a Wiki
would be more scalable that having one person write a document, though I do still like the
"ownership" and consistency of style that can come from a document written by a single person rather
than committee. Committees come up with something that attempts to please everybody but often ends
up being uninspired and bland.
Thanks,
-Neil
Embperl - Building dynamic Websites with Perl
Copyright (c) 1997-2004 Gerald Richter / ecos gmbh www.ecos.de
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: README.v2,v 1.7 2005/02/27 20:05:47 richter Exp $
Hints for using Embperl 2.x
---------------------------
Embperl 2 is a total rewrite. Most of the Perl code has been moved
into C to speed up processing. The core has been totally redesigned to
give a lot of new possibilities.
The Embperl core now works in a totally different way from 1.x. The processing
of the source toward the output is done by providers. Every provider
takes a small step. Which providers are used is defined by a recipe.
The standard Embperl recipe contains the following providers:
1 reading the source
2 parsing
3 compiling
4 executing
5 outputing
The providers works in a similar way as Unix shell programs which
process a single source in a pipeline toward the output. In
Embperl this is not only a simple pipeline, but a tree structure,
so multiple sources can be incorporated in one result.
Recipes describe how providers are executed.
Rearranging the providers or writing and using new ones gives added
flexibility and power. In addition to the standard Embperl providers
Embperl also ships with an XML parser and XSLT processor providers.
The new execution scheme is also faster than before, because html tags and
metacommands
are parsed only once (Perl code was also (and is still) cached in 1.x)
My initial benchmarks show 50%-100% faster execution under mod_perl
compared to Embperl 1.x.
Another new feature is that the syntax of the Embperl parser is defined
within the module Embperl::Syntax and can be modified as necessary.
Embperl comes with a set of syntax definitons which can be modified by
the user. So far there are syntax definitions for SSI, Text only, Perl-only,
ASP, POD, RTF 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 can change the syntax dynamically inside the page via the
[$ syntax $] command. You also could specify more than one syntax at the same
time, e.g. [$ syntax Embperl SSI $] to mix Embperl tags and SSI tags in the same
page.
If you'd like to create your own syntax read:
perldoc Embperl::Syntax
and look at the files under Embperl/Syntax/ for examples on how to do it.
Also new is the ability to cache (parts of) the output. See
the new configuration directives below.
Starting with 2.0b6 Embperl provides a set of new objects, which allow
access to the Embperl internals and manipulating the processing. Basically there
are three major objects:
- Application
- Request
- Component
The application object is responsible for a set of pages that forms an
application. It is used to configure things like session handling and
logging which should be unique across these pages. More important
it can be overridden and the overridden object can contain the application
logic, to create a proper separation of logic and presentation.
The request object holds everything which spans a whole (HTTP-)request.
The component object is responsible for a single component, inside the
desired output. It holds things like the sourcefile etc.
All three objects have a subobject which holds the configuration and a
subobject for its current parameters.
Debugging
---------
Starting with 2.0b2 Embperl files can debugged via the interactive 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 choice. Apache::DB is available from CPAN.
The following differences to Embperl 1.x apply:
------------------------------------------------------
- When running under mod_perl you _must_ load Embperl
at server startup time. Either with a
PerlModule Embperl
in your httpd.conf or a
use Embperl ;
inside of a startup script.
You can use the Embperl configuration directives now
directly, (without PerlSetEnv/SetEnv). If you still
want to use enviroment varibales to configure Embperl, write
Embperl_UseEnv on
- Embperl now supports Apache 2 / mod_perl 2, but you need a additional
configuration line in your httpd.conf:
LoadModule embperl_module /path/to/perl/site/lib/Embperl/Embperl.so
- For every container in your httpd.conf (e.g. VirtualHost,Directory,Location)
where you want to define any application level configuration directives
(see below under tAppConfig for a list), you need to set a unique
value for EMBPERL_APPNAME. This is for example necessary for all
Embperl::Object parameters. Example:
<Location /eo>
EMBPERL_APPNAME my_embperl_app
EMBPERL_OBJECT_BASE base.epl
</Location>
- The following options can currently only be set from httpd.conf:
optKeepSpaces
- The option optRawInput is replaced by EMBPERL_INPUT_ESCMODE,
which is off by default (same as when optRawInput was set
in 1.x)
- The following options are currently not supported:
optRedirectStdout
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 done properly. I.e. you cannot put a <table> tag (for a
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) $] now requires 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 any more. Also the expression must _not_ be
terminated with a semicolon. To let old code work, just wrap it into a 'do'
e.g. [+ do { my $a = $b + 5 ; $a } +]
- EMBPERL_INPUT_FUNC and EMBPERL_OUTPUT_FUNC are not supported anymore
You can the same result and much more by writing a custom provider.
- Embperl doesn't change the current working directory any more to the
directory of the source file. This is done for performance reasons
and because it won't reliably work with threads under mod_perl 2.0.
You can use $req -> component -> cwd to get the directory of the
sourcefile (where $req is Embperl request object, which is the first
paramter passed to the page i.e. $_[0])
- safe namespaces are not supported anymore, since are are not really
safe anyway
- errors can be mailed to an administrator
- Parameters of SetupSession, CleanupSession and SetSessionCookie have changed.
Embperl 1.x compatibility flag
------------------------------
The compatibility flag isn't available anymore in 2.0b6. Since now
Embperl 2.0 lives in his own namespace, you can install Embperl 1.x and
2.x on the same machine without conflicts.
exit
----
B<exit> will override the normal Perl exit in every Embperl document. Calling
exit will immediately stop any further processing of that file and send the
already-done work to the output/browser.
B<NOTE 1:> If you are inside of an Execute, Embperl will only exit this
Execute, but
the file which called the file containing the exit with Execute will continue.
If
you want to exit the whole request, call exit with an argument e.g. exit (200)
B<NOTE 2:> If you write a module which should work with Embperl under mod_perl,
you must use Embperl::exit instead of the normal Perl exit. (In 1.3.x it was
Apache::Exit)
-------------------
Enjoy
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
