.. ratus documentation master file, created by
   sphinx-quickstart on Fri Feb  7 20:38:37 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to ratus's documentation!
=================================

.. toctree::
   :maxdepth: 2

   usage
   language
   tokenisation
   parsing
   execution
   evaluation


Ratus is a simple expression language that can be used to easily extend Python
applications with an embedded expression language. Evaluating basic expressions
is as simple as:

::

    from ratus import Evaluator

    evaluator = Evaluator()
    evaluator.evaluate("1 + 1") # 1
    evaluator.evaluate("1 > 1") # False
    evaluator.evaluate("if(1 < 2, 10, 5)") # 5

Expression language
-------------------

The ratus expression language allows the following constructs:

- Int, Float and String literals
- Comparison operations

  - Greater than (`>`)
  - Greater than or equal (`>=`)
  - Less than (`<`)
  - Less than or equal (`<=`)
  - Equal (`=`)
  - Not equal (`!=`)

Function injection
------------------

You can add new functions by creating the `Evaluator` object with a dictionary
argument in the constructor that maps the function name to a callable that
performs the desired behavior.

::

    from ratus import Evaluator

    def f(x):
        return x**2

    evaluator = Evaluator({
        "f": f,
        "g": lambda x: x**3
    })
    evaluator.evaluate("f(2)") # 4
    evaluator.evaluate("g(2)") # 8

Unary/Binary operation override
-------------------------------

You can override what the unary and binary operations do by providing a
dictionary as the `unary_ops` and `binary_ops` argument, respectively, to
`Evaluator`'s constructor. This will update the mapping for the specified
operations but will not change any of the others.

::

    from ratus import Evaluator, BinaryOpTypes, UnaryOpTypes

    def gt(x, y):
        return x >= y
    def neg(x):
        return x

    evaluator = Evaluator(
        binary_ops={BinaryOpTypes.GREATER: gt},
        unary_ops={UnaryOpTypes.NEGATIVE: neg}
    )
    evaluator.evaluate("-1") # 1
    evaluator.evaluate("1 > 1") # True

This is a contrived example and hopefully not something you would need to do but
it serves as an example of how you can alter the behavior of all operators.


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`