1[comment {-*- tcl -*- doctools manpage}]
2[vset YAML_VERSION 0.4.1]
3[manpage_begin yaml n [vset YAML_VERSION]]
4[see_also base64]
5[see_also huddle]
6[see_also json]
7[keywords {data exchange}]
8[keywords huddle]
9[keywords parsing]
10[keywords {text processing}]
11[keywords yaml]
12[copyright {2008 KATO Kanryu <kanryu6@users.sourceforge.net>}]
13[moddesc   {YAML processing}]
14[titledesc {YAML Format Encoder/Decoder}]
15[require Tcl 8.4]
16[require yaml [opt [vset YAML_VERSION]]]
17[description]
18[para]
19
20The [package yaml] package provides a simple Tcl-only library for parsing the
21YAML [uri http://www.yaml.org/] data exchange format as specified in
22[uri http://www.yaml.org/spec/1.1/].
23
24[para]
25The [package yaml] package returns
26data as a Tcl [cmd dict].  Either the [package dict] package or Tcl 8.5 is
27required for use.
28
29[section COMMANDS]
30
31[list_begin definitions]
32
33[call [cmd ::yaml::yaml2dict] [opt [arg options]] [arg txt]]
34[call [cmd ::yaml::yaml2huddle] [opt [arg options]] [arg txt]]
35
36Parse yaml formatted text [arg txt] into a Tcl dict/huddle and return the value.
37
38[list_begin options]
39[opt_def [const -file]]
40
41[arg txt] is a filename of YAML-stream.
42
43[opt_def [const -stream]]
44
45[arg txt] is just a YAML-stream.
46
47[opt_def "[const -types] [arg list]"]
48
49The [arg list] is a type list for the yaml-scalar types.(e.g. !!str !!timestamp !!integer !!true ...)
50
51[example { -types {timestamp integer null true false}}
52]
53In this case, if a string matched "timestamp", converted to the TCL internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183)
54
55[opt_def "[const -m:true] [arg param]"]
56
57The [arg param] is two elements of list for the value of true, and considered strings.
58
59[example { -m:true {1 {true on + yes y}}}
60]
61In this case, the string "yes" found in YAML Stream, automatically converted 1.
62
63[opt_def "[const -m:false] [arg param]"]
64
65The [arg param] is two elements of list for the value of false, and considered strings.
66
67[example { -m:false {0 {false off - no n}}}
68]
69
70[opt_def "[const -m:null] [arg param]"]
71
72The [arg param] is two elements of list for the value of null, and considered strings.
73
74[example { -m:null {"" {null nil "" ~}}}
75]
76
77[opt_def [const -validate]]
78
79Experiment,old: Output stream contains YAML's-tag, each node.
80
81[example {% puts [::yaml::load -validate {[aaa, bbb]}]
82=>
83!!seq {{!!str aaa} {!!str bbb}}
84}]
85[list_end]
86
87[call [cmd ::yaml::setOption] [opt [arg options]]]
88Change implicit options for the library.
89Now, the params are the same as [cmd ::yaml::yaml2dict].
90Arguments of[cmd ::yaml::yaml2dict] is more priority than this setting.
91
92[call [cmd ::yaml::dict2yaml] [arg dict] [opt [arg indent]] [opt [arg wordwrap]]]
93[call [cmd ::yaml::list2yaml] [arg list] [opt [arg indent]] [opt [arg wordwrap]]]
94[call [cmd ::yaml::huddle2yaml] [arg huddle] [opt [arg indent]] [opt [arg wordwrap]]]
95Convert a dict/list/huddle object into YAML stream.
96
97[list_begin definitions]
98[def indent]
99spaces indent of each block node.
100currently default is 2.
101
102[def wordwrap]
103word wrap for YAML stream.
104currently default is 40.
105[list_end]
106
107[list_end]
108[para]
109
110[section EXAMPLES]
111[para]
112
113An example of a yaml stream converted to Tcl.  A yaml stream is returned as a
114single item with multiple elements.
115
116[para]
117[example {{
118--- !<tag:clarkevans.com,2002:invoice>
119invoice: 34843
120date   : 2001-01-23
121bill-to: &id001
122    given  : Chris
123    family : Dumars
124    address:
125        lines: |
126            458 Walkman Dr.
127            Suite #292
128        city    : Royal Oak
129        state   : MI
130        postal  : 48046
131ship-to: *id001
132product:
133    - sku         : BL394D
134      quantity    : 4
135      description : Basketball
136      price       : 450.00
137    - sku         : BL4438H
138      quantity    : 1
139      description : Super Hoop
140      price       : 2392.00
141tax  : 251.42
142total: 4443.52
143comments:
144    Late afternoon is best.
145    Backup contact is Nancy
146    Billsmer @ 338-4338.
147}
148=>
149invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr.
150Suite #292
151} city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr.
152Suite #292
153} city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.}}]
154[para]
155
156An example of a yaml object converted to Tcl.  A yaml object is returned as a
157multi-element list (a dict).
158
159[para]
160[example {{
161---
162- [name        , hr, avg  ]
163- [Mark McGwire, 65, 0.278]
164- [Sammy Sosa  , 63, 0.288]
165-
166  Mark McGwire: {hr: 65, avg: 0.278}
167  Sammy Sosa: { hr: 63, avg: 0.288}
168}
169=>
170{name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}}
171}]
172
173[section LIMITATIONS]
174
175[para]
176tag parser not implemented. currentry, tags are merely ignored.
177
178[para]
179Only Anchor => Aliases ordering. back alias-referring is not supported.
180
181[para]
182Too many braces, or too few braces.
183
184[para]
185Not enough character set of line feeds. Please use only "\n" as line breaks.
186
187[vset CATEGORY yaml]
188[include ../common-text/feedback.inc]
189[manpage_end]
190