cl-json

API Reference

cl-json

JSON in Lisp. JSON (JavaScript Object Notation) is a lightweight data-interchange format.

JSON

  • Macro WITH-SHADOWED-CUSTOM-VARS (&body body)
  • Macro SET-CUSTOM-VARS (&rest customizations)
  • Macro BIND-CUSTOM-VARS ((&rest customizations) &body body)
  • Variable *USE-STRICT-JSON-RULES*
    t
    If non-nil, signal error on unrecognized escape sequences in JSON Strings. If nil, translate any such sequence to the char after slash.
  • Variable *JSON-SYMBOLS-PACKAGE*
    (find-package 'keyword)
    The package where JSON Object keys etc. are interned. Default KEYWORD, NIL = use current *PACKAGE*.
  • Function JSON-INTERN (string)
    Intern STRING in the current *JSON-SYMBOLS-PACKAGE*.
  • Condition UNKNOWN-SYMBOL-ERROR  (PARSE-ERROR)
    Signalled by safe-json-intern when a symbol that is not already interned in *json-symbols-package* is found.
  • Function UNKNOWN-SYMBOL-ERROR (string)
  • Function SAFE-JSON-INTERN (string)
    The default json-intern is not safe. Interns of many unique symbols could potentially use a lot of memory. An attack could exploit this by submitting something that is passed through cl-json that has many very large, unique symbols. This version is safe in that respect because it only allows symbols that already exists.
  • Variable *JSON-IDENTIFIER-NAME-TO-LISP*
    'json:camel-case-to-lisp
    Designator for a function which maps string (a JSON Object key) to string (name of a Lisp symbol).
  • Variable *LISP-IDENTIFIER-NAME-TO-JSON*
    'json:lisp-to-camel-case
    Designator for a function which maps string (name of a Lisp symbol) to string (e. g. JSON Object key).
  • Variable *IDENTIFIER-NAME-TO-KEY*
    'json:json-intern
    Designator for a function which, during decoding, maps the *json-identifier-name-to-lisp* -transformed key to the value it will have in the result object.
  • Macro WITH-LOCAL-CLASS-REGISTRY ((&key inherit) &body body)
    Run BODY in a dynamic environment where *CLASS-REGISTRY* is a temporary local list. If :INHERIT is non-null, the local registry shall initially have the same content as the exterior *CLASS-REGISTRY*, otherwise it shall be NIL.
  • Function CLEAR-CLASS-REGISTRY
    Reset the *CLASS-REGISTRY* to NIL.
  • Class FLUID-CLASS  (STANDARD-CLASS)
    A class to whose instances arbitrary new slots may be added on the fly.
    No slots.
  • Class FLUID-OBJECT  (STANDARD-OBJECT)
    Any instance of a fluid class.
    No slots.
  • Class FLUID-OBJECT  (STANDARD-OBJECT)
    Any instance of a fluid class.
    No slots.
  • Generic-Function MAKE-OBJECT (bindings class &optional superclasses)
    If CLASS is not NIL, create an instance of that class. Otherwise, create a fluid object whose class has the given SUPERCLASSES (null list by default). In either case, populate the resulting object using BINDINGS (an alist of slot names and values).
  • Method MAKE-OBJECT (bindings (class (eql nil)) &optional (superclasses nil))
    Create a FLUID-OBJECT with the slots given by BINDINGS and whose class has all the given SUPERCLASSES. If the current *CLASS-REGISTRY* has a member with exactly the same direct superclasses, it is updated to include all the given slots. Otherwise, a new FLUID-CLASS is allocated and added to the *CLASS-REGISTRY*.
  • Method MAKE-OBJECT (bindings class &optional superclasses)
    If the CLASS is explicitly specified, just create and populate an instance, discarding any of the BINDINGS which do not correspond to the slots of that CLASS.
  • Method MAKE-OBJECT (bindings (class (eql (find-class 'cons))) &optional superclasses)
    If the CLASS is given as 'CONS, return the BINDINGS as alist.
  • Method MAKE-OBJECT (bindings (class (eql (find-class 'list))) &optional superclasses)
    If the CLASS is given as 'LIST, return the BINDINGS as plist.
  • Method MAKE-OBJECT (bindings (class (eql (find-class 'hash-table))) &optional superclasses)
    If the CLASS is given as 'HASH-TABLE, return the BINDINGS as hash table.
  • Method MAKE-OBJECT (bindings (class symbol) &optional superclasses)
    If the CLASS is given as a symbol, find it and resort to the usual procedure.
  • Variable *PROTOTYPE-NAME*
    'json:prototype
    The key of the prototype field in a JSON Object, and the name of a slot in a Lisp object which accepts its prototype.
  • Class PROTOTYPE
    A PROTOTYPE contains metadata for an object's class in a format easily serializable to JSON: either the name of the class as a string or (if it is anonymous) the names of the superclasses as a list of strings; and the name of the Lisp package into which the names of the class's slots and the name of the class / superclasses are to be interned.
    LISP-CLASS   Reader: LISP-CLASS
    LISP-SUPERCLASSES   Reader: LISP-SUPERCLASSES
    LISP-PACKAGE   Reader: LISP-PACKAGE
  • Generic-Function MAKE-OBJECT-PROTOTYPE (object &optional slot-names)
    Return a PROTOTYPE describing the OBJECT's class or superclasses, and the package into which the names of the class / superclasses and of the OBJECT's slots are to be interned.
  • Method MAKE-OBJECT-PROTOTYPE (object &optional slot-names)
    Return a PROTOTYPE describing the OBJECT's class or superclasses, and the package into which the names of the class / superclasses and of the OBJECT's slots are to be interned.
  • Method MAKE-OBJECT-PROTOTYPE ((class-name symbol) &optional slot-names)
    Return a PROTOTYPE of an object of the class named by CLASS-NAME.
  • Method MAKE-OBJECT-PROTOTYPE ((object prototype) &optional slot-names)
    Prototypes are not to be given their own prototypes, otherwise we would proceed ad malinfinitum.
  • Function SIMPLIFIED-CAMEL-CASE-TO-LISP (camel-string)
    Insert - between lowercase and uppercase chars. Ignore _ + * and several consecutive uppercase.
  • Function CAMEL-CASE-TO-LISP (string)
    Take a camel-case string and convert it into a string with Lisp-style hyphenation.
  • Function LISP-TO-CAMEL-CASE (string)
    Take a string with Lisp-style hyphentation and convert it to camel case. This is an inverse of CAMEL-CASE-TO-LISP.
  • Condition JSON-SYNTAX-ERROR  (SIMPLE-ERROR, STREAM-ERROR)
    Signalled when non-well-formed JSON data are encountered.
  • Function JSON-SYNTAX-ERROR (stream format-control &rest format-arguments)
    Signal a JSON-SYNTAX-ERROR condition.
  • Condition NO-CHAR-FOR-CODE  (ERROR)
    Signalled when, in a JSON String, an escaped code point (uXXXX) is encountered which is greater than the application's CHAR-CODE-LIMIT or for which CODE-CHAR returns NIL.
  • Variable *JSON-INPUT*
    (make-synonym-stream '*standard-input*)
    The default input stream for decoding operations.
  • Variable *INTEGER-HANDLER*
    (constantly 0)
    Designator for a function of 1 string argument (integer token).
  • Variable *REAL-HANDLER*
    (constantly 0)
    Designator for a function of 1 string argument (real token).
  • Variable *BOOLEAN-HANDLER*
    (constantly t)
    Designator for a function of 1 string argument (boolean token).
  • Variable *BEGINNING-OF-STRING-HANDLER*
    (constantly t)
    Designator for a function of no arguments (called at encountering an opening quote for a String).
  • Variable *STRING-CHAR-HANDLER*
    (constantly t)
    Designator for a function of 1 character argument (String char).
  • Variable *END-OF-STRING-HANDLER*
    (constantly "")
    Designator for a function of no arguments (called at encountering a closing quote for a String).
  • Variable *BEGINNING-OF-ARRAY-HANDLER*
    (constantly t)
    Designator for a function of no arguments (called at encountering an opening bracket for an Array).
  • Variable *ARRAY-MEMBER-HANDLER*
    (constantly t)
    Designator for a function of 1 arbitrary argument (decoded member of Array).
  • Variable *END-OF-ARRAY-HANDLER*
    (constantly nil)
    Designator for a function of no arguments (called at encountering a closing bracket for an Array).
  • Variable *JSON-ARRAY-TYPE*
    'vector
    The Lisp sequence type to which JSON Arrays are to be coerced.
  • Variable *BEGINNING-OF-OBJECT-HANDLER*
    (constantly t)
    Designator for a function of no arguments (called at encountering an opening brace for an Object).
  • Variable *OBJECT-KEY-HANDLER*
    (constantly t)
    Designator for a function of 1 string argument (decoded member key of Object).
  • Variable *OBJECT-VALUE-HANDLER*
    (constantly t)
    Designator for a function of 1 arbitrary argument (decoded member value of Object).
  • Variable *END-OF-OBJECT-HANDLER*
    (constantly nil)
    Designator for a function of no arguments (called at encountering a closing brace for an Object).
  • Variable *INTERNAL-DECODER*
    'json:decode-json
    Designator for a function of 1 stream argument called (instead of DECODE-JSON) to decode a member of an Array or of an Object.
  • Variable *OBJECT-SCOPE-VARIABLES*
    '(json:*internal-decoder*)
    A list of symbols naming dynamic variables which should be re-bound in the scope of every JSON Object.
  • Variable *ARRAY-SCOPE-VARIABLES*
    '(json:*internal-decoder*)
    A list of symbols naming dynamic variables which should be re-bound in the scope of every JSON Array.
  • Variable *STRING-SCOPE-VARIABLES*
    nil
    A list of symbols naming dynamic variables which should be re-bound in the scope of every JSON String.
  • Variable *AGGREGATE-SCOPE-VARIABLES*
    nil
    A list of symbols naming dynamic variables which should be re-bound in the scope of every JSON aggregate value (Object, Array or String).
  • Function DECODE-JSON (&optional (stream *json-input*))
    Read a JSON Value from STREAM and return the corresponding Lisp value.
  • Macro CUSTOM-DECODER (&rest customizations)
    Return a function which is like DECODE-JSON called in a dynamic environment with the given CUSTOMIZATIONS.
  • Function DECODE-JSON-FROM-STRING (json-string)
    Read a JSON Value from JSON-STRING and return the corresponding Lisp value.
  • Function DECODE-JSON-FROM-SOURCE (source &optional (decoder 'decode-json))
    Decode a JSON Value from SOURCE using the value of DECODER (default 'DECODE-JSON) as decoder function. If the SOURCE is a string, the input is from this string; if it is a pathname, the input is from the file that it names; otherwise, a stream is expected as SOURCE.
  • Function DECODE-JSON-STRICT (&optional (stream *json-input*))
    Same as DECODE-JSON, but allow only Objects or Arrays on the top level, no junk afterwards.
  • Function SET-DECODER-SIMPLE-LIST-SEMANTICS
    Set the decoder semantics to the following: * Strings and Numbers are decoded naturally, reals becoming floats. * The literal name true is decoded to T, false and null to NIL. * Arrays are decoded to sequences of the type *JSON-ARRAY-TYPE*. * Objects are decoded to alists. Object keys are converted by the function *JSON-IDENTIFIER-NAME-TO-LISP* and then interned in the package *JSON-SYMBOLS-PACKAGE*.
  • Macro WITH-DECODER-SIMPLE-LIST-SEMANTICS (&body body)
    Execute BODY in a dynamic environement where the decoder semantics is such as set by SET-DECODER-SIMPLE-LIST-SEMANTICS.
  • Function SET-DECODER-SIMPLE-CLOS-SEMANTICS
    Set the decoder semantics to the following: * Strings and Numbers are decoded naturally, reals becoming floats. * The literal name true is decoded to T, false and null to NIL. * Arrays are decoded to sequences of the type *JSON-ARRAY-TYPE*. * Objects are decoded to CLOS objects. Object keys are converted by the function *JSON-IDENTIFIER-NAME-TO-LISP*. If a JSON Object has a field whose key matches *PROTOTYPE-NAME*, the class of the CLOS object and the package wherein to intern slot names are inferred from the corresponding value which must be a valid prototype. Otherwise, a FLUID-OBJECT is constructed whose slot names are interned in *JSON-SYMBOLS-PACKAGE*.
  • Macro WITH-DECODER-SIMPLE-CLOS-SEMANTICS (&body body)
    Execute BODY in a dynamic environement where the decoder semantics is such as set by SET-DECODER-SIMPLE-CLOS-SEMANTICS.
  • Macro CURRENT-DECODER (&rest keys)
    Capture current values of custom variables and return a custom decoder which restores these values in its dynamic environment.
  • Macro WITH-CUSTOM-DECODER-LEVEL ((&rest customizations) &body body)
    Execute BODY in a dynamic environment such that, when nested structures are decoded, the outermost level is decoded with the given custom handlers (CUSTOMIZATIONS) whereas inner levels are decoded in the usual way.
  • Variable *JSON-OUTPUT*
    (make-synonym-stream '*standard-output*)
    The default output stream for encoding operations.
  • Condition UNENCODABLE-VALUE-ERROR  (TYPE-ERROR)
    Signalled when a datum is passed to ENCODE-JSON (or another encoder function) which actually cannot be encoded.
  • Function UNENCODABLE-VALUE-ERROR (value &optional context)
    Signal an UNENCODABLE-VALUE-ERROR.
  • Macro WITH-SUBSTITUTE-PRINTED-REPRESENTATION-RESTART ((object stream) &body body)
    Establish a SUBSTITUTE-PRINTED-REPRESENTATION restart for OBJECT and execute BODY.
  • Generic-Function ENCODE-JSON (object &optional stream)
    Write a JSON representation of OBJECT to STREAM and return NIL.
  • Function ENCODE-JSON-TO-STRING (object)
    Return the JSON representation of OBJECT as a string.
  • Method ENCODE-JSON (anything &optional (stream *json-output*))
    If OBJECT is not handled by any specialized encoder signal an error which the user can correct by choosing to encode the string which is the printed representation of the OBJECT.
  • Method ENCODE-JSON ((nr number) &optional (stream *json-output*))
    Write the JSON representation of the number NR to STREAM (or to *JSON-OUTPUT*).
  • Method ENCODE-JSON ((s string) &optional (stream *json-output*))
    Write the JSON representation of the string S to STREAM (or to *JSON-OUTPUT*).
  • Method ENCODE-JSON ((c character) &optional (stream *json-output*))
    JSON does not define a character type, we encode characters as Strings.
  • Method ENCODE-JSON ((s symbol) &optional (stream *json-output*))
    Write the JSON representation of the symbol S to STREAM (or to *JSON-OUTPUT*). If S is boolean, a boolean literal is written. Otherwise, the name of S is passed to *LISP-IDENTIFIER-NAME-TO-JSON* and the result is written as String.
  • Macro WITH-ARRAY ((&optional (stream '*json-output*)) &body body)
    Open a JSON Array, run BODY, then close the Array. Inside the BODY, AS-ARRAY-MEMBER or ENCODE-ARRAY-MEMBER should be called to encode Members of the Array.
  • Macro AS-ARRAY-MEMBER ((&optional (stream '*json-output*)) &body body)
    BODY should be a program which encodes exactly one JSON datum to STREAM. AS-ARRAY-MEMBER ensures that the datum is properly formatted as a Member of an Array, i. e. separated by comma from any preceding or following Member.
  • Function ENCODE-ARRAY-MEMBER (object &optional (stream *json-output*))
    Encode OBJECT as the next Member of the innermost JSON Array opened with WITH-ARRAY in the dynamic context. OBJECT is encoded using the ENCODE-JSON generic function, so it must be of a type for which an ENCODE-JSON method is defined.
  • Function STREAM-ARRAY-MEMBER-ENCODER (stream &optional (encoder #'encode-json))
    Return a function which takes an argument and encodes it to STREAM as a Member of an Array. The encoding function is taken from the value of ENCODER (default is #'ENCODE-JSON).
  • Macro WITH-OBJECT ((&optional (stream '*json-output*)) &body body)
    Open a JSON Object, run BODY, then close the Object. Inside the BODY, AS-OBJECT-MEMBER or ENCODE-OBJECT-MEMBER should be called to encode Members of the Object.
  • Macro AS-OBJECT-MEMBER ((key &optional (stream '*json-output*)) &body body)
    BODY should be a program which writes exactly one JSON datum to STREAM. AS-OBJECT-MEMBER ensures that the datum is properly formatted as a Member of an Object, i. e. preceded by the (encoded) KEY and colon, and separated by comma from any preceding or following Member.
  • Function ENCODE-OBJECT-MEMBER (key value &optional (stream *json-output*))
    Encode KEY and VALUE as a Member pair of the innermost JSON Object opened with WITH-OBJECT in the dynamic context. KEY and VALUE are encoded using the ENCODE-JSON generic function, so they both must be of a type for which an ENCODE-JSON method is defined. If KEY does not encode to a String, its JSON representation (as a string) is encoded over again.
  • Function STREAM-OBJECT-MEMBER-ENCODER (stream &optional (encoder #'encode-json))
    Return a function which takes two arguments and encodes them to STREAM as a Member of an Object (String : Value pair).
  • Function JSON-BOOL (value)
    Intended for the JSON-EXPLICT-ENCODER. Converts a non-nil value to a value (:true) that creates a json true value when used in the explict encoder. Or (:false).
  • Function JSON-OR-NULL (value)
    Intended for the JSON-EXPLICT-ENCODER. Returns a non-nil value as itself, or a nil value as a json null-value
  • Function USE-GUESSING-ENCODER
  • Function USE-EXPLICIT-ENCODER
  • Macro WITH-GUESSING-ENCODER (&body body)
  • Macro WITH-EXPLICIT-ENCODER (&body body)
  • Method ENCODE-JSON ((s list) &optional (stream *json-output*))
    Write the JSON representation of the list S to STREAM (or to *JSON-OUTPUT*), using one of the two rules specified by first calling USE-GUESSING-ENCODER or USE-EXPLICIT-ENCODER. The guessing encoder: If S is a list encode S as a JSON Array, if S is a dotted list encode it as an Object (per ENCODE-JSON-ALIST). The explicit decoder: If S is a list, the first symbol defines the encoding: If (car S) is 'TRUE return a JSON true value. If (car S) is 'FALSE return a JSON false value. If (car S) is 'NULL return a JSON null value. If (car S) is 'JSON princ the strings in (cdr s) to stream If (car S) is 'LIST or 'ARRAY encode (cdr S) as a a JSON Array. If (car S) is 'OBJECT encode (cdr S) as A JSON Object, interpreting (cdr S) either as an A-LIST or a P-LIST.
  • Method ENCODE-JSON ((s sequence) &optional (stream *json-output*))
    Write the JSON representation (Array) of the sequence S (not an alist) to STREAM (or to *JSON-OUTPUT*).
  • Method ENCODE-JSON ((h hash-table) &optional (stream *json-output*))
    Write the JSON representation (Object) of the hash table H to STREAM (or to *JSON-OUTPUT*).
  • Method ENCODE-JSON ((o standard-object) &optional (stream *json-output*))
    Write the JSON representation (Object) of the CLOS object O to STREAM (or to *JSON-OUTPUT*).
  • Function ENCODE-JSON-ALIST (alist &optional (stream *json-output*))
    Write the JSON representation (Object) of ALIST to STREAM (or to *JSON-OUTPUT*). Return NIL.
  • Function ENCODE-JSON-ALIST-TO-STRING (alist)
    Return the JSON representation (Object) of ALIST as a string.
  • Function ENCODE-JSON-PLIST (plist &optional (stream *json-output*))
    Write the JSON representation (Object) of PLIST to STREAM (or to *JSON-OUTPUT*). Return NIL.
  • Function ENCODE-JSON-PLIST-TO-STRING (plist)
    Return the JSON representation (Object) of PLIST as a string.
  • Macro JSON-BIND ((&rest vars) json-source &body body)

JSON-RPC

  • Variable +JSON-RPC-1.1+
    (if (and (boundp 'json-rpc:+json-rpc-1.1+)
             (equalp (symbol-value 'json-rpc:+json-rpc-1.1+) "1.1"))
        (symbol-value 'json-rpc:+json-rpc-1.1+)
        "1.1")
  • Variable +JSON-RPC-2.0+
    (if (and (boundp 'json-rpc:+json-rpc-2.0+)
             (equalp (symbol-value 'json-rpc:+json-rpc-2.0+) "2.0"))
        (symbol-value 'json-rpc:+json-rpc-2.0+)
        "2.0")
  • Variable *JSON-RPC-VERSION*
    json-rpc:+json-rpc-1.1+
    Bind this variable to influence whether you want to use JSON-RPC version 1.1 or 2.0.
  • Function CLEAR-EXPORTED
  • Macro DEFUN-JSON-RPC (name type lambda-list &body body)
    Defines a function and registers it as a json-rpc target.
  • Macro DEF-JSON-RPC-ENCODING (keyword (var) &rest body)
    Define a new encoding keyword, KEYWORD. When the encoding is invoked, the raw value will be bound to VAR, and the BODY should return the encoded value.
  • Function EXPORT-AS-JSON-RPC (func function-name &optional type)
    Registers a lambda function FUNC as a json-rpc function. TYPE determines how the return value of FUNC should be interpreted: :explicit using the explicit encoder syntax, :guessing using the guessing encode syntax :streaming as a raw JSON string.
  • Function INVOKE-RPC (json-source)
    A remote method is invoked by sending a request to a remote service. The request is a single object serialized using JSON. It has three properties: * method - A String containing the name of the method to be invoked. * params - An Array of objects to pass as arguments to the method. * id - The request id. This can be of any type. It is used to match the response with the request that it is replying to.
  • Condition JSON-RPC-CALL-ERROR  (ERROR)
  • Function INVOKE-RPC-PARSED (method params &optional id)
  • Function SEND-ERROR (errmsg code &optional condition)
  • Function SEND-ERROR-OBJECT (explicit-errobject &optional condition)
  • Function SEND-NOTHING (&optional condition)
  • Function SEND-INTERNAL-ERROR (&optional condition)