###################################################################### YAML::Logic 0.05 ###################################################################### NAME YAML::Logic - Simple boolean logic in YAML SYNOPSIS use YAML::Syck qw(Load); use YAML::Logic; my $logic = YAML::Logic->new(); ### Tests defined somewhere in a YAML file ... my $data = Load(q{ # is $var equal to "foo"? rule: - $var - foo }); ### Tests performed in application code: if( $logic->evaluate( $data->{rule}, { var => "foo" }) ) { print "True!\n"; } DESCRIPTION YAML::Logic allows users to define simple boolean logic in a configuration file, without permitting them to run arbitrary code. While Perl code can be controlled with the "Safe" module, "Safe" can't prevent the user from defining infinite loops, exhausting all available memory or crashing the interpreter by exploiting well-known perl bugs. YAML::Logic isn't perfect in this regard either, but it makes it reasonably hard to define harmful code. The syntax for the boolean logic within a YAML file was inspired by John Siracusa's "Rose::DB::Object::QueryBuilder" module, which provides data structures to define logic that is then transformed into SQL. YAML::Logic takes the data structure instead and transforms it into Perl code. For example, the data structure to check whether a variable $var is equal to a value "foo", looks like this: [$var, "foo"] It's a reference to an array containing both the value of the variable and the value to compare it with. In YAML, this looks like rule: - $var - foo and this is exactly the syntax that YAML::Logic accepts. Note that after parsing the YAML configuration above, you need to pass *only* the array ref inside the "rule" entry to YAML::Logic's "evaluate()" method: $logic->evaluate( $yaml_data->{rule}, ... Passing the entire YAML data would cause an error with YAML::Logic, as it expects to receive an array ref. Variable Interpolation Note that variables like $var will be interpolated so that they'll represent their value before the evaluation starts. So if you have rule: - $var - foo and run my $data = YAML::Load( $yaml ); my $rc = $logic->evaluate( $data->{rule}, { var => "bar" } ); then YAML::Logic will substitute $var by the string "bar", and then run the test ["bar", "foo"] which checks if "bar" equals "foo". Since this is false, "evaluate" returns false. Variable interpolation happens on both sides of the comparison, so comparing rule: - $foo - $bar will search for two variables, "foo" and "bar", replace the placeholders by the variable values and then compare the two entries. If a referenced variable is immediately followed by some text, you can also use Perl's "${foo}" notation to reference a variable: rule: - ${foo}text - $bar Several comparisons can be combined by lining them up in the array. The lineup [$var1, "foo", $var2, "bar"] returns true if $var1 is equal to "foo" *and* $var2 is equal to "bar". In YAML::Logic syntax, these two ANDed comparisons are written as rule: - $var1 - foo - $var2 - bar in a YAML file. Interpolation is done by the "Template Toolkit", so all the magic it does for arrays and hashes applies: rule: - $hash.somekey - foo with my $data = YAML::Load( $yaml ); my $rc = $logic->evaluate( $data->{rule}, { hash => { somekey => "foo" } } ); will test if "foo" equals "foo" and hence return a true value. Likewise, rule: - $array.1 - el2 with my $data = YAML::Load( $yaml ); my $rc = $logic->evaluate( $data->{rule}, { array => [ 'el1', 'el2' ] } ); will test if "el2" equals "el2" and return a true value. Check "perldoc Template" or read the O'Reilly Template Toolkit book for a more detailed explanation of Template's variable interpolation magic. Other Comparators Not only equality can be tested. In addition, these Perl operators are supported: eq ne lt gt < <= > >= == != =~ like The way to specify a different operator $op is to put it as key into a hash: [ $var, { $op, $value } ] So, the previous rule comparing $var to "foo" can be written as rule: - $var - eq: foo which is essentially running $var eq "foo" in Perl. To perform a numerical comparison, use the "==" operator, rule: - $var - ==: 123 which runs a test of "$var == 123" instead. Regular Expressions Regular expression matching is supported as well, so to verify if $var matches the regular expression "/^foo/", use rule: - $var - like: "^foo" or rule: - $var1 - =~: "^foo" Both are equivalent. Regular expressions are given without delimiters, e.g. if you want to match against /abc/, simply use rule: - '$var' - like: abc To add regex modifiers like "/i" or "/ms", use the "(?...)" syntax. The setting rule: - '$var' - like: (?i)abc will match like "$var =~ /abc/i". Logical NOT A logical NOT is expressed by putting an exclamation mark in front of the variable, so ["!$var1", "foo"] will return true if $var1 is NOT equal to "foo". The YAML notation is rule: - "!$var1" - foo for this logical expression. Note that YAML requires putting a string starting with an exclatmation mark in quotes. By default, additional rules are chained up with a logical AND operator, so to check if a variable is not set to "foo" and not set to "bar", use: rule: - '!$var' - foo - '!$var' - bar And to verify that the variable matches neither /^foo.*/ nor /^bar.*/, use: rule: - '!$var' - - like: "^foo.*" - like: "^bar.*" Also note that "^foo.*" requires quotes in YAML. Logical OR To specify a rule that is satisfied if *any* of a series of tests succeeds, use the 'or' keyword in place of a variable: [ "or", [ $var, "foo", $var, "bar" ] ] This data structure indicates that the entire test is supposed to return true if either "$var eq "foo"" or "$var eq "bar"" holds true. It looks like this in YAML: rule: - or - - $var - foo - $var - bar Pay close attention to the indentation: After the "- or" follows a line with a dash at the same indentation level, followed by a sub-array which has its elements indented to the next level. Logical AND By default, YAML::Logic chains up clauses by logical ANDs, i.e. rule: - $var1 - foo - $var2 - bar checks if $var1 is equal to "foo" *and* $var2 is equal to "bar". Alternatively, the "and" keyword can be used similar to the "or" keyword explained in the previous section: rule: - and - - $var - foo - $var - bar With the above, you can't have variables named "and" or "or". If you do, use a hash key, as explained below. Defined-ness The Template Toolkit interpolates undefined variables as empty strings. But using TT's virtual methods, you can test if a variable is defined in the template context or not. The YAML logic rule: - $var1.defined - 1 will return true if $var1 has been defined. Conversely, rule: - $var1.defined - "" will return true if the variable $var1 is *not* defined. Note that defined returns 1 on definedness and the empty string ("") if the variable is not defined. Logical Set Operations (not yet implemented) rule: - $var1 - - element1 - element2 (not yet implemented) rule: - $var1 - like: - element1 - element2 YAML Traps The original YAML implementation has a number of nasty bugs (e.g. RT42015), so using YAML::Syck is recommended, which is a both faster and more reliable parser. Also, YAML as a configuration format can be tricky at times. For example if you type in my $data = Load(q{ # is $var equal to "foo"? rule: - $var - foo }); literally (like in the SYNOPSIS section of this document), keeping the indentation intact, YAML will complain that it's not happy about the final blank line, which contains whitespace characters: Code: YAML_PARSE_ERR_NO_FINAL_NEWLINE To avoid this, either use a YAML file, in which not using unnecessary indentation will feel natural. When using YAML strings, make sure there's no last line containing just whitespace, before feeding it to the YAML parser: my $yaml_string = q{ # is $var equal to "foo"? rule: - $var - foo }; $yaml_string =~ s/^\s+\Z//m; my $data = Load($yaml_string); Also, certain characters have a special meaning in YAML, so you can't write # WRONG rule: - $var - !blah! because YAML will parse that to [$var, undef] within the "rule" hash entry. Why? Lines starting with an exclamation mark are *tags* in YAML. To avoid getting tripped up by this, use quotes: # CORRECT rule: - $var - "!blah!" which correctly parses to [$var, "!blah!"] within the "rule" hash entry instead. ERROR HANDLING If a rule fails, the error() method can be used to obtain a detailed textual description on why a comparison or a regex match failed. if( $logic->evaluate( $data->{rule}, { var => "foo" }) ) { print "True!\n"; } else { print "Failed, reason is: ", $logic->error(); } This will print something like Failed, reason is: Test ["foo" eq "bar"] returned [] saying the when it compared "foo" to "bar", the result was the empty string (Perl's idea of 'false'). TROUBLESHOOTING Error Message: Unknown type: HASH(0x857d51c) at YAML/Logic.pm This means that you've fed a hash to YAML::Logic. For example, if your YAML file says rule: - "foo" - "bar" you've probably read the YAML file like my $data = LoadFile( $file ); and now the data looks like { rule => ["foo", "bar"] } which, when you feed it unmodified to YAML::Logic as in $logic->evaluate( $data ); presents the "rule" field to YAML::Logic, which it doesn't understand. Pass the content of the rule to YAML::Logic instead: $logic->evaluate( $data->{rule} ); and it will work as expected. LEGALESE Copyright 2008 by Mike Schilli, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR 2008, Mike Schilli <cpan@perlmeister.com>