The SML of NJ Library
The `JSONUtil` structure

some overview

## 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 `i`th 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`.

## See Also

`JSON`, The JSON Library

SML/NJ Version 110.99.3 (August 1, 2023)
Last updated 2023-07-31 17:59:01 UTC