deprecated

- The JSON library has been moved to library(json). This stub loads and reexports the new library. Please update your code accordingly.

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.

 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 or chars.

 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 and false 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) or end_of_file.

value_string_as(+Type)

Prolog type used for strings used as value. Default is atom. The alternative is string, producing a packed string object. Please note that codes or chars would produce ambiguous output and are therefore not supported.

See also

- json_read_dict/3 to read a JSON term using the version 7 extended data types.

 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 and false 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) or end_of_file.

value_string_as(+Type)

Prolog type used for strings used as value. Default is atom. The alternative is string, producing a packed string object. Please note that codes or chars would produce ambiguous output and are therefore not supported.

See also

- json_read_dict/3 to read a JSON term using the version 7 extended data types.

 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 increment 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 (default false), 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 representation 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(+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 increment 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 (default false), 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 representation 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 and null constants.

 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 and null 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 and null 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 is atom, producing a packed string object.

 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 and null 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 is atom, 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.

 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 additional option

as(Type)

defines the output type, which is one of atom, string or codes.

 json(+Content, +Vars, +VarDict, -JSON) is det

The predicate json/4 implements JSON quasi quotations. These quotations produce a JSON dict that is suitable for json_write_dict/2. The quasi quoter only accepts valid, but possibly partial JSON documents. The quoter replaces content whose value is a Prolog variable that appears in the argument list of the json indicator. Notably, you can't use a Prolog variable in place of an object key. Here is an example.

  {|json(Name)||
      { "name": Name,
        "created": {
          "day":null,
          "month":"December",
          "year":2007
        },
        "confirmed":true,
        "members":[1,2,3]
      }
  |}.