The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Config-HAProxy-1.08
River stage zero No dependents
1 ++
/ Config::HAProxy

NAME

Config::HAProxy - Parser for HAProxy configuration file

SYNOPSIS

    use Config::HAProxy;
    $cfg = new Config::HAProxy($filename);
    $cfg->parse;

    $name = $cfg->filename;

    @frontends = $cfg->select(name => 'frontend');

    $itr = $cfg->iterator(inorder => 1);
    while (defined($node = $itr->next)) {
        # do something with $node
    }

    $cfg->lint(enable => 1, command => 'haproxy -c -f',
               path => '/sbin:/usr/sbin')

    $cfg->save(%hash);

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

    $cfg->backup;
    $name = $self->backup_name;

    $cfg->reset;
    $cfg->push($node);
    $node = $cfg->pop;
    $node = $cfg->tos;
    $node = $cfg->tree;

DESCRIPTION

The Config::HAProxy class is a parser that converts the HAProxy configuration file to a parse tree and provides methods for various operations on this tree, such as: searching, modifying and saving it to a file.

An object of this class contains a parse tree representing the configuration read from the file (or created from scratch). Nodes in the tree can be of four distinct classes:

Empty

Represents an empty line.

Comment

Represents a comment line.

Statement

Represents a simple statement.

Section

A container, representing a compound statement, i.e. a statement that contains multiple sub-statements. Compound statements are: global, defaults, frontend, backend, and resolvers. The list of compound statements may be modified using the declare_section and undeclare_section class methods (see below).

In addition to these four classes, a special class Root is provided, which represents the topmost node in the parse tree (i.e. the parent of other nodes).

A set of attributes is associated with each node. Among these, the orig attribute contains the original line from the configuration file that triggered creation of this node, and locus contains the location of this line (or lines, for sections) in the configuration file (as a Text::Locus) object.

These two attributes are meaningful for all nodes. For statement nodes (simple statements and sections) the kw attribute contains the statement keyword, and the argv attribute - its arguments. For example, the statement

    server localhost 127.0.0.1:8080

is represented by a node of class Config::HAProxy::Node::Statement, with server as kw and list (localhost, 127.0.0.1:8080) as argv.

Additionally, section nodes provide methods for accessing their subtrees.

For a detailed description of the node class and its methods, please refer to Config::HAProxy::Node.

CLASS METHODS

    $cfg = Config::HAProxy::declare_section($name)

Declares $name as a top-level section.

    $cfg = Config::HAProxy::undeclare_section($name)

Cancels declaration of $name as a top-level section.

CONSTRUCTOR

    $cfg = new Config::HAProxy($filename);

Creates and returns a new object for manipulating the HAProxy configuration. Optional $filename specifies the name of the file to read configuration from. It defaults to /etc/haproxy/haproxy.cfg.

filename

    $s = $cfg->filename;

Returns the configuration file name given when creating the object.

PARSING

parse

    $cfg->parse;

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

BUILDING THE PARSE TREE

reset

    $cfg->reset;

Clears the parse tree.

push

    $cfg->push($node);

Appends the $node (the Config::HAProxy::Node object), to the end of the parse tree.

pop

    $node = $cfg->pop;

Removes the tail node from the tree and returns it.

INSPECTING THE TREE

tree

    $node = $cfg->tree;

Returns the top of the tree.

tos

    $node = $cfg->tos;

Returns the last node in the tree.

SAVING

lint

    $cfg->lint(%hash);

Configures configuration syntax check. The check will be run by the save method prior to writing to the configuration file. Takes a hash as argument. 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 HAProxy configuration file to check.

Default command is haproxy -c -f.

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.

Returns the command name.

save

    $cfg->save(%hash);

Saves the parse tree in 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 reintent_comments is present, and its value is evaluated as true, then comments are reindented following the rules described above.

SEE ALSO

Config::HAProxy::Node, Config::HAProxy::Node::Section, Config::HAProxy::Node::Statement, Config::HAProxy::Iterator.

AUTHOR

Sergey Poznyakoff, <gray@gnu.org>

COPYRIGHT AND LICENSE

Copyright (C) 2018 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/>.