json.pl -- Reading and writing JSON serialization
This module supports reading and writing JSON objects. This library supports two Prolog representations (the new representation is only supported in SWI-Prolog version 7 and later):
- The classical representation is provided by json_read/3 and
json_write/3. This represents a JSON object as
json(NameValueList)
, a JSON string as an atom and the JSON constantsnull
,true
andfalse
as @(null), @(true) and @false. - The new representation is provided by json_read_dict/3 and
json_write_dict/3. This represents a JSON object as a dict, a JSON
string as a Prolog string and the JSON constants using the Prolog
atoms
null
,true
andfalse
.
- atom_json_term(?Atom, ?JSONTerm, +Options) is det
- Convert between textual representation and a JSON term. In
write mode (JSONTerm to Atom), the option
- as(Type)
- defines the output type, which is one of
atom
(default),string
,codes
orchars
.
- json_read(+Stream, -Term) is det
- json_read(+Stream, -Term, +Options) is det
- Read next JSON value from Stream into a Prolog term. The
canonical representation for Term is:
- A JSON object is mapped to a term
json(NameValueList)
, where NameValueList is a list of Name=Value. Name is an atom created from the JSON string. - A JSON array is mapped to a Prolog list of JSON values.
- A JSON string is mapped to a Prolog atom
- A JSON number is mapped to a Prolog number
- The JSON constants
true
andfalse
are mapped -like JPL- to @(true) and @(false). - The JSON constant
null
is mapped to the Prolog term @(null)
Here is a complete example in JSON and its corresponding Prolog term.
{ "name":"Demo term", "created": { "day":null, "month":"December", "year":2007 }, "confirmed":true, "members":[1,2,3] }
json([ name='Demo term', created=json([day= @null, month='December', year=2007]), confirmed= @true, members=[1, 2, 3] ])
The following options are processed:
- null(+NullTerm)
- Term used to represent JSON
null
. Default @(null) - true(+TrueTerm)
- Term used to represent JSON
true
. Default @(true) - false(+FalseTerm)
- Term used to represent JSON
false
. Default @(false) - end_of_file(+ErrorOrTerm)
- If end of file is reached after skipping white space
but before any input is processed take the following
action (default
error
):- If ErrorOrTerm ==
error
, throw an unexpected end of file syntax error - Otherwise return ErrorOrTerm.
Returning an status term is required to process Concatenated JSON. Suggested values are
@(eof)
orend_of_file
. - If ErrorOrTerm ==
- value_string_as(+Type)
- Prolog type used for strings used as value. Default is
atom
. The alternative isstring
, producing a packed string object. Please note thatcodes
orchars
would produce ambiguous output and are therefore not supported.
- A JSON object is mapped to a term
- json_write(+Stream, +Term) is det
- json_write(+Stream, +Term, +Options) is det
- Write a JSON term to Stream. The JSON object is of the same format
as produced by json_read/2, though we allow for some more
flexibility with regard to pairs in objects. All of Name=Value,
Name-Value and Name(Value) produce the same output.
Values can be of the form #(Term), which causes Term to be stringified if it is not an atom or string. Stringification is based on term_string/2.
Rational numbers are emitted as floating point numbers. The hook json_write_hook/4 can be used to realize domain specific alternatives.
The version 7 dict type is supported as well. Optionally, if the dict has a tag, a property "type":"tag" can be added to the object. This behaviour can be controlled using the
tag
option (see below). For example:?- json_write(current_output, point{x:1,y:2}). { "x":1, "y":2 }
?- json_write(current_output, point{x:1,y:2}, [tag(type)]). { "type":"point", "x":1, "y":2 }
In addition to the options recognised by json_read/3, we process the following options are recognised:
- width(+Width)
- Width in which we try to format the result. Too long lines switch from horizontal to vertical layout for better readability. If performance is critical and human readability is not an issue use Width = 0, which causes a single-line output.
- step(+Step)
- Indentation increnment for next level. Default is 2.
- tab(+TabDistance)
- Distance between tab-stops. If equal to Step, layout is generated with one tab per level.
- serialize_unknown(+Boolean)
- If
true
(defaultfalse
), serialize unknown terms and print them as a JSON string. The default raises a type error. Note that this option only makes sense if you can guarantee that the passed value is not an otherwise valid Prolog reporesentation of a Prolog term.
If a string is emitted, the sequence
</
is emitted as<\/
. This is valid JSON syntax which ensures that JSON objects can be safely embedded into an HTML<script>
element. - json_write_hook(+Term, +Stream, +State, +Options) is semidet[multifile]
- Hook that can be used to emit a JSON representation for Term to
Stream. If the predicate succeeds it must have written a
valid JSON data element and if it fails it may not have produced
any output. This facility may be used to map arbitrary Prolog terms
to JSON. It was added to manage the precision with which floating
point numbers are emitted.
Note that this hook is shared by all users of this library. It is generally adviced to map a unique compound term to avoid interference with normal output.
- json_dict_pairs(+Dict, -Pairs) is semidet[multifile]
- This hook may be used to order the keys of an object. If it fails, dict_pairs/3 is used which produces an ordered list of keys.
- is_json_term(@Term) is semidet
- is_json_term(@Term, +Options) is semidet
- True if Term is a json term. Options are the same as for
json_read/2, defining the Prolog representation for the JSON
true
,false
andnull
constants. - json_read_dict(+Stream, -Dict) is det
- json_read_dict(+Stream, -Dict, +Options) is det
- Read a JSON object, returning objects as a dicts. The
representation depends on the options, where the default is:
- String values are mapped to Prolog strings
- JSON
true
,false
andnull
are represented using these Prolog atoms. - JSON objects are mapped to dicts.
- Optionally, a
type
field in an object assigns a tag for the dict.
The predicate json_read_dict/3 processes the same options as json_read/3, but with different defaults. In addition, it processes the
tag
option. See json_read/3 for details about the shared options.- tag(+Name)
- When converting to/from a dict, map the indicated JSON attribute to the dict tag. No mapping is performed if Name is the empty atom ('', default). See json_read_dict/2 and json_write_dict/2.
- default_tag(+Tag)
- Provide the default tag if the above
tag
option does not apply. - null(+NullTerm)
- Default the atom
null
. - true(+TrueTerm)
- Default the atom
true
. - false(+FalseTerm)
- Default the atom
false
- end_of_file(+ErrorOrTerm)
- Action on reading end-of-file. See json_read/3 for details.
- value_string_as(+Type)
- Prolog type used for strings used as value. Default
is
string
. The alternative isatom
, producing a packed string object.
- json_write_dict(+Stream, +Dict) is det
- json_write_dict(+Stream, +Dict, +Options) is det
- Write a JSON term, represented using dicts. This is the same as json_write/3, but assuming the default representation of JSON objects as dicts.
- atom_json_dict(+Atom, -JSONDict, +Options) is det
- atom_json_dict(-Text, +JSONDict, +Options) is det
- Convert between textual representation and a JSON term
represented as a dict. Options are as for json_read/3.
In write mode, the addtional option
- as(Type)
- defines the output type, which is one of
atom
,string
orcodes
.
Re-exported predicates
The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.
- json_read(+Stream, -Term) is det
- json_read(+Stream, -Term, +Options) is det
- Read next JSON value from Stream into a Prolog term. The
canonical representation for Term is:
- A JSON object is mapped to a term
json(NameValueList)
, where NameValueList is a list of Name=Value. Name is an atom created from the JSON string. - A JSON array is mapped to a Prolog list of JSON values.
- A JSON string is mapped to a Prolog atom
- A JSON number is mapped to a Prolog number
- The JSON constants
true
andfalse
are mapped -like JPL- to @(true) and @(false). - The JSON constant
null
is mapped to the Prolog term @(null)
Here is a complete example in JSON and its corresponding Prolog term.
{ "name":"Demo term", "created": { "day":null, "month":"December", "year":2007 }, "confirmed":true, "members":[1,2,3] }
json([ name='Demo term', created=json([day= @null, month='December', year=2007]), confirmed= @true, members=[1, 2, 3] ])
The following options are processed:
- null(+NullTerm)
- Term used to represent JSON
null
. Default @(null) - true(+TrueTerm)
- Term used to represent JSON
true
. Default @(true) - false(+FalseTerm)
- Term used to represent JSON
false
. Default @(false) - end_of_file(+ErrorOrTerm)
- If end of file is reached after skipping white space
but before any input is processed take the following
action (default
error
):- If ErrorOrTerm ==
error
, throw an unexpected end of file syntax error - Otherwise return ErrorOrTerm.
Returning an status term is required to process Concatenated JSON. Suggested values are
@(eof)
orend_of_file
. - If ErrorOrTerm ==
- value_string_as(+Type)
- Prolog type used for strings used as value. Default is
atom
. The alternative isstring
, producing a packed string object. Please note thatcodes
orchars
would produce ambiguous output and are therefore not supported.
- A JSON object is mapped to a term
- json_write(+Stream, +Term) is det
- json_write(+Stream, +Term, +Options) is det
- Write a JSON term to Stream. The JSON object is of the same format
as produced by json_read/2, though we allow for some more
flexibility with regard to pairs in objects. All of Name=Value,
Name-Value and Name(Value) produce the same output.
Values can be of the form #(Term), which causes Term to be stringified if it is not an atom or string. Stringification is based on term_string/2.
Rational numbers are emitted as floating point numbers. The hook json_write_hook/4 can be used to realize domain specific alternatives.
The version 7 dict type is supported as well. Optionally, if the dict has a tag, a property "type":"tag" can be added to the object. This behaviour can be controlled using the
tag
option (see below). For example:?- json_write(current_output, point{x:1,y:2}). { "x":1, "y":2 }
?- json_write(current_output, point{x:1,y:2}, [tag(type)]). { "type":"point", "x":1, "y":2 }
In addition to the options recognised by json_read/3, we process the following options are recognised:
- width(+Width)
- Width in which we try to format the result. Too long lines switch from horizontal to vertical layout for better readability. If performance is critical and human readability is not an issue use Width = 0, which causes a single-line output.
- step(+Step)
- Indentation increnment for next level. Default is 2.
- tab(+TabDistance)
- Distance between tab-stops. If equal to Step, layout is generated with one tab per level.
- serialize_unknown(+Boolean)
- If
true
(defaultfalse
), serialize unknown terms and print them as a JSON string. The default raises a type error. Note that this option only makes sense if you can guarantee that the passed value is not an otherwise valid Prolog reporesentation of a Prolog term.
If a string is emitted, the sequence
</
is emitted as<\/
. This is valid JSON syntax which ensures that JSON objects can be safely embedded into an HTML<script>
element. - is_json_term(@Term) is semidet
- is_json_term(@Term, +Options) is semidet
- True if Term is a json term. Options are the same as for
json_read/2, defining the Prolog representation for the JSON
true
,false
andnull
constants. - json_read_dict(+Stream, -Dict) is det
- json_read_dict(+Stream, -Dict, +Options) is det
- Read a JSON object, returning objects as a dicts. The
representation depends on the options, where the default is:
- String values are mapped to Prolog strings
- JSON
true
,false
andnull
are represented using these Prolog atoms. - JSON objects are mapped to dicts.
- Optionally, a
type
field in an object assigns a tag for the dict.
The predicate json_read_dict/3 processes the same options as json_read/3, but with different defaults. In addition, it processes the
tag
option. See json_read/3 for details about the shared options.- tag(+Name)
- When converting to/from a dict, map the indicated JSON attribute to the dict tag. No mapping is performed if Name is the empty atom ('', default). See json_read_dict/2 and json_write_dict/2.
- default_tag(+Tag)
- Provide the default tag if the above
tag
option does not apply. - null(+NullTerm)
- Default the atom
null
. - true(+TrueTerm)
- Default the atom
true
. - false(+FalseTerm)
- Default the atom
false
- end_of_file(+ErrorOrTerm)
- Action on reading end-of-file. See json_read/3 for details.
- value_string_as(+Type)
- Prolog type used for strings used as value. Default
is
string
. The alternative isatom
, producing a packed string object.
- json_write_dict(+Stream, +Dict) is det
- json_write_dict(+Stream, +Dict, +Options) is det
- Write a JSON term, represented using dicts. This is the same as json_write/3, but assuming the default representation of JSON objects as dicts.