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

herodotus

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

* Herodotus

** Installation

The library is available on quicklisp since the ~2021-04-11~ dist so
you can install with
#+begin_src lisp
(ql:quickload :herodotus)
#+end_src

To install from source clone the repo into your lisp sources directory
and load with asdf
#+begin_src lisp
(asdf:load-system :herodotus)
#+end_src
or use [[https://github.com/fukamachi/qlot][qlot]]
#+begin_src txt
git herodotus https://github.com/HenryS1/herodotus.git :branch master
#+end_src

** 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 #<SIMPLE-ERROR "Could not find parser for
; class NOT-PARSEABLE. Please define a json model for it."
; {100599D903}>.
#+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 argument 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.



alexandria

cl-ppcre

yason

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).

herodotus

Upstream URL

Author

Maintainer

License

herodotus

Version:

License:

Authors:

Maintainers:

Dependencies:

Dependencies (4)

Dependents (0)