mirror of https://github.com/status-im/NimYAML.git
Improved quickstart documentation
This commit is contained in:
Felix Krause
parent
57b4518564
commit
537ba1ca01
368
doc/index.txt
368
doc/index.txt
|
|
@ -14,66 +14,322 @@ Source code can be found on `GitHub <https://github.com/flyx/NimYAML>`_. You can
|
||||||
install it with `Nimble <https://github.com/nim-lang/nimble>`_:
|
install it with `Nimble <https://github.com/nim-lang/nimble>`_:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
nimble install nimyaml
|
||||||
nimble install nimyaml
|
|
||||||
|
|
||||||
Quickstart
|
Quickstart
|
||||||
----------
|
==========
|
||||||
|
|
||||||
Data used in quickstart code may not be accurate and is solely used to showcase
|
Dumping Nim objects as YAML
|
||||||
NimYAML's features.
|
--------------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>out.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
.. code-block:: nim
|
.. code-block:: nim
|
||||||
import yaml
|
import yaml
|
||||||
type
|
type Person = object
|
||||||
GenderKind* = enum
|
name : string
|
||||||
male, female, other
|
age : int32
|
||||||
|
|
||||||
Person* = object
|
var personList = newSeq[Person]()
|
||||||
name*: string
|
personList.add(Person(name: "Karl Koch", age: 23))
|
||||||
gender*: GenderKind
|
personList.add(Person(name: "Peter Pan", age: 12))
|
||||||
age*: int32
|
|
||||||
spouse*: ref Person
|
|
||||||
offspring*: seq[ref Person]
|
|
||||||
|
|
||||||
let input = newStringStream("""
|
var s = newFileStream("out.yaml", fmWrite)
|
||||||
%YAML 1.2
|
dump(personList, s)
|
||||||
---
|
s.close()
|
||||||
- &a
|
|
||||||
name: Luke Skywalker
|
.. raw:: html
|
||||||
gender: male
|
</td>
|
||||||
age: 19
|
<td>
|
||||||
spouse: ~
|
|
||||||
offspring: []
|
.. code-block:: yaml
|
||||||
- &b
|
%YAML 1.2
|
||||||
name: Han Solo
|
--- !nim:system:seq(nim:custom:Person)
|
||||||
gender: male
|
-
|
||||||
age: 35
|
name: Karl Koch
|
||||||
spouse: &c
|
age: 23
|
||||||
name: Leia Organa
|
-
|
||||||
gender: female
|
name: Peter Pan
|
||||||
age: 19
|
age: 12
|
||||||
spouse: *b
|
|
||||||
offspring: []
|
.. raw:: html
|
||||||
offspring: []
|
</td></tr></tbody></table>
|
||||||
- *c
|
|
||||||
-
|
Loading Nim objects from YAML
|
||||||
name: Anakin Skywalker
|
----------------------------
|
||||||
gender: male
|
|
||||||
age: 42
|
.. raw:: html
|
||||||
spouse: ~
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
offspring: [*a, *c]
|
<th>in.yaml</th></tr></thead><tbody><tr><td>
|
||||||
""")
|
|
||||||
var persons: seq[ref Person]
|
.. code-block:: nim
|
||||||
load(input, persons)
|
import yaml
|
||||||
for person in persons:
|
type Person = object
|
||||||
echo person.name, "\nage ", person.age
|
name : string
|
||||||
if person.spouse != nil:
|
age : int32
|
||||||
echo "spouse: ", person.spouse.name
|
|
||||||
for child in person.offspring:
|
var personList: seq[Person]
|
||||||
case child.gender
|
var s = newFileStream("in.yaml")
|
||||||
of male: echo "son: ", child.name
|
load(s, personList)
|
||||||
of female: echo "daughter: ", child.name
|
s.close()
|
||||||
of other: echo "child: ", child.name
|
|
||||||
echo "------------------------"
|
.. raw:: html
|
||||||
dump(persons, newFileStream(stdout))
|
</td>
|
||||||
|
<td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
%YAML 1.2
|
||||||
|
---
|
||||||
|
- { name: Karl Koch, age: 23 }
|
||||||
|
- { name: Peter Pan, age: 12 }
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
||||||
|
Customizing output style
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>out.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
|
.. code-block:: nim
|
||||||
|
import yaml
|
||||||
|
type Person = object
|
||||||
|
name: string
|
||||||
|
age: int32
|
||||||
|
|
||||||
|
var personList: seq[Person]
|
||||||
|
personList.add(Person(name: "Karl Koch", age: 23))
|
||||||
|
personList.add(Person(name: "Peter Pan", age: 12))
|
||||||
|
|
||||||
|
var s = newFileStream("out.yaml")
|
||||||
|
dump(personList, s, options = defineOptions(
|
||||||
|
style = psCanonical,
|
||||||
|
indentationStep = 3,
|
||||||
|
newlines = nlLF,
|
||||||
|
outputVersion = ov1_1))
|
||||||
|
s.close()
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td><td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
%YAML 1.1
|
||||||
|
--- !nim:system:seq(nim:custom:Person)
|
||||||
|
[
|
||||||
|
!nim:custom:Person {
|
||||||
|
? !!str "name"
|
||||||
|
: !!str "Karl Koch",
|
||||||
|
? !!str "age"
|
||||||
|
: !nim:system:int32 "23"
|
||||||
|
},
|
||||||
|
!nim:custom:Person {
|
||||||
|
? !!str "name"
|
||||||
|
: !!str "Peter Pan",
|
||||||
|
? !!str "age"
|
||||||
|
: !nim:system:int32 "12"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
||||||
|
Dumping reference types and cyclic structures
|
||||||
|
---------------------------------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>out.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
|
.. code-block:: nim
|
||||||
|
import yaml
|
||||||
|
type
|
||||||
|
Node = ref NodeObj
|
||||||
|
NodeObj = object
|
||||||
|
name: string
|
||||||
|
left, right: Node
|
||||||
|
|
||||||
|
var node1, node2, node3: Node
|
||||||
|
new(node1); new(node2); new(node3)
|
||||||
|
node1.name = "Node 1"
|
||||||
|
node2.name = "Node 2"
|
||||||
|
node3.name = "Node 3"
|
||||||
|
node1.left = node2
|
||||||
|
node1.right = node3
|
||||||
|
node2.right = node3
|
||||||
|
node3.left = node1
|
||||||
|
|
||||||
|
var s = newFileStream("out.yaml", fmWrite)
|
||||||
|
dump(node1, s)
|
||||||
|
s.close()
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td><td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
%YAML 1.2
|
||||||
|
--- !nim:custom:NodeObj &a
|
||||||
|
name: Node 1
|
||||||
|
left:
|
||||||
|
name: Node 2
|
||||||
|
left: !!null ~
|
||||||
|
right: &b
|
||||||
|
name: Node 3
|
||||||
|
left: *a
|
||||||
|
right: !!null ~
|
||||||
|
right: *b
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
||||||
|
Loading reference types and cyclic structures
|
||||||
|
---------------------------------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>in.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
|
.. code-block:: nim
|
||||||
|
import yaml
|
||||||
|
type
|
||||||
|
Node = ref NodeObj
|
||||||
|
NodeObj = object
|
||||||
|
name: string
|
||||||
|
left, right: Node
|
||||||
|
|
||||||
|
var node1: Node
|
||||||
|
|
||||||
|
var s = newFileStream("in.yaml")
|
||||||
|
load(s, node1)
|
||||||
|
s.close()
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td><td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
%YAML 1.2
|
||||||
|
--- !nim:custom:NodeObj &a
|
||||||
|
name: Node 1
|
||||||
|
left:
|
||||||
|
name: Node 2
|
||||||
|
left: ~
|
||||||
|
right: &b
|
||||||
|
name: Node 3
|
||||||
|
left: *a
|
||||||
|
right: ~
|
||||||
|
right: *b
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
||||||
|
Defining a custom tag uri for a type
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>out.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
|
.. code-block:: nim
|
||||||
|
import yaml
|
||||||
|
type Mob = object
|
||||||
|
level, experience: int32
|
||||||
|
|
||||||
|
setTagUriForType(Mob, "!Mob")
|
||||||
|
|
||||||
|
var mob = Mob(level: 42, experience: 1800)
|
||||||
|
var s = newFileStream("out.yaml", fmWrite)
|
||||||
|
dump(mob, s)
|
||||||
|
s.close()
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td><td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
%YAML 1.2
|
||||||
|
--- !Mob
|
||||||
|
level: 42
|
||||||
|
experience: 1800
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
||||||
|
Dumping Nim objects as JSON
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>out.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
|
.. code-block:: nim
|
||||||
|
import yaml
|
||||||
|
type Person = object
|
||||||
|
name : string
|
||||||
|
age : int32
|
||||||
|
|
||||||
|
var personList = newSeq[Person]()
|
||||||
|
personList.add(Person(name: "Karl Koch", age: 23))
|
||||||
|
personList.add(Person(name: "Peter Pan", age: 12))
|
||||||
|
|
||||||
|
var s = newFileStream("out.yaml", fmWrite)
|
||||||
|
dump(personList, s, options = defineOptions(style = psJson))
|
||||||
|
s.close()
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "Karl Koch",
|
||||||
|
"age": 23
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Peter Pan",
|
||||||
|
"age": 12
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
||||||
|
Loading Nim objects from JSON
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
<table class="quickstart-example"><thead><tr><th>code.nim</th>
|
||||||
|
<th>in.yaml</th></tr></thead><tbody><tr><td>
|
||||||
|
|
||||||
|
.. code-block:: nim
|
||||||
|
import yaml
|
||||||
|
type Person = object
|
||||||
|
name : string
|
||||||
|
age : int32
|
||||||
|
|
||||||
|
var personList: seq[Person]
|
||||||
|
|
||||||
|
var s = newFileStream("in.yaml")
|
||||||
|
load(s, personList)
|
||||||
|
s.close()
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td>
|
||||||
|
<td>
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "Karl Koch",
|
||||||
|
"age": 23
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Peter Pan",
|
||||||
|
"age": 12
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
</td></tr></tbody></table>
|
||||||
|
|
@ -102,3 +102,33 @@ object {
|
||||||
margin-right: auto;
|
margin-right: auto;
|
||||||
display: block;
|
display: block;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
.quickstart-example {
|
||||||
|
border-collapse: collapse;
|
||||||
|
border: 1px solid #e8e8e8;
|
||||||
|
width: 100%;
|
||||||
|
}
|
||||||
|
|
||||||
|
.quickstart-example th {
|
||||||
|
background: #e8e8e8;
|
||||||
|
}
|
||||||
|
|
||||||
|
.quickstart-example td {
|
||||||
|
width: 50%;
|
||||||
|
vertical-align: top;
|
||||||
|
padding: 0;
|
||||||
|
background: whitesmoke;
|
||||||
|
}
|
||||||
|
|
||||||
|
.quickstart-example td:first-child {
|
||||||
|
border-right: 1px solid #e8e8e8;
|
||||||
|
}
|
||||||
|
|
||||||
|
.quickstart-example pre {
|
||||||
|
border: 0;
|
||||||
|
margin: 0;
|
||||||
|
display: block;
|
||||||
|
border-radius: 0;
|
||||||
|
-moz-border-radius: 0;
|
||||||
|
-webkit-border-radius: 0;
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue