.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "docs::api::Apache2::CmdParms 3pm"
.TH docs::api::Apache2::CmdParms 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Apache2::CmdParms \- Perl API for Apache command parameters object
.SH Synopsis
.IX Header "Synopsis"
.Vb 3
\&  use Apache2::CmdParms ();
\&  use Apache2::Module ();
\&  use Apache2::Const \-compile => qw(NOT_IN_LOCATION);
\&  
\&  my @directives = (
\&    {
\&      name => \*(AqMyDirective\*(Aq,
\&      cmd_data => \*(Aqsome extra data\*(Aq,
\&    },
\&  );
\&  
\&  Apache2::Module::add(_\|_PACKAGE_\|_, \e@directives);
\&  
\&  sub MyDirective {
\&      my ($self, $parms, $args) = @_;
\&  
\&      # push config
\&      $parms\->add_config([\*(AqServerTokens off\*(Aq]);
\&  
\&      # this command\*(Aqs command object
\&      $cmd = $parms\->cmd;
\&  
\&      # check the current command\*(Aqs context
\&      $error = $parms\->check_cmd_context(Apache2::Const::NOT_IN_LOCATION);
\&  
\&      # this command\*(Aqs context
\&      $context = $parms\->context;
\&  
\&      # this command\*(Aqs directive object
\&      $directive = $parms\->directive;
\&  
\&      # the extra information passed thru cmd_data to
\&      # Apache2::Module::add()
\&      $info = $parms\->info;
\&  
\&      # which methods are <Limit>ed ?
\&      $is_limited = $parms\->method_is_limited(\*(AqGET\*(Aq);
\&  
\&      # which allow\-override bits are set
\&      $override = $parms\->override;
\&  
\&      # which Options are allowed by AllowOverride (since Apache 2.2)
\&      $override = $parms\->override_opts;
\&  
\&      # the path this command is being invoked in
\&      $path = $parms\->path;
\&  
\&      # this command\*(Aqs pool
\&      $p = $parms\->pool;
\&  
\&      # this command\*(Aqs configuration time pool
\&      $p = $parms\->temp_pool;
\&  }
.Ve
.SH Description
.IX Header "Description"
\&\f(CW\*(C`Apache2::CmdParms\*(C'\fR provides the Perl API for Apache command
parameters object.
.SH API
.IX Header "API"
\&\f(CW\*(C`Apache2::CmdParms\*(C'\fR provides the following functions and/or methods:
.ie n .SS """add_config"""
.el .SS \f(CWadd_config\fP
.IX Subsection "add_config"
Dynamically add Apache configuration at request processing runtime:
.PP
.Vb 1
\&  $parms\->add_config($lines);
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "arg1: $lines (ARRAY ref)" 4
.el .IP "arg1: \f(CW$lines\fR (ARRAY ref)" 4
.IX Item "arg1: $lines (ARRAY ref)"
.PD
An ARRAY reference containing configuration lines per element, without
the new line terminators.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
See also:
\&\f(CW\*(C`$s\->add_config\*(C'\fR,
\&\f(CW\*(C`$r\->add_config\*(C'\fR
.ie n .SS """check_cmd_context"""
.el .SS \f(CWcheck_cmd_context\fP
.IX Subsection "check_cmd_context"
Check the current command against a context bitmask of forbidden contexts.
.PP
.Vb 1
\&  $error = $parms\->check_cmd_context($check);
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "arg1: $check ( ""Apache2::Const :context constant"" )" 4
.el .IP "arg1: \f(CW$check\fR ( \f(CWApache2::Const :context constant\fR )" 4
.IX Item "arg1: $check ( Apache2::Const :context constant )"
.PD
the context to check against.
.ie n .IP "ret: $error ( string / undef )" 4
.el .IP "ret: \f(CW$error\fR ( string / undef )" 4
.IX Item "ret: $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
\&\f(CW\*(C`undef\*(C'\fR.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example here is how to check whether a command is allowed in the
\&\f(CW\*(C`<Location>\*(C'\fR container:
.PP
.Vb 4
\&  use Apache2::Const \-compile qw(NOT_IN_LOCATION);
\&  if (my $error = $parms\->check_cmd_context(Apache2::Const::NOT_IN_LOCATION)) {
\&      die "directive ... not allowed in <Location> context"
\&  }
.Ve
.ie n .SS """cmd"""
.el .SS \f(CWcmd\fP
.IX Subsection "cmd"
This module's command information
.PP
.Vb 1
\&  $cmd = $parms\->cmd();
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $cmd ( ""Apache2::Command object"" )" 4
.el .IP "ret: \f(CW$cmd\fR ( \f(CWApache2::Command object\fR )" 4
.IX Item "ret: $cmd ( Apache2::Command object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """directive"""
.el .SS \f(CWdirective\fP
.IX Subsection "directive"
This command's directive object in the configuration tree
.PP
.Vb 1
\&  $directive = $parms\->directive;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $directive ( ""Apache2::Directive object"" )" 4
.el .IP "ret: \f(CW$directive\fR ( \f(CWApache2::Directive object\fR )" 4
.IX Item "ret: $directive ( Apache2::Directive object )"
.PD
The current directive node in the configuration tree
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """info"""
.el .SS \f(CWinfo\fP
.IX Subsection "info"
The extra information passed through \f(CW\*(C`cmd_data\*(C'\fR in
\&\f(CWApache2::Module::add()\fR.
.PP
.Vb 1
\&  $info = $parms\->info;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $info ( string )" 4
.el .IP "ret: \f(CW$info\fR ( string )" 4
.IX Item "ret: $info ( string )"
.PD
The string passed in \f(CW\*(C`cmd_data\*(C'\fR
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example here is how to pass arbitrary information to a directive
subroutine:
.PP
.Vb 10
\&  my @directives = (
\&    {
\&      name => \*(AqMyDirective1\*(Aq,
\&      func => \e&MyDirective,
\&      cmd_data => \*(AqOne\*(Aq,
\&    },
\&    {
\&      name => \*(AqMyDirective2\*(Aq,
\&      func => \e&MyDirective,
\&      cmd_data => \*(AqTwo\*(Aq,
\&    },
\&  );
\&  Apache2::Module::add(_\|_PACKAGE_\|_, \e@directives);
\&  
\&  sub MyDirective {
\&    my ($self, $parms, $args) = @_;
\&    my $info = $parms\->info;
\&  }
.Ve
.PP
In this example \f(CW$info\fR will either be \f(CW\*(AqOne\*(Aq\fR or \f(CW\*(AqTwo\*(Aq\fR depending
on whether the directive was called as \fIMyDirective1\fR or
\&\fIMyDirective2\fR.
.ie n .SS """method_is_limited"""
.el .SS \f(CWmethod_is_limited\fP
.IX Subsection "method_is_limited"
Discover if a method is <Limit>ed in the current scope
.PP
.Vb 1
\&  $is_limited = $parms\->method_is_limited($method);
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "arg1: $method (string)" 4
.el .IP "arg1: \f(CW$method\fR (string)" 4
.IX Item "arg1: $method (string)"
.PD
The name of the method to check for
.ie n .IP "ret: $is_limited ( boolean )" 4
.el .IP "ret: \f(CW$is_limited\fR ( boolean )" 4
.IX Item "ret: $is_limited ( boolean )"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
For example, to check if the \f(CW\*(C`GET\*(C'\fR method is being
\&\f(CW\*(C`<Limit>\*(C'\fRed in the current scope, do:
.PP
.Vb 3
\&  if ($parms\->method_is_limited(\*(AqGET\*(Aq) {
\&      die "...";
\&  }
.Ve
.ie n .SS """override"""
.el .SS \f(CWoverride\fP
.IX Subsection "override"
Which allow-override bits are set (\f(CW\*(C`AllowOverride\*(C'\fR directive)
.PP
.Vb 1
\&  $override = $parms\->override;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $override ( bitmask )" 4
.el .IP "ret: \f(CW$override\fR ( bitmask )" 4
.IX Item "ret: $override ( bitmask )"
.PD
the allow-override bits bitmask, which can be tested against
\&\f(CW\*(C`Apache2::Const :override
constants\*(C'\fR.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example to check that the \f(CW\*(C`AllowOverride\*(C'\fR's \f(CW\*(C`AuthConfig\*(C'\fR and
\&\f(CW\*(C`FileInfo\*(C'\fR options are enabled for this command, do:
.PP
.Vb 6
\&  use Apache2::Const \-compile qw(:override);
\&  $wanted = Apache2::Const::OR_AUTHCFG | Apache2::Const::OR_FILEINFO;
\&  $masked = $parms\->override & $wanted;
\&  unless ($wanted == $masked) {
\&      die "...";
\&  }
.Ve
.ie n .SS """override_opts"""
.el .SS \f(CWoverride_opts\fP
.IX Subsection "override_opts"
Which options are allowed to be overridden by \f(CW\*(C`.htaccess\*(C'\fR files. This is
set by \f(CW\*(C`AllowOverride Options=...\*(C'\fR.
.PP
.Vb 1
\&  $override_opts = $parms\->override_opts;
.Ve
.PP
Enabling single options was introduced with Apache 2.2. For Apache 2.0 this
function simply returns a bitmask with all options allowed.
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $override_opts ( bitmask )" 4
.el .IP "ret: \f(CW$override_opts\fR ( bitmask )" 4
.IX Item "ret: $override_opts ( bitmask )"
.PD
the bitmask, which can be tested against
\&\f(CW\*(C`Apache2::Const :options
constants\*(C'\fR.
.IP "since: 2.0.3" 4
.IX Item "since: 2.0.3"
.ie n .SS """path"""
.el .SS \f(CWpath\fP
.IX Subsection "path"
The current pathname/location/match of the block this command is in
.PP
.Vb 1
\&  $path = $parms\->path;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $path ( string / ""undef"" )" 4
.el .IP "ret: \f(CW$path\fR ( string / \f(CWundef\fR )" 4
.IX Item "ret: $path ( string / undef )"
.PD
If configuring for a block like <Location>,
<LocationMatch>, <Directory>, etc., the pathname part
of that directive. Otherwise, \f(CW\*(C`undef\*(C'\fR is returned.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
For example for a container block:
.PP
.Vb 3
\&  <Location /foo>
\&  ...
\&  </Location>
.Ve
.PP
\&\fI'/foo'\fR will be returned.
.ie n .SS """pool"""
.el .SS \f(CWpool\fP
.IX Subsection "pool"
Pool associated with this command
.PP
.Vb 1
\&  $p = $parms\->pool;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $p ( ""APR::Pool object"" )" 4
.el .IP "ret: \f(CW$p\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "ret: $p ( APR::Pool object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """server"""
.el .SS \f(CWserver\fP
.IX Subsection "server"
The (vhost) server this command was defined in \fIhttpd.conf\fR
.PP
.Vb 1
\&  $s = $parms\->server;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $s ( ""Apache2::Server object"" )" 4
.el .IP "ret: \f(CW$s\fR ( \f(CWApache2::Server object\fR )" 4
.IX Item "ret: $s ( Apache2::Server object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """temp_pool"""
.el .SS \f(CWtemp_pool\fP
.IX Subsection "temp_pool"
Pool for scratch memory; persists during configuration, but destroyed
before the first request is served.
.PP
.Vb 1
\&  $temp_pool = $parms\->temp_pool;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $temp_pool ( ""APR::Pool object"" )" 4
.el .IP "ret: \f(CW$temp_pool\fR ( \f(CWAPR::Pool object\fR )" 4
.IX Item "ret: $temp_pool ( APR::Pool object )"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
Most likely you shouldn't use this pool object, unless you know what
you are doing. Use \f(CW\*(C`$parms\->pool\*(C'\fR instead.
.SH "Unsupported API"
.IX Header "Unsupported API"
\&\f(CW\*(C`Apache2::CmdParms\*(C'\fR 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 the mod_perl development mailing
list so we can help each other take the steps necessary
to shift the method to an officially supported API.
.ie n .SS """context"""
.el .SS \f(CWcontext\fP
.IX Subsection "context"
Get context containing pointers to modules' per-dir
config structures.
.PP
.Vb 1
\&  $context = $parms\->context;
.Ve
.ie n .IP "obj: $parms ( ""Apache2::CmdParms object"" )" 4
.el .IP "obj: \f(CW$parms\fR ( \f(CWApache2::CmdParms object\fR )" 4
.IX Item "obj: $parms ( Apache2::CmdParms object )"
.PD 0
.ie n .IP "ret: $newval ( ""Apache2::ConfVector object"" )" 4
.el .IP "ret: \f(CW$newval\fR ( \f(CWApache2::ConfVector object\fR )" 4
.IX Item "ret: $newval ( Apache2::ConfVector object )"
.PD
Returns the commands' per-dir config structures
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.SH "See Also"
.IX Header "See Also"
mod_perl 2.0 documentation.
.SH Copyright
.IX Header "Copyright"
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
.SH Authors
.IX Header "Authors"
The mod_perl development team and numerous
contributors.