improve documentation part2
authorJens Rehsack <sno@NetBSD.org>
Fri, 10 Aug 2012 11:04:38 +0000 (10 13:04 +0200)
committerJens Rehsack <sno@NetBSD.org>
Fri, 10 Aug 2012 11:04:38 +0000 (10 13:04 +0200)
bin/wtscript2json.pl
lib/WWW/Mechanize/Script.pm
lib/WWW/Mechanize/Script/Plugin.pm
lib/WWW/Mechanize/Script/Util.pm

index 54abcc6..b6d4cc3 100644 (file)
@@ -51,6 +51,10 @@ defined( $opts{usage} ) and $opts{usage} and pod2usage(1);
 opt_required_all( \%opts, qw(input-files) );
 opt_exclusive( \%opts, qw(output-files output-pattern) );
 opt_required_one( \%opts, qw(output-files output-pattern) );
+
+_ARRAY( $opts{"input-files"} ) and $opts{"input-files"} = [ split(",", join(",", @{$opts{"input-files"}}) ) ];
+_ARRAY( $opts{"output-files"} ) and $opts{"output-files"} = [ split(",", join(",", @{$opts{"output-files"}}) ) ];
+
 _ARRAY( $opts{"input-files"} )
   and _ARRAY( $opts{"output-files"} )
   and scalar( @{ $opts{"input-files"} } ) != scalar( @{ $opts{"output-files"} } )
@@ -110,3 +114,41 @@ foreach my $filename ( @{ $opts{"input-files"} } )
 
 __END__
 
+=head1 DESCRIPTION
+
+wtscript2json is a helper to convert WebTest Script files into a modern
+format. Currently the format is hard-coded to JSON.
+
+To avoid conflicts or duplicates running check_web(2), it's recommended to
+use different C<script_dirs> in special configuration files for check_web(2)
+and wtscript2json (check-web2.json vs. wtscript2json.json vs. check_web.json
+as common configuration file for both). See
+L<WWW::Mechanize::Script::Util/load_config> for further information.
+
+=head1 SYNOPSIS
+
+  # search in $config->{script_dirs} for any loadable script config
+  $ wtscript2json --input-files service1/script1,service1/script2,service2/cool_script \
+      --output-files /opt/new_checks/service1/script1.json \
+      --output-files /opt/new_checks/service1/script2.json \
+      --output-files /opt/new_checks/service2/cool_script.json
+
+  # in-location conversion ...
+  $ find . -name "*splunk*"
+  ./check_web_config/log/test_splunk_1.txt
+  ./check_web_config/log/test_splunk_2.txt
+  ./check_web_config/log/test_splunk_3.txt
+  ./check_web_config/log/test_splunk_4.txt
+  $ wtscript2json --input-files log/test_splunk[1-4] --output-pattern .txt .json
+  $ find . -name "*splunk*"
+  $ find . -name "*splunk*"
+  ./check_web_config/log/test_splunk_1.txt
+  ./check_web_config/log/test_splunk_2.txt
+  ./check_web_config/log/test_splunk_3.txt
+  ./check_web_config/log/test_splunk_4.txt
+  ./check_web_config/log/test_splunk_4.json
+  ./check_web_config/log/test_splunk_3.json
+  ./check_web_config/log/test_splunk_2.json
+  ./check_web_config/log/test_splunk_1.json
+
+=cut
index 7091b87..311faae 100644 (file)
@@ -373,6 +373,11 @@ Which checks are executed is defined below C<< test->check >>. Each valid
 plugin below the I<WWW::Mechanize::Script::Plugin> namespace is approved
 for relevance for the test (see L<WWW::Mechanize::Script::Plugin/can_check>).
 
+The test specification is enriched by the configuration in
+C<< config->defaults >> using L<Hash::Merge> with the I<LEFT_PRECEDENT>
+ruleset. Please care about the ruleset especially when merging arrays
+is to expect.
+
 The code to accumulate the return codes from each test is taken
 from C<< test->check >> as described in L</_gen_code_compute>.
 
index ce63475..1c2be40 100644 (file)
@@ -9,31 +9,52 @@ our $VERSION = '0.001_003';
 
 use 5.014;
 
+=method new()
+
+Instantiates new WWW::Mechanize::Script::Plugin. This is an abstract class.
+
+=cut
+
 sub new
 {
-    my ( $class, $default ) = @_;
+    my ( $class ) = @_;
 
-    my $self = bless( { %{$default} }, $class );
+    my $self = bless( { }, $class );
 
     return $self;
 }
 
+=method get_check_value(\%check,$value_name)
+
+Retrieves the value for I<$value_name> from the hash I<%check>.
+
+=cut
+
 sub get_check_value
 {
     my ( $self, $check, $value_name ) = @_;
 
     $value_name or return;
 
-    return $check->{check}->{$value_name} // $self->{check}->{$value_name};
+    return $check->{check}->{$value_name};
 }
 
+=method get_check_value_as_bool(\%check,$value_name)
+
+Retrieves the value for I<$value_name> from the hash I<%check> and returns
+true when it can be interpreted as a boolean value with true content
+(any object is always returned as it is, (?:(?i)true|on|yes) evaluates to
+I<true>, anything else to I<false>).
+
+=cut
+
 sub get_check_value_as_bool
 {
     my ( $self, $check, $value_name ) = @_;
 
     $value_name or return;
 
-    my $val = $check->{check}->{$value_name} // $self->{check}->{$value_name};
+    my $val = $check->{check}->{$value_name};
 
     defined($val) or return;
     ref($val) and return $val;
@@ -45,6 +66,14 @@ sub get_check_value_as_bool
     return 0;
 }
 
+=method can_check(\%check)
+
+Proves whether this instance can check anything on the current run test.
+Looks if any of the required L</check_value_names> are specified in the
+check parameters of the current test.
+
+=cut
+
 sub can_check
 {
     my ( $self, $check ) = @_;
@@ -61,8 +90,35 @@ sub can_check
 
 }
 
+=method check_value_names()
+
+Returns list of check values which are used to check the response.
+
+Each I<value> has a I<value>C<_code> counterpart which is used to modify
+the return value of L</check_response> when the check upon that value
+fails.
+
+=cut
+
 sub check_value_names { ... }
 
+=method check_response(\%check,$mech)
+
+Checks the response based on test specifications. See individual plugins
+for specific test information.
+
+Returns the accumulated code for each failing check along with optional
+messages containing details about each failure.
+
+  # no error
+  return (0);
+  # some error
+  return ($code,@messages);
+  # some error but no details
+  return ($code);
+
+=cut
+
 sub check_response { ... }
 
 1;
index d8e1e81..5f17bde 100644 (file)
@@ -24,6 +24,43 @@ $VERSION = '0.001_003';
 @EXPORT_OK   = qw(opt_required_all opt_required_one opt_exclusive load_config find_scripts);
 %EXPORT_TAGS = ( ALL => \@EXPORT_OK );
 
+=head1 EXPORTS
+
+This module doesn't export anything by default, but any of the following on request:
+
+=over 4
+
+=item *
+
+opt_required_all
+
+=item *
+
+opt_required_one
+
+=item *
+
+opt_exclusive
+
+=item *
+
+load_config
+
+=item *
+
+find_scripts
+
+=back
+
+=head1 FUNCTIONS
+
+=head2 opt_required_one(\%opt_hash, @opt_names)
+
+Fails by invoking pod2usage when none of the options in @opt_names are
+given in %opt_hash.
+
+=cut
+
 sub opt_required_one
 {
     my ( $opt_hash, @opt_names ) = @_;
@@ -35,6 +72,13 @@ sub opt_required_one
                -message => "Missing at least one of " . join( ", ", map { "--$_" } @opt_names ) );
 }
 
+=head2 opt_required_all(\%opt_hash, @opt_names)
+
+Fails by invoking pod2usage when any of the options in @opt_names are
+missing in %opt_hash.
+
+=cut
+
 sub opt_required_all
 {
     my ( $opt_hash, @opt_names ) = @_;
@@ -51,6 +95,13 @@ sub opt_required_all
              );
 }
 
+=head2 opt_exclusive(\%opt_hash, @opt_names)
+
+Fails by invoking pod2usage when more than one of the options in @opt_names
+are given in %opt_hash.
+
+=cut
+
 sub opt_exclusive
 {
     my ( $opt_hash, @opt_names ) = @_;
@@ -68,6 +119,20 @@ sub opt_exclusive
              );
 }
 
+=head2 load_config(;\%opt_hash)
+
+Tries to load the primary configuration. It looks in any directory returned
+by L<File::ConfigDir/config_dirs> for files named either I<check_web> or
+like the basename of the invoking script (C<$0>) with any extension
+supported by L<Config::Any>. The found configuration files are merged into
+a single configuration hash using L<Hash::Merge> with the I<LEFT_PRECEDENT>
+ruleset.
+
+When an option hash is given, the default agent is computed based on
+the value of I<$opt_hash{file}>.
+
+=cut
+
 sub load_config
 {
     my %opts;
@@ -96,7 +161,7 @@ sub load_config
     # find config file
     my @cfg_dirs = uniq map { realpath($_) } config_dirs();
     my $progname = fileparse( $0, qr/\.[^.]*$/ );
-    my @cfg_pattern = map { ( $progname . "." . $_, "check_web." . $_ ) } Config::Any->extensions();
+    my @cfg_pattern = map { ( "check_web." . $_, $progname . "." . $_ ) } Config::Any->extensions();
     my @cfg_files = File::Find::Rule->file()->name(@cfg_pattern)->maxdepth(1)->in(@cfg_dirs);
     if (@cfg_files)
     {
@@ -122,6 +187,65 @@ sub load_config
     return %cfg;
 }
 
+=head2 find_scripts(\%cfg,@patterns)
+
+Finds scripts based on configuration and given patterns.
+
+=over 4
+
+=item *
+
+When C<%cfg> contains an array with full qualified path names below the
+I<script_dirs>, those directories are scanned. When the directories are
+relative, the are concatenated using L<File::ConfigDir/config_dirs> (each
+entry in the I<script_dirs> is evaluated separately).
+
+When C<%cfg> contains a string below the key I<script_dirs>, the
+I<config_dirs($cfg{script_dirs})> is used to find the scripts.
+
+In any other case, I<config_dirs("check_web")> is used.
+
+=item *
+
+The C<@patterns> list must contain one or more file names or expandable
+shell patterns with or without directory parts and/or extensions.
+
+Valid entries are for example:
+
+=over 8
+
+=item -
+
+qw(check_host_app_one)
+
+=item -
+
+qw(check_host/app_one)
+
+=item -
+
+qw(check_host_app_one.json)
+
+=item -
+
+qw(check_host/app_one.yml)
+
+=item -
+
+qw(check_splunk_[1-5])
+
+=item -
+
+qw(splunk/test*)
+
+=back
+
+=back
+
+Returns the list of found script file names.
+
+=cut
+
 sub find_scripts
 {
     my ( $cfg, @patterns ) = @_;