summaryrefslogtreecommitdiffabout
path: root/lib/Config/HAProxy.pm
Side-by-side diff
Diffstat (limited to 'lib/Config/HAProxy.pm') (more/less context) (ignore whitespace changes)
-rw-r--r--lib/Config/HAProxy.pm140
1 files changed, 115 insertions, 25 deletions
diff --git a/lib/Config/HAProxy.pm b/lib/Config/HAProxy.pm
index 7938bcb..f99bf33 100644
--- a/lib/Config/HAProxy.pm
+++ b/lib/Config/HAProxy.pm
@@ -182,10 +182,10 @@ sub save {
$self->backup;
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;
$self->tree->clear_dirty
}
@@ -215,39 +215,90 @@ __END__
=head1 NAME
-Config::HAProxy - HAProxy configuration file
+Config::HAProxy - Parser for HAProxy configuration file
=head1 SYNOPSIS
-use Config::HAProxy;
-$cfg = new Config::HAProxy($filename);
-$cfg->parse;
+ 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->save;
-$cfg->write($file_or_handle);
+ $cfg->write($file_or_handle);
-$cfg->backup;
-$name = $self->backup_name;
+ $cfg->backup;
+ $name = $self->backup_name;
-$cfg->reset;
-$cfg->push($node);
-$node = $cfg->pop;
-$node = $cfg->tos;
-$node = $cfg->tree;
+ $cfg->reset;
+ $cfg->push($node);
+ $node = $cfg->pop;
+ $node = $cfg->tos;
+ $node = $cfg->tree;
=head1 DESCRIPTION
-FIXME
+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>.
+
+=back
+
+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 127.0.0.1:8080
+
+is represented by a node of class B<Config::HAProxy::Node::Statement>, with
+C<server> as B<kw> and list (C<localhost>, C<127.0.0.1:8080>) 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
+B<Config::HAProxy::Node>.
=head1 CONSTRUCTOR
@@ -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>.
-=head1 THE PARSE TREE
+=head2 filename
+
+ $s = $cfg->filename;
+
+Returns the configuration file name given when creating the object.
+
+=head1 PARSING
=head2 parse
$cfg->parse;
Reads and parses the configuration file. Croaks if the file does not exist.
+Returns B<$cfg>.
-
+=head1 BUILDING THE PARSE TREE
+
=head2 reset
$cfg->reset;
@@ -305,7 +364,7 @@ Returns the last node in the tree.
$cfg->save;
-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
+
+B<Config::HAProxy::Node>,
+B<Config::HAProxy::Node::Section>,
+B<Config::HAProxy::Node::Statement>,
+B<Config::HAProxy::Iterator>.
+
+=head1 AUTHOR
+
+Sergey Poznyakoff, E<lt>gray@gnu.orgE<gt>
+
+=head1 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/>.
+
+=cut
+
+

Return to:

Send suggestions and report system problems to the System administrator.