# 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 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