extra/yaml/yaml-docs.factor

   1 ! Copyright (C) 2014 Jon Harper.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays assocs byte-arrays hash-sets hashtables calendar
   4 help.markup help.syntax kernel linked-assocs math sequences sets
   5 strings yaml.ffi yaml.config yaml.conversion ;
   6 IN: yaml
   7
   8 HELP: >yaml
   9 { $values
  10     { "obj" object }
  11     { "str" string }
  12 }
  13 { $description "Serializes the object into a YAML formatted string with one document representing the object." } ;
  14
  15 HELP: >yaml-docs
  16 { $values
  17     { "seq" sequence }
  18     { "str" string }
  19 }
  20 { $description "Serializes the sequence into a YAML formatted string. Each element is outputted as a YAML document." } ;
  21
  22 HELP: yaml-docs>
  23 { $values
  24     { "str" string }
  25     { "arr" array }
  26 }
  27 { $description "Deserializes the YAML formatted string into a Factor array. Each document becomes an element of the array." } ;
  28
  29 HELP: yaml>
  30 { $values
  31     { "str" string }
  32     { "obj" object }
  33 }
  34 { $description "Deserializes the YAML formatted string into a Factor object. Throws "
  35 { $link yaml-no-document } " when there is no document (for example the empty string)."
  36 $nl
  37 }
  38 { $notes
  39 "Contrary to " { $link yaml-docs> } ", this word only parses the input until one document is produced."
  40 " Valid or invalid content after the first document is ignored."
  41 " To verifiy that the whole input is one valid YAML document, use "
  42 { $link yaml-docs> } " and assert that the length of the output array is 1."
  43 }
  44 ;
  45
  46 HELP: libyaml-emitter-error
  47 { $values
  48     { "error" yaml_error_type_t } { "problem" string }
  49 }
  50 { $description "yaml_emitter_emit returned with status 0. The slots of this error give more information." } ;
  51
  52 HELP: libyaml-initialize-error
  53 { $description "yaml_*_initialize returned with status 0. This usually means LibYAML failed to allocate memory." } ;
  54
  55 HELP: libyaml-parser-error
  56 { $values
  57     { "error" yaml_error_type_t } { "problem" string } { "problem_offset" integer } { "problem_value" integer } { "problem_mark" yaml_mark_t } { "context" string } { "context_mark" yaml_mark_t }
  58 }
  59 { $description "yaml_parser_parse returned with status 0. The slots of this error give more information." } ;
  60
  61 HELP: yaml-no-document
  62 { $description "The input of " { $link yaml> } " had no documents." } ;
  63
  64 HELP: yaml-undefined-anchor
  65 { $values
  66     { "anchor" string } { "anchors" sequence }
  67 }
  68 { $description "The document references an undefined anchor " { $snippet "anchor" } ". For information, the list of currently defined anchors in the document is " { $snippet "anchors" } "." } ;
  69
  70 HELP: yaml-unexpected-event
  71 { $values
  72     { "actual" yaml_event_type_t } { "expected" sequence }
  73 }
  74 { $description "LibYAML produced the unexpected event " { $snippet "actual" } ", but the list of expected events is " { $snippet "expected" } "." } ;
  75
  76 HELP: ?apply-merge-key
  77 { $values
  78     { "assoc" assoc }
  79     { "assoc'" assoc }
  80 }
  81 { $description "Merges the value of the !!merge key in " { $snippet "assoc" } } ;
  82 { merge ?apply-merge-key } related-words
  83 { value scalar-value } related-words
  84
  85 HELP: scalar-value
  86 { $values
  87     { "obj" object }
  88     { "obj'" object }
  89 }
  90 { $description "If " { $snippet "obj" } " is hashtable, returns it's default value, else return " { $snippet "obj" } " itself." } ;
  91
  92 ARTICLE: "yaml-mapping" "Mapping between Factor and YAML types"
  93 { $heading "Types mapping" }
  94 "The rules in the table below are used to convert between yaml and factor objects."
  95 " They are based on " { $url "http://www.yaml.org/spec/1.2/spec.html" } ", section \"10.3. Core Schema\" and " { $url "http://yaml.org/type/" } ", adapted to factor's conventions."
  96 { $table
  97   { { $snippet "yaml" } { $snippet "factor" } }
  98   { { $snippet "scalars" } "" }
  99   { "!!null" { $link f } }
 100   { "!!bool" { $link boolean } }
 101   { "!!int" { $link integer } }
 102   { "!!float" { $link float } }
 103   { "!!str" { $link string } }
 104   { "!!binary" { $link byte-array } }
 105   { "!!timestamp" { $link timestamp } }
 106   { { $snippet "sequences" } "" }
 107   { "!!seq" { $link array } }
 108   { "!!omap" { $link linked-assoc } }
 109   { "!!pairs" { $link "alists" } }
 110   { { $snippet "mappings" } "" }
 111   { "!!map" { $link hashtable } }
 112   { "!!set" { $link hash-set } }
 113   { { $snippet "special keys" } "" }
 114   { "!!merge" { $link yaml-merge } }
 115   { "!!value" { $link yaml-value } }
 116 }
 117
 118 { $heading "YAML to Factor Round Tripping" }
 119 "The following YAML types are not preserved:"
 120 { $list
 121   { "!!null -> " { $link boolean } " -> !!bool" }
 122   { "!!pairs -> " { $link "alists" } " -> !!seq" }
 123 }
 124 { $heading "Factor to YAML Round Tripping" }
 125 "The following Factor types are not preserved, unless another type has precedence:"
 126 { $list
 127   { { $link assoc } " -> !!map -> " { $link hashtable } }
 128   { { $link set } " -> !!set -> " { $link hash-set } }
 129   { { $link sequence } " -> !!seq -> " { $link array } }
 130 }
 131 "Examples of type precedence which preserves type: " { $link byte-array } " over " { $link sequence } "."
 132 ;
 133
 134 ARTICLE: "yaml-errors" "YAML errors"
 135 { $heading "libYAML's errors" }
 136 "LibYAML exposes error when parsing/emitting yaml. See " { $url "http://pyyaml.org/wiki/LibYAML" } ". More information is available directly in pyyaml's source code in their C interface. They are groupped in the following errors:"
 137 { $list
 138   { $link libyaml-parser-error }
 139   { $link libyaml-emitter-error }
 140   { $link libyaml-initialize-error }
 141 }
 142 { $heading "Conversion errors" }
 143 "Additional errors are thrown when converting to/from factor objects:"
 144 { $list
 145   { $link yaml-undefined-anchor }
 146   { $link yaml-no-document }
 147   "Or many errors thrown by library words (eg unparseable numbers, converting unsupported objects to yaml, etc)"
 148 }
 149 { $heading "Bugs" }
 150 "The following error probably means that there is a bug in the implementation: " { $link yaml-unexpected-event }
 151 ;
 152
 153 ARTICLE: "yaml-keys" "Special mapping keys"
 154 "The following special keys have been implemented for !!map. By default, these keys will be taken into account when deserializing yaml documents. To keep the original document structure, configuration variables can be set. See " { $link "yaml-config" } "."
 155 { $heading "!!merge" }
 156 "See " { $url "http://yaml.org/type/merge.html" } $nl
 157 "As per " { $url "http://sourceforge.net/p/yaml/mailman/message/12308050" }
 158 ", the merge key is implemented bottom up:" $nl
 159 { $unchecked-example "USING: yaml prettyprint ;
 160 \"
 161 foo: 1
 162 <<:
 163   bar: 2
 164   <<:
 165     baz: 3
 166 \" yaml> ."
 167 "H{ { \"baz\" 3 } { \"foo\" 1 } { \"bar\" 2 } }" }
 168 { $heading "!!value" }
 169 "See " { $url "http://yaml.org/type/value.html" } $nl
 170 { $unchecked-example "USING: yaml prettyprint ;
 171 \"
 172 ---     # Old schema
 173 link with:
 174   - library1.dll
 175   - library2.dll
 176 ---     # New schema
 177 link with:
 178   - = : library1.dll
 179     version: 1.2
 180   - = : library2.dll
 181     version: 2.3
 182 \" yaml-docs> ."
 183 "{
 184     H{ { \"link with\" { \"library1.dll\" \"library2.dll\" } } }
 185     H{ { \"link with\" { \"library1.dll\" \"library2.dll\" } } }
 186 }"
 187 }
 188
 189 ;
 190 ARTICLE: "yaml" "YAML serialization"
 191 "The " { $vocab-link "yaml" } " vocabulary implements YAML serialization/deserialization. It uses LibYAML, a YAML parser and emitter written in C (" { $url "http://pyyaml.org/wiki/LibYAML" } ")."
 192 { $heading "Main conversion words" }
 193 { $subsections
 194     >yaml
 195     >yaml-docs
 196     yaml>
 197     yaml-docs>
 198 }
 199 { $heading "Next topics:" }
 200 { $subsections
 201 "yaml-mapping"
 202 "yaml-keys"
 203 "yaml-errors"
 204 "yaml-config"
 205 }
 206 { $examples
 207   { $heading "Input" }
 208   { $unchecked-example "USING: prettyprint yaml ;"
 209 "\"- true
 210 - null
 211 - ! 42
 212 - \\\"42\\\"
 213 - 42
 214 - 0x2A
 215 - 0o52
 216 - 42.0
 217 - 4.2e1\" yaml> ."
 218 "{ t f \"42\" \"42\" 42 42 42 42.0 42.0 }"
 219  }
 220 { $heading "Output -- human readable" }
 221   { $unchecked-example "USING: yaml yaml.config ;"
 222 "t implicit-tags set
 223 t implicit-start set
 224 t implicit-end set
 225 +libyaml-default+ emitter-canonical set
 226 +libyaml-default+ emitter-indent set
 227 +libyaml-default+ emitter-width set
 228 +libyaml-default+ emitter-line-break set
 229 t emitter-unicode set
 230 "
 231 "{
 232   H{
 233     { \"name\" \"Mark McGwire\" }
 234     { \"hr\" 65 }
 235     { \"avg\" 0.278 }
 236   }
 237   H{
 238     { \"name\" \"Sammy Sosa\" }
 239     { \"hr\" 63 }
 240     { \"avg\" 0.288 }
 241   }
 242 } >yaml print"
 243     "- name: Mark McGwire
 244   hr: 65
 245   avg: 0.278
 246 - name: Sammy Sosa
 247   hr: 63
 248   avg: 0.288
 249 "
 250   }
 251 { $heading "Output -- verbose" }
 252   { $unchecked-example "USING: yaml yaml.config ;"
 253 "f implicit-tags set
 254 f implicit-start set
 255 f implicit-end set
 256 +libyaml-default+ emitter-canonical set
 257 +libyaml-default+ emitter-indent set
 258 +libyaml-default+ emitter-width set
 259 +libyaml-default+ emitter-line-break set
 260 t emitter-unicode set
 261
 262 { t 32 \"foobar\" { \"nested\" \"list\" } H{ { \"nested\" \"assoc\" } } } >yaml print"
 263     "--- !!seq\n- !!bool true\n- !!int 32\n- !!str foobar\n- !!seq\n  - !!str nested\n  - !!str list\n- !!map\n  !!str nested: !!str assoc\n...\n"
 264   }
 265 }
 266 ;
 267
 268
 269 { >yaml >yaml-docs } related-words
 270 { yaml> yaml-docs> } related-words
 271
 272 ABOUT: "yaml"