Skip to content
jq for Jackson Java JSON Processor
Branch: develop
Clone or download

README.md

jackson-jq

jq for Jackson JSON Processor

CircleCI

Installation

Just add jackson-jq in your pom.xml.

<dependencies>
	<dependency>
		<groupId>net.thisptr</groupId>
		<artifactId>jackson-jq</artifactId>
		<version>0.0.10</version>
	</dependency>
</dependencies>

Requirements

  • Java 8 or later

Usage

See jackson-jq/src/test/java/examples/Usage.java.

Using a jackson-jq command line tool

We provide a CLI tool for testing a jackson-jq query. The tool has to be build with mvn package, but alternatively, Homebrew (or Linuxbrew) users can just brew tap eiiches/jackson-jq && brew install jackson-jq and jackson-jq will be available on $PATH.

$ bin/jackson-jq '.foo' <<< '{"foo":10}'
10

See bin/jackson-jq --help for more information.

Implementation status and current limitations

jackson-jq aims to be a compatible jq implementation. However, not all the features are available; some features are not relevant as being a java library and some features are just yet to be implemented. The following table (generated from jq-1.5 manual) lists all the features jq provides. I try to keep this list accurate but if you find something wrong, please report an issue.

Language Features / Functions jackson-jq
Basic filters
    • .
    • .foo, .foo.bar
    • .foo?
    • .[<string>], .[2], .[10:15]
    • .[]
    • .[]?
    • ,
    • ǀ
Types and Values
    • Array construction - []
    • Objects - {}
Builtin operators and functions
    • Addition - +
    • Subtraction - -
    • Multiplication, division, modulo - *, /, and %
    • length
    • keys, keys_unsorted
    • has(key)
    • in
    • path(path_expression) ×
    • del(path_expression)
    • to_entries, from_entries, with_entries
    • select(boolean_expression)
    • arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars
    • empty
    • error(message)
    • $__loc__ ×
    • map(x), map_values(x)
    • paths, paths(node_filter), leaf_paths
    • add
    • any, any(condition), any(generator; condition)
    • all, all(condition), all(generator; condition)
    • flatten, flatten(depth)
    • range(upto), range(from;upto) range(from;upto;by)
    • floor
    • sqrt
    • tonumber
    • tostring
    • type
    • infinite, nan, isinfinite, isnan, isfinite, isnormal
    • sort, sort_by(path_expression)
    • group_by(path_expression)
    • min, max, min_by(path_exp), max_by(path_exp)
    • unique, unique_by(path_exp)
    • reverse
    • contains(element)
    • indices(s)
    • index(s), rindex(s)
    • inside
    • startswith(str)
    • endswith(str)
    • combinations, combinations(n)
    • ltrimstr(str)
    • rtrimstr(str)
    • explode
    • implode
    • split
    • join(str)
    • ascii_downcase, ascii_upcase
    • while(cond; update)
    • until(cond; next)
    • recurse(f), recurse, recurse(f; condition), recurse_down
    • ..
    • env ×
    • transpose
    • bsearch(x) ×
    • String interpolation - \(foo)
    • Convert to/from JSON
    • Format strings and escaping ※4
    • Dates ×
Conditionals and Comparisons
    • ==, !=
    • if-then-else
    • >, >=, <=, <
    • and/or/not
    • Alternative operator - //
    • try-catch
    • Breaking out of control structures ×※2
    • ? operator
Regular expressions (PCRE)
    • test(val), test(regex; flags)
    • match(val), match(regex; flags)
    • capture(val), capture(regex; flags)
    • scan(regex), scan(regex; flags)
    • split(regex; flags)
    • splits(regex), splits(regex; flags)
    • sub(regex; tostring) sub(regex; string; flags)
    • gsub(regex; string), gsub(regex; string; flags)
Advanced features
    • Variables
    • Defining Functions ※3
    • Reduce
    • limit(n; exp)
    • first(expr), last(expr), nth(n; expr)
    • first, last, nth(n)
    • foreach
    • Recursion
    • Generators and iterators
Math
I/O N/A
    • input N/A
    • inputs N/A
    • debug N/A
    • input_filename N/A
    • input_line_number N/A
Streaming N/A
    • truncate_stream(stream_expression) N/A
    • fromstream(stream_expression) N/A
    • tostream N/A
Assignment
    • =
    • ǀ=
    • +=, -=, *=, /=, %=, //=
    • Complex assignments ※1
Modules ×
    • import RelativePathString as NAME [<metadata>]; ×
    • include RelativePathString [<metadata>]; ×
    • import RelativePathString as $NAME [<metadata>]; ×
    • module <metadata>; ×
    • modulemeta ×

※1) Currently, complex assignments only work when the left-hand side is a simple field access. Won't work if select/1 or any filters are used in left-hand side. E.g.

  • jackson-jq '.a[]|.b += 10' <<< '{"a": [{"b": 1}, {"b": 2}]} does work.
  • jackson-jq '.a[]|select(.b>1) += 10' <<< '{"a": [{"b": 1}, {"b": 2}]}' does not work.

※2) jq once had label-less break in reduce and foreach in the master branch, but the feature was removed without ever being shipped as jq-1.5. Actually, jackson-jq implemented it then and still has it. Proper label $out and break $out syntax will be implemented in the future version of jackson-jq. E.g.

  • jackson-jq -n '(1,2,3) | label $out | if . == 2 then break $out else . end' does not work.

※3) When the function with the same name is defined more than once in the same-level scope, jackson-jq uses the last one. E.g.

  • def f: 1; def g: f; def f: 2; g evaluates to 2 in jackson-jq, while jq evaluates it to 1.

※4) @html, @uri, @sh, @base64 are not implemented yet.

Additionally, test cases used in jackson-jq (from the jq unit tests) might be useful to know what kind of queries work or not work.

Using jackson-jq-extra module

jackson-jq-extra module provides extra functions that you might find useful. These functions do not exist in jq.

POM

<dependencies>
    <dependency>
        <groupId>net.thisptr</groupId>
        <artifactId>jackson-jq-extra</artifactId>
        <version>0.0.10</version>
    </dependency>
</dependencies>

Examples

uuid4/0

  • jackson-jq -n 'uuid4' #=> "a69cf146-f40e-42e1-ae88-12590bdae947"

random/0

  • jackson-jq -n 'random' #=> 0.43292159535427466

timestamp/0, strptime/{1, 2}, strftime/{1, 2}

  • jackson-jq -n 'timestamp' #=> 1477162056362
  • jackson-jq -n '1477162342372 | strftime("yyyy-MM-dd HH:mm:ss.SSSXXX")' #=> "2016-10-23 03:52:22.372+09:00"
  • jackson-jq -n '1477162342372 | strftime("yyyy-MM-dd HH:mm:ss.SSSXXX"; "UTC")' #=> "2016-10-22 18:52:22.372Z"
  • jackson-jq -n '"2016-10-23 03:52:22.372+09:00" | strptime("yyyy-MM-dd HH:mm:ss.SSSXXX")' #=> 1477162342372
  • jackson-jq -n '"2016-10-22 18:52:22.372" | strptime("yyyy-MM-dd HH:mm:ss.SSS"; "UTC")' #=> 1477162342372

uriparse/0

  • jackson-jq -n '"http://user@www.example.com:8080/index.html?foo=1&bar=%20#hash" | uriparse' #=>

    {
      "scheme" : "http",
      "user_info" : "user",
      "raw_user_info" : "user",
      "host" : "www.example.com",
      "port" : 8080,
      "authority" : "user@www.example.com:8080",
      "raw_authority" : "user@www.example.com:8080",
      "path" : "/index.html",
      "raw_path" : "/index.html",
      "query" : "foo=1&bar= ",
      "raw_query" : "foo=1&bar=%20",
      "query_obj" : {
        "bar" : " ",
        "foo" : "1"
      },
      "fragment" : "hash",
      "raw_fragment" : "hash"
    }

uridecode/0

  • jackson-jq -n '"%66%6f%6f" | uridecode' #=> "foo"

hostname/0

  • jackson-jq -n 'hostname' #=> "jenkins-slave01"

License

This software is licensed under Apache Software License, Version 2.0, with some exceptions:

See COPYING for details.

You can’t perform that action at this time.