path: root/lib/Config/
diff options
authorSergey Poznyakoff <>2018-07-08 22:16:49 +0300
committerSergey Poznyakoff <>2018-07-08 22:16:49 +0300
commit69ff9c1766ed89edf0ffdb63bf487396b6bd081b (patch)
treeef644a810f50d81d3b4e47d7cdbf64df976d8be6 /lib/Config/
parent32b6c6394dc6a789826bd51575d9703bb4097f70 (diff)
Add documentationv1.00
Diffstat (limited to 'lib/Config/')
1 files changed, 115 insertions, 25 deletions
diff --git a/lib/Config/ b/lib/Config/
index 7938bcb..f99bf33 100644
--- a/lib/Config/
+++ b/lib/Config/
@@ -182,10 +182,10 @@ sub save {
rename($tempfile, $self->filename)
or croak "can't rename $tempfile to ".$self->tempfile.": $!";
- # This will fail unless we are root, let it be so.
- chown $sb->uid, $sb->gid, $self->filename;
# This will succeed: we've created the file, so we're owning it.
chmod $sb->mode & 0777, $self->filename;
+ # This will fail unless we are root, let it be so.
+ chown $sb->uid, $sb->gid, $self->filename;
@@ -215,39 +215,90 @@ __END__
=head1 NAME
-Config::HAProxy - HAProxy configuration file
+Config::HAProxy - Parser for HAProxy configuration file
-use Config::HAProxy;
-$cfg = new Config::HAProxy($filename);
+ use Config::HAProxy;
+ $cfg = new Config::HAProxy($filename);
+ $cfg->parse;
-$name = $cfg->filename;
+ $name = $cfg->filename;
-@frontends = $cfg->select(name => 'frontend');
+ @frontends = $cfg->select(name => 'frontend');
-$itr = $cfg->iterator(inorder => 1);
-while (defined($node = $itr->next)) {
- # do something with $node
+ $itr = $cfg->iterator(inorder => 1);
+ while (defined($node = $itr->next)) {
+ # do something with $node
+ }
+ $cfg->save;
+ $cfg->write($file_or_handle);
-$name = $self->backup_name;
+ $cfg->backup;
+ $name = $self->backup_name;
-$node = $cfg->pop;
-$node = $cfg->tos;
-$node = $cfg->tree;
+ $cfg->reset;
+ $cfg->push($node);
+ $node = $cfg->pop;
+ $node = $cfg->tos;
+ $node = $cfg->tree;
+The B<Config::HAProxy> class is a parser that converts the B<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 I<parse tree> representing the
+configuration read from the file (or created from scratch). Nodes in the
+tree can be of four distinct classes:
+=over 4
+=item Empty
+Represents an empty line.
+=item Comment
+Represents a comment line.
+=item Statement
+Represents a simple statement.
+=item Section
+A container, representing a C<compound statement>, i.e. a statement that
+contains multiple sub-statements. Compound statements are: B<global>,
+B<defaults>, B<frontend>, and B<backend>.
+In addition to these four classes, a special class B<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 B<orig>
+attribute contains the original line from the configuration file that triggered
+creation of this node, and B<locus> contains the location of this line (or
+lines, for sections) in the configuration file (as a B<Text::Locus>) object.
+These two attributes are meaningful for all nodes. For statement nodes (simple
+statements and sections) the B<kw> attribute contains the statement I<keyword>,
+and the B<argv> attribute - its arguments. For example, the statement
+ server localhost
+is represented by a node of class B<Config::HAProxy::Node::Statement>, with
+C<server> as B<kw> and list (C<localhost>, C<>) as B<argv>.
+Additionally, section nodes provide methods for accessing their subtrees.
+For a detailed description of the node class and its methods, please refer to
@@ -257,15 +308,23 @@ Creates and returns a new object for manipulating the HAProxy configuration.
Optional B<$filename> specifies the name of the file to read configuration
from. It defaults to F</etc/haproxy/haproxy.cfg>.
+=head2 filename
+ $s = $cfg->filename;
+Returns the configuration file name given when creating the object.
+=head1 PARSING
=head2 parse
Reads and parses the configuration file. Croaks if the file does not exist.
+Returns B<$cfg>.
=head2 reset
@@ -305,7 +364,7 @@ Returns the last node in the tree.
-Saves the configuration file.
+Saves the parse tree in the configuration file.
=head2 write
@@ -327,3 +386,34 @@ Normally, comments retain their original indentation. However, if the
key B<reintent_comments> is present, and its value is evaluated as true,
then comments are reindented following the rules described above.
+=head1 SEE ALSO
+=head1 AUTHOR
+Sergey Poznyakoff, E<lt>gray@gnu.orgE<gt>
+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
+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 <>.

Return to:

Send suggestions and report system problems to the System administrator.