From b9ddd9310ea896a5e644f784013a386d9e7212a9 Mon Sep 17 00:00:00 2001 From: Tobi Oetiker Date: Fri, 11 Feb 2005 20:48:36 +0000 Subject: niko has revamped smokeping to parse configuration much more strictly. It is all documented in software/doc/smokeping_upgrade.pod --- lib/Smokeping/Examples.pm | 633 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 633 insertions(+) create mode 100644 lib/Smokeping/Examples.pm (limited to 'lib/Smokeping') diff --git a/lib/Smokeping/Examples.pm b/lib/Smokeping/Examples.pm new file mode 100644 index 0000000..5adbfff --- /dev/null +++ b/lib/Smokeping/Examples.pm @@ -0,0 +1,633 @@ +# -*- perl -*- +package Smokeping::Examples; +use strict; +use Smokeping; + +=head1 NAME + +Smokeping::Examples - A module for generating the smokeping_examples document + +=head1 OVERVIEW + +This module generates the smokeping_examples document and the example +configuration files distributed with Smokeping. It is supposed to be +invoked from the smokeping distribution top directory, as it will need +the C template configuration file and will create files +in the directories C and C. + +=head1 DESCRIPTION + +The entry point to the module is the C subroutine. It takes one optional +parameter, C, that makes the module run a syntax check for all the +created example configuration files. + +=head1 BUGS + +This module uses more or less internal functions from C. It's a +separate module only because the latter is much too big already. + +It should be possible to include POD markup in the configuration explanations +and have this module filter them away for the config files. + +=head1 COPYRIGHT + +Copyright 2005 by Niko Tyni. + +=head1 LICENSE + +This program 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 2 of the License, or (at your option) any later +version. + +This program 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 program; if not, write to the Free +Software Foundation, Inc., 675 Mass Ave, Cambridge, MA +02139, USA. + +=head1 AUTHOR + +Niko Tyni + +=cut + +use strict; + +sub read_config_template { + my $file = "etc/config.dist"; + my $h = { + common => "", # everything up to the Probes section + probes => "", # the Probes section, without the *** Probes *** line + targets => "", # the Targets section, without the *** Targets *** line + }; + open(F, "<$file") or die("open template configuration file $file for reading: $!"); + my %found; + while () { + /\*\*\*\s*(Probes|Targets)\s*\*\*\*/ and $found{$1} = 1, next; + $h->{common} .= $_ and next unless $found{Probes}; + $h->{probes} .= $_ and next unless $found{Targets}; + $h->{targets} .= $_; + } + close F; + return $h; +} + +sub prologue { + my $e = "="; + return < directory in the +Smokeping documentation. Note that the DNS names in the examples are +non-functional. + +Details of the syntax and all the variables are found in the +smokeping_config reference document and in the documentation of the +corresponding probe, if applicable. + +This manual is automatically generated from the Smokeping source code. + +${e}head1 DESCRIPTION + +Currently the examples differ only in the C and C +sections. The other sections are taken from the C +configuration template in the Smokeping distribution so that the example +files are complete. + +If you would like to provide more examples, document the other sections +or enhance the existing examples, please do so, preferably by sending +the proposed changes to the smokeping-users mailing list. + +DOC +} + +sub epilogue { + my $e = "="; + return < + +${e}head1 SEE ALSO + +The other Smokeping documents, especially smokeping_config. +DOC +} + +sub make { + print "Generating example files...\n"; + my $check = shift; # check the syntax of the generated config files + my $template = read_config_template(); + my $examples = examples($template); + my $manual = prologue(); + for my $ex (sort { $examples->{$a}{order} <=> $examples->{$b}{order} } keys %$examples) { + my $h = $examples->{$ex}; + $manual .= "\n=head2 Example $h->{order}: config.$ex\n\n" + . genpod($h); + my $cfgfile = "doc/examples/config.$ex"; + print "\t$cfgfile ...\n"; + writecfg($cfgfile, $template, $h); + if ($check) { + local $Smokeping::cfg = undef; + eval { + Smokeping::verify_cfg($cfgfile); + }; + die("Syntax check for $cfgfile failed: $@") if $@; + } + } + $manual .= epilogue(); + writemanual($manual); + print "done.\n"; +} + +sub writemanual { + my $text = shift; + my $filename = "doc/smokeping_examples.pod"; + print "\t$filename ...\n"; + open(F, ">$filename") or die("open $filename for writing: $!"); + print F $text; + close F; +} + +sub genpod { + my $h = shift; + my $text = ""; + $text .= "=over\n\n"; + $text .= "=item Probe configuration\n\n"; + $text .= " *** Probes ***\n"; + $text .= join("\n", map { " $_" } split(/\n/, $h->{probes})); + $text .= "\n\n=item Probe explanation\n\n"; + $text .= $h->{probedoc}; + $text .= "\n\n=item Target configuration\n\n"; + $text .= " *** Targets ***\n"; + $text .= join("\n", map { " $_" } split(/\n/, $h->{targets})); + $text .= "\n\n=item Target explanation\n\n"; + $text .= $h->{targetdoc}; + $text .= "\n\n=back\n\n"; + return $text; +} + +sub writecfg { + my $file = shift; + my $template = shift; + my $h = shift; + open(F, ">$file") or die("open $file for writing: $!"); + print F <{common}; + print F "# (The actual example starts here.)\n"; + print F "\n *** Probes ***\n\n"; + print F join("\n", map { "# $_" } split(/\n/, $h->{probedoc})); + print F "\n\n"; + print F $h->{probes}; + print F "\n *** Targets ***\n\n"; + print F join("\n", map { "# $_" } split(/\n/, $h->{targetdoc})); + print F "\n\n"; + print F $h->{targets}; + close F; +} + +sub examples { + my $template = shift; + return { + simple => { + order => 1, + probes => < < < < { + order => 2, + probes => < < < < { + order => 3, + probes => < < < < { + order => 4, + probes => < < < < { + order => 5, + probes => < < < < { + order => 6, # last + probes => $template->{probes}, + targets => $template->{targets}, + probedoc => < <