ENH: Add jsonlogic binary (#23)

* ENH: Add jsonlogic binary

Add a binary to use jsonlogic from the commandline. Input data can be
provided as an argument or via stdin. Multiple calls can be chained
together, parsing the output of the previous call as data.

* FIX: typo on optional

* DOC: more extensive cmdline example

Author: mplanchard

Diff for: CHANGELOG.md

@@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## Added
+
+- A new `cmdline` feature that builds a `jsonlogic` binary for JsonLogic on
+  the commandline
+
+## [0.1.3] - 2020-07-15
+
+- More minor CI fixes
+
 ## [0.1.2] - 2020-07-14
 
 ### Chore
@@ -15,7 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.1] - 2020-07-14
 
 ### Fixed
-- The Python source dist wasn't generating a Cargo lockfile prior to attempting 
+- The Python source dist wasn't generating a Cargo lockfile prior to attempting
   to determine the package version, causing the `cargo pkgid` command to fail
 
 ### Chore

Diff for: Cargo.toml

@@ -18,7 +18,13 @@ version = "0.1.3"
 # lib for regular rust stuff
 crate-type = ["cdylib", "lib"]
 
+[[bin]]
+name = "jsonlogic"
+path = "src/bin.rs"
+required-features = ["cmdline"]
+
 [features]
+cmdline = ["anyhow", "clap"]
 default = []
 python = ["cpython"]
 wasm = ["wasm-bindgen"]
@@ -38,6 +44,14 @@ features = ["extension-module"]
 optional = true
 version = "0.5"
 
+[dependencies.anyhow]
+optional = true
+version = "~1.0.31"
+
+[dependencies.clap]
+optional = true
+version = "~2.33.1"
+
 [dev-dependencies.reqwest]
 features = ["blocking"]
 version = "~0.10.6"

Diff for: README.md

@@ -32,11 +32,17 @@ languages. The table below describes current language support:
 
 ### Rust
 
-Just add to your `Cargo.toml`:
+To use as a Rust library, add to your `Cargo.toml`:
 
 ``` toml
 [dependencies]
-jsonlogic-rs = "~0.1.1"
+jsonlogic-rs = "~0.1"
+```
+
+If you just want to use the commandline `jsonlogic` binary:
+
+``` sh
+cargo install jsonlogic-rs --features cmdline
 ```
 
 ### Node/Browser
@@ -52,14 +58,15 @@ Note that the package is distributed as a node package, so you'll need to use
 
 ### Python
 
-Wheels are distributed for many platforms, so you should often be able to just
-run:
+Supports Python 3.6+.
+
+Wheels are distributed for many platforms, so you can often just run:
 
 ``` sh
 pip install jsonlogic-rs
 ```
 
-If a wheel does _not_ exist for your system, this will attempt to build the 
+If a wheel does _not_ exist for your system, this will attempt to build the
 package. In order for the package to build successfully, you MUST have Rust
 installed on your local system, and `cargo` MUST be present in your `PATH`.
 
@@ -71,15 +78,15 @@ See [Building](#Building) below for more details.
 
 ```rust
 use jsonlogic_rs;
-use serde_json::json;
+use serde_json::{json, from_str, Value};
 
-// You can pass JSON values deserialized with serde straight
-// into apply().
+// You can pass JSON values deserialized with serde straight into apply().
 fn main() {
+    let data: Value = from_str(r#"{"a": 7}"#)
     assert_eq!(
         jsonlogic_rs::apply(
             json!({"===": [{"var": "a"}, 7]}),
-            json!({"a": 7}),
+            data,
         ),
         json!(true)
     );
@@ -109,14 +116,87 @@ res = jsonlogic_rs.apply(
 
 assert res == True
 
-# If You have serialized JsonLogic and data, the `apply_serialized` method can 
+# If You have serialized JsonLogic and data, the `apply_serialized` method can
 # be used instead
 res = jsonlogic_rs.apply_serialized(
     '{"===": [{"var": "a"}, 7]}',
     '{"a": 7}'
 )
 ```
 
+### Commandline
+
+``` raw
+Parse JSON data with a JsonLogic rule.
+
+When no <data> or <data> is -, read from stdin.
+
+The result is written to stdout as JSON, so multiple calls
+can be chained together if desired.
+
+USAGE:
+    jsonlogic <logic> [data]
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+ARGS:
+    <logic>    A JSON logic string
+    <data>     A string of JSON data to parse. May be provided as stdin.
+
+EXAMPLES:
+    jsonlogic '{"===": [{"var": "a"}, "foo"]}' '{"a": "foo"}'
+    jsonlogic '{"===": [1, 1]}' null
+    echo '{"a": "foo"}' | jsonlogic '{"===": [{"var": "a"}, "foo"]}'
+
+Inspired by and conformant with the original JsonLogic (jsonlogic.com).
+```
+
+Run `jsonlogic --help` the most up-to-date usage.
+
+An example of chaining multiple results:
+
+``` sh
+$ echo '{"a": "a"}' \
+    | jsonlogic '{"if": [{"===": [{"var": "a"}, "a"]}, {"result": true}, {"result": false}]}' \
+    | jsonlogic '{"if": [{"!!": {"var": "result"}}, "result was true", "result was false"]}'
+
+"result was true"
+```
+
+Using `jsonlogic` on the cmdline to explore an API:
+
+``` sh
+> curl -s "https://catfact.ninja/facts?limit=5"
+
+{"current_page":1,"data":[{"fact":"The Egyptian Mau is probably the oldest breed of cat. In fact, the breed is so ancient that its name is the Egyptian word for \u201ccat.\u201d","length":132},{"fact":"Julius Ceasar, Henri II, Charles XI, and Napoleon were all afraid of cats.","length":74},{"fact":"Unlike humans, cats cannot detect sweetness which likely explains why they are not drawn to it at all.","length":102},{"fact":"Cats can be taught to walk on a leash, but a lot of time and patience is required to teach them. The younger the cat is, the easier it will be for them to learn.","length":161},{"fact":"Researchers believe the word \u201ctabby\u201d comes from Attabiyah, a neighborhood in Baghdad, Iraq. Tabbies got their name because their striped coats resembled the famous wavy patterns in the silk produced in this city.","length":212}],"first_page_url":"https:\/\/catfact.ninja\/facts?page=1","from":1,"last_page":67,"last_page_url":"https:\/\/catfact.ninja\/facts?page=67","next_page_url":"https:\/\/catfact.ninja\/facts?page=2","path":"https:\/\/catfact.ninja\/facts","per_page":"5","prev_page_url":null,"to":5,"total":332}
+
+> curl -s "https://catfact.ninja/facts?limit=5" | jsonlogic '{"var": "data"}'
+
+[{"fact":"A cat's appetite is the barometer of its health. Any cat that does not eat or drink for more than two days should be taken to a vet.","length":132},{"fact":"Some notable people who disliked cats:  Napoleon Bonaparte, Dwight D. Eisenhower, Hitler.","length":89},{"fact":"During the time of the Spanish Inquisition, Pope Innocent VIII condemned cats as evil and thousands of cats were burned. Unfortunately, the widespread killing of cats led to an explosion of the rat population, which exacerbated the effects of the Black Death.","length":259},{"fact":"A cat has approximately 60 to 80 million olfactory cells (a human has between 5 and 20 million).","length":96},{"fact":"In just seven years, a single pair of cats and their offspring could produce a staggering total of 420,000 kittens.","length":115}]
+
+> curl -s "https://catfact.ninja/facts?limit=5" | jsonlogic '{"var": "data.0"}'
+
+{"fact":"A tiger's stripes are like fingerprints","length":39}
+
+> curl -s "https://catfact.ninja/facts?limit=5" | jsonlogic '{"var": "data.0.fact"}'
+"Neutering a male cat will, in almost all cases, stop him from spraying (territorial marking), fighting with other males (at least over females), as well as lengthen his life and improve its quality."
+
+> curl -s "https://catfact.ninja/facts?limit=5" \
+    | jsonlogic '{"var": "data.0.fact"}' \
+    | jsonlogic '{"in": ["cat", {"var": ""}]}'
+
+true
+
+> curl -s "https://catfact.ninja/facts?limit=5" \
+    | jsonlogic '{"var": "data.0.fact"}' \
+    | jsonlogic '{"in": ["cat", {"var": ""}]}' \
+    | jsonlogic '{"if": [{"var": ""}, "fact contained cat", "fact did not contain cat"]}'
+
+"fact contained cat"
+```
+
 ## Building
 
 ### Prerequisites

Diff for: src/bin.rs

@@ -0,0 +1,73 @@
+use std::io;
+use std::io::Read;
+
+use anyhow::{Context, Result};
+use clap::{App, Arg};
+use serde_json;
+use serde_json::Value;
+
+use jsonlogic_rs;
+
+fn configure_args<'a, 'b>(app: App<'a, 'b>) -> App<'a, 'b> {
+    app.version(env!("CARGO_PKG_VERSION"))
+        .author("Matthew Planchard <[email protected]>")
+        .about(
+            "Parse JSON data with a JsonLogic rule.\n\
+            \n\
+            When no <data> or <data> is -, read from stdin.
+            \n\
+            The result is written to stdout as JSON, so multiple calls \n\
+            can be chained together if desired.",
+        )
+        .arg(
+            Arg::with_name("logic")
+                .help("A JSON logic string")
+                .required(true)
+                .takes_value(true),
+        )
+        .arg(
+            Arg::with_name("data")
+                .help("A string of JSON data to parse. May be provided as stdin.")
+                .required(false)
+                .takes_value(true),
+        )
+        .after_help(
+            r#"EXAMPLES:
+    jsonlogic '{"===": [{"var": "a"}, "foo"]}' '{"a": "foo"}'
+    jsonlogic '{"===": [1, 1]}' null
+    echo '{"a": "foo"}' | jsonlogic '{"===": [{"var": "a"}, "foo"]}'
+
+Inspired by and conformant with the original JsonLogic (jsonlogic.com).
+
+Report bugs to github.com/Bestowinc/json-logic-rs."#,
+        )
+}
+
+fn main() -> Result<()> {
+    let app = configure_args(App::new("jsonlogic"));
+    let matches = app.get_matches();
+
+    let logic = matches.value_of("logic").expect("logic arg expected");
+    let json_logic: Value =
+        serde_json::from_str(logic).context("Could not parse logic as JSON")?;
+
+    // let mut data: String;
+    let data_arg = matches.value_of("data").unwrap_or("-");
+
+    let mut data: String;
+    if data_arg != "-" {
+        data = data_arg.to_string();
+    } else {
+        data = String::new();
+        io::stdin().lock().read_to_string(&mut data)?;
+    }
+    let json_data: Value =
+        serde_json::from_str(&data).context("Could not parse data as JSON")?;
+
+    let result = jsonlogic_rs::apply(&json_logic, &json_data)
+        .context("Could not execute logic")?;
+
+    println!("{}", result.to_string());
+
+    Ok(())
+}