/ 
Set-Formula-0.01
River stage zero No dependents
/ Set::Formula

NAME

Set::Formula - Formula calculation for sets

VERSION

Version 0.01

SYNOPSIS

use Set::Formula;
formula_checker (string_containing_formula);    # syntax check without debug
formula_checker (string_containing_formula, 1); # syntax check with    debug

formula_calcul  (string_containing_formula, \%result, \%HoH_sets);    # without debug
formula_calcul  (string_containing_formula, \%result, \%HoH_sets, 1); # with    debug

equality_checker (\%set1, \%set2);              # without debug
equality_checker (\%set1, \%set2, 1);           # with    debug

DESCRIPTION

formula_checker  - checks syntax of formula without its calculation.
formula_calcul   - calculates formula without its syntax check.
equality_checker - checks, if 2 sets are equal.

Formula should be written in common arithmetic notation (infix notation)
and can contain unrestricted amount of nested parentheses ().

Supported set operators are
  "+"    - union,
  "-"    - complement,
  "^"    - intersection.

All these operators are binary operators, i.e. they require 2 operands.

Formula without parentheses is evaluated from left to right
with equal priority for all operators.
Parentheses increase priority of partial formula expressions.

White characters including new line in formula are accepted and ignored.
Thus formula might be placed into both a single line and multiple lines.

formula_checker and formula_calcul return nonzero on success,
the undefined value otherwise.

equality_checker returns 1 if both sets are equal, else 0.

TECHNICAL IMPLEMENTATION OF SETS

For formula_checker and formula_calcul
--------------------------------------
All formula operands must be highest level keys of a hash of hashes,
that is named in example below as %HoH_sets.
Lowest level keys of this hash of hashes form corresponding sets.
Values of lowest level hashes are irrelevant (can be undefined).

Name convention for formula operands: begin with a character, optionally
following by any amount of characters, digits, underlines.
Operand names are case sensitive.

For equality_checker
--------------------
Operands are sets, written in keys of one dimensional hashes.

EXAMPLES

use Set::Formula;

@A{qw (bisque  red      blue  yellow)} = (); 
@B{qw (bisque  brown    white yellow)} = (); 
@C{qw (magenta pink     green       )} = (); 
@D{qw (magenta pink     rose        )} = (); 
@E{qw (bisque  honeydew             )} = (); 
%HoH_sets = ( A=>\%A, B=>\%B, C=>\%C, D=>\%D, E=>\%E );

# or alternatively
%HoH_sets = ( 
   A => { bisque  => 0,  red      => 0,  blue  => 0,  yellow => 0, },
   B => { bisque  => 0,  brown    => 0,  white => 0,  yellow => 0, },
   C => { magenta => 0,  pink     => 0,  green => 0,               },
   D => { grey    => 0,  pink     => 0,  rose  => 0,               },
   E => { bisque  => 0,  honeydew => 0,                            }
);
#  A, B, C, D, F are operands. Every of them is a set, written in keys of sublevel hash.

$formula  = "A ^ ( B + (C ^ D) ) - E";
%result = ();  # this hash must be declared, but it must not be emptied before
               # call of formula_calcul()

# Usage of formula_checker() before formula_calcul() is recommended,
# but is not mandatory
formula_checker ($formula)                       || die "Error in formula\n";
formula_calcul  ($formula, \%result, \%HoH_sets) || die "Error in formula\n";

for (keys %result) {print "$_\n"}   # prints result of formula calculation

@expected_result{qw (magenta yellow)} = ();
if (equality_checker (\%result, \%expected_result)) { print "equal\n" }
else                                                { print "not equal\n" }

EXPORT

formula_checker,
formula_calcul,
equality_checker.

SEE ALSO

Part "Basic operations" - http://en.wikipedia.org/wiki/Set_(mathematics)
Infix notation          - http://en.wikipedia.org/wiki/Infix_notation

AUTHOR

Mart Rivilis, E<lt>rivilism@cpan.comE<gt>

BUGS

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

SUPPORT

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

You can also look for information at:

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Mart Rivilis

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.