/ 
Eval-Logic-1
River stage zero No dependents
/ Eval::Logic

NAME

Eval::Logic - Evaluate simple logical expressions from a string.

DESCRIPTION

With this module simple logical expressions from strings which use logical operators like and, or, not and the ternary operator can be evaluated.

This module was created because I wanted to be able to use a simple argument validator which can be fully configured from YAML. This module allows a specification like "we require a_value and some_other_value, or a a_third_option should be specified" to be expressed as a simple string "(a_value && some_other_value) || a_third_option".

The module uses eval() and while it does take care to check for anything other than a logical expression you should take a lot of care when evaluating expressions from an untrusted source (in fact, I would not recommend doing that at all).

SYNOPSIS

$l = Eval::Logic->new ( '(a || b) && c' );
$l->evaluate ( a => 1, b => 0, c => 1 ); 	# returns 1 for true
$l->evaluate ( a => 1, b => 1, c => 0 );	# returns 0 for false
$l->evaluate_if_true ( 'a', 'b' );		# an alternative for that second example
$l->evaluate_if_false ( 'c' );			# and another alternative

METHODS

new (constructor)

$l = Eval::Logic->new ( 'a && b' );

Create a new instance of Eval::Logic. Optionally an expression can be specified which is immediately loaded in the object, see the expression method for more information about the expression syntax.

expression

$expression = $l->expression;
$l->expression ( 'a && b' );

If called without an argument the current expression is returned, otherwise the current expression in this object is replaced by whatever was specified. If multiple strings are specified they are combined in a single expression that will require all individual expressions to be true.

An expression is a string in which the truth values are specified as simple (bare) words which can contain letters, digits and underscores and which must not begin with a digit. In addition to this, the Perl logical operators && (and), || (or), ! (not) can be used, as well as the ternary ?: operator and parentheses. Whitespace is ignored.

The barewords TRUE and FALSE have a special meaning which you can probably guess.

The method will croak if the expression provided is invalid.

evaluate

$outcome = $l->evaluate ( a => 1, b => 0 );

Evaluate the logic expression given the specified truth values. If no default for undefined truth values is specified and some truth values are not defined or not present, a warning is given.

The outcome is returned as 1 for true or 0 for false.

evaluate_if_false

$outcome = $l->evaluate_if_false ( 'a' );

Evaluate the logic expression given the specified values to be false, and all other values to be true. This is a shortcut to the evaluate method.

evaluate_if_true

$outcome = $l->evaluate_if_true ( 'b' );

Evaluate the logic expression given the specified values to be true, and all other values to be false. This is a shortcut to the evaluate method.

truth_values

@truth_values = $l->truth_values;

Return a list of all variable truth values which are present in the currently loaded expression.

undef_default

$default = $l->undef_default;
$l->undef_default ( $default );

Returns the current default for undefined truth values if specified without an argument, or sets the default value to the specified argument. If you want undefined values to default to false you must explicitly call this method with an argument that is defined and evaluates to false to suppress warnings given about undefined values by the evaluate method.

AUTHOR

Sebastiaan Hoogeveen <pause-zebaz@nederhost.nl>

COPYRIGHT

Copyright (c) 2016 Sebastiaan Hoogeveen. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html