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 NotBool of JSON.value
exception NotInt of JSON.value
exception NotNumber of JSON.value
exception NotString of JSON.value

exception NotObject of JSON.value

exception FieldNotFound of JSON.value * string

exception NotArray of JSON.value

exception ArrayBounds of JSON.value * int

exception ElemNotFound of JSON.value

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 NotBool of JSON.value

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

exception NotInt of JSON.value

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

exception NotNumber of JSON.value

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

exception NotString of JSON.value

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

exception NotObject of JSON.value

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

exception FieldNotFound of JSON.value * string

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

exception NotArray of JSON.value

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

exception ArrayBounds of JSON.value * int

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

exception ElemNotFound of JSON.value

This exception is raised 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 exceptions defined in the JSONUtil structure and 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 NotBool exception if the value 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 NotInt exception if the value 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 NotInt exception if the value 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 NotNumber exception is raised.

val asString : JSON.value -> string

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

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 that is not a JSON object, then it raises the NotObject exception.

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 FieldNotFound exception otherwise. If lookupField is called on a value that is not a JSON object, then it raises the NotObject exception.

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 NotArray exception 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 NotArray exception if the second argument 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 one of the NotObject, NotArray, FieldNotFound, or ElemNotFound exceptions if there is an inconsistency between the path and the structure of jv.