Yupeek/booleano

=========================================
Booleano: Boolean Expressions Interpreter
=========================================



**Booleano** is an interpreter of `boolean expressions
<http://en.wikipedia.org/wiki/Boolean_expression>`_, a library to **define
and run filters** available as text (e.g., in a natural language) or in
`Python <http://python.org/>`_ code.


stable branche

.. image:: https://img.shields.io/travis/Yupeek/booleano/master.svg
    :target: https://travis-ci.org/Yupeek/booleano

.. image:: https://readthedocs.org/projects/booleano/badge/?version=latest
    :target: http://booleano.readthedocs.org/en/latest/

.. image:: https://coveralls.io/repos/github/Yupeek/booleano/badge.svg?branch=master
    :target: https://coveralls.io/github/Yupeek/booleano?branch=master

.. image:: https://img.shields.io/pypi/v/booleano.svg
    :target: https://pypi.python.org/pypi/booleano
    :alt: Latest PyPI version

.. image:: https://img.shields.io/pypi/dm/booleano.svg
    :target: https://pypi.python.org/pypi/booleano
    :alt: Number of PyPI downloads per month

.. image:: https://codeclimate.com/github/Yupeek/booleano/badges/gpa.svg
   :target: https://codeclimate.com/github/Yupeek/booleano
   :alt: Code Climate


development status

.. image:: https://img.shields.io/travis/Yupeek/booleano/develop.svg
    :target: https://travis-ci.org/Yupeek/booleano

.. image:: https://coveralls.io/repos/github/Yupeek/booleano/badge.svg?branch=develop
    :target: https://coveralls.io/github/Yupeek/booleano?branch=develop


In order to handle text-based filters, Booleano ships with a fully-featured
parser whose grammar is `adaptive
<http://en.wikipedia.org/wiki/Adaptive_grammar>`_: Its properties
can be overridden using simple configuration directives.

On the other hand, the library exposes a pythonic API for filters written
in pure Python. These filters are particularly useful to build reusable
conditions from objects provided by a third party library.

TLDR;
-----

a string + some variable = safe boolean evaluation

.. code:: python

    # is this character a minor guy with a "0" in his name and born after 1983 ?
    eval_boolean(
        'age < const:majority & "o" in name & birthdate > "1983-02-02"',
        {"name": "sokka", "age": 15, "birthdate": datetime.date(1984, 1, 1)},
        {'majority': 18},
        grammar_tokens={'belongs_to': 'in'}
    ) => True



The Fun Use Case
----------------

Booleano allow to safely evaluate an expression into something usable.

- ``user:name is "john" and user:surname in {"doe", "shepard"}``


+``{"user": {"name": "katara"}}`` => False
+``{"user": {"name": "john", "surname": "doe"}}`` => True

with some code, you can provide any type you want, and the expression can still be in text:

+``user:birthdate > "03-07-1987"``
+``duration > 1m30s``

check the sample dirrectory to view more running examples !


Documentation
-------------

The full documentation is at http://booleano.readthedocs.io/en/latest/.


Contribute
----------

this project was not created by the current maintainer. in fact, the knowlege of this project from us is fare from
perfect, but with 100% of test coverages, it's not hard to keep it running.

if you find a bug, or want some feature, feel free to create a issues, or a Pull Request, but keep in mind that
it can be hard for us to work on it. the best way to have it fixed, it's to write a Pull Request with passing tests,
and we will merge it if it's a good piece of code.

see CONTRIBUTING.rst to know how work with ease on this project.

Upgrade Note
------------

the old alpha release 1.0a1 is not compatible with newer version (starting with 1.1a1) because of heavy
import path changes. all import from the modules (__init__.py) is discouraged.


Credit
------

**forked** from  Gustavo Narea's booleano project on `launchpad.net <https://launchpad.net/booleano>`_.

**maintened** by yupeek


Links
-----

* `Web site <https://github.com/Yupeek/booleano>`_.
* `Bug reports <https://github.com/Yupeek/booleano/issues>`_.