The define-json-expander Reference Manual

Table of Contents

The define-json-expander Reference Manual

This is the define-json-expander Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:41:25 2021 GMT+0.

1 Introduction

define-json-expander

Small 'library' for writing simple interfaces between JSON files and CLOS. The `define-json-expander' macro creates both a CLOS-class and a decoder function named DECODE-* where * = name (this can be changed with accessor-prefix) for simple use. define-json-expander is supposed to be used in tandem with cl-json as its decode-functions expects cl-json list-decoded JSON output as input.

This library is written by Johan Sjölén and is licensed under the MIT license.

Usage

define-json-expander has the same syntax as defclass with two new slot-options: :json-prop :json-decoder. :json-prop expects a keyword that represents a property name. :json-decoder expects a function of one argument whose output will be used as the value for the slot. The input to the :json-decoder function is the value of the json property.

All accessors (if not already defined) are on the form *-OF

If no :json-prop is defined then the slot-name as a keyword will be taken automatically.

All unknown/unusued data will be put in the REST slot of the resulting object.

Example usage

The following JSON is taken from json.org/example.html

JSON

{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}
    ]
  }
}}

Code

(define-json-expander menu ()
 ((menu :json-decoder #'decode-menu-slots)))

(define-json-expander menu-slots ()
         ((id)
          (value)
          (popup :json-decoder #'decode-menuitem)))

(define-json-expander menuitem ()
  ((menuitem :json-decoder (lambda (x) (loop for obj in x collect (decode-button obj))))))

(define-json-expander button ()
  ((value) (onclick)))
`

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 define-json-expander

Author

Johan Sjölén

License

MIT

Description

Small facility for converting between JSON and CLOS

Source

define-json-expander.asd (file)

Components

• package.lisp (file)
• define-json-expander.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 define-json-expander.asd

Location

define-json-expander.asd

Systems

define-json-expander (system)

3.1.2 define-json-expander/package.lisp

Parent

define-json-expander (system)

Location

package.lisp

Packages

define-json-expander

3.1.3 define-json-expander/define-json-expander.lisp

Dependency

package.lisp (file)

Parent

define-json-expander (system)

Location

define-json-expander.lisp

Exported Definitions

• *accessor-prefix* (special variable)
• define-json-expander (macro)

Internal Definitions

• clean-option (function)
• clean-options (function)
• define-json-decoder (macro)
• flatten-n-times (function)
• get-prop (function)
• group (function)

4 Packages

Packages are listed by definition order.

4.1 define-json-expander

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *accessor-prefix* (special variable)
• define-json-expander (macro)

Internal Definitions

• clean-option (function)
• clean-options (function)
• define-json-decoder (macro)
• flatten-n-times (function)
• get-prop (function)
• group (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *accessor-prefix*

Package

define-json-expander

Source

define-json-expander.lisp (file)

5.1.2 Macros

Macro: define-json-expander NAME DIRECT-SUPERCLASSES DIRECT-SLOTS &rest OPTIONS

Package

define-json-expander

Source

define-json-expander.lisp (file)

5.2 Internal definitions

5.2.1 Macros

Macro: define-json-decoder NAME &rest SLOT/JSON-LIST

Generates a decoder function with the name decode-‘name’
The ‘slot/json-list’ is of the form (slot-name json-property-name &optional decoder-function) where slot-name refers to the slot’s initarg
decoder-function refers to the function which will be called upon a structure if so provided

The decoder automatically takes all unused JSON-properties and puts them into the rest slot

Example definition and expansion:
(define-4chan-decoder post
(:no :no)
(:name :name)
(:e-mail :email)
(:body :com)
(:date :time))
(DEFUN DECODE-POST (POST)
"Takes a JSON document in list form and decodes it into a CLOS POST object"
(FLET ((P (KEY)
(CDR (ASSOC KEY POST))))
(MAKE-INSTANCE ’POST :NO (P :NO) :NAME (P :NAME) :E-MAIL (P :EMAIL) :BODY
(P :COM) :DATE (P :TIME) :REST
(REMOVE-IF
(LAMBDA (ELT)
(MEMBER (CAR ELT)
’((:NO :NO) (:NAME :NAME) (:E-MAIL :EMAIL)
(:BODY :COM) (:DATE :TIME))
:KEY #’CADR :TEST #’EQ))
POST))))

Package

define-json-expander

Source

define-json-expander.lisp (file)

5.2.2 Functions

Function: clean-option DIRECT-SLOT OPTION

Returns two values, the first being the ‘direct-slot’ with the ‘option’ and its value stripped and the second being a list consisting of the name of the slot and the found prop and value. If such a prop isn’t found then the second element is NIL.

Package

define-json-expander

Source

define-json-expander.lisp (file)

Function: clean-options SLOTS &rest OPTIONS

Cleans several options from several slots.

Package

define-json-expander

Source

define-json-expander.lisp (file)

Function: flatten-n-times TREE &optional N

Flatten a tree by n levels of subtrees. n = 1 doesn’t flatten at all.

Package

define-json-expander

Source

define-json-expander.lisp (file)

Function: get-prop SYMBOL LIST

Package

define-json-expander

Source

define-json-expander.lisp (file)

Function: group SOURCE N

Package

define-json-expander

Source

define-json-expander.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types