From 83347ee964d72b3649ee0cff4b16ff1af09e354c Mon Sep 17 00:00:00 2001
From: Jon Harper <jon.harper87@gmail.com>
Date: Sat, 29 Mar 2014 21:48:17 +0100
Subject: [PATCH] YAML: docs

---
 extra/yaml/yaml-docs.factor | 89 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 2 deletions(-)

diff --git a/extra/yaml/yaml-docs.factor b/extra/yaml/yaml-docs.factor
index 03cd805380..b67e43b848 100644
--- a/extra/yaml/yaml-docs.factor
+++ b/extra/yaml/yaml-docs.factor
@@ -1,6 +1,8 @@
 ! Copyright (C) 2014 Jon Harper.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: arrays help.markup help.syntax kernel sequences strings ;
+USING: arrays assocs byte-arrays hash-sets hashtables
+help.markup help.syntax kernel linked-assocs math sequences sets
+strings ;
 IN: yaml
 
 HELP: >yaml
@@ -8,7 +10,7 @@ HELP: >yaml
     { "obj" object }
     { "str" string }
 }
-{ $description "Serializes the object into a YAML formatted string." } ;
+{ $description "Serializes the object into a YAML formatted string with one document representing the object."  } ;
 
 HELP: >yaml-docs
 { $values
@@ -31,16 +33,99 @@ HELP: yaml>
 }
 { $description "Deserializes the YAML formatted string into a Factor object." } ;
 
+ARTICLE: "yaml-mapping" "Mapping between Factor and YAML types"
+{ $heading "Types mapping" }
+"The rules in the table below are used to convert between yaml and factor objects."
+" 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."
+{ $table
+  { { $snippet "yaml" } { $snippet "factor" } }
+  { { $snippet "scalars" } "" }
+  { "!!null" { $link f } }
+  { "!!bool" { $link boolean } }
+  { "!!int" { $link integer } }
+  { "!!float" { $link float } }
+  { "!!str" { $link string } }
+  { "!!binary" { $link byte-array } }
+  { "!!timestamp" "Not supported yet" }
+  { { $snippet "sequences" } "" }
+  { "!!seq" { $link array } }
+  { "!!omap" { $link linked-assoc } }
+  { "!!pairs" { $link "alists" } }
+  { { $snippet "mappings" } "" }
+  { "!!map" { $link hashtable } }
+  { "!!set" { $link hash-set } }
+}
+
+{ $heading "YAML to Factor Round Tripping" }
+"The following YAML types are not preserved:"
+{ $list
+  { "!!null -> " { $link boolean } " -> !!bool" }
+  { "!!pairs -> " { $link "alists" } " -> !!seq" }
+}
+{ $heading "Factor to YAML Round Tripping" }
+"The following Factor types are not preserved, unless another type has precedence:"
+{ $list
+  { { $link assoc } " -> !!map -> " { $link hashtable } }
+  { { $link set } " -> !!set -> " { $link hash-set } }
+  { { $link sequence } " -> !!seq -> " { $link array } }
+}
+"Examples of type precedence which preserves type: " { $link byte-array } " over " { $link sequence } "."
+;
+
+ARTICLE: "yaml-output" "Serialization control"
+"TODO allow to control the serialization details, for example"
+{ $list
+  "force explicit/implicit types"
+  "force flow/block styles"
+  "etc."
+}
+;
+ARTICLE: "yaml-input" "Deserialization control"
+"TODO, implement or drop the following features:"
+{ $list
+  "Activate/deactivate !!value"
+  "Activate/deactivate !!merge ?"
+  "Activate/deactivate YAML1.1 compatibility (ie boolean as On, OFF etc)"
+  "select schema: \"failsafe\", \"JSON\", \"Core\" ?"
+  "etc."
+}
+;
 ARTICLE: "yaml" "YAML serialization"
 "The " { $vocab-link "yaml" } " vocabulary implements YAML serialization/deserialization."
+{ $heading "Main conversion words" }
 { $subsections
     >yaml
     >yaml-docs
     yaml>
     yaml-docs>
 }
+{ $heading "Next topics:" }
+{ $subsections
+"yaml-mapping"
+"yaml-output"
+"yaml-input"
+}
+{ $examples
+  { $example "USING: prettyprint yaml ;"
+"\"- true
+- null
+- ! 42
+- \\\"42\\\"
+- 42
+- 0x2A
+- 0o52
+- 42.0
+- 4.2e1\" yaml> ."
+"{ t f \"42\" \"42\" 42 42 42 42.0 42.0 }"
+ }
+  { $example "USING: yaml ;"
+"""{ t 32 "foobar" { "nested" "list" } H{ { "nested" "assoc" } } } >yaml print"""
+    "--- !!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"
+  }
+}
 ;
 
+
 { >yaml >yaml-docs } related-words
 { yaml> yaml-docs> } related-words