The herodotus Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The herodotus Reference Manual

This is the herodotus Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:19:52 2021 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

[[https://github.com/HenryS1/herodotus/tree/master][https://github.com/HenryS1/herodotus/actions/workflows/ci.yaml/badge.svg]]

* Herodotus

** Basic usage

This library provides a macro that generates JSON serialisation and
deserialisation at the same time as defining a CLOS class.

For example the below definition creates a CLOS class with two fields
~x~ and ~y~ which have obvious accessors (~x~ and ~y~) and initargs
(~:x~ and ~:y~). 
#+begin_src lisp
CL-USER> (herodotus:define-json-model point (x y))
#+end_src

It also defines a package named ~point-json~ with a function for
parsing json ~point-json:from-json~ and also implements a generic method
for writing to json in the herodotus package.

#+begin_src lisp
CL-USER> (defvar *point* (point-json:from-json "{ \"x\": 1, \"y\": 2 }"))
*POINT*
CL-USER> (x *point*)
1
CL-USER> (y *point*)
2
CL-USER> (herodotus:to-json *point*)
"{\"x\":1,\"y\":2}"
#+end_src

** Nested classes 

You can also define classes that have class members using the type
specifier syntax. This block defines two json models ~tree~ and
~branch~. A ~tree~ has ~branch~ members and the branch members will be
parsed from json using the parser defined for the ~tree~.

#+begin_src lisp
CL-USER> (herodotus:define-json-model branch (size))
CL-USER> (herodotus:define-json-model tree ((branches branch)))
#+end_src

The syntax ~(branches branch)~ declares that the field named
~branches~ must be parsed as the type ~branch~. Json models for nested
classes need to be defined before the models for the classes they are
nested in or an error will be thrown. The error is thrown at macro
expansion time.

#+begin_src lisp
CL-USER> (herodotus:define-json-model test-no-parser ((things not-parseable)))
CL-USER> (herodotus:define-json-model test-no-parser ((things not-parseable)))
class-name TEST-NO-PARSER slots ((THINGS NOT-PARSEABLE))
; Evaluation aborted on #.
#+end_src

** None, one or many semantics

Fields in class definitions are parsed as either nil (if missing from
the json), a single instance if the field is not an array and isn't
empty or a vector if the json contains an array of elements.

#+begin_src lisp
CL-USER> (herodotus:define-json-model numbers (ns))
CL-USER> (ns (numbers-json:from-json "{ }"))
NIL
CL_USER> (ns (numbers-json:from-json "{ \"ns\": 1 }"))
1
CL-USER> (ns (numbers-json:from-json "{ \"ns\": [1, 2, 3] }"))
#(1 2 3)
#+end_src

** Setting the parsing case

The macro ~define-json-model~ has an optional third argument which
specifies the case convention for parsing json fields. The options for
this argument are

#+begin_src lisp
:camel-case ;; camelCase
:kebab-case ;; kebab-case
:snake-case ;; snake_case
:screaming-snake-case ;; SCREAMING_SNAKE_CASE
#+end_src

The default value of the argumet is ~:camel-case~. Below is an example
of changing the default case to snake case.

#+begin_src lisp
CL-USER> (herodotus:define-json-model snake-case (pet-snake) :snake-case)
CL-USER> (pet-snake (snake-case-json:from-json "{ \"pet_snake\": \"boa\" }"))
"boa"
CL-USER> (herodotus:to-json (snake-case-json:from-json "{ \"pet_snake\": \"boa\" }"))
"{\"pet_snake\":\"boa\"}"
#+end_src

** Special case field names

Parsing specific field names can be done using the third argument of a
field specifier. If a special field name is provided it doesn't have
to match the name of the slot in the CLOS class and can use any
formatting convention.

#+begin_src lisp
CL-USER> (herodotus:define-json-model special-case ((unusual-format () "A_very-UniqueNAME"))
CL-USER> (unusual-format (special-case-json:from-json "{ \"A_very-UniqueNAME\": \"Phineas Fog\" }"))
"Phineas Fog"
CL-USER> (herodotus:to-json (special-case-json:from-json "{ \"A_very-UniqueNAME\": \"Phineas Fog\" }"))
"{\"A_very-UniqueNAME\":\"Phineas Fog\"}"
#+end_src

** Macro specification

The ~define-json-model~ macro takes three arguments: ~name~, ~slots~
and an optional argument for ~case-type~. The ~name~ argument is the
name of the generated CLOS class. The ~slots~ argument is a collection
of slot descriptors and the ~case-type~ argument is a keyword.

Slot descriptors can be either symbols or lists. If a slot descriptor
is a symbol then the value of the corresponding CLOS slot will be a
deserialised json primitive in lisp form: a number, boolean, string,
vector (for arrays), or hash-table (for objects).

If a slot descriptor is a list then first argument is the CLOS slot
name, the second argument is either ~()~ or the name of a previously
defined json model to deserialise the value of this field to. The
optional third argument is a special case name for this field which
can have custom formatting.

The ~case-type~ keyword argument is one of ~:screaming-snake-case~,
~:snake-case~, ~:kebab-case~ and ~:camel-case~ and defines the
formatting convention for field names in a json object.

** Dependencies

The project depends on [[https://github.com/phmarek/yason][YASON]] which does the json parsing and
serialisation under the hood, [[https://github.com/edicl/cl-ppcre][CL-PPCRE]] for text manipulation during
code generation and [[https://github.com/kmx-io/alexandria][Alexandria]] for macro writing utilities.

** License

This project is provided under the MIT license. See the LICENSE file for details.



Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 herodotus

Maintainer

<henry.steere@gmail.com>

Author

Henry Steere

License

BSD

Description

Wrapper around Yason JSON parser/encoder with convenience methods for CLOS

Long Description

Provides a define-serialiser macro that defines both an encoder and decoder for a common lisp class. Allows one to easily specify case convention for fields in a JSON object as either snake case, camel case, or screaming snake case (with apologies to the rust library serde).

Version

1.0.0

Dependencies
Source

herodotus.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 herodotus/src

Parent

herodotus (system)

Location

src/

Component

herodotus.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 herodotus.asd

Location

herodotus.asd

Systems

herodotus (system)


Previous: , Up: Lisp files   [Contents][Index]

4.1.2 herodotus/src/herodotus.lisp

Parent

src (module)

Location

src/herodotus.lisp

Packages

herodotus

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 herodotus

Source

herodotus.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: define-json-model NAME SLOTS &optional CASE-TYPE
Package

herodotus

Source

herodotus.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Generic functions

Generic Function: to-json CLASS
Package

herodotus

Source

herodotus.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Macros

Macro: define-encoder CLASS-NAME SLOTS CASE-FN
Package

herodotus

Source

herodotus.lisp (file)

Macro: define-json-constructor CLASS-NAME SLOTS CASE-FN
Package

herodotus

Source

herodotus.lisp (file)

Macro: define-parser CLASS-NAME SLOTS CASE-FN
Package

herodotus

Source

herodotus.lisp (file)

Macro: within-package PACKAGE-NAME &rest BODY
Package

herodotus

Source

herodotus.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: camel-case STR
Package

herodotus

Source

herodotus.lisp (file)

Function: get-slot SLOT-SPEC
Package

herodotus

Source

herodotus.lisp (file)

Function: get-slot-defs SLOT-SPECS
Package

herodotus

Source

herodotus.lisp (file)

Function: get-slot-type SLOT
Package

herodotus

Source

herodotus.lisp (file)

Function: has-custom-key X
Package

herodotus

Source

herodotus.lisp (file)

Function: has-object-constructor SLOT
Package

herodotus

Source

herodotus.lisp (file)

Function: json-package-name CLASS-NAME
Package

herodotus

Source

herodotus.lisp (file)

Function: make-hash-parser-name CLASS-NAME
Package

herodotus

Source

herodotus.lisp (file)

Function: make-init-arg SLOT-SPEC
Package

herodotus

Source

herodotus.lisp (file)

Function: make-keys SLOTS CASE-FN
Package

herodotus

Source

herodotus.lisp (file)

Function: make-keyword SYM
Package

herodotus

Source

herodotus.lisp (file)

Function: make-object-slot INIT-ARG KEY SLOT JSON-OBJ
Package

herodotus

Source

herodotus.lisp (file)

Function: make-standard-slot INIT-ARG KEY JSON-OBJ
Package

herodotus

Source

herodotus.lisp (file)

Function: screaming-snake-case STR
Package

herodotus

Source

herodotus.lisp (file)

Function: select-case-function CASE-TYPE
Package

herodotus

Source

herodotus.lisp (file)

Function: slot-accessor SLOT-DESCRIPTION
Package

herodotus

Source

herodotus.lisp (file)

Function: snake-case STR
Package

herodotus

Source

herodotus.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   H   L   M  
Index Entry  Section

F
File, Lisp, herodotus.asd: The herodotus․asd file
File, Lisp, herodotus/src/herodotus.lisp: The herodotus/src/herodotus․lisp file

H
herodotus.asd: The herodotus․asd file
herodotus/src: The herodotus/src module
herodotus/src/herodotus.lisp: The herodotus/src/herodotus․lisp file

L
Lisp File, herodotus.asd: The herodotus․asd file
Lisp File, herodotus/src/herodotus.lisp: The herodotus/src/herodotus․lisp file

M
Module, herodotus/src: The herodotus/src module

Jump to:   F   H   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   D   F   G   H   J   M   S   T   W  
Index Entry  Section

C
camel-case: Internal functions

D
define-encoder: Internal macros
define-json-constructor: Internal macros
define-json-model: Exported macros
define-parser: Internal macros

F
Function, camel-case: Internal functions
Function, get-slot: Internal functions
Function, get-slot-defs: Internal functions
Function, get-slot-type: Internal functions
Function, has-custom-key: Internal functions
Function, has-object-constructor: Internal functions
Function, json-package-name: Internal functions
Function, make-hash-parser-name: Internal functions
Function, make-init-arg: Internal functions
Function, make-keys: Internal functions
Function, make-keyword: Internal functions
Function, make-object-slot: Internal functions
Function, make-standard-slot: Internal functions
Function, screaming-snake-case: Internal functions
Function, select-case-function: Internal functions
Function, slot-accessor: Internal functions
Function, snake-case: Internal functions

G
Generic Function, to-json: Exported generic functions
get-slot: Internal functions
get-slot-defs: Internal functions
get-slot-type: Internal functions

H
has-custom-key: Internal functions
has-object-constructor: Internal functions

J
json-package-name: Internal functions

M
Macro, define-encoder: Internal macros
Macro, define-json-constructor: Internal macros
Macro, define-json-model: Exported macros
Macro, define-parser: Internal macros
Macro, within-package: Internal macros
make-hash-parser-name: Internal functions
make-init-arg: Internal functions
make-keys: Internal functions
make-keyword: Internal functions
make-object-slot: Internal functions
make-standard-slot: Internal functions

S
screaming-snake-case: Internal functions
select-case-function: Internal functions
slot-accessor: Internal functions
snake-case: Internal functions

T
to-json: Exported generic functions

W
within-package: Internal macros

Jump to:   C   D   F   G   H   J   M   S   T   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   H   P   S  
Index Entry  Section

H
herodotus: The herodotus system
herodotus: The herodotus package

P
Package, herodotus: The herodotus package

S
System, herodotus: The herodotus system

Jump to:   H   P   S