stas 2004/08/13 12:45:33
Modified: src/docs/2.0/api/Apache CmdParms.pod
Log:
polish
Revision Changes Path
1.7 +112 -58 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.6
retrieving revision 1.7
diff -u -u -r1.6 -r1.7
--- CmdParms.pod 13 Aug 2004 05:45:49 -0000 1.6
+++ CmdParms.pod 13 Aug 2004 19:45:33 -0000 1.7
@@ -11,37 +11,38 @@
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;
+ 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;
}
@@ -72,7 +73,7 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
=item ret: C<$cmd>
@@ -90,14 +91,19 @@
Check the current command against a context bitmask of forbidden contexts.
- $error = $parms->check_cmd_context(Apache::NOT_IN_LOCATION);
+ $error = $parms->check_cmd_context($check);
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$error>
+=item arg1: C<$check> ( C<L<Apache::Const :context
+constant|docs::2.0::api::Apache::Const/C__context_>> )
+
+the context to check against.
+
+=item ret: C<$error> ( string / undef )
If the context is forbidden, this method returns a textual description
of why it was forbidden. If the context is permitted, this method returns
@@ -107,6 +113,19 @@
=back
+For example here is how to check whether a command is allowed in the
+E<lt>LocationE<gt> container:
+
+ use Apache::Const -compile qw(NOT_IN_LOCATION);
+ if (my $error = $parms->check_cmd_context(Apache::NOT_IN_LOCATION)) {
+ die "directive ... not allowed in <Location> context"
+ }
+
+
+
+
+
+
=head2 C<directive>
@@ -117,7 +136,7 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
=item ret: C<$newval>
@@ -136,17 +155,17 @@
=head2 C<info>
-The extra information passed thru C<cmd_data> in
+The extra information passed thru C<cmd_data> in
C<L<@APACHE_MODULE_COMMANDS|docs::2.0::user::config::custom/C_cmd_data_>>
$info = $parms->info;
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$info> (string)
+=item ret: C<$info> ( string )
The string passed in C<cmd_data>
@@ -167,36 +186,60 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$limit> (integer)
+=item ret: C<$limit> ( integer )
=item since: 1.99_12
=back
+ META: and how exactly is it supposed to be used, should this be
+ tested against $r->method_number (e.g. Apache::M_POST) ? what's
+ $limit? (notice that the test of this method isn't so good, it
+ tests some hardcoded -1 value, how do you know that it does what you
+ think it does?)
+
+
+
=head2 C<override>
-Which allow-override bits are set
+Which allow-override bits are set (C<AllowOverride> directive)
$override = $parms->override;
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$override> (integer)
+=item ret: C<$override> ( bitmask )
+
+the allow-override bits bitmask, which can be tested against
+C<L<Apache::Const :override
+constants|docs::2.0::api::Apache::Const/C__override_>>.
=item since: 1.99_12
=back
+For example to check that the C<AllowOverride>'s C<AuthConfig> and
+C<FileInfo> options are enabled for this command, do:
+
+ use Apache::Const -compile qw(:override);
+ $wanted = Apache::OR_AUTHCFG | Apache::OR_FILEINFO;
+ $masked = $parms->override & $wanted;
+ unless ($wanted == $masked) {
+ die "...";
+ }
+
+
+
@@ -209,14 +252,14 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$path> (string)
+=item ret: C<$path> ( string / undef )
-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.
+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
@@ -224,6 +267,10 @@
+
+
+
+
=head2 C<pool>
Pool associated with this command
@@ -232,11 +279,11 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
=item ret: C<$p>
-(C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
+( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
=item since: 1.99_12
@@ -255,10 +302,11 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$s> (C<L<Apache::Server|docs::2.0::api::Apache::ServerRec>>)
+=item ret: C<$s>
+( C<L<Apache::Server object|docs::2.0::api::Apache::ServerRec>> )
=item since: 1.99_12
@@ -271,22 +319,28 @@
=head2 C<temp_pool>
-Pool for scratch memory; persists during configuration, but
-wiped before the first request is served...
+Pool for scratch memory; persists during configuration, but destroyed
+before the first request is served.
$p = $parms->temp_pool;
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
-=item ret: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>>)
+=item ret: C<$p>
+( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
=item since: 1.99_12
=back
+Most likely you shouldn't use this pool object, unless you know what
+you are doing. Use C<L<$parms-E<gt>pool|/C_pool_>> instead.
+
+
+
@@ -315,7 +369,7 @@
=over 4
-=item parms: C<$parms>
+=item obj: C<$parms>
( C<L<Apache::CmdParms object|docs::2.0::api::Apache::CmdParms>> )
=item ret: C<$newval>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
