From 69ff9c1766ed89edf0ffdb63bf487396b6bd081b Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sun, 8 Jul 2018 22:16:49 +0300 Subject: Add documentation --- lib/Config/HAProxy/Node/Comment.pm | 31 +++++++ lib/Config/HAProxy/Node/Empty.pm | 29 +++++++ lib/Config/HAProxy/Node/Root.pm | 52 +++++++++++- lib/Config/HAProxy/Node/Section.pm | 153 ++++++++++++++++++++++++++++++++++- lib/Config/HAProxy/Node/Statement.pm | 45 +++++++++++ 5 files changed, 308 insertions(+), 2 deletions(-) (limited to 'lib/Config/HAProxy/Node') diff --git a/lib/Config/HAProxy/Node/Comment.pm b/lib/Config/HAProxy/Node/Comment.pm index 5d7ef88..17a513b 100644 --- a/lib/Config/HAProxy/Node/Comment.pm +++ b/lib/Config/HAProxy/Node/Comment.pm @@ -1,6 +1,37 @@ package Config::HAProxy::Node::Comment; use parent 'Config::HAProxy::Node'; +=head1 NAME + +Config::HAProxy::Node::Comment - comment node in HAProxy configuration + +=head1 DESCRIPTION + +Objects of this class represent comments in HAProxy configuration file. + +=head1 METHODS + +=head2 is_comment + +Returns true. + +=head2 orig + +Returns original line as it appeared in the configuration file. + +=head2 locus + +Returns the location of this statement in the configuration file (the +B object). + +=head1 SEE ALSO + +B, B. + +=cut + sub is_comment { 1 } 1; + + diff --git a/lib/Config/HAProxy/Node/Empty.pm b/lib/Config/HAProxy/Node/Empty.pm index bee0f2e..19ce5da 100644 --- a/lib/Config/HAProxy/Node/Empty.pm +++ b/lib/Config/HAProxy/Node/Empty.pm @@ -1,6 +1,35 @@ package Config::HAProxy::Node::Empty; use parent 'Config::HAProxy::Node'; +=head1 NAME + +Config::HAProxy::Node::Empty - empty HAProxy configuration node + +=head1 DESCRIPTION + +Objects of this class represent empty lines in HAProxy configuration file. + +=head1 METHODS + +=head2 is_empty + +Always true. + +=head2 orig + +Returns original line as it appeared in the configuration file. + +=head2 locus + +Returns the location of this statement in the configuration file (the +B object). + +=head1 SEE ALSO + +B, B. + +=cut + sub is_empty { 1 } 1; diff --git a/lib/Config/HAProxy/Node/Root.pm b/lib/Config/HAProxy/Node/Root.pm index 656bb9f..ca6e575 100644 --- a/lib/Config/HAProxy/Node/Root.pm +++ b/lib/Config/HAProxy/Node/Root.pm @@ -4,6 +4,19 @@ use warnings; use parent 'Config::HAProxy::Node::Section'; use Carp; +=head1 NAME + +Config::HAProxy::Node::Root - root node of HAProxy configuration parse tree + +=head1 DESCRIPTION + +Objects of this class represent the topmost node in HAProxy configuration tree. +Each parse tree contains exactly one object of this class. This node can be +reached from every node in the tree by following its B attribute +and is returned by the B method of B class. + +=cut + sub new { my $class = shift; my $self = $class->SUPER::new(@_); @@ -11,21 +24,58 @@ sub new { return $self; } +=head1 METHODS + +=head2 is_root + +Always true. + +=head2 is_dirty + + $bool = $node->is_dirty; + +Returns true if the tree is C, i.e. it was modified since it has been +created from the disk configuration file. + +=cut + sub is_dirty { my $self = shift; return $self->{dirty} } +=head2 mark_dirty + + $node->mark_dirty; + +Sets the C attribute. + +=cut + sub mark_dirty { my $self = shift; $self->{dirty} = 1; } +=head2 clear_dirty + + $node->clear_dirty; + +Clears the C attribute. + +=cut + sub clear_dirty { my $self = shift; $self->{dirty} = 0; } - + +=head1 SEE ALSO + +B. + +=cut + 1; diff --git a/lib/Config/HAProxy/Node/Section.pm b/lib/Config/HAProxy/Node/Section.pm index c332155..3ef1cf0 100644 --- a/lib/Config/HAProxy/Node/Section.pm +++ b/lib/Config/HAProxy/Node/Section.pm @@ -4,6 +4,18 @@ use warnings; use parent 'Config::HAProxy::Node'; use Carp; +=head1 NAME + +Config::HAProxy::Node::Section - HAProxy configuration section + +=head1 DESCRIPTION + +Objects of this class represent a C
in the HAProxy configuration file. +A section is a statement that can contain sub-statements. The following +statements form sections: B, B, B, and B. + +=cut + sub new { my $class = shift; my $self = $class->SUPER::new(@_); @@ -11,8 +23,51 @@ sub new { return $self; } +=head1 ATTRIBUTES + +=head2 is_section + +Always true. + +=cut + sub is_section { 1 } +=head1 METHODS + +=head2 kw + +Returns the configuration keyword. + +=head2 argv + +Returns the list of arguments to the configuration keyword. + +=head2 arg + + $s = $node->arg($n) + +Returns the B<$n>th argument. + +=head2 orig + +Returns original line as it appeared in the configuration file. + +=head2 locus + +Returns the location of this statement in the configuration file (the +B object). + +=head2 append_node + + $section->append_node(@nodes); + +Takes a list of objects of B derived classes as +arguments. Adds these objects after the last node in the subtree in this +section. + +=cut + sub append_node { my $self = shift; my $n = @{$self->{_tree}}; @@ -24,6 +79,15 @@ sub append_node { } @_; } +=head2 append_node_nonempty + + $section->append_node_nonempty(@nodes); + +Same as B, but adds new nodes after the last non-empty +node in the subtree. + +=cut + sub append_node_nonempty { my $self = shift; my $n = $#{$self->{_tree}}; @@ -32,7 +96,15 @@ sub append_node_nonempty { } $self->insert_node($n+1, @_); } - + +=head2 insert_node + + $section->insert_node($idx, @nodes); + +Inserts B<@nodes> after subnode in position B<$idx> (0-based). + +=cut + sub insert_node { my $self = shift; my $n = shift; @@ -48,6 +120,14 @@ sub insert_node { } } +=head2 delete_node + + $section->delete_node($i); + +Deletes B<$i>th subnode from the B<$section>. + +=cut + sub delete_node { my ($self, $n) = @_; splice @{$self->{_tree}}, $n, 1; @@ -57,6 +137,18 @@ sub delete_node { $self->root->mark_dirty; } +=head2 tree + + @nodes = $section->tree; + +Returns subnodes as a list of B derived objects. + + $node = $section->tree($i); + +Returns B<$i>th subnode from the B<$section>. + +=cut + sub tree { my ($self, $n) = @_; if ($n) { @@ -66,6 +158,15 @@ sub tree { return @{shift->{_tree}} }; +=head2 ends_in_empty + + $bool = $section->ends_in_empty + +Returns true if the last node in the list of sub-nodes in B<$section> is +an empty node. + +=cut + sub ends_in_empty { my $self = shift; while ($self->is_section) { @@ -110,6 +211,50 @@ my %match = ( } ); +=head2 select + + @nodes = $section->select(%cond); + +Returns nodes from B<$section> that match conditions in B<%cond>. Valid +conditions are: + +=over 4 + +=item B> I<$s> + +Node matches if its keyword (B) equals I<$s>. + +=item B> B<{ n =E> I<$n>, B =E I<$s> B<}> + +Node mathches if its I<$n>th argument equals I<$s>. + +=item B
> I<$bool> + +Node matches if it is (or is not, if I<$bool> is false) a section. + +=item B> I<$bool> + +Node matches if it is (not) a simple statement. + +=item B> I<$bool> + +Node matches if it is (not) a comment. + +=back + +Multiple conditions are checked in the order of their appearance in the +argument list and are joined by the short-circuit logical C. + +For example, to return all B statements: + + @fe = $section->select(name => 'frontend'); + +To return the frontend named C: + + ($fe) = $section->select( name => 'frontend', + arg => { n => 0, v => 'in' } ); + +=cut sub select { my $self = shift; @@ -138,6 +283,12 @@ sub _test_node { return 1; } +=head1 SEE ALSO + +B, B, B. + +=cut + 1; diff --git a/lib/Config/HAProxy/Node/Statement.pm b/lib/Config/HAProxy/Node/Statement.pm index abf0e50..305c529 100644 --- a/lib/Config/HAProxy/Node/Statement.pm +++ b/lib/Config/HAProxy/Node/Statement.pm @@ -1,6 +1,51 @@ package Config::HAProxy::Node::Statement; use parent 'Config::HAProxy::Node'; +=head1 NAME + +Config::HAProxy::Node::Statement - simple statement node in HAProxy tree + +=head1 DESCRIPTION + +Objects of this class represent simple statements in HAProxy configuration +file. A C is any statement excepting: B, B, +B, and B. + +=head1 METHODS + +=head2 is_statement + +Returns true. + +=head2 kw + +Returns the configuration keyword. + +=head2 argv + +Returns the list of arguments to the configuration keyword. + +=head2 arg + + $s = $node->arg($n) + +Returns the B<$n>th argument. + +=head2 orig + +Returns original line as it appeared in the configuration file. + +=head2 locus + +Returns the location of this statement in the configuration file (the +B object). + +=head1 SEE ALSO + +B, B, B. + +=cut + sub is_statement { 1 } 1; -- cgit v1.2.1