Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the clop Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:25:01 2022 GMT+0.
Next: Systems, Previous: The clop Reference Manual, Up: The clop Reference Manual [Contents][Index]
* CLOP - Common Lisp tOml Parser
** Overview
[[https://toml.io][Tom's Obvious Minimal Language (TOML)]] is a human friendly configuration file format. This library implements a parser (decoder) for it.
Clop strictly follows TOML 1.0 specification and is fully compatible with it. It passes all 296 tests defined in [[https://github.com/BurntSushi/toml-test][BurntSushi/toml-test]].
It is implemented by utilizing [[https://github.com/scymtym/esrap][ESRAP]], which is a really awesome library.
** Installation
Once it gets into Quicklisp, you can load it by:
#+BEGIN_SRC lisp
;; Load it.
(ql:quickload "clop")
;; Run some basic tests.
(asdf:test-system "clop")
#+END_SRC
If you want to run comprehensive tests, you need to first clone [[https://github.com/BurntSushi/toml-test][toml-test]] and set it up locally.
Use the following command to test it:
#+BEGIN_SRC sh
cd /path/to/clop/roswell
ros build decoder.ros
/path/to/toml-test/toml-test ./decoder
#+END_SRC
You should now see a line of:
#+BEGIN_SRC text
toml-test [/path/to/clop/roswell/decoder]: using embedded tests: 296 passed, 0 failed
#+END_SRC
** Usage
*** Functions
The main entry point of Clop is ~parse~ function.
#+BEGIN_SRC lisp
(defparameter +toml-text+ "
[server]
port = 5000
print-access-log = false
")
(clop:parse +toml-text+)
; => (("server" ("port" . 5000) ("print-access-log")))
#+END_SRC
This function takes an optional keyword argument ~style~ that controls the output style:
- ~:alist~. The default. TOML tables are transformed to alists.
- ~:jsown~. TOML tables are transformed to jsown style ~(:obj "key" "value")~.
- ~:raw~. TOML tables are transformed to Clop internal representations, i.e. classes ~table~, ~table-array~ and ~inline-table~.
*** Configurations
The behavior of Clop can be tuned by settings configuration variables. Wrap them in a let lexical context or change their values globally to make it work.
|---------------+---------------+----------------------------|
| Variable | Default Value | Meaning |
|---------------+---------------+----------------------------|
| *value-+inf* | :+INF | The value of +inf |
| *value--inf* | :-INF | The value of -inf |
| *value-+nan* | :+NAN | The value of +nan |
| *value--nan* | :-NAN | The value of -nan |
| *value-true* | T | The value of boolean true |
| *value-false* | NIL | The value of boolean false |
|---------------+---------------+----------------------------|
*** Extending Clop
Clop implementation has 2 concepts: value parser and block parser.
- Value parser is used for handling basic values, i.e. string, integer, float, bool, datetime, datetime-local, date-local, time-local.
- Block parser is used for handling TOML blocks, i.e. key-value-pair, table, inline-table and table-array.
**** Tuning Value Parser
For basic values, you may:
1. Define your own value parser function that takes 2 arguments: type and value, and return the resulting value.
2. Set ~clop.config:*value-parser*~ variable to your own function.
You may refer to ~roswell/decoder.ros~ for an example. ~toml-test~ requires values to be a JSON object like:
#+BEGIN_SRC json
{
"type": "integer",
"value": 123
}
#+END_SRC
Code in ~roswell/decoder.ros~ tunes value parser to return such ~jsown~ object.
**** Tuning Block Parser
Instead of implementing your own block parser, you may pass a ~:raw~ style to ~clop:parse~ function and start from the return value. Check docstrings in ~src/toml-block-parser~ for more detail.
Next: Modules, Previous: Introduction, Up: The clop Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Next: Files, Previous: Systems, Up: The clop Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
clop (system).
Next: Packages, Previous: Modules, Up: The clop Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: clop/src/toml-value-parser.lisp, Previous: clop/clop.asd, Up: Lisp [Contents][Index]
src (module).
Next: clop/src/config.lisp, Previous: clop/src/conditions.lisp, Up: Lisp [Contents][Index]
src (module).
parse-value (generic function).
Next: clop/src/toml-block.lisp, Previous: clop/src/toml-value-parser.lisp, Up: Lisp [Contents][Index]
src (module).
Next: clop/src/toml-block-parser.lisp, Previous: clop/src/config.lisp, Up: Lisp [Contents][Index]
src (module).
Next: clop/src/rules.lisp, Previous: clop/src/toml-block.lisp, Up: Lisp [Contents][Index]
src (module).
Next: clop/src/clop.lisp, Previous: clop/src/toml-block-parser.lisp, Up: Lisp [Contents][Index]
src (module).
Next: Definitions, Previous: Files, Up: The clop Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: clop.toml-block, Previous: Packages, Up: Packages [Contents][Index]
parse (function).
serialize (generic function).
Next: clop.config, Previous: clop, Up: Packages [Contents][Index]
common-lisp.
Next: clop.conditions, Previous: clop.toml-block, Up: Packages [Contents][Index]
common-lisp.
Next: clop.rules, Previous: clop.config, Up: Packages [Contents][Index]
common-lisp.
Next: clop.toml-block-parser, Previous: clop.conditions, Up: Packages [Contents][Index]
clop.
Next: clop.toml-value-parser, Previous: clop.rules, Up: Packages [Contents][Index]
clop.
Previous: clop.toml-block-parser, Up: Packages [Contents][Index]
common-lisp.
parse-value (generic function).
Next: Indexes, Previous: Packages, Up: The clop Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
The value of +inf when decoding TOML.
The value of +nan when decoding TOML.
The value of -inf when decoding TOML.
The value of -nan when decoding TOML.
The value of false when decoding TOML.
The value of true when decoding TOML.
Next: Generic functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Parse given string TEXT and convert the result to given STYLE.
The STYLE can be one of:
* :alist (the default)
* :jsown (jsown-like object)
* :raw (should be rarely used)
The top-level of result is an alist.
You may implement your own style by implementing SERIALIZE method.
Given a LIST of components (tables or key-value pairs), return an alist.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
A table of any kind. Note that for a table, its own name is not stored as a property of itself, but as a hash key in children property of its parent collection. The parsed result is a table representing root table.
automatically generated reader method
keys.
automatically generated writer method
keys.
automatically generated reader method
automatically generated writer method
automatically generated reader method
automatically generated writer method
Return a plist with keys (:hour :minute :second).
Return a plist with keys (:year :month :day).
Return a plist with keys (:year :month :day :hour :minute :second).
Return a timestamp.
automatically generated reader method
automatically generated writer method
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
error.
error.
:names
Previous: Conditions, Up: Public Interface [Contents][Index]
A table of any kind. Note that for a table, its own name is not stored as a property of itself, but as a hash key in children property of its parent collection. The parsed result is a table representing root table.
(make-hash-table :test (function equal))
Internal use.
Indicates if the table is defined or not.
A table is defined in the following ways:
1. By [Table] header.
2. By being a path of dotted.key.tables. In this case, all the tables along the
way are created and defined.
Its value can be:
- NIL means table is opened but not defined.
- T means defined via [Table] header.
- A table instance means defined under corresponding table section.
boolean
:definition-context
(list)
list
:pairs
string
:names
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Generic functions, Previous: Internals, Up: Internals [Contents][Index]
Append TABLE as a child to TABLE-ARRAY.
Get the child of TABLE specified by NAME.
Get the last child of TABLE-ARRAY.
Parse number from STRING with underscores dropped.
Set the child of TABLE specified by NAME to VALUE.
Next: Classes, Previous: Ordinary functions, Up: Internals [Contents][Index]
automatically generated reader method
automatically generated writer method
Internal use.
Indicates if the table is defined or not.
A table is defined in the following ways:
1. By [Table] header.
2. By being a path of dotted.key.tables. In this case, all the tables along the
way are created and defined.
Its value can be:
- NIL means table is opened but not defined.
- T means defined via [Table] header.
- A table instance means defined under corresponding table section.
automatically generated reader method
Convert given TABLE to STYLE.
The TABLE should be the root table containing
clop.
text.
Previous: Generic functions, Up: Internals [Contents][Index]
Previous: Definitions, Up: The clop Reference Manual [Contents][Index]
| Jump to: | (
A B C D F G H K L M N P R S T V |
|---|
| Jump to: | (
A B C D F G H K L M N P R S T V |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
C D K N P R S T V |
|---|
| Jump to: | *
C D K N P R S T V |
|---|
| Jump to: | C F I M P R S T |
|---|
| Jump to: | C F I M P R S T |
|---|