Awesome

jsonreader: functions module for shellfire

This module provides a simple framework for parsing JSON with a shellfire application. Since JSON and shell script don't mix easily, we user an event-based parser with callbacks. In any POSIX shell - not just bash! This allows handling of JSON of arbitrary complexity, as long as:-

• There are no empty keys;
• There isn't ascii NUL once decoded

These are both highly unlikely.

Compatibility

• Tag release_2015.0117.1750-1 is compatible with shellfire release release_2015.0117.1750-1.

Overview

Usage couldn't be simpler:-

jsonreader_parse /path/to/file my_callback

where my_callback is a function that accepts JSON parse events:-

my_callback()
{
	echo "Depth $jsonreader_path"
	echo "$eventKind"
	echo "$eventVariant"
	echo "$eventValue"
}

There is a helper function, jsonreader_matches(), to make it easier to distinguish events. For example, the following real logic is taken from the github api module for handling arrays of error message objects:-

_github_api_v3_errorMessageExit()
{
	local errorMessage=''
	local requestId=''
	
	local resource=''
	local code=''
	local field=''
	
	local errors
	local errors_initialised
	core_variable_array_initialise errors
	
	# eg {"message":"Validation Failed","request_id":"d4cb5605-73cd-11e4-85aa-d38119fad9f5","documentation_url":"https://developer.github.com/v3","errors":[{"resource":"ReleaseAsset","code":"already_exists","field":"name"}]}
	_github_api_v3_errorMessage_event()
	{
		if jsonreader_eventMatches '/message' string; then
			errorMessage="$eventValue"
			return 0
		fi
		
		if jsonreader_eventMatches '/request_id' string; then
			requestId="$eventValue"
			return 0
		fi
		
		if jsonreader_eventMatches "/errors:${jsonreader_path_index}/" start; then
			resource=''
			code=''
			field=''
		fi
		
		if jsonreader_eventMatches "/errors:${jsonreader_path_index}/resource" string; then
			resource="$eventValue"
		fi
		
		if jsonreader_eventMatches "/errors:${jsonreader_path_index}/code" string; then
			code="$eventValue"
		fi
		
		if jsonreader_eventMatches "/errors:${jsonreader_path_index}/field" string; then
			field="$eventValue"
		fi
		
		if jsonreader_eventMatches "/errors:${jsonreader_path_index}/" end; then
			core_variable_array_append errors "There is the error (number $eventIndex) '$code' in resource '$resource's field '$field'."
		fi
	}
	
	jsonreader_parse "$github_api_v3_responseFilePath" _github_api_v3_errorMessage_event
	
	core_exitError $core_commandLine_exitCode_DATAERR "GitHub errors for request '$requestId' ($curl_httpStatusCode) was '$errorMessage' (Details: $(core_variable_array_string errors " "))"

This logic does not run in a subshell and so can change variables, mutate state or event exit the running program.

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/jsonreader.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/jsonreader.git above if using a fork.

You will also need to add paths - include the module paths.d.

You will also need to import the unicode module.

Namespace jsonreader

This namespace contains the core functionality needed to access the API.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn jsonreader

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn jsonreader
	…
}

Global Constants

Functions

jsonreader_parse()

The callback function is passed no arguments, but has the following variables available to it:-

jsonreader_path

jsonreader_path is used to quickly identify depth in the JSON graph. Examples best illustrate its values:-

A : is used to denote an array, and a / for an object. Object keys are then post-fixed to /. Array indices are post-fixed, fixed-width, to :. The reason for the weird numbering syntax for array ordinal position is that the fixed width allows use of the shells' glob syntax, rather than a call out to grep - the width permits 99,999,999 entries in an array. An empty key in a JSON object would cause a path fragment of //.

Matching the jsonreader_path can be done using the helper function jsonreader_matches(). The glob expression to match array indices can use the constant jsonreader_path_index.

jsonreader_matches()

Helper function to match events. Use the value jsonreader_path_index to glob-match array indices, eg to match /array:0000000005/hello, use /array:${jsonreader_path_index}/hello.