The pp-toml Reference Manual

Table of Contents

The pp-toml Reference Manual

This is the pp-toml Reference Manual, version 1.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 12:11:58 2021 GMT+0.

1 Introduction

Paul's Parser for Tom's Own Minimal Language

Common Lisp TOML parser.

Compliance notes

• Supports the TOML v0.1.0 spec with the following exceptions:

• Complications arising from escaping quote & comment syntax are known and deferred until someone gets bit and is angry enough to send a pull request fixing them.

• Not enforcing array homogeneity. Partly this is because of Postel's dictum, but partly because it might be more convenient to have heterogenous lists. Future work - might add a strict mode which throws errors here.

• Unicode support may have some issues. It should work, but Unicode on Common Lisp is sometimes dependant on your system's configuration. Testing should be done before rolling your work to production.

• Common Lisp is pretty good with numbers. Therefore, instead of manually differentiating between floats and integers, pp-toml calls them NUMBERS and lets your Lisp take care of the rest. Again, test before rolling to production.

Testing

To run the tests, do this:

 sbcl --script run-sbcl-tests.lisp

Which will produce a test report.

Contributions

Gratefully accepted. Please add test cases for bug reports you fix or features you add.

License is LLGPL.

Remarks

Since Tom thought it'd be a good idea to put his name on the language, I'm putting my name on this parser.

2 Systems

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

2.1 pp-toml

Maintainer

Paul Nathan <pnathan@alumni.uidaho.edu>

Author

Paul Nathan <pnathan@alumni.uidaho.edu>

License

LLGPL

Description

TOML parser

Long Description

Implements a TOML parser. PARSE-TOML is the top-level function

Version

1.0.1

Dependencies

• alexandria
• cl-ppcre
• generic-comparability
• local-time
• parse-number
• split-sequence
• esrap

Source

pp-toml.asd (file)

Component

pp-toml.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 pp-toml.asd

Location

pp-toml.asd

Systems

pp-toml (system)

3.1.2 pp-toml/pp-toml.lisp

Parent

pp-toml (system)

Location

pp-toml.lisp

Packages

pp-toml

Exported Definitions

• parse-string (function)
• parse-toml (function)
• strip-comments (function)

Internal Definitions

• *comment-scanner* (special variable)
• explode-hash-table (function)
• extract-lisp-structure (function)
• key-p (function)
• make-nested-hash (function)
• not-bracket (function)
• not-doublequote (function)
• not-integer (function)
• not-special-case (function)
• process-value-data (function)
• splode-y (function)
• transliterate-to-specials (function)
• transliterate-unicode (function)

4 Packages

Packages are listed by definition order.

4.1 pp-toml

Source

pp-toml.lisp (file)

Use List

• generic-comparability
• esrap
• common-lisp

Exported Definitions

• parse-string (function)
• parse-toml (function)
• strip-comments (function)

Internal Definitions

• *comment-scanner* (special variable)
• explode-hash-table (function)
• extract-lisp-structure (function)
• key-p (function)
• make-nested-hash (function)
• not-bracket (function)
• not-doublequote (function)
• not-integer (function)
• not-special-case (function)
• process-value-data (function)
• splode-y (function)
• transliterate-to-specials (function)
• transliterate-unicode (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: parse-string STRING

Returns the toml parsed structure from ‘string‘ or :parse-error

Package

pp-toml

Source

pp-toml.lisp (file)

Function: parse-toml STRING &key STRICT

Parse a TOML ‘string‘, returning a hash table comparable by EQUAL.

‘strict‘ is not supported at present.

Package

pp-toml

Source

pp-toml.lisp (file)

Function: strip-comments STRING

Strips the comments from the string

Package

pp-toml

Source

pp-toml.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *comment-scanner*

Scanner for # comments. Handles "#" strings

Package

pp-toml

Source

pp-toml.lisp (file)

5.2.2 Functions

Function: explode-hash-table TABLE

Package

pp-toml

Source

pp-toml.lisp (file)

Function: extract-lisp-structure PARSED-STRUCTURE

Package

pp-toml

Source

pp-toml.lisp (file)

Function: key-p KEY TABLE

Does ‘key‘ exist in ‘table?

Package

pp-toml

Source

pp-toml.lisp (file)

Function: make-nested-hash TABLE KEY-LIST VALUE

Package

pp-toml

Source

pp-toml.lisp (file)

Function: not-bracket CHAR

Package

pp-toml

Source

pp-toml.lisp (file)

Function: not-doublequote CHAR

Package

pp-toml

Source

pp-toml.lisp (file)

Function: not-integer STRING

Package

pp-toml

Source

pp-toml.lisp (file)

Function: not-special-case CHAR

Package

pp-toml

Source

pp-toml.lisp (file)

Function: process-value-data VALUE

‘value‘ may be any of the standard toml value types: array,
datetime, bool, number, or string. Of those, arrays are a special case:
Supposing an array is encountered, process-value-data recurses upon the array.

Toml does not support references as of v0.1, and there for we can traverse arrays without cyles of references.

Package

pp-toml

Source

pp-toml.lisp (file)

Function: splode-y TABLE SPLITTER KEY VALUE

Package

pp-toml

Source

pp-toml.lisp (file)

Function: transliterate-to-specials STRING

Transliterate escape characters into Common Lisp characters

Package

pp-toml

Source

pp-toml.lisp (file)

Function: transliterate-unicode STRING

Package

pp-toml

Source

pp-toml.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types