/ 
Config-Proxy-1.0
/ Config::Proxy

NAME

Config::Proxy - Loader class for HTTP proxy configuration parsers.

DESCRIPTION

This package provides a mechanism for parsing and editing configuration files of two HTTP proxy servers: HAProxy and Pound. It is extensible, so that support for another proxy implementation can be easily added.

CONSTRUCTOR

$cfg = new Config::Proxy($impl, [$filename, $linter])

Loads proxy parser class implementation $impl, invokes its new method with the given arguments, and returns the result. Implementations are stored as Perl sources in Config/Proxy/Impl/$impl.pm. As of this version, two implementations are available:

haproxy

Parses HAProxy configuration file. Refer to Config::HAProxy, for a detailed discussion.

pound

Parses Pound configuration file. Refer to Config::Pound, for a detailed discussion.

The $filename parameter gives the name of the configuration file to use.

$linter is a shell command that will be used to check the modified configuration file syntax, before writing it to disk file (used by write and save methods, see below). The command will be called with the configuration file name as its argument. Implementations provide default values for these two parameters.

Normally, this constructor is not invoked directly. Instead, either Config::HAProxy of Config::Pound constructors are used.

The returned $cfg object provides the following methods:

ATTRIBUTES

filename

$s = $cfg->filename;

Returns the configuration file name given when creating the object.

PARSE TREE

The parse tree consists of nodes, each node representing a single configuration statement. Given that the created object can be used to edit the configuration file and save it after modification, empty lines and comments are treated as statements and included in the parse tree. The tree consists of nodes of the following types (each being a derivative of Config::Proxy::Node class).

Comment (Config::Proxy::Node::Comment)

Represents a comment line.

Empty (Config::Proxy::Node::Empty)

Represents an empty line.

Root (Config::Proxy::Node::Root)

This class represents the topmost node in the parse tree (i.e. the parent of other nodes).

Section (Config::Proxy::Node::Section)

A container, representing a compound statement, or section: a statement that contains multiple sub-statements.

Statement (Config::Proxy::Node::Statement)

Represents a simple statement.

A set of attributes is associated with each node. Attributes common for all node types are:

kw

Keyword under which the statement appears in the configuration file.

argv

Arguments, given to the statement. These are parsed and split according to the syntax of the corresponding proxy configuration file. The argv attribute keeps the resulting argument list.

orig

Original line from the configuration file that this node represents. The line is saved verbatim, with leading and trailing whitespace preserved, but without terminated newline character.

locus

Location of this line (or lines, for sections) in the configuration file (as a Text::Locus) object.

parent

Points to the parent node.

index

A 0-based index of this node in its parent node.

For a detailed discussion of these, see Config::Proxy::Node.

Some node classes provide additional attributes and methods. See Config::Proxy::Node::Section, Config::Proxy::Node::Root, for a detailed discussion of these.

Implementations may also provide additional node types, as does, for example, Config::Pound.

A parse tree can either be produced as a result of configuration file parsing, or built from scratch.

CONFIGURATION FILE PARSING

parse

$cfg->parse;

Reads and parses the configuration file. Croaks if the file does not exist. Returns $cfg.

BUILDING THE PARSE TREE

To build or modify the parse tree, use the following methods of its $cfg->tree attribute or its subnodes: append_node, append_node_nonempty, insert_node, delete_node. Refer to "METHODS" in Config::Proxy::Node::Section, for a detailed discussion of these.

Additional functions:

reset

$cfg->reset;

Clears the parse tree.

INSPECTING THE TREE

tree

$node = $cfg->tree;

Returns the top node (Config::Proxy::Node::Root) of the tree.

select

@nodes = $cfg->select(%conditions)

Select and return all nodes matching the given %conditions. For a detailed description of %conditions, see "select" in Config::Proxy::Node::Section.

iterator

$itr = $node->iterator(@args);

Returns iterator for all nodes in the tree. See Config::Proxy::Iterator, for a detailed discussion.

SAVING

lint

$command = $cfg->lint();
$cfg->lint(bool);
$cfg->lint(%hash);

Configures syntax checking, which is performed by the save method prior to writing configuration file to disk, and inspects its settings.

Called without arguments, returns the currently configured syntax-checking command. If syntax checking is disabled, returns undef.

Called with a single boolean value, enables syntax-checking, if the value is true, or disables it, if it is false.

When called with a hash as argument, configures syntax checking. Allowed keys are:

enable => BOOL

If BOOL is 0, disables syntax check. Default is 1.

command => CMD

Defines the shell command to use for syntax check. The command will be run as

CMD FILE

where FILE is the name of the Pound configuration file to check.

Default value is implementation-specific.

path => PATH

Sets the search path for the syntax checker. PATH is a colon-delimited list of directories. Unless the first word of command is an absolute file name, it will be looked for in these directories. The first match will be used. Default is system $PATH.

When called this way, the method returns the syntax-checker command name, if syntax checking is enabled, and undef otherwise.

save

$cfg->save(%hash);

Saves the parse tree to the configuration file. Syntax check will be run prior to saving (unless previously disabled). If syntax errors are discovered, the method will croak with a diagnostic message starting with words Syntax check failed:.

If %hash contains a non-zero dry_run value, save will only run syntax check, without actually saving the file. If $cfg->lint(enable => 0) was called previously, this is a no-op.

Other keys in %hash are the same as in write, described below.

write

$cfg->write($file, %hash);

Writes configuration to the named file or file handle. First argument can be a file name, file handle or a string reference. If it is the only argument, the original indentation is preserved. Otherwise, if %hash controls the indentation of the output. It must contain at least the indent key, which specifies the amount of indentation per nesting level. If tabstop key is also present, its value must be a reference to the list of tabstop columns. For each statement with arguments, this array is consulted to determine the column number for each subsequent argument. Arguments are zero-indexed. Starting column where the argument should be placed is determined as $tabstop[$i], where $i is the argument index. Arguments with $i greater than or equal to @tabstop are appended to the resulting output, preserving their original offsets.

Normally, comments retain their original indentation. However, if the key reindent_comments is present, and its value is evaluated as true, then comments are reindented following the rules described above.

SEE ALSO

Config::HAProxy, Config::Pound, Config::Proxy::Node, Config::Proxy::Node::Comment, Config::Proxy::Node::Empty, Config::Proxy::Node::Root, Config::Proxy::Node::Section, Config::Proxy::Node::Statement, Config::Proxy::Iterator.

AUTHOR

Sergey Poznyakoff, <gray@gnu.org>

COPYRIGHT AND LICENSE

Copyright (C) 2018, 2024 by Sergey Poznyakoff

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see <http://www.gnu.org/licenses/>.