=head1 NAME

Apache::Module - Perl API for creating and working with Apache modules




=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;
      my $minor_version = $modp->minor_version;
      my $index = $modp->module_index;
      my $commands = $modp->cmds;
  }
  
  # find a specific module
  my $module = Apache::Module::find_linked_module('mod_ssl.c');
  
  # remove a specific module
  $module->remove_loaded_module();
  
  # 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

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:






=head2 C<cmds>

The C<L<Apache::Command|docs::2.0::api::Apache::Command>> object
that describes all of the directives this module defines.

  $commands = $module->cmds();

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item ret: C<$commands>
( C<L<Apache::Command object|docs::2.0::api::Apache::Command>> )

=item since: 1.99_12

=back







=head2 C<get_config>

Retrieves a module's configuration. Used by configuration directives.

  $cfg = Apache::Module->get_config($class, $server, [$dir_config]);
  $cfg = $self->get_config($server, [$dir_config]);

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item arg1: C<$class> ( string )

The perl package this configuration is for

=item arg1: C<$server> 
( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )

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>> )

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.

=item ret: C<$cfg> (HASH reference)

A reference to the hash holding the module configuration data.

=item since: 1.99_12

=back

See also L<Apache Server Configuration Customization in Perl|docs::2.0::user::config::custom>






=head2 C<find_linked_module>

Find a module based on the name of the module

  $module = Apache::Module::find_linked_module($name);

=over 4

=item arg1: C<$name> ( string )

The name of the module ending in C<.c>

=item ret: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

The module object if found, undef otherwise

=item since: 1.99_12

=back





=head2 C<loaded>

Determines if a certain module is loaded

  $loaded = Apache::Module::loaded($module);

=over 4

=item name: C<$module> ( string )

The name of the module to search for.

If C<$module> ends with C<.c>, search all the modules,
statically compiled and dynamically loaded.

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.

=item since: 1.99_12

=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|docs::2.0::api::Apache::Status>> is
loaded:

  if (Apache::Module::loaded('Apache::Status')) {
      [...]
  }







=head2 C<minor_version>

API minor version. Provides API feature milestones. Not checked
during module init

  $minor_version = $module->minor_version();

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item ret: C<$minor_version> ( integer )

=item since: 1.99_12

=back





=head2 C<module_index>

Index to this modules structures in config vectors.

  $index = $module->module_index();

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item ret: C<$index> ( integer )

=item since: 1.99_12

=back





=head2 C<name>

The name of the module's C file

  $name = $module->name();

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item ret: C<$name> ( string )

=item since: 1.99_12

=back





=head2 C<next>

The next module in the list, undef if the last module in the list.

  $next_module = $module->next();

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item ret: C<$next_module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item since: 1.99_12

=back






=head2 C<remove_loaded_module>

Remove a module from the list of loaded modules permanently.

  $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<top_module>

Returns the first module in the module list. Usefull to start a
module iteration.

  $ret = Apache::Module->top_module();

=over 4

=item obj: C<Apache::Module> ( class name )

=item ret: C<$ret>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item since: 1.99_12

=back





=head2 C<version>

API version, B<not> module version; check that module is
compatible with this version of the server.

  $version = $module->version();

=over 4

=item obj: C<$module>
( C<L<Apache::Module object|docs::2.0::api::Apache::Module>> )

=item ret: C<$version> ( integer )

=item since: 1.99_12

=back





=head1 See Also

L<mod_perl 2.0 documentation|docs::2.0::index>.




=head1 Copyright

mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.




=head1 Authors

L<The mod_perl development team and numerous
contributors|about::contributors::people>.

=cut

