Eqn

Eqn uses the Treetop parser generator to safely evaluate mathematical expressions in Ruby.

Installation

Add this line to your application's Gemfile:

gem 'eqn'

And then execute:

$ bundle

Or install it yourself as:

$ gem install eqn

Usage

To evaluate an equation string, run the following:

Eqn::Calculator.calc('1 + 1')
# => 2

You can also check if an equation is valid:

Eqn::Calculator.valid?('1 + 1')
# => true
Eqn::Calculator.valid?('1 + / 1')
# => false

If you want to peek at how Eqn is parsing an equation, run the following to get the syntax tree:

Eqn::Parser.parse('1 + 1')
# => <syntax tree is printed>

Eqn follows the standard mathematical order of operations: parentheses, exponentiation, multiplication/division, addition/subtraction. It ignores whitespace, so 1 + 1 === 1+1. (However, it does not ignore whitespace between two numbers, so 1 1 is invalid.)

Variables

Eqn supports dynamically inserting values into an equation. Variables are passed to the calculator method via a hash; variable names may contain any lowercase or uppercase letters. Some examples:

Eqn::Calculator.calc('a + 1', a: 1)
# => 2

Eqn::Calculator.calc('5 * value', value: 2.5)
# => 12.5

Eqn::Calculator.calc('if(a > 10, b, c)', a: 15, b: 1, c: 0) # see below for function documentation
# => 1

If you need distinct equations with variable sets, you can instantiate separate instances:

calc = Eqn::Calculator.new('1 + abc', abc: 2.0)
calc.calc
# => 3.0
calc_two = Eqn::Calculator.new('1 + abc', abc: 5.0)
calc_two.calc
# => 6.0

On calculator instances, variables can be set via key-value syntax, hash syntax, or as a method:

calc = Eqn::Calculator.new('1 + abc')
calc.set(:abc, 3.0)
calc.abc
# => 3.0
calc.set(abc: 4.0)
calc.abc
# => 4.0
calc.abc = 5.0
calc.abc
# => 5.0

Functions

Eqn presently supports four functions:

Syntax: if(comparison, value_if_true, value_if_false)

For example, if(5 > 3, 1, 2) would evaluate to 1.

round

Syntax: round(number, [decimals])

Rounds the number up if the decimal is greater than 0.5 and down otherwise (i.e. "normal" rounding). Optionally, pass a number of decimal places to round to as a second parameter (the default is 0).

roundup

Syntax: roundup(number, [decimals])

Rounds the number up (i.e. ceiling function). Optionally, pass a number of decimal places to round to as a second parameter (the default is 0).

rounddown

Syntax: rounddown(number, [decimals])

Rounds the number down (i.e. floor function). Optionally, pass a number of decimal places to round to as a second parameter (the default is 0).

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

The gem uses rspec for testing and appraisal to test against multiple versions of treetop (the only runtime dependency). From the command line, run bundle exec appraisal install to install gems and bundle exec appraisal rspec to run the complete test suite. (You can still run bundle exec rspec to only test against the latest version of treetop while developing.)

Authorship

Written by Zach Schneider for Aha!, the world's #1 product roadmap software

Contributing

Fork it (https://github.com/schneidmaster/eqn/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

msnider/eqn