Awesome

jsonwriter: functions module for shellfire

This module provides a simple framework for writing JSON with a shellfire application. It consists of a number of helper methods for correctly generating suitably escaped JSON. The API for this module is not yet stable.

An example user is the github api module used by swaddle.

Compatibility

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

Overview

For example, to create a standalone JSON object, suitable for a lot of REST APIs:-

jsonwriter_object \
	string tag_name "tag" \
	string name "who-are-you" \
	string body "my body" \
	boolean draft true \
	boolean prerelease false \
>/path/to/file.json

Alternatively, it is possible to use the functions in templates*:-

printf '%s' "{
	$(jsonwriter_string 'tag_name'):$(jsonwriter_string 'tag')
	$(jsonwriter_string 'name'):$(jsonwriter_string 'who-are-you')
	$(jsonwriter_string 'body'):$(jsonwriter_string 'my-body')
}"

This approach is useful when building JSON graphs recursively. jsonwriter's primary use case is for REST API calls, which rarely require large, complex or highly nested JSON. (In fact, many REST APIs use such simple objects that the traditional application/x-www-form-urlencoded content type would be far more suitable and browser friendly (and arguably more byte-efficient), but many API authors haven't yet seen enough winters).

Strictly speaking, the object's key should always be passed through the jsonwriter_string function, but, in practice, nearly all object keys are well-known values that don't contain anything that needs escaping. Of course, if using untrusted input…

* Note: We don't use echo as, by default, it responds to escape sequences. The options to disable this vary by shell and are inherently non-portable.

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/jsonwriter.git"
cd -
git submodule init --update

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

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

Namespace jsonwriter

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 jsonwriter

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 jsonwriter
	…
}

Functions

jsonwriter_object

Writes a JSON object from triplets to standard out.

The values of fieldType may be:-

jsonwriter_list

Writes a JSON list from triplets to standard out.

The values of fieldType may be:-

jsonwriter_null

Writer a JSON null value to standard out. Useful for embedding in heredoc templates.

jsonwriter_boolean

Writes a JSON boolean value to standard out. Useful for embedding in heredoc templates. As an extension, if boolean is empty, omitted (unset), 2 or null (lower case, upper case or title case), then a JSON null value is written.

jsonwriter_number

Writes a JSON boolean value to standard out. Useful for embedding in heredoc templates.

jsonwriter_string

Writes a JSON string value to standard out, correctly escaped and with quotes. Useful for embedding in heredoc templates. Suitable for object keys, object values and lists, as well as root values. It is impossible to write a NUL in a string using this function, as the shell does not support ASCII NUL values (unless using zsh). This is unlikely to be a problem in practice.