``````package Decision::ParseTree;

use base qw{Exporter};
our @EXPORT_OK = qw{ParseTree};

use warnings;
use strict;

Decision::ParseTree - Replacing waterfall IF-ELSIF-ELSE blocks

Version 0.041

=cut

our \$VERSION = '0.041';

Death to long if-elsif-else blocks that are hard to maintain, and hard to
explain to your manager. Heres an overly simplistic example:

if ( \$obj->is_numeric ) {
if ( \$obj->is_positive ) {
print 'Positive Number';
}
elsif ( \$obj->is_negative )
print 'Negative Number';
}
else {
print 'Looks like zero';
}
else {
print 'Non-Numeric Value';
}

---
- is_num :
0 : Non-Numeric Value
1 : - is_pos :
1 : Positive Number
- is_neg :
= : Looks like zero
1 : Negative Number
...

package Rules;
use Scalar::Util;

sub is_num {
my ( \$self, \$obj ) = @_;
return (Scalar::Util::looks_like_number(\$obj->{value})) ? 1 : 0;
}

sub is_pos {
my ( \$self, \$obj ) = @_;
return (\$obj->{value} > 0 ) ? 1 : 0;
}

sub is_neg {
my ( \$self, \$obj ) = @_;
return (\$obj->{value} < 0 ) ? 1 : 0;
}

=head3 Goal Object to be passed thru the rules

package Number;

sub new {
my ( \$class, \$value ) = @_
my \$self = { parse_path => [],
value => \$value };
return bless \$self, \$class;
}

=head3 Replacement to that if-else block

use Decision::ParseTree q{ParseTree};

my \$rules = Rules->new;

print ParseTree( \$tree, \$rules, Number->new(10) ); # Positive Number
print ParseTree( \$tree, \$rules, Number->new(-1) ); # Negative Number
print ParseTree( \$tree, \$rules, Number->new(0)  ); # Looks like zero
print ParseTree( \$tree, \$rules, Number->new('a')); # Non-Numeric Value

=head1 YAML as a Decision tree

To make this all work we need a few parts:

=over

=item * A rules object: This will be a library of rules.

=item * An object that will be passed thru the rules.

=item * A YAML doc that outlines your decision tree.

=back

So this all started as a way to make a decision tree thats easy to parse and
easy to read for non-programmers. So to do this I looked to YAML, it's easy
to read and easy to parse. Though make this work we have some hard and fast
rules to follow for the tree construction:

=over

=item * RULES are a key value pair

=over

=item * the key is the method to run in the rules object

=item * the value must be an arrayref or hashref

=back

=item * ARRAYS are a series of rules run in order

=item * HASHES are a series of answers

=item * SCALARS are endpoints

=back

=head2 Why add more parts, why blow everything in to separate objects.

Sometimes you have to make things messy before they can get clean.

Theres a flexibility that comes with breaking things apart in to nice, neat
little chunks. By separating the rule logic in to one place you can make
very complex rules that do not gunk up your code. You pull the order of these
rules in to another place as it's completely possible that you would want to
tweak the order. And lastly you need to glue these separate things together,
so you have an object that gets passed thru to make this all work. Tada!

It would be nice to whip up a big example here to show all the interesting
bits, sadly I can't think of a good example. Ideas?

=over

=item * Selecting a tests to run for hardware

=item * Building settings/configuration files on the fly for varried hardware.

=item * Would any one like to use this to write up a GO AI engine? Chess?

=back

=over

=over

=item * If \$obj->{parse_path} exists then every step that this obj takes thru
the rules will be tracked. This path will be stored as an array ref, of hash refs.

\$obj = Number->new(10);
ParseTree( \$tree, \$rules, \$obj );
# \$obj->{parse_path} will now look like :
#   [  { 'is_num' => 1 },
#      { 'is_pos' => 1 },
#   ]

=item * If \$obj->{parse_answer} exists then, when an answer is found, then it
gets stored here as well as being returned.

=back

=back

ParseTree is the only thing that can get exported, it's also the only thing in
here, so export away.

Runs \$obj thru \$tree, using \$rules as the library of rules.

Returns the first endpoint that you run into as the answer.

=cut

#===  FUNCTION  ================================================================
#         NAME:  ParseTree
#      PURPOSE:  walk a decision tree to get an answer
#   PARAMETERS:  \$tree : Expected to be a big array ref of stuff pulled from YAML
#                \$rules: an object of rules that holds \$tree's nodes
#                \$obj  : The concept is that this \$obj is what is passed thru the
#                        rules. So build your rules as though \$obj will be passed
#                        to them.
#                        Also, there are two 'plugins' for \$obj:
#                         \$obj->{parse_path}   : if exists it will contain the path
#                                                that the \$obj took
#                         \$obj->{parse_answer} : if exists it will hold the result
#      RETURNS:  the proper value from \$tree or undef
#       THROWS:  there are many assertions that will die on failure
#===============================================================================

sub ParseTree {
use YAML; # to get YAML::Value
use Carp::Assert::More;
my(\$tree, \$rules, \$obj) = @_;

assert_listref( \$tree, q{A list of rules must be an array.} );

NODE : foreach my \$task (@\$tree) {

#---------------------------------------------------------------------------
#  grab the values as they are the answers that we will check agenst
#---------------------------------------------------------------------------
assert_hashref( \$answers, q{You answers need to be presented as a hashref.} );

#---------------------------------------------------------------------------
#  grab the action
#---------------------------------------------------------------------------

#---------------------------------------------------------------------------
#  run the action to get the reply
#---------------------------------------------------------------------------
assert_defined( \$rules->can(\$action), q{Your rule needs to exist in your rules object.} );

#---------------------------------------------------------------------------
#  Log to the obj if theres a place to log to
#---------------------------------------------------------------------------
if (defined \$obj->{parse_path}) {
}

#---------------------------------------------------------------------------
#  handle default YAML values if they exist if not by spec if we get
# undef back we continue to the next node
#---------------------------------------------------------------------------
) {
# YAML::Value is a constant in YAML that specifies any default (=) key
} else {
}
}

#---------------------------------------------------------------------------
#  Deal with sub trees
#---------------------------------------------------------------------------

#---------------------------------------------------------------------------
#---------------------------------------------------------------------------
}

}
return undef; #catch all failure... this should never happen
}

=over

=item * Currently \$tree is expected to be a pre-parsed YAML File, This should
change here soon to also accept a filename. Currently though it does not.

=item * would like even more examples.

=item * need to flush out the docs more.

=back

ben hengst, C<< <notbenh at cpan.org> >>

Please report any bugs or feature requests to
C<bug-decision-parsetree at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Decision-ParseTree>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

You can find documentation for this module with the perldoc command.

perldoc Decision::ParseTree

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Decision-ParseTree>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Decision-ParseTree>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Decision-ParseTree>

=item * Search CPAN

L<http://search.cpan.org/dist/Decision-ParseTree>

=back