https://github.com/balance-platform/ex_pression

Evaluate user input expressions
https://github.com/balance-platform/ex_pression

elixir elixir-library expression expression-evaluator user-input

Last synced: 9 days ago
JSON representation

Evaluate user input expressions

• Host: GitHub
• URL: https://github.com/balance-platform/ex_pression
• Owner: balance-platform
• License: mit
• Created: 2024-01-03T15:55:26.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2024-11-23T19:49:31.000Z (5 months ago)
• Last Synced: 2025-04-06T13:47:28.639Z (14 days ago)
• Topics: elixir, elixir-library, expression, expression-evaluator, user-input
• Language: Elixir
• Homepage:
• Size: 70.3 KB
• Stars: 11
• Watchers: 3
• Forks: 3
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-elixir - ex_pression - Evaluate user input expressions. (Text and Numbers)

README

        
# ExPression

[![Hex Version](https://img.shields.io/hexpm/v/ex_pression.svg)](https://hex.pm/packages/ex_pression)

[![Docs](https://img.shields.io/badge/docs-hexpm-blue.svg)](https://hexdocs.pm/ex_pression)

[![License](https://img.shields.io/hexpm/l/ex_pression.svg)](LICENSE)

[![Coverage Status](https://coveralls.io/repos/github/balance-platform/ex_pression/badge.svg?branch=master)](https://coveralls.io/github/balance-platform/ex_pression?branch=master)

Evaluate user input expressions.

## Installation

The package can be installed by adding `ex_pression` to your list of dependencies in `mix.exs`:

```elixir

def deps do

  [

    {:ex_pression, "~> 0.5.0"}

  ]

end

```

## Key features

1. **Safe** evaluation without access to other Elixir modules.

```elixir

iex> ExPression.eval("exit(self())")

{:error, %ExPression.Error{name: "UndefinedFunctionError", message: "Function 'self/0' was referenced, but was not defined", data: %{function: :self}}}

```

2. Support for **JSON** syntax and data types.

```elixir

iex> ExPression.eval("""

{

  "name": "ex_pression",

  "deps": ["xpeg"]

}

""")

{:ok, %{"name" => "ex_pression", "deps" => ["xpeg"]}}

```

3. Familiar **python**-like operators and standard functions.

```elixir

iex> ExPression.eval(~s/{"1": "en", "2": "fr"}[str(int_code)]/, bindings: %{"int_code" => 1})

{:ok, "en"}

```

4. **Extend** expressions by providing Elixir module with functions that you want to use.

```elixir

defmodule MyFunctions do

  # use $ special symbol in expressions

  def handle_special("$", date_str), do: Date.from_iso8601!(date_str)

  # Use diff function in expressions

  def diff(date_1, date_2), do: Date.diff(date_1, date_2)

end

iex> ExPression.eval(~s/diff($"2023-02-02", $"2022-02-02")/, functions_module: MyFunctions)

{:ok, 365}

```

Full language description can be found in [FULL_DESCRIPTION.md](./FULL_DESCRIPTION.md)

## Implementation

String representation of expression is parsed into AST form. Parsing is done with PEG grammar parser [xpeg](https://github.com/zevv/xpeg). Grammar is defined in module `ExPression.Parser.Grammar`.

AST interpretation logic is written in plain `Elixir` in module `ExPression.Interpreter`.

## Contribution

Feel free to make a pull request. All contributions are appreciated!