/ 
Log-Munger-0.0.1
/ Log::Munger::RulesTemplateOrder

NAME

Log::Munger::RulesTemplateOrder - Works out the order a rule file's templated vars must be resolved in.

VERSION

Version 0.0.1

SYNOPSIS

use Log::Munger::RulesTemplateOrder;

my $order = Log::Munger::RulesTemplateOrder->order_for_rules_file( 'file' => 'base' );
foreach my $var ( @{$order} ) {
    print $var . "\n";
}

A rule file's vars_templated entries reference each other. TIMESTAMP_ISO8601 is built out of YEAR, MONTHNUM, TIME and friends, and TIME is in turn built out of HOUR, MINUTE and SECOND. Resolving them in hash order would leave a [% TIME %] sitting unsubstituted in the middle of a timestamp pattern, so Log::Munger::RuleFileParser asks this module for a working order first.

The dependencies are read straight off the [% VAR %] references in each templated var and handed to Algorithm::Dependency::Ordered, which returns a schedule where nothing comes before something it needs.

log_munger rule_file_template_order -f <file> prints that schedule, and adding -d prints the dependency map it was derived from.

METHODS

order_for_rules_hash

Returns the order the templated vars of an already loaded rules hash have to be resolved in.

The hash wants to be one from "load_no_templating" in Log::Munger::RuleFileParser. Once load has run, the templating is already done and the [% VAR %] references this reads have been substituted away.

Plain vars are treated as already resolved: a templated var may reference any of them, but they do not appear in the returned schedule. A name defined under both vars and vars_templated resolves as the plain var, which is what lets a file shadow an include's templated var with a plain one.

- rules :: The rules hash ref to process.
    Default :: undef

Returns an array ref of the vars_templated names, in the order they should be resolved. A file with neither vars nor vars_templated gets an empty array ref. Dies on anything "depends_for_rules_hash" dies on, if a templated var references a name that is not defined anywhere, or if the references are circular.

my $order = Log::Munger::RulesTemplateOrder->order_for_rules_hash( 'rules' => $rules_hash );

depends_for_rules_hash

Returns the raw dependency map behind "order_for_rules_hash", for when you want to see what references what rather than just the resulting order.

Each templated var is scanned for [% VAR %] references and gets an entry listing the names it mentions. A var that references nothing gets an empty list. Nothing is checked for existence here, so a reference to a var that was never defined shows up in the map the same as any other; "order_for_rules_hash" is what dies on it.

- rules :: The rules hash ref to process.
    Default :: undef

Returns a hash ref of { var_name => [ names it references ] }, or an empty hash ref if the file has no vars_templated. Dies if rules is undef, is not a hash ref, holds a vars / vars_templated that is not a hash ref, or holds a vars_templated entry whose value is not a plain string.

my $depends = Log::Munger::RulesTemplateOrder->depends_for_rules_hash( 'rules' => $rules_hash );
# $depends->{TIME} = [ 'HOUR', 'MINUTE', 'SECOND' ]

order_for_rules_file

"order_for_rules_hash" for a rule file on disk. The file is loaded with "load_no_templating" in Log::Munger::RuleFileParser, which is the state the ordering has to be worked out in, and the resulting hash is handed straight over.

- file :: The file to load. Either a bare name resolved through the search
    path, such as "base", or a path. Required.
    Default :: undef

Returns an array ref of var names in the order they should be resolved. Dies if the file cannot be found or loaded.

my $order = Log::Munger::RulesTemplateOrder->order_for_rules_file( 'file' => 'base' );

depends_for_rules_file

"depends_for_rules_hash" for a rule file on disk, loaded the same way "order_for_rules_file" loads it.

- file :: The file to load. Either a bare name resolved through the search
    path, such as "base", or a path. Required.
    Default :: undef

Returns a hash ref of { var_name => [ names it references ] }. Dies if the file cannot be found or loaded.

my $depends = Log::Munger::RulesTemplateOrder->depends_for_rules_file( 'file' => 'base' );