Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 8 - Customizing the Apache Configuration Process / The Apache Configuration Directive API
Designing Configuration Directives

We'll now look in more detail at how you can precisely control the behavior of configuration directives.

As you recall, a module's configuration directives are declared in an array of hashes passed to the command_table() function. Each hash contains the required keys, name and errmsg. In addition, there may be any of four optional keys: func, args_how, req_override, and cmd_data.

For example, this code fragment defines two configuration directives named TrafficCopSpeedLimit and TrafficCopRightOfWay:

@directives = (
        {
          name   => 'TrafficCopSpeedLimit',
          errmsg => 'an integer specifying the maximum allowable
                     kilobytes per second',
          func   =>  'right_of_way',
          args_how => 'TAKE1',
          req_override => 'OR_ALL',
         },
         {
          name   =>  'TrafficCopRightOfWay',
          errmsg =>  'list of domains that can go as fast as they
                      want',
          args_how => 'ITERATE',
          req_override => 'OR_ALL',
          cmd_data => '[A-Z_]+',
          },
      );
command_table(\@directives);

The required name key points to the name of the directive. It should have exactly the same spelling and capitalization as the directive you want to implement (Apache doesn't actually care about the capitalization of directives, but Perl does when it goes to call your configuration processing callbacks). Alternatively, you can use the optional func key to specify a subroutine with a different name than the configuration directive.

The mandatory errmsg key should be a short but succinct usage statement that summarizes the arguments that the directive takes.

The optional args_how key tells Apache how to parse the directive. There are 11 (!) possibilities corresponding to different numbers of mandatory and optional arguments. Because the number of arguments passed to the Perl callback function for processing depends on the value of args_how, the callback function must know in advance how many arguments to expect. The various args_how options are described in the next section.

The optional cmd_data key is used to pass arbitrary information to the directive handler. The handler can retrieve this information by calling the info() method of the Apache::CmdParms object that is passed to the directive callback. In our example, we use this information to pass a pattern match expression to the callback. This is how it might be used:

sub TrafficCopRightOfWay ($$@) {
   my($cfg, $parms, $domain) = @_;
   my $pat = $parms->info;
   unless ($domain =~ /^$pat$/i) {
       die "Invalid domain: $domain\n";
   }
   $cfg->{RightOfWay}{$domain}++;
}

req_override, another optional key, is used to restrict the directive so that it can only legally appear in certain sections of the configuration files.