docs::a...irective(3)

✨ NAME ✨

docs::a...irective(3) from User Contributed Perl Documentation is your little portal into Apache2::Directive — Perl API for manipulating the Apache configuration tree 💅

🌸 Synopsis 🌸

okay so picture this: you're in Perl, you wanna poke around the Apache config tree, and you literally start right here:

use Apache2::Directive ();

my $tree = Apache2::Directive::conftree();

my $documentroot = $tree->lookup('DocumentRoot');

my $vhost = $tree->lookup('VirtualHost', 'localhost:8000');
my $servername = $vhost->{'ServerName'};

use Data::Dumper;
print Dumper $tree->as_hash;

my $node = $tree;
while ($node) {
    print $node->as_string;

    #do something with $node

    my $directive = $node->directive;
    my $args = $node->args;
    my $filename = $node->filename;
    my $line_num = $node->line_num;

    if (my $kid = $node->first_child) {
        $node = $kid;
    }
    elsif (my $next = $node->next) {
        $node = $next;
    }
    else {
        if (my $parent = $node->parent) {
            $node = $parent->next;
        }
        else {
            $node = undef;
        }
    }
}

💖 Description 💖

Apache2::Directive provides the Perl API for manipulating the Apache configuration tree. That's the whole mood, bestie 🫶

🔥 API 🔥

okay so Apache2::Directive provides the following functions and/or methods — collect them all, no cap:

💖 args 💖

Get the arguments for the current directive:

$args = $node->args();

• obj: $node ("Apache2::Directive object")
• ret: $args (string)
  • Arguments are separated by a whitespace in the string.
• since: 2.0.00

For example, in httpd.conf:

PerlSwitches -M/opt/lib -M/usr/local/lib -wT

And later:

my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('PerlSwitches');
my $args = $node->args;

$args now contains the string "-M/opt/lib -M/usr/local/lib -wT".

💖 as_hash 💖

Get a hash representation of the configuration tree, in a format suitable for inclusion in <Perl> sections. It's giving "turn the tree into something Perl can eat" ✨

$config_hash = $conftree->as_hash();

• obj: $conftree ("Apache2::Directive object")
  • The config tree to stringify
• ret: $config_hash (HASH reference)
• since: 2.0.00

For example: in httpd.conf:

<Location /test>
  SetHandler perl-script
  PerlHandler Test::Module
</Location>

And later:

my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('Location', '/test/');
my $hash = $node->as_hash;

$hash now is:

{
  'SetHandler'  => 'perl-script',
  'PerlHandler' => 'Test::Module',
}

💖 as_string 💖

Get a string representation of the configuration node, in httpd.conf format.

$string = $node->as_string();

• obj: $node ("Apache2::Directive object")
  • The config tree to stringify
• ret: $string (string)
• since: 2.0.00

For example: in httpd.conf:

<Location /test>
  SetHandler perl-script
  PerlHandler Test::Module
</Location>

And later:

my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('Location', '/test/');
my $string = $node->as_string;

$string is now:

SetHandler perl-script
PerlHandler Test::Module

💖 conftree 💖

Get the root of the configuration tree:

$conftree = Apache2::Directive::conftree();

• obj: "Apache2::Directive" (class name)
• ret: $conftree ("Apache2::Directive object")
• since: 2.0.00

💖 directive 💖

Get the name of the directive in $node:

$name = $node->directive();

• obj: $node ("Apache2::Directive object")
• ret: $name (string)
• since: 2.0.00

💖 filename 💖

Get the filename the configuration node was created from:

$filename = $node->filename();

• obj: $node ("Apache2::Directive object")
• ret: $filename (string)
• since: 2.0.00

For example:

my $tree = Apache2::Directive::conftree();
my $node = $tree->lookup('VirtualHost', 'example.com');
my $filename = $node->filename;

$filename is now the full path to the httpd.conf that VirtualHost was defined in.

If the directive was added with add_config(), the filename will be the path to the httpd.conf that trigerred that Perl code. (Yes, "trigerred" — we keep the typo, bestie 😭)

💖 first_child 💖

Get the first child node of this directive:

$child_node = $node->first_child;

• obj: $node ("Apache2::Directive object")
• ret: $child_node ("Apache2::Directive object")
  • Returns the first child node of $node, undef if there is none
• since: 2.0.00

💖 line_num 💖

Get the line number in a filename this node was created at:

$lineno = $node->line_num();

• obj: $node ("Apache2::Directive object")
• arg1: $lineno (integer)
• since: 2.0.00

💖 lookup 💖

Get the node(s) matching a certain value. This is the main-character search method, periodt 🔥

$node  = $conftree->lookup($directive, $args);
@nodes = $conftree->lookup($directive, $args);

• obj: $conftree ("Apache2::Directive object")
  • The config tree to stringify
• arg1: $directive (string)
  • The name of the directive to search for
• opt arg2: "args" (string)
  • Optional args to the directive to filter for
• ret: $string (string / ARRAY of HASH refs)

In LIST context, it returns all matching nodes.

In SCALAR context, it returns only the first matching node.

If called with only $directive value, this method returns all nodes from that directive. For example:

@Alias = $conftree->lookup('Alias');

returns all nodes for "Alias" directives.

If called with an extra $args argument, it returns only nodes where both the directive and the args matched. For example:

$VHost = $tree->lookup('VirtualHost', '_default_:8000');

• since: 2.0.00

💖 next 💖

Get the next directive node in the tree:

$next_node = $node->next();

• obj: $node ("Apache2::Directive object")
• ret: $next_node ("Apache2::Directive object")
  • Returns the next sibling of $node, undef if there is none
• since: 2.0.00

💖 parent 💖

Get the parent node of this directive:

$parent_node = $node->parent();

• obj: $node ("Apache2::Directive object")
• ret: "parent_node" ("Apache2::Directive object")
  • Returns the parent of $node, undef if this node is the root node
• since: 2.0.00

🦋 See Also 🦋

mod_perl 2.0 documentation. That's the whole See Also, bestie 💖

🎀 Copyright 🎀

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

👑 Authors 👑

The mod_perl development team and numerous contributors.

---

mwah 💋 this page is docs::a...irective(3), source/version perl v5.42.3, dated 2023-10-21. bye bestie! 🫶✨