perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From go...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache CmdParms.pod Command.pod
Date Fri, 13 Aug 2004 05:45:50 GMT
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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message