Efficient JSON parser that extracts values matching specified patterns using a single pass. It conveniently collects values for processing in batches or at once. Values not collected have minimal overhead, ideal for processing a subset of large JSON.

Match

Match objects, arrays, or field names (not field values) in the JSON:

• / Path separator.
• name Matches field "name".
• a,b,c Matches fields "a", "b", or "c".
• * Matches one object, array, or field.
• ** Matches zero or more objects, arrays, or fields.

Capture

Surround any match with parenthesis to capture that value.

• (name) Captures field "name".
• (a),b,(c,d) Captures multiple fields.
• (*) or (**) Captures wildcard matches.

Process

Use @ after a match to control when processors receive captured values.

• devices/(id,name) Without @ values are processed once at the end and only the first values matched are captured.
• devices/(id@,name@) Process "id" and "name" as soon as each is captured.
• devices/(id,name)@ Same as (id@,name@).
• devices@/(id,name) Process "id" and "name" as a pair for each device.
• *@/(id,name) Any match can be annotated to process.
• **@/(id,name) All captures after **@ are processed as soon as each is captured.

Arrays

Arrays are captured as-is:

• data/(items) with {data:{items:[1,2,3]}} gives: {items=[1,2,3]}

Use [] in a capture to collect into an array rather than as a single value.

• */(id) with {first:{id:1},second:{id:2}} gives: {id=1} (parsing ends after first match)
• */(id[]) gives: {id=[1, 2]} (all matches collected in an array)

Examples

{users:[{name:nate},{name:iva}]}
Process each user name: users@/(name)

1. The JSON root is matched implicitly.
2. users matches the users:[ array. The field name and value are matched together.
3. @ processes captured values at the end of each array item.
4. (name) captures the "name" field and value.
5. Result: Processors are called with nate and again with iva.

{config:{port:8081}}
Get the first port from "config" found at any depth: **/config/(port)
Result: Processors are called with: 8081

{services:[{status:up},{status:down},{status:failed}]}
Get all service statuses in an array: services/*/(status[])
Result: Processors are called with: [up, down, failed]

{items:[{id:123,type:cookies},{id:456,type:cake}]}
Process each "id" and "type" pair: items@/(id,type)
Result: Since there are multiple captures, processors are called with an object: {id=123,type=cookies} and {id=456,type=cake}

Escaping

Use special characters /,*@()[]',\ by surrounding them with single quotes.

• email/'moo@dog.com' Uses "[email protected]" as a literal string.
• words/'can''t' Escape single quote with two single quotes.

Keys

Capture keys using ().

• object/() with {object:{a:1,b:2,c:3}} gives: a (parsing ends after first match)
• object/()[] gives: [a,b,c] (all keys collected in an array)

Behavior notes

• When multiple patterns are added they match in parallel, each with independent capture and processing.
• reject() prevents further matching at this level or deeper, useful for filtering. A pattern can reject a different pattern.
• clear() discards unprocessed captured values.
• parseValue() returns captures at the end of parsing for convenience rather than using a processor.
• parseStart() and parseEnd() can be overidden to take action before or after parsing.
• end() prevents further matching and ends parsing. stop() does the same but also clears.
• If not using *@, **@, or [] parsing ends once all specified values are captured.
• A single capture before processing provides the value directly, multiple captures provide an object.
• No patterns or a "" pattern captures the entire JSON document.

JsonValues

• JsonValue instances are reused for @ processing, references should not be kept.
• JsonValue references can safely be held only by processors called at the end of parsing.
• JsonValue types are object, array, null, boolean, or String.
• Numbers are provided as String, deferring number parsing until explicitly converted (eg JsonValue#asFloat()).

Accessing values

Use process() or a processor to handle captures one by one. Use parseValue() to obtain captures directly:

JsonValue values = matcher.parseValue(json);
String error = value.getString("message", null);
if (error != null) fail(error);
return value.getString("access_token");

If an anonymous class processes values, var provides access to the fields (Java 10+):

var matcher = new JsonMatcher("(message,access_token)") {
	String error, accessToken;

	protected void process (JsonValue value) {
		error = value.getString("message", null);
		accessToken = value.getString("access_token");
	}
};
matcher.parse(json);
if (matcher.error != null) fail(matcher.error);
return matcher.accessToken;