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:
if
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; run rspec
from the application root to execute the tests.
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