stas 2002/12/26 23:05:22
Modified: src/docs/2.0/api/ModPerl-Registry/ModPerl Registry.pod
RegistryBB.pod RegistryCooker.pod
Log:
registry docs, work in progress
Revision Changes Path
1.3 +5 -1
modperl-docs/src/docs/2.0/api/ModPerl-Registry/ModPerl/Registry.pod
Index: Registry.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/api/ModPerl-Registry/ModPerl/Registry.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Registry.pod 19 May 2002 09:41:39 -0000 1.2
+++ Registry.pod 27 Dec 2002 07:05:21 -0000 1.3
@@ -11,7 +11,7 @@
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
#PerlOptions +ParseHeaders
- #PerlOptions +GlobalRequest
+ #PerlOptions -GlobalRequest
Options +ExecCGI
</Location>
@@ -35,6 +35,10 @@
$r->print("mod_perl rules!");
XXX: STOPPED here
+
+META: document that for now we don't chdir() into the script's dir,
+because it affects the whole process under threads.
+
This module emulates the CGI environment, allowing programmers to
write scripts that run under CGI or mod_perl without change. Existing
1.3 +1 -1
modperl-docs/src/docs/2.0/api/ModPerl-Registry/ModPerl/RegistryBB.pod
Index: RegistryBB.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/api/ModPerl-Registry/ModPerl/RegistryBB.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- RegistryBB.pod 19 May 2002 09:41:39 -0000 1.2
+++ RegistryBB.pod 27 Dec 2002 07:05:22 -0000 1.3
@@ -11,7 +11,7 @@
SetHandler perl-script
PerlResponseHandler ModPerl::RegistryBB
#PerlOptions +ParseHeaders
- #PerlOptions +GlobalRequest
+ #PerlOptions -GlobalRequest
Options +ExecCGI
</Location>
1.3 +197 -0
modperl-docs/src/docs/2.0/api/ModPerl-Registry/ModPerl/RegistryCooker.pod
Index: RegistryCooker.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/api/ModPerl-Registry/ModPerl/RegistryCooker.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- RegistryCooker.pod 19 May 2002 09:41:39 -0000 1.2
+++ RegistryCooker.pod 27 Dec 2002 07:05:22 -0000 1.3
@@ -4,7 +4,204 @@
=head1 Synopsis
+ # shouldn't be used as-is but sub-classed first
+ # see ModPerl::Registry for an example
+
=head1 Description
+
+C<ModPerl::RegistryCooker> is used to create flexible and overridable
+registry modules which emulate mod_cgi for Perl scripts. The concepts
+are discussed in the manpage of the following modules:
+C<L<ModPerl::Registry>>, C<L<ModPerl::Registry>> and
+C<L<ModPerl::RegistryBB>>.
+
+C<ModPerl::RegistryCooker> has two purposes:
+
+=over
+
+=item *
+
+Provide ingredients that can be used by registry sub-classes
+
+=item *
+
+Provide a default behavior, which can be overriden in sub-classed
+
+META: in the future this functionality may move into a separate class.
+
+=back
+
+Here are the current overridable methods:
+
+=over
+
+=item * new()
+
+default: new()
+
+=item * init()
+
+default: init()
+
+=item * default_handler()
+
+default: default_handler()
+
+=item * run()
+
+default: run()
+
+=item * can_compile()
+
+default: can_compile()
+
+=item * make_namespace()
+
+default: make_namespace()
+
+=item * namespace_root()
+
+default: namespace_root()
+
+
+=item * namespace_from()
+
+default: namespace_from()
+
+=item * is_cached()
+
+default: is_cached()
+
+=item * should_compile()
+
+default: should_compile()
+
+=item * flush_namespace()
+
+default: flush_namespace()
+
+
+=item * cache_table()
+
+default: cache_table()
+
+=item * cache_it()
+
+default: cache_it()
+
+=item * read_script()
+
+default: read_script()
+
+=item * rewrite_shebang()
+
+default: rewrite_shebang()
+
+=item * set_script_name()
+
+default: set_script_name()
+
+=item * chdir_file()
+
+default: chdir_file()
+
+=item * get_mark_line()
+
+default: get_mark_line()
+
+=item * compile()
+
+default: compile()
+
+
+=item * error_check()
+
+default: error_check()
+
+=item * strip_end_data_segment()
+
+default: strip_end_data_segment()
+
+=item * convert_script_to_compiled_handler()
+
+default: convert_script_to_compiled_handler()
+
+=back
+
+Special Predefined functions
+
+=over
+
+=item * NOP()
+
+META: compelete
+
+=back
+
+=head1 Sub-classing Techniques
+
+To override the default C<ModPerl::RegistryCooker> methods, first,
+sub-class C<ModPerl::RegistryCooker> or one of its existing
+sub-classes, using C<use base>. Second, override the methods.
+
+Those methods that weren't overridden will be resolved at run time
+when used for the first time and cached for the future requests. One
+way to to shortcut this first run resolution is to use the symbol
+aliasing feature. For example to alias
C<ModPerl::MyRegistry::flush_namespace>
+as C<ModPerl::RegistryCooker::flush_namespace>, you can do:
+
+ package ModPerl::MyRegistry;
+ use base qw(ModPerl::RegistryCooker);
+ *ModPerl::MyRegistry::flush_namespace =
+ \&ModPerl::RegistryCooker::flush_namespace;
+ 1;
+
+In fact, it's a good idea to explicitly alias all the methods so you
+know exactly what functions are used, rather then relying on the
+defaults. For that purpose C<ModPerl::RegistryCooker> class method
+install_aliases() can be used. Simply prepare a hash with method names
+in the current package as keys and corresponding fully qualified
+methods to be aliased for as values and pass it to
+install_aliases(). Continuing our example we could do:
+
+ package ModPerl::MyRegistry;
+ use base qw(ModPerl::RegistryCooker);
+ my %aliases = (
+ flush_namespace => 'ModPerl::RegistryCooker::flush_namespace',
+ );
+ __PACKAGE__->install_aliases(\%aliases);
+ 1;
+
+The values use fully qualified packages so you can mix methods from
+different classes.
+
+=head1 Examples
+
+The best examples are existing core registry modules:
+C<L<ModPerl::Registry>>, C<L<ModPerl::Registry>> and
+C<L<ModPerl::RegistryBB>>. Look at the source code and their manpages
+to see how they subclass C<ModPerl::RegistryCooker>.
+
+For example by default C<L<ModPerl::Registry>> uses the script's path
+when creating a package's namespace. If for example you want to use a
+uri instead you can override it with:
+
+ *ModPerl::MyRegistry::namespace_from =
+ \&ModPerl::RegistryCooker::namespace_from_uri;
+ 1;
+
+Since the C<namespace_from_uri> component already exists in
+C<ModPerl::RegistryCooker>. If you want to write your own method,
+e.g., that creates a namespace based on the inode, you can do:
+
+ sub namespace_from_inode {
+ my $self = shift;
+ return (stat $self->[FILENAME])[1];
+ }
+
+META: when $r->finfo will be ported it'll be more effecient. (stat
+$r->finfo)[1]
+
=head1 Authors
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
