gozer 2004/08/12 22:45:50
Modified: src/docs/2.0/api/Apache CmdParms.pod Command.pod
Log:
Apache::CmdParms is completed.
Awaiting review by Stas please...
Revision Changes Path
1.6 +109 -181 modperl-docs/src/docs/2.0/api/Apache/CmdParms.pod
Index: CmdParms.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/CmdParms.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- CmdParms.pod 10 Aug 2004 03:15:52 -0000 1.5
+++ CmdParms.pod 13 Aug 2004 05:45:49 -0000 1.6
@@ -1,6 +1,6 @@
=head1 NAME
-Apache::CmdParms - Perl API for XXX
+Apache::CmdParms - Perl API for Apache command parameters object
@@ -8,15 +8,50 @@
=head1 Synopsis
use Apache::CmdParms ();
+ use Apache::Const -compile => qw(NOT_IN_LOCATION);
+
+ sub MyDirective {
+ my ($self, $parms, $args) = @_;
+
+ # this command's command object
+ $cmd = $parms->cmd;
+
+ # check the current command's context
+ $error = $parms->check_cmd_context(Apache::NOT_IN_LOCATION);
+
+ # this command's context
+ $context = $parms->context;
+
+ # this command's directive object
+ $directive = $parms->directive;
+
+ # the extra information passed thru cmd_data in @APACHE_MODULE_COMMANDS
+ $info = $parms->info;
+
+ # which methods are <Limit>ed ?
+ $limit = $parms->limited;
+
+ # which allow-override bits are set
+ $override = $parms->override;
+
+ # the path this command is being invoked in
+ $path = $parms->path;
+
+ # this command's pool
+ $p = $parms->pool;
+
+ # this command's configuration time pool
+ $p = $parms->temp_pool;
+ }
-META: to be completed
=head1 Description
-META: to be completed
+C<Apache::CmdParms> provides the Perl API for Apache command
+parameters object.
@@ -27,110 +62,68 @@
-Comments for Philippe:
-
- should the elements of ap_params_t elements be writable? see the
- comments in the API section of the Command.pod and Directive.pod. if
- unsure, make things read-only. we can always enable them back later.
-
-
-
=head2 C<cmd>
-META: Autogenerated - needs to be reviewed/completed
-
-configuration command
+This module's command information
- $obj->cmd($newval);
+ $cmd = $parms->cmd();
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
+=item ret: C<$cmd>
( C<L<Apache::Command object|docs::2.0::api::Apache::Command>> )
-=item ret: no return value
-
-=item since: 1.99_12
-
-=back
-
-
-
-
-
-=head2 C<config_file>
-
-META: Autogenerated - needs to be reviewed/completed
-
-Config file structure.
-
- $obj->config_file($newval);
-
-=over 4
-
-=item obj: C<$obj>
-( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-
-=item arg1: C<$newval>
-( C<L<Apache::ConfigFile object|docs::2.0::api::Apache::ConfigFile>> )
-
-=item ret: no return value
-
=item since: 1.99_12
-
=back
-=head2 C<context>
-META: Autogenerated - needs to be reviewed/completed
+=head2 C<check_cmd_context>
-per_dir_config vector passed to handle_command
+Check the current command against a context bitmask of forbidden contexts.
- $obj->context($newval);
+ $error = $parms->check_cmd_context(Apache::NOT_IN_LOCATION);
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
-( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
+=item ret: C<$error>
-=item ret: no return value
+If the context is forbidden, this method returns a textual description
+of why it was forbidden. If the context is permitted, this method returns
+C<undef>.
-=item since: 1.99_12
+=item since: 1.99_16
=back
-
=head2 C<directive>
-META: Autogenerated - needs to be reviewed/completed
-
-the directive specifying this command
+This command's directive object in the configuration tree
- $obj->directive($newval);
+ $directive = $parms->directive;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
+=item ret: C<$newval>
( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )
-=item ret: no return value
+The current directive node in the configuration tree
=item since: 1.99_12
@@ -141,47 +134,21 @@
-=head2 C<err_directive>
-
-META: Autogenerated - needs to be reviewed/completed
-
-directive with syntax error
-
- $obj->err_directive($newval);
-
-=over 4
-
-=item obj: C<$obj>
-( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-
-=item arg1: C<$newval>
-( C<L<Apache::Directive object|docs::2.0::api::Apache::Directive>> )
-
-=item ret: no return value
-
-=item since: 1.99_12
-
-=back
-
-
-
=head2 C<info>
-META: Autogenerated - needs to be reviewed/completed
-
-Argument to command from cmd_table
+The extra information passed thru C<cmd_data> in
+C<L<@APACHE_MODULE_COMMANDS|docs::2.0::user::config::custom/C_cmd_data_>>
- $obj->info($newval);
+ $info = $parms->info;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
-(XXX)
+=item ret: C<$info> (string)
-=item ret: no return value
+The string passed in C<cmd_data>
=item since: 1.99_12
@@ -194,21 +161,16 @@
=head2 C<limited>
-META: Autogenerated - needs to be reviewed/completed
+Which methods are currently E<lt>LimitE<gt>ed
-Which methods are E<lt>LimitE<gt>ed
-
- $obj->limited($newval);
+ $limit = $parms->limited;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
-(number)
-
-=item ret: no return value
+=item ret: C<$limit> (integer)
=item since: 1.99_12
@@ -218,48 +180,18 @@
-=head2 C<limited_xmethods>
-
-META: Autogenerated - needs to be reviewed/completed
-
-methods which are limited
-
- $obj->limited_xmethods($newval);
-
-=over 4
-
-=item obj: C<$obj>
-( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-
-=item arg1: C<$newval>
-(C<L<APR::ArrayHeader|docs::2.0::api::APR::ArrayHeader>>)
-
-=item ret: no return value
-
-=item since: 1.99_12
-
-=back
-
-
-
-
=head2 C<override>
-META: Autogenerated - needs to be reviewed/completed
-
Which allow-override bits are set
- $obj->override($newval);
+ $override = $parms->override;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
-(integer)
-
-=item ret: no return value
+=item ret: C<$override> (integer)
=item since: 1.99_12
@@ -271,26 +203,20 @@
=head2 C<path>
-META: Autogenerated - needs to be reviewed/completed
+The current pathname/location/match of the block this command is in
-If configuring for a directory, pathname of that directory. NOPE!
-That's what it meant previous to the existance of E<lt>FilesE<gt>,
-E<lt>LocationE<gt> and regex matching. Now the only usefulness that
-can be derived from this field is whether a command is being called in
-a server context (path == NULL) or being called in a dir context (path
-!= NULL).
-
- $obj->path($newval);
+ $path = $parms->path;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
-(string)
+=item ret: C<$path> (string)
-=item ret: no return value
+If configuring for a block like E<lt>LocationE<gt>, E<lt>LocationMatchE<gt>,
+E<lt>DirectoryE<gt>, etc, the pathname part of that directive. Otherwise,
+C<undef> is returned.
=item since: 1.99_12
@@ -300,22 +226,18 @@
=head2 C<pool>
-META: Autogenerated - needs to be reviewed/completed
-
-Pool to allocate new storage in
+Pool associated with this command
- $obj->pool($newval);
+ $p = $parms->pool;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
+=item ret: C<$p>
(C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
-=item ret: no return value
-
=item since: 1.99_12
=back
@@ -327,20 +249,16 @@
=head2 C<server>
-META: Autogenerated - needs to be reviewed/completed
+The server this command is appearing in
-server_rec being configured for
-
- $obj->server($s);
+ $s = $parms->server;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::ServerRec>>)
-
-=item ret: no return value
+=item ret: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::ServerRec>>)
=item since: 1.99_12
@@ -353,21 +271,17 @@
=head2 C<temp_pool>
-META: Autogenerated - needs to be reviewed/completed
-
Pool for scratch memory; persists during configuration, but
wiped before the first request is served...
- $obj->temp_pool($p);
+ $p = $parms->temp_pool;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
-
-=item ret: no return value
+=item ret: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
=item since: 1.99_12
@@ -377,23 +291,37 @@
-=head2 C<xlimited>
+=head1 Unsupported API
+
+C<Apache::CmdParms> also provides auto-generated Perl interface for
+a few other methods which aren't tested at the moment and therefore
+their API is a subject to change. These methods will be finalized
+later as a need arises. If you want to rely on any of the following
+methods please contact the L<the mod_perl development mailing
+list|maillist::dev> so we can help each other take the steps necessary
+to shift the method to an officially supported API.
+
+
-META: Autogenerated - needs to be reviewed/completed
-methods which are xlimited
- $obj->xlimited($newval);
+
+=head2 C<context>
+
+Get context containing pointers to modules' per-dir
+config structures.
+
+ $context = $parms->context;
=over 4
-=item obj: C<$obj>
+=item parms: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item arg1: C<$newval>
-(C<L<Apache::MethodList|docs::2.0::api::Apache::MethodList>>)
+=item ret: C<$newval>
+( C<L<Apache::ConfVector object|docs::2.0::api::Apache::ConfVector>> )
-=item ret: no return value
+Returns the commands' per-dir config structures
=item since: 1.99_12
1.7 +0 -29 modperl-docs/src/docs/2.0/api/Apache/Command.pod
Index: Command.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Command.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Command.pod 11 Aug 2004 18:15:06 -0000 1.6
+++ Command.pod 13 Aug 2004 05:45:50 -0000 1.7
@@ -56,35 +56,6 @@
-=head2 C<check_cmd_context>
-
-META: This probably belongs in Apache::CmdParams
-
- $ret = $cmd->check_cmd_context($forbidden);
-
-=over 4
-
-=item obj: C<$cmd>
-(C<L<Apache::CmdParms|docs::2.0::api::Apache::CmdParms>>)
-
-The command to check
-
-=item arg1: C<$forbidden> (XXX)
-
-Where the command is forbidden.
-
-=item ret: C<$ret> ( string )
-
-Error string on error, C<undef> on success
-
-=item since: 1.99_12
-
-=back
-
-
-
-
-
=head2 C<errmsg>
'usage' message for that command, in case of syntax errors
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
