/ 
Math-Calc-Parser-0.005
River stage one • 2 direct dependents • 2 total dependents
4 ++
/ Math::Calc::Parser

NAME

Math::Calc::Parser - Parse and evaluate mathematical expressions

SYNOPSIS

  use Math::Calc::Parser 'calc';
  
  my $result = calc '2 + 2';
  my $result = calc 'int rand 5';
  my $result = calc 'sqrt -1';
  eval { $result = calc '1/0'; 1 } or die $@;
  
  # Class methods
  my $result = Math::Calc::Parser->evaluate('2 + 2');
  my $result = Math::Calc::Parser->evaluate('3pi^2');
  my $result = Math::Calc::Parser->evaluate('0.7(ln 4)');
  
  # With more advanced error handling
  my $result = Math::Calc::Parser->try_evaluate('malformed(expression');
  if (defined $result) {
    print "Result: $result\n";
  } else {
    print "Error: $Math::Calc::Parser::ERROR\n";
  }
  
  # Or as an object for more control
  my $parser = Math::Calc::Parser->new;
  $parser->add_functions(triple => { args => 1, code => sub { $_[0]*3 } });
  $parser->add_functions(pow => { args => 2, code => sub { $_[0] ** $_[1] });
  $parser->add_functions(one => sub { 1 }, two => sub { 2 }, three => sub { 3 });
  
  my $result = $parser->evaluate('2(triple one)'); # returns 6
  my $result = $parser->evaluate('pow(triple two, three)'); # (2*3)^3
  my $result = $parser->try_evaluate('triple triple');
  die $parser->error unless defined $result;
  
  $parser->remove_functions('pi', 'e');
  $parser->evaluate('3pi'); # dies

DESCRIPTION

Math::Calc::Parser is a simplified mathematical expression evaluator with support for complex and trigonometric operations, implicit multiplication, and perlish "parentheses optional" functions, while being safe for arbitrary user input. It parses input strings into a structure based on Reverse Polish notation (RPN), and then evaluates the result. The list of recognized functions may be customized using "add_functions" and "remove_functions".

FUNCTIONS

calc

  use Math::Calc::Parser 'calc';
  my $result = calc '2+2';
  
  $ perl -MMath::Calc::Parser -E 'say calc "2+2"'

Compact exportable function wrapping "evaluate" for string expressions. Throws an exception on error.

ATTRIBUTES

error

  my $result = $parser->try_evaluate('2//');
  die $parser->error unless defined $result;

Returns the error message after a failed "try_evaluate".

METHODS

parse

  my $parsed = Math::Calc::Parser->parse('5 / e^(i*pi)');

Parses a mathematical expression. Can be called as either an object or class method. On success, returns an array reference representation of the expression in RPN notation which can be passed to "evaluate". Throws an exception on failure.

evaluate

  my $result = Math::Calc::Parser->evaluate($parsed);
  my $result = Math::Calc::Parser->evaluate('log rand 7');

Evaluates a mathematical expression. Can be called as either an object or class method, and the argument can be either an arrayref from "parse" or a string expression. Returns the result of the expression on success or throws an exception on failure.

try_evaluate

  if (defined (my $result = Math::Calc::Parser->evaluate('floor 2.5'))) {
    print "Result: $result\n";
  } else {
    print "Error: $Math::Calc::Parser::ERROR\n";
  }
  
  if (defined (my $result = $parser->evaluate('log(5')) {
        print "Result: $result\n";
  } else {
        print "Error: ".$parser->error."\n";
  }

Same as "evaluate" but instead of throwing an exception on failure, returns undef and sets $Math::Calc::Parser::ERROR to the error message. If called on an object instance, the error can be retrieved using the "error" accessor.

add_functions

  $parser->add_functions(
    my_function => { args => 5, code => sub { return grep { $_ > 0 } @_; } },
    other_function => sub { 20 }
  );

Adds functions to be recognized by the parser object. Keys are function names and must consist only of word characters. Values are either a hashref containing args and code keys, or a coderef that is assumed to be a 0-argument function. args must be an integer greater than or equal to 0. code or the passed coderef will be called with the numeric operands passed as parameters, and must either return a numeric result or throw an exception.

remove_functions

  $parser->remove_functions('rand','nonexistent');

Removes functions from the parser object if they exist. Can be used to remove default functions as well as functions previously added with "add_functions".

OPERATORS

Math::Calc::Parser recognizes the following operators with their usual definitions.

  +, -, *, /, %, ^, <<, >>

Note: + and - can represent a unary operation (negation) in addition to addition and subtraction.

DEFAULT FUNCTIONS

Math::Calc::Parser parses several functions by default, which can be customized using "add_functions" or "remove_functions" on an object instance.

acos
asin
atan

Inverse sine, cosine, and tangent.

ceil

Round up to nearest integer.

cos

Cosine.

e

Euler's number.

floor

Round down to nearest integer.

i

Imaginary unit.

int

Cast (truncate) to integer.

ln

Natural log.

log

Log base 10.

logn

Log with arbitrary base given as second argument.

pi

π

rand

Random value between 0 and 1.

sin

Sine.

sqrt

Square root.

CAVEATS

While parentheses are optional for functions with 0 or 1 argument, they are required when a comma is used to separate multiple arguments.

Due to the nature of handling complex numbers, the evaluated result may be a Math::Complex object. These objects can be directly printed or used in numeric operations but may be more difficult to use in comparisons.

BUGS

Report any issues on the public bugtracker.

AUTHOR

Dan Book, dbook@cpan.org

COPYRIGHT AND LICENSE

Copyright 2015, Dan Book.

This library is free software; you may redistribute it and/or modify it under the terms of the Artistic License version 2.0.

SEE ALSO

Math::Complex