The JSONUtil structure

The JSONUtil module defines a collection of utility functions for working with JSON values. These include operations for testing if a value is of a given type and navigating the structure of a JSON value.

Synopsis

structure JSONUtil

Interface

exception JSONError of exn * JSON.value

exception NotBool
exception NotInt
exception NotNumber
exception NotString

exception NotObject

exception FieldNotFound of string

exception NotArray

exception ArrayBounds of int

exception ElemNotFound

val exnMessage : exn -> string

val asBool : JSON.value -> bool
val asInt : JSON.value -> Int.int
val asIntInf : JSON.value -> IntInf.int
val asNumber : JSON.value -> Real.real
val asString : JSON.value -> string

val findField : JSON.value -> string -> JSON.value option
val lookupField : JSON.value -> string -> JSON.value
val hasField : string -> JSON.value -> bool
val testField : string -> (JSON.value -> bool) -> JSON.value -> bool

val asArray : JSON.value -> JSON.value vector

val arrayMap : (JSON.value -> 'a) -> JSON.value -> 'a list

datatype edge
  = SEL of string
  | SUB of int
  | FIND of JSON.value -> bool

type path = edge list

val get : JSON.value * path -> JSON.value

val replace : JSON.value * path * JSON.value -> JSON.value

val insert : JSON.value * path * string * JSON.value -> JSON.value

val append : JSON.value * path * JSON.value list -> JSON.value

Description

exception JSONError of exn * JSON.value

raised when an error is detected during processing of a JSON value. The first argument, which is one of the exceptions described below, details the type of error and the second argument is the value that was being processed at the point of the error.

exception NotBool of JSON.value

used by the asBool function when the argument is not a JSON boolean.

exception NotInt of JSON.value

used by the asInt and asIntInf functions when the argument is not a JSON integer number.

exception NotNumber of JSON.value

used by the asNumber function when the argument is not a JSON number.

exception NotString of JSON.value

used by the asString function when the argument is not a JSON string.

exception NotObject of JSON.value

used by the findField and lookupField functions when the argument is not a JSON object.

exception FieldNotFound of JSON.value * string

This exception is used when the given field is not found in an object.

exception NotArray of JSON.value

This exception is used when trying to process a non-array value as an array.

exception ArrayBounds of JSON.value * int

This exception is used when access to an array value is out of bounds.

exception ElemNotFound of JSON.value

This exception is used when there is no element of an array that satisfies the predicate of a FIND edge in a path. The argument will be the array in question.

val exnMessage : exn -> string

exnMessage exn returns an error-message string for the exception value exn. This function produces specialized messages for the JSONError wrapped around the other exceptions defined in this structure (or the Fail exception). It falls back to the General.exnMessage function for other exceptions.

val asBool : JSON.value -> bool

asBool (JSON.BOOL b) returns the value b. This function raises the exception value JSONError(NotBool, jv) if the argument jv is not a JSON boolean value.

val asInt : JSON.value -> int

asInt (JSON.INT n) returns the value n converted to int. This function raises the exception value JSONError(NotInt, jv) if the argument jv is not a JSON integer value. It may also raise the Overflow exception if n is too large for the default int type.

val asIntInf : JSON.value -> IntInf.int

asIntInf (JSON.INT n) returns the value n. This function raises the exception value JSONError(NotInt, jv) if the argument jv is not a JSON integer value.

val asNumber : JSON.value -> Real.real

asNumber jv converts the JSON number jv to an SML real value. The jv argument can either have the form JSON.INT n, in which case n is converted to the real type and returned, or JSON.FLOAT f, in which case f is returned; otherwise, the exception value JSONError(NotNumber, jv) is raised.

val asString : JSON.value -> string

asBool (JSON.STRING s) returns the value s. This function raises the exception value JSONError(NotString, jv) if the argument jv is not a JSON string.

val findField : JSON.value -> string -> JSON.value option

findField (JSON.OBJECT flds) key returns SOME jv when the list of fields flds contains (key, jv) and NONE otherwise. If findField is called on a value v that is not a JSON object, then it raises the exception value JSONError(NotObject, v)

val lookupField : JSON.value -> string -> JSON.value

lookupField (JSON.OBJECT flds) key returns jv when the list of fields flds contains (key, jv) and raises the exception value JSONError(FieldNotFound key, v) otherwise. If lookupField is called on a value v that is not a JSON object, then it raises the exception value JSONError(NotObject, v).

val hasField : string -> JSON.value -> bool

hasField key v returns true when the value v is a JSON object that has a field with key as its label and false otherwise.

val testField : string -> (JSON.value -> bool) -> JSON.value -> bool

testField key pred v returns the result of pred jv when the value v is a JSON object that contains (key, jv). It returns false otherwise.

val asArray : JSON.value -> JSON.value vector

asArray jv converts the JSON array value jv to an SML vector value. It raises the exception value JSONError(NotArray, jv) when jv is not a JSON array.

val arrayMap : (JSON.value -> 'a) -> JSON.value -> 'a list

map a conversion function over a JSON array to produce a list; this function raises the exception value JSONError(NotArray, v) if the second argument v is not an array.

datatype edge = …​

specifies an edge of a path into a JSON value. The constructors have the following meaning:

SEL of string

SEL key specifies the value labeled by key in a JSON object.

SUB of int

SUB i specifies the ith element of a JSON array.

FIND of JSON.value -> bool

FIND pred specifies the first element of a JSON array that satisfies the given predicate.

type path = edge list

specifies a path into a JSON value.

val get : JSON.value * path -> JSON.value

get (jv, path) returns the component of jv named by path. It raises the JSONError exception if there is an inconsistency between the path and the structure of jv. The first argument to the JSONError exception will be one of the NotObject, NotArray, FieldNotFound, or ElemNotFound exceptions.

See Also

JSON, JSONDecode, The JSON Library