gozer 2004/08/17 16:51:46
Modified: src/docs/2.0/api/Apache Module.pod
Log:
Various improvements for Apache::Module.
Revision Changes Path
1.8 +87 -87 modperl-docs/src/docs/2.0/api/Apache/Module.pod
Index: Module.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Module.pod,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Module.pod 15 Aug 2004 00:52:44 -0000 1.7
+++ Module.pod 17 Aug 2004 23:51:45 -0000 1.8
@@ -8,7 +8,8 @@
=head1 Synopsis
use Apache::Module ();
-
+
+ # iterate over the whole module list
for (my $modp = Apache::Module->top_module; $modp; $modp = $modp->next) {
my $name = $modp->name;
my $version = $modp->version;
@@ -17,23 +18,44 @@
my $commands = $modp->cmds;
}
+ # find a specific module
+ my $module = Apache::Module::find_linked_module('mod_ssl.c');
+
+ # access module configuration from a directive
sub MyDirective {
my ($self, $parms, $args) = @_;
my $srv_cfg = Apache::Module->get_config($self, $parms->server);
[...]
}
+
+ # test if an Apache module is loaded
+ if (Apache::Module::loaded('mod_ssl.c')) {
+ [...]
+ }
+
+ # test if a Perl module is loaded
+ if (Apache::Module::loaded('Apache::Status')) {
+ [...]
+ }
+
+
+
+
=head1 Description
-The API provided by this module opens up access to Apache's internal module
-list. It can be used to find and query currently enabled/loaded modules.
+C<Apache::Module> provides the Perl API for creating and working with
+Apache modules
See L<Apache Server Configuration Customization in
Perl|docs::2.0::user::config::custom>.
+
+
+
=head1 API
C<Apache::Module> provides the following functions and/or methods:
@@ -45,17 +67,17 @@
=head2 C<cmds>
-Get an C<L<Apache::Command|docs::2.0::api::Apache::Command>> object
+The C<L<Apache::Command|docs::2.0::api::Apache::Command>> object
that describes all of the directives this module defines.
- $cmd_rec = $module->cmds();
+ $commands = $module->cmds();
=over 4
=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )
-=item ret: C<$cmd_rec>
+=item ret: C<$commands>
( C<L<Apache::Command object|docs::2.0::api::Apache::Command>> )
=item since: 1.99_12
@@ -71,25 +93,34 @@
=head2 C<get_config>
Retrieves a module's configuration. Used by configuration directives.
-
- $cfg = Apache::Module->get_config($self, $parms->server);
- $cfg = Apache::Module->get_config($self, $r->server, $r->per_dir_config);
+
+ $cfg = Apache::Module->get_config($class, $server, [$dir_config]);
+ $cfg = $self->get_config($server, [$dir_config]);
=over 4
-=item obj: C<$self> ( string or ref )
+=item obj: C<$module>
+( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )
-The name of the Perl module this configuration is for
+=item arg1: C<$class> ( string )
-=item obj: C<$server>
+The perl package this configuration is for
+
+=item arg1: C<$server>
( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
-=item obj: C<$dir_config>
+The current server, typically C<$r-E<gt>server> or C<$parms-E<gt>server>
+
+=item opt arg1: C<$dir_config>
( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
-=item ret: C<$cfg> (HASH)
+By default, the configuration returned is the server level one. To retrieve
+the per directory configuration, use C<$r-E<gt>per_dir_config> as a last
+argument.
-The hash holding the module configuration data.
+=item ret: C<$cfg> (HASH reference)
+
+A reference to the hash holding the module configuration data.
=back
@@ -104,18 +135,18 @@
Find a module based on the name of the module
- $modp = Apache::Module::find_linked_module($name);
+ $module = Apache::Module::find_linked_module($name);
=over 4
-=item obj: C<$name> ( string )
+=item arg1: C<$name> ( string )
-the name of the module
+The name of the module ending in C<.c>
-=item ret: C<$modp>
+=item ret: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )
-the module structure if found, undef otherwise
+The module object if found, undef otherwise
=item since: 1.99_12
@@ -129,30 +160,51 @@
Determines if a certain module is loaded
- if (Apache::Module->loaded($module)) {
- [...]
- }
-
- if (Apache::Module->loaded('Apache::Status')) {
- [...]
- }
-
-The argument to this function can be many things. If the module ends in
-'.c', true will be returned if that module is loaded If the module ends
-in '.so', true will be returned if that module is loaded and was loaded
-as a DSO with LoadModule. Otherwise, true will be returned if that Perl
-module is loaded.
+ $loaded = Apache::Module->loaded($module);
=over 4
=item name: C<$module> ( string )
-the name of the module
+The name of the module to search for.
+
+If C<$module> ends with C<.c>, search all the modules,
+statically compiled and dynamically loaded.
-=item ret: ( boolean )
+If C<$module> ends with C<.so>, search only the dynamically
+loaded modules.
+
+If C<$module> doesn't contain a C<.>, search the loaded Perl
+modules.
+
+=item ret: C<$loaded> ( boolean )
+
+Returns true if the module is loaded, false otherwise.
=back
+For example, to test if this server supports ssl:
+
+ if(Apache::Module::loaded('mod_ssl.c')) {
+ [...]
+ }
+
+To test is this server dynamically loaded mod_perl:
+
+ if(Apache::Module::loaded('mod_perl.so')) {
+ [...]
+ }
+
+To test if C<L<Apache::Status>> is loaded:
+
+ if(Apache::Module::loaded('Apache::Status')) {
+ [...]
+ }
+
+
+
+
+
=head2 C<minor_version>
API minor version. Provides API feature milestones. Not checked
@@ -234,58 +286,6 @@
=item since: 1.99_12
=back
-
-
-
-
-
-
-
-
-=head2 C<remove_loaded_module>
-
-Remove a module from the chained modules list and the list of loaded
-modules
-
- $module->remove_loaded_module();
-
-=over 4
-
-=item obj: C<$module>
-( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )
-
-
-=item ret: no return value
-
-=item since: 1.99_12
-
-=back
-
-
-
-=head2 C<remove_module>
-
-Remove a module from the server. There are some caveats:
-when the module is removed, its slot is lost so all the current
-per-dir and per-server configurations are invalid. So we should
-only ever call this function when you are invalidating almost
-all our current data. I.e. when doing a restart.
-
- $module->remove_module();
-
-=over 4
-
-=item obj: C<$module>
-( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )
-
-the module structure of the module to remove
-
-=item ret: no return value
-
-=item since: 1.99_12
-
-=back
-
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
