refactor: create a separate namespace (#20)

* refactor: cleanup lib and docs

Author: dainiusjocas

Diff for: .github/workflows/release.yml

@@ -67,7 +67,7 @@ jobs:
       - name: Install clojure tools-deps
         uses: DeLaGuardo/setup-clojure@master
         with:
-          tools-deps: 1.10.3.956
+          tools-deps: 1.10.3.967
 
       - name: Compile uberjar
         run: |
@@ -201,7 +201,7 @@ jobs:
       - name: Install clojure tools-deps
         uses: DeLaGuardo/setup-clojure@master
         with:
-          tools-deps: 1.10.3.956
+          tools-deps: 1.10.3.967
 
       - name: Publish lib to Clojars
         run: |

Diff for: .github/workflows/test.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Install clojure tools-deps
         uses: DeLaGuardo/setup-clojure@master
         with:
-          tools-deps: 1.10.3.956
+          tools-deps: 1.10.3.967
 
       - name: Unit Tests
         run: clojure -A:dev:test

Diff for: CHANGELOG.md

@@ -6,6 +6,9 @@ For a list of breaking changes, check [here](#breaking-changes).
 
 ## New
 
+- introduce `jq.api` namespace
+- deprecate `jq.core` namespace
+
 ## Breaking changes
 
 ## Unreleased

Diff for: Makefile

@@ -4,11 +4,11 @@ test:
 
 .PHONY: lint
 lint:
-	clojure -M:clj-kondo
+	clojure -M:clj-kondo --lint build cli src test
 
 .PHONY: check-deps
 check-deps:
-	clojure -Sdeps '{:deps {antq/antq {:mvn/version "RELEASE"}}}' -M -m antq.core
+	clojure -Sdeps '{:deps {com.github.liquidz/antq {:mvn/version "RELEASE"} org.slf4j/slf4j-nop {:mvn/version "RELEASE"}}}' -M -m antq.core
 
 .PHONY: uberjar
 uberjar:
@@ -26,4 +26,5 @@ native-image: uberjar
 
 .PHONY: static-native-image
 static-native-image: uberjar
-	CLJ_JQ_STATIC=true ./script/compile
+	./script/setup-musl
+	PATH=$$HOME/.musl/bin:$$PATH CLJ_JQ_STATIC=true CLJ_JQ_MUSL=true ./script/compile

Diff for: README.md

@@ -4,15 +4,20 @@
 
 # clj-jq
 
-A library to execute `jq` scripts on JSON data. It is a thin wrapper around [jackson-jq](https://github.com/eiiches/jackson-jq).
+A library to execute [`jq`](https://stedolan.github.io/jq/) scripts on JSON data within a Clojure application.
+It is a thin wrapper around [jackson-jq](https://github.com/eiiches/jackson-jq):
+a pure Java `jq` Implementation for Jackson JSON Processor.
 
 Available `jq` functions can be found [here](https://github.com/eiiches/jackson-jq#implementation-status-and-current-limitations).
 
+This library is compatible with the GraalVM `native-image`.
+
 ## Alternatives
 
 There is another `jq` library for Clojure: [clj-jq](https://github.com/BrianMWest/clj-jq). 
-This library works by shelling-out to an embedded `jq`. The problem is that it has costs for
-every invocation. Also, it creates difficulties to use this library with the GraalVM native-image.
+This library works by shelling-out to an embedded `jq` instance.
+The problem with this approach is that it has fixed costs for every invocation. 
+Also, it creates difficulties to use this library with the GraalVM native-image.
 
 ## Use cases
 
@@ -21,7 +26,7 @@ The library intends to be used for stream processing.
 ### Compiling a script to execute it multiple times
 
 ```clojure
-(require '[jq.core :as jq])
+(require '[jq.api :as jq])
 
 (let [data "[1,2,3]"
       query "map(.+1)"
@@ -37,7 +42,7 @@ Or inline:
 => "[2,3,4]"
 ```
 
-### One of script execution
+### One-off script execution
 
 ```clojure
 (let [data "[1,2,3]"
@@ -46,20 +51,34 @@ Or inline:
 => "[2,3,4]"
 ```
 
+## How to join multiple scripts together
+
+Joining `jq` scripts is as simple as "piping" output of one script to another:
+join `jq` script strings with `|` character.
+
+```clojure
+(let [data "[1,2,3]"
+      script-inc "map(.+1)"
+      script-reverse "reverse"
+      query (clojure.string/join " | " [script-inc script-reverse])]
+  (jq/execute data query))
+=> "[4,3,2]"
+```
+
 ## Performance
 
 ```clojure
 (use 'criterium.core)
-(let [jq-script (time (jq.core/processor ".a[] |= sqrt"))] 
+(let [jq-script (time (jq/processor ".a[] |= sqrt"))]
   (quick-bench (jq-script "{\"a\":[10,2,3,4,5],\"b\":\"hello\"}")))
 =>
-"Elapsed time: 0.098731 msecs"
-Evaluation count : 203586 in 6 samples of 33931 calls.
-Execution time mean : 3.729388 µs
-Execution time std-deviation : 490.874949 ns
-Execution time lower quantile : 2.960691 µs ( 2.5%)
-Execution time upper quantile : 4.082989 µs (97.5%)
-Overhead used : 1.977144 ns
+"Elapsed time: 0.063264 msecs"
+Evaluation count : 198870 in 6 samples of 33145 calls.
+Execution time mean : 3.687955 µs
+Execution time std-deviation : 668.209042 ns
+Execution time lower quantile : 3.041275 µs ( 2.5%)
+Execution time upper quantile : 4.280444 µs (97.5%)
+Overhead used : 1.766661 ns
 ```
 
 ## Future work

Diff for: cli/jq/cli.clj

@@ -3,7 +3,7 @@
   (:require [clojure.java.io :as io]
             [clojure.string :as str]
             [clojure.tools.cli :as cli]
-            [jq.core :as jq])
+            [jq.api :as jq])
   (:import (java.io Reader BufferedReader)))
 
 (def cli-options
@@ -23,7 +23,7 @@
   (println "Supported options:")
   (println summary))
 
-(defn execute [jq-filter files options]
+(defn execute [jq-filter files _]
   (let [jq-processor (jq/processor jq-filter)]
     (if (seq files)
       (doseq [f files]

Diff for: deps.edn

@@ -6,15 +6,15 @@
  :aliases
  {:dev
   {:extra-paths ["dev" "classes" "test" "test/resources"]
-   :extra-deps  {org.clojure/tools.deps.alpha {:mvn/version "0.12.1030"
+   :extra-deps  {org.clojure/tools.deps.alpha {:mvn/version "0.12.1036"
                                                :exclusions  [org.slf4j/slf4j-log4j12
                                                              org.slf4j/slf4j-api
                                                              org.slf4j/slf4j-nop]}
                  criterium/criterium          {:mvn/version "0.4.6"}}}
   :test
   {:extra-paths ["test" "test/resources"]
    :extra-deps  {com.cognitect/test-runner {:git/url "https://github.com/cognitect-labs/test-runner.git"
-                                            :sha     "e7660458ce25bc4acb4ccc3e2415aae0a4907198"}}
+                                            :sha     "dd6da11611eeb87f08780a30ac8ea6012d4c05ce"}}
    :main-opts   ["-m" "cognitect.test-runner"]}
   :clj-kondo
   {:main-opts  ["-m" "clj-kondo.main" "--lint" "src" "test"]
@@ -24,9 +24,10 @@
   {:extra-paths ["cli" "classes" "resources"]
    :extra-deps  {org.clojure/tools.cli {:mvn/version "1.0.206"}}}
   :build
-  {:deps {io.github.clojure/tools.build {:git/tag "v0.1.9" :git/sha "6736c83"}}
+  {:deps {io.github.clojure/tools.build {:git/tag "v0.2.2" :git/sha "3049217"}}
    :extra-paths ["build"]
-   :ns-default build}
+   :ns-default build
+   :jvm-opts   ["-Dclojure.compiler.direct-linking=true"]}
   :deploy
   {:replace-deps {slipset/deps-deploy {:mvn/version "0.1.5"}}
    :exec-fn deps-deploy.deps-deploy/deploy

Diff for: doc/cli.md

@@ -0,0 +1,44 @@
+# CLI utility
+
+`clj-jq`: `jackson-jq` based command-line JSON processor.
+
+## Installation
+
+For MacOS and linux use `brew`:
+```shell
+brew install dainiusjocas/brew/clj_jq
+```
+
+Upgrade:
+
+```shell
+brew upgrade clj-jq
+```
+
+Or download the latest binaries yourself from [Github release page](https://github.com/dainiusjocas/clj-jq/releases).
+
+In case you're running MacOS then give run permissions for the executable binary:
+```shell
+sudo xattr -r -d com.apple.quarantine clj-jq
+```
+
+## Options
+
+```text
+clj-jq 1.1.0
+jackson-jq based command-line JSON processor
+Usage: clj-jq [options] jq-filter [file...]
+Supported options:
+  -h, --help
+```
+
+## Examples
+
+```shell
+echo "[1,2,3,4]" | ./clj-jq '
+.
+| map(.+1)
+| reverse
+'
+#=> [5,4,3,2]
+```

Diff for: src/jq/api.clj

@@ -0,0 +1,55 @@
+(ns jq.api
+  (:require [jq.api.api-impl :as impl])
+  (:import (net.thisptr.jackson.jq JsonQuery)))
+
+(set! *warn-on-reflection* true)
+
+; jq docs http://manpages.ubuntu.com/manpages/hirsute/man1/jq.1.html
+(defn execute
+  "Given a JSON data string (1) and a JQ query string (2)
+  returns a JSON string result of (2) applied on (1)."
+  ^String [^String data ^String query]
+  (impl/apply-json-query-on-string-data data (impl/compile-query query)))
+
+(defn processor
+  "Given a JQ query string (1) compiles it and returns a function that given
+  a JSON string (2) will return a JSON string with (1) applied on (2)."
+  [^String query]
+  (let [^JsonQuery json-query (impl/compile-query query)]
+    (fn ^String [^String data]
+      (impl/apply-json-query-on-string-data data json-query))))
+
+(defn flexible-processor
+  "Given a JQ query string (1) compiles it and returns a function that given
+  a JsonNode object or a String (2) will return
+  either a JSON string or json node with (1) applied on (2)."
+  ([^String query] (flexible-processor query {}))
+  ([^String query opts]
+   (let [^JsonQuery query (impl/compile-query query)
+         output-format (get opts :output :string)]
+     (fn [json-data]
+       (cond
+         ; string => string
+         (and (string? json-data) (= :string output-format))
+         (impl/apply-json-query-on-string-data json-data query)
+
+         ; string => json-node
+         (and (string? json-data) (not= :string output-format))
+         (impl/apply-json-query-on-json-node (impl/string->json-node json-data) query)
+
+         ; json-node => string
+         (and (not (string? json-data)) (= :string output-format))
+         (impl/apply-json-query-on-json-node-data json-data query)
+
+         ; json-node => json-node
+         (and (not (string? json-data)) (not= :string output-format))
+         (impl/apply-json-query-on-json-node json-data query))))))
+
+(comment
+  (jq.api/execute "{\"a\":[1,2,3,4,5],\"b\":\"hello\"}" ".")
+
+  ((jq.api/processor ".") "{\"a\":[1,2,3,4,5],\"b\":\"hello\"}")
+
+  ((jq.api/flexible-processor ".") "{\"a\":[1,2,3,4,5],\"b\":\"hello\"}")
+
+  ((jq.api/flexible-processor "." {:output :json-node}) "{\"a\":[1,2,3,4,5],\"b\":\"hello\"}"))

Diff for: src/jq/api/api_impl.clj

@@ -0,0 +1,60 @@
+(ns ^{:doc "Internal implementation details."
+      :no-doc true}
+  jq.api.api-impl
+  (:import (net.thisptr.jackson.jq JsonQuery Versions Scope BuiltinFunctionLoader Output)
+           (com.fasterxml.jackson.databind ObjectMapper JsonNode)))
+
+(set! *warn-on-reflection* true)
+
+(def ^ObjectMapper mapper (ObjectMapper.))
+
+(def jq-version Versions/JQ_1_6)
+
+(def ^Scope root-scope
+  "Scope that contains all the available Builtin functions."
+  (let [scope (Scope/newEmptyScope)]
+    ; Load all the functions available for the JQ-1.6
+    (.loadFunctions (BuiltinFunctionLoader/getInstance) jq-version scope)
+    scope))
+
+; Helper interface that specifies a method to get a string value.
+(definterface IGetter
+  (^com.fasterxml.jackson.databind.JsonNode getValue []))
+
+; Container class helper that implements the net.thisptr.jackson.jq.Output
+; interface that enables the class to be used as a callback for JQ and exposes the
+; unsynchronized-mutable container field for the result of the JQ transformation.
+(deftype OutputContainer [^:unsynchronized-mutable ^JsonNode container]
+  Output
+  (emit [_ json-node] (set! container json-node))
+  IGetter
+  (getValue [_] container))
+
+(defn apply-json-query-on-json-node
+  "Given a JSON data string and a JsonQuery object applies the query
+  on the JSON data string and return JsonNode."
+  ^JsonNode [^JsonNode json-node ^JsonQuery json-query]
+  (let [output-container (OutputContainer. nil)]
+    (.apply json-query (Scope/newChildScope root-scope) json-node output-container)
+    (.getValue output-container)))
+
+(defn string->json-node ^JsonNode [^String data]
+  (.readTree mapper data))
+
+(defn json-node->string ^String [^JsonNode data]
+  (.writeValueAsString mapper data))
+
+(defn ^String apply-json-query-on-string-data
+  "Reads data JSON string into a JsonNode and passes to the query executor."
+  [^String data ^JsonQuery query]
+  (json-node->string (apply-json-query-on-json-node (string->json-node data) query)))
+
+(defn ^String apply-json-query-on-json-node-data
+  "Reads data JSON string into a JsonNode and passes to the query executor."
+  ^String [^JsonNode data ^JsonQuery query]
+  (json-node->string (apply-json-query-on-json-node data query)))
+
+(defn compile-query
+  "Compiles a JQ query string into a JsonQuery object."
+  ^JsonQuery [^String query]
+  (JsonQuery/compile query jq-version))