path: root/README.md

Datafu
======

Datafu is a Rust library for extracting data from config objects and other
arbitrary object graphs, using a custom query language. As a query language,
it takes on aspects of both XPath and jq, but differs significantly in scope.
As a library, it attempts to keep things relatively straightforward.

Comparison with XPath
---------------------

XPath is more-or-less standard. While it is primarily designed for XML, there
are implementations of XPath that can work with JSON and other formats. It's
also more or less type-aware and can do operations like numeric range checks
without the use of user callbacks.

Unlike XPath, Datafu is not primarily designed for XML, but rather as a more
general-purpose tool that can also be used for XML. It even supports cyclic
graphs, such as those which can be found in Lua tables.

Comparison with jq
------------------

jq is first and foremost a CLI tool. It's also Turing-complete. If an
[undecidable schema][halting_problem] isn't your thing, and the previous
section of this README didn't convince you to use XPath, then Datafu should be
your tool of choice.

[halting_problem]:
    https://en.wikipedia.org/wiki/Halting_problem
    "Halting problem (Wikipedia)"

License
-------

```text
Datafu - Rust library for extracting data from object graphs.
Copyright (C) 2021  Soni L.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
```