JSONPathEx

A powerful and flexible Elixir library for parsing, evaluating, and navigating JSON data using JSONPath.

Features

• JSONPath Parsing: Robust support for JSONPath syntax, including recursive descent, filters, and array slicing.
• JSONPath Evaluation: Navigate and query JSON objects or arrays with ease.
• Highly Configurable: Modular design allows easy customization and extension.
• Efficient Parsing: Built on NimbleParsec, ensuring performance and flexibility.

Installation

Add jsonpath_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:jsonpath_ex, "~> 0.1.0"}
  ]
end

Then run:

mix deps.get

Usage

Evaluating JSONPath Expressions

The JSONPathEx module provides a convenient evaluate/2 function to parse and evaluate a JSONPath expression in one step:

iex> json_data = %{
...>   "store" => %{
...>     "book" => [
...>       %{
...>         "category" => "reference",
...>         "author" => "Nigel Rees",
...>         "title" => "Sayings of the Century",
...>         "price" => 8.95
...>       }
...>     ]
...>   }
...> }
iex> JSONPathEx.evaluate("$.store.book[*].title", json_data)
{:ok, ["Sayings of the Century"]}

Parsing JSONPath Expressions

Use JSONPathEx.parse/1 to parse a JSONPath string into an Abstract Syntax Tree (AST):

iex> JSONPathEx.parse("$.store.book[*].author")
{:ok, [root: "$", dot_child: ["store"], dot_child: ["book"], array: [array_wildcard: {:wildcard, "*"}], dot_child: ["author"]]}

Evaluating ASTs Directly

You can also parse and evaluate separately using JSONPathEx.Parser and JSONPathEx.Evaluator:

iex> {:ok, ast} = JSONPathEx.Parser.parse("$.store.book[*].author")
iex> json = %{
...>   "store" => %{
...>     "book" => [
...>       %{"author" => "Author 1"},
...>       %{"author" => "Author 2"}
...>     ]
...>   }
...> }
iex> JSONPathEx.Evaluator.evaluate(ast, json)
["Author 1", "Author 2"]

Supported JSONPath Features

• Root Selector ($)
• Current Context (@)
• Dot Notation (.key)
• Bracket Notation (['key'])
• Wildcard Selector (*)
• Recursive Descent (..)
• Array Slicing ([start:end:step])
• Filters ([?(@.key < 10)])
• Functions: length(), min(), max(), sum(), avg(), concat()
• Shorthand filters ([?@.key == 42] without extra parentheses)
• Escape sequences in quoted keys (\', \", \\)
• Quoted dot-child ($."key", $..'key')
• Nested filters ($[?(@.tags[?(@.name == "important")])])

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Commit your changes: git commit -m "Add my feature".
4. Push to the branch: git push origin feature/my-feature.
5. Create a pull request.

Please ensure all tests pass before submitting your pull request:

mix test

License

This project is licensed under the MIT License.