Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-yaml Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:28:36 2018 GMT+0.
• Introduction: | What cl-yaml is all about | |
• Systems: | The systems documentation | |
• Modules: | The modules documentation | |
• Files: | The files documentation | |
• Packages: | The packages documentation | |
• Definitions: | The symbols documentation | |
• Indexes: | Concepts, functions, variables and data types |
A YAML parser and emitter built on top of libyaml. Uses the cl-libyaml library.
The yaml
package exports three functions:
(parse string-or-pathname)
: Parses a string or a pathname into Lisp values.(emit value stream)
: Emit a Lisp value into a stream.(emit-to-string value)
: Emit a Lisp value into a string.CL-USER> (yaml:parse "[1, 2, 3]")
(1 2 3)
CL-USER> (yaml:parse "{ a: 1, b: 2 }")
{"a" => 1, "b" => 2}
CL-USER> (yaml:parse "- Mercury
- Venus
- Earth
- Mars")
("Mercury" "Venus" "Earth" "Mars")
CL-USER> (yaml:parse "foo
---
bar" :multi-document-p t)
(:DOCUMENTS "foo" "bar")
CL-USER> (yaml:emit-to-string (list 1 2 3))
"[1, 2, 3]"
CL-USER> (yaml:emit-to-string
(alexandria:alist-hash-table '(("a" . 1)
("b" . 2))))
"{ b: 2, a: 1 }"
CL-USER> (yaml:emit (list t 123 3.14) *standard-output*)
[true, 123, 3.14]
cl-yaml uses YAML's Core Schema to map YAML values to Lisp types an vice versa. A table showing the correspondence of values and types is shown below:
| YAML type | Lisp type |
| ---------- | ----------------- |
| Null | nil
|
| Boolean | t
and nil
|
| Integer | Integer |
| Float | Double float |
| String | String |
| List | List |
| Map | Hash table |
| Document | (:document ...)
|
Common Lisp doesn't natively support the IEEE special floating point values: NaN (Not a number), positive infinity and negative infinity are unrepresentable in portable Common Lisp. Since YAML allows documents to include these values, we have to figure out what to do with them. cl-yaml supports multiple float strategies.
The default strategy is :keyword
, which uses keywords to represent these
values. The strategy can be customized by setting the value of
yaml.float:*float-strategy*
to one of the following keywords:
:error
: The simplest approach, simply signal the condition
yaml.error:unsupported-float-value
whenever a NaN or infinity value is
encountered.
:keyword
: Use keywords to represent the different values, i.e.: :NaN
for
NaN, :+Inf
for positive infinity and :-Inf
for negative infinity.
:best-effort
: Use implementation-specific values whenever possible, fall
back on :keyword
in unsupported implementations. On SBCL and Allegro Common
Lisp, NaN and infinity can be represented.
Copyright (c) 2013-2015 Fernando Borretti
Licensed under the MIT License.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-yaml system: |
Fernando Borretti <eudoxiahp@gmail.com>
Fernando Borretti <eudoxiahp@gmail.com>
(:git "git@github.com:eudoxia0/cl-yaml.git")
MIT
A YAML parser and emitter.
# cl-yaml
[](https://travis-ci.org/eudoxia0/cl-yaml)
[](https://coveralls.io/r/eudoxia0/cl-yaml?branch=master)
[](http://quickdocs.org/cl-yaml/)
A YAML parser and emitter built on top of [libyaml][libyaml]. Uses the
[cl-libyaml][cl-libyaml] library.
# Usage
The ‘yaml‘ package exports three functions:
* ‘(parse string-or-pathname)‘: Parses a string or a pathname into Lisp values.
* ‘(emit value stream)‘: Emit a Lisp value into a stream.
* ‘(emit-to-string value)‘: Emit a Lisp value into a string.
## Parsing
“‘lisp
CL-USER> (yaml:parse "[1, 2, 3]")
(1 2 3)
CL-USER> (yaml:parse "{ a: 1, b: 2 }")
{"a" => 1, "b" => 2}
CL-USER> (yaml:parse "- Mercury
- Venus
- Earth
- Mars")
("Mercury" "Venus" "Earth" "Mars")
CL-USER> (yaml:parse "foo
—
bar" :multi-document-p t)
(:DOCUMENTS "foo" "bar")
“‘
## Emitting
“‘lisp
CL-USER> (yaml:emit-to-string (list 1 2 3))
"[1, 2, 3]"
CL-USER> (yaml:emit-to-string
(alexandria:alist-hash-table ’(("a" . 1)
("b" . 2))))
"{ b: 2, a: 1 }"
CL-USER> (yaml:emit (list t 123 3.14) *standard-output*)
[true, 123, 3.14]
“‘
# Documentation
## Type Mapping
cl-yaml uses YAML’s [Core Schema][core-schema] to map YAML values to Lisp types
an vice versa. A table showing the correspondence of values and types is shown
below:
| YAML type | Lisp type |
| ———- | —————– |
| Null | ‘nil‘ |
| Boolean | ‘t‘ and ‘nil‘ |
| Integer | Integer |
| Float | Double float |
| String | String |
| List | List |
| Map | Hash table |
| Document | ‘(:document ...)‘ |
## IEEE Floating Point Support
Common Lisp doesn’t natively support the IEEE special floating point values: NaN
(Not a number), positive infinity and negative infinity are unrepresentable in
portable Common Lisp. Since YAML allows documents to include these values, we
have to figure out what to do with them. cl-yaml supports multiple float
strategies.
The default strategy is ‘:keyword‘, which uses keywords to represent these
values. The strategy can be customized by setting the value of
‘yaml.float:*float-strategy*‘ to one of the following keywords:
1. ‘:error‘: The simplest approach, simply signal the condition
‘yaml.error:unsupported-float-value‘ whenever a NaN or infinity value is
encountered.
2. ‘:keyword‘: Use keywords to represent the different values, i.e.: ‘:NaN‘ for
NaN, ‘:+Inf‘ for positive infinity and ‘:-Inf‘ for negative infinity.
3. ‘:best-effort‘: Use implementation-specific values whenever possible, fall
back on ‘:keyword‘ in unsupported implementations. On SBCL and Allegro Common
Lisp, NaN and infinity can be represented.
[core-schema]: http://www.yaml.org/spec/1.2/spec.html#id2804923
[libyaml]: http://pyyaml.org/wiki/LibYAML
[cl-libyaml]: https://github.com/eudoxia0/cl-libyaml
# License
Copyright (c) 2013-2015 Fernando Borretti
Licensed under the MIT License.
0.1
cl-yaml.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
• The cl-yaml/src module: |
cl-yaml (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files: |
Next: The cl-yaml/src/error<dot>lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-yaml.asd
cl-yaml (system)
Next: The cl-yaml/src/float<dot>lisp file, Previous: The cl-yaml<dot>asd file, Up: Lisp files [Contents][Index]
src (module)
src/error.lisp
Next: The cl-yaml/src/scalar<dot>lisp file, Previous: The cl-yaml/src/error<dot>lisp file, Up: Lisp files [Contents][Index]
error.lisp (file)
src (module)
src/float.lisp
*sbcl-nan-value* (special variable)
Next: The cl-yaml/src/parser<dot>lisp file, Previous: The cl-yaml/src/float<dot>lisp file, Up: Lisp files [Contents][Index]
float.lisp (file)
src (module)
src/scalar.lisp
parse-scalar (function)
Next: The cl-yaml/src/emitter<dot>lisp file, Previous: The cl-yaml/src/scalar<dot>lisp file, Up: Lisp files [Contents][Index]
scalar.lisp (file)
src (module)
src/parser.lisp
Next: The cl-yaml/src/yaml<dot>lisp file, Previous: The cl-yaml/src/parser<dot>lisp file, Up: Lisp files [Contents][Index]
parser.lisp (file)
src (module)
src/emitter.lisp
Previous: The cl-yaml/src/emitter<dot>lisp file, Up: Lisp files [Contents][Index]
emitter.lisp (file)
src (module)
src/yaml.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The yaml.error package: | ||
• The yaml.float package: | ||
• The yaml.scalar package: | ||
• The yaml.parser package: | ||
• The yaml.emitter package: | ||
• The cl-yaml package: |
Next: The yaml<dot>float package, Previous: Packages, Up: Packages [Contents][Index]
YAML errors.
error.lisp (file)
common-lisp
Next: The yaml<dot>scalar package, Previous: The yaml<dot>error package, Up: Packages [Contents][Index]
Handle IEEE floating point values.
float.lisp (file)
common-lisp
*sbcl-nan-value* (special variable)
Next: The yaml<dot>parser package, Previous: The yaml<dot>float package, Up: Packages [Contents][Index]
Parser for scalar values.
scalar.lisp (file)
common-lisp
parse-scalar (function)
Next: The yaml<dot>emitter package, Previous: The yaml<dot>scalar package, Up: Packages [Contents][Index]
The YAML parser.
parser.lisp (file)
common-lisp
Next: The cl-yaml package, Previous: The yaml<dot>parser package, Up: Packages [Contents][Index]
The YAML emitter.
emitter.lisp (file)
common-lisp
Previous: The yaml<dot>emitter package, Up: Packages [Contents][Index]
The main YAML interface.
yaml.lisp (file)
yaml
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions: | ||
• Internal definitions: |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported special variables: | ||
• Exported macros: | ||
• Exported functions: | ||
• Exported generic functions: | ||
• Exported conditions: |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
float.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
emitter.lisp (file)
emitter.lisp (file)
Emit a value to a stream.
emitter.lisp (file)
emitter.lisp (file)
Emit a value to string.
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
float.lisp (file)
float.lisp (file)
Parse a YAML scalar string into a Lisp scalar value.
scalar.lisp (file)
parser.lisp (file)
float.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
error.lisp (file)
Emit YAML representation of obj
emitter.lisp (file)
Write the YAML corresponding to value to a stream.
emitter.lisp (file)
Encode a hash table.
Encode a vector.
Encode a list.
Encode a string.
Encode a float.
Encode an integer.
Encode false.
Encode true.
error.lisp (file)
error.lisp (file)
Parse a YAML string or a pathname to a YAML file into Lisp data.
Convert a scalar object into its printed representation
emitter.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
An error when parsing a YAML file.
error.lisp (file)
yaml-error (condition)
The error message.
:message
message (generic function)
The line where the error happened.
:line
line (generic function)
The column where the error happened.
:column
column (generic function)
This condition is signalled when the parser receives an IEEE
floating point special value it cannot parse. This is only signalled when the
floating point strategy is :error.
error.lisp (file)
yaml-error (condition)
The base class of all YAML conditions.
error.lisp (file)
condition (condition)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables: | ||
• Internal functions: |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
float.lisp (file)
The falsehood constant. Nil by default.
scalar.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
parser.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
The NULL constant. Nil by default.
scalar.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
scalar.lisp (file)
parser.lisp (file)
parser.lisp (file)
scalar.lisp (file)
Previous: Internal special variables, Up: Internal definitions [Contents][Index]
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
emitter.lisp (file)
emitter.lisp (file)
parser.lisp (file)
parser.lisp (file)
Parse a YAML string, returning a list of tokens.
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index: | ||
• Function index: | ||
• Variable index: | ||
• Data type index: |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | C F L M |
---|
Jump to: | C F L M |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | C D E F G L M N P R S W |
---|
Jump to: | C D E F G L M N P R S W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
+
C L M S |
---|
Jump to: | *
+
C L M S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C P S U Y |
---|
Jump to: | C P S U Y |
---|