diff --git a/config.nims b/config.nims index 36e6f50..0d2610f 100644 --- a/config.nims +++ b/config.nims @@ -22,7 +22,11 @@ task documentation, "Generate documentation": exec "mkdir -p docout" exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml" # bash! ah-ah \\ savior of the universe - exec r"find yaml -type f -print0 | while read -d '' -r f; do a=${f#yaml/}; nim doc2 -o:docout/yaml.${a%%.nim}.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` $f; done" + for file in listFiles("yaml"): + let packageName = file[5..^5] + exec r"nim doc2 -o:docout/yaml." & packageName & + ".html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` " & + file exec r"nim rst2html -o:docout/index.html doc/index.txt" exec r"nim rst2html -o:docout/api.html doc/api.txt" exec r"nim rst2html -o:docout/serialization.html doc/serialization.txt" diff --git a/doc/api.txt b/doc/api.txt index d8ae049..9d38333 100644 --- a/doc/api.txt +++ b/doc/api.txt @@ -25,8 +25,8 @@ Intermediate Representation =========================== The base of all YAML processing with NimYAML is the -`YamlStream `_. This is basically an iterator over -`YamlStreamEvent `_ objects. Every proc that +`YamlStream `_. This is basically an iterator over +`YamlStreamEvent `_ objects. Every proc that represents a single stage of the loading or dumping process will either take a ``YamlStream`` as input or return a ``YamlStream``. Procs that implement the whole process in one step hide the ``YamlStream`` from the user. Every proc that @@ -45,16 +45,17 @@ Loading YAML ============ If you want to load YAML character data directly into a native Nim variable, you -can use `load `_. This is the easiest and recommended -way to load YAML data. The following paragraphs will explain the steps involved. +can use `load `_. This is the easiest and +recommended way to load YAML data. This section gives an overview about how +``load`` is implemented. It is absolutely possible to reimplement the loading +step using the low-level API. -For parsing, a `YamlParser `_ object is needed. This -object stores some state while parsing that may be useful for error reporting to -the user. The -`parse `_ proc implements the YAML processing -step of the same name. All syntax errors in the input character stream are -processed by ``parse``, which will raise a ``YamlParserError`` if it encounters -a syntax error. +For parsing, a `YamlParser `_ object is needed. +This object stores some state while parsing that may be useful for error +reporting to the user. The `parse `_ +proc implements the YAML processing step of the same name. All syntax errors in +the input character stream are processed by ``parse``, which will raise a +``YamlParserError`` if it encounters a syntax error. Transforming a ``YamlStream`` to a native YAML object is done via ``construct``. It skips the ``compose`` step for efficiency reasons. As Nim is @@ -67,19 +68,21 @@ Dumping YAML ============ Dumping is preferredly done with -`dump `_, -which serializes a native Nim variable to a character stream. Like ``load``, you -can use the steps involved separately. +`dump `_, +which serializes a native Nim variable to a character stream. As with ``load``, +the following paragraph describes how ``dump`` is implemented using the +low-level API. -You transform a variable into a ``YamlStream`` with -`represent `_. Depending on the -``AnchorStyle`` you specify, this will transform ``ref`` variables with multiple -instances into anchored elements and aliases (for ``asTidy`` and ``asAlways``) -or write the same element into all places it occurs (for ``asNone``). Be aware -that if you use ``asNone``, the value you serialize might not round-trip. +A Nim value is transformed into a ``YamlStream`` with +`represent `_. +Depending on the ``AnchorStyle`` you specify, this will transform ``ref`` +variables with multiple instances into anchored elements and aliases (for +``asTidy`` and ``asAlways``) or write the same element into all places it +occurs (for ``asNone``). Be aware that if you use ``asNone``, the value you +serialize might not round-trip. Transforming a ``YamlStream`` into YAML character data is done with -`present `_. +`present `_. You can choose from multiple presentation styles. ``psJson`` is not able to process some features of ``YamlStream`` s, the other styles support all features and are guaranteed to round-trip to the same ``YamlStream`` if you parse the @@ -90,11 +93,12 @@ The Document Object Model Much like XML, YAML also defines a *document object model*. If you cannot or do not want to load a YAML character stream to native Nim types, you can instead -load it into a ``YamlDocument``. This ``YamlDocument`` can also be serialized -into a YAML character stream. All tags will be preserved exactly as they are -when transforming from and to a ``YamlDocument``. The only important thing to -remember is that when a value has no tag, it will get the non-specific tag -``"!"`` for quoted scalars and ``"?"`` for all other nodes. +load it into a `YamlDocument `_. This +``YamlDocument`` can also be serialized into a YAML character stream. All tags +will be preserved exactly as they are when transforming from and to a +``YamlDocument``. The only important thing to remember is that when a value has +no tag, it will get the non-specific tag ``"!"`` for quoted scalars and ``"?"`` +for all other nodes. While tags are preserved, anchors will be resolved during loading and re-added during serialization. It is allowed for a ``YamlNode`` to occur multiple times diff --git a/doc/processing.svg b/doc/processing.svg index 734b5d1..a312738 100644 --- a/doc/processing.svg +++ b/doc/processing.svg @@ -68,18 +68,18 @@ - + Application YAML - + Native Nim Types - + Representation @@ -87,7 +87,7 @@ YamlDocument - + Serialization @@ -95,7 +95,7 @@ YamlStream - + Presentation @@ -104,87 +104,87 @@ - + represent - + - + serialize - + - + present - + construct - + - + compose - + - + parse - + - + represent - + construct - + - + dump - - dumpDOM + + dumpDOM - + loadDOM - + load - + \ No newline at end of file diff --git a/doc/serialization.txt b/doc/serialization.txt index 07c8f61..8835a55 100644 --- a/doc/serialization.txt +++ b/doc/serialization.txt @@ -8,10 +8,11 @@ Introduction NimYAML tries hard to make transforming YAML characters streams to native Nim types and vice versa as easy as possible. In simple scenarios, you might not need anything else than the two procs -`dump `_ and -`load `_. On the other side, the process should be as -customizable as possible to allow the user to tightly control how the generated -YAML character stream will look and how a YAML character stream is interpreted. +`dump `_ +and `load `_. On the other side, the process +should be as customizable as possible to allow the user to tightly control how +the generated YAML character stream will look and how a YAML character stream is +interpreted. An important thing to remember in NimYAML is that unlike in interpreted languages like Ruby, Nim cannot load a YAML character stream without knowing the @@ -42,7 +43,8 @@ added in the future. This also means that NimYAML is generally able to work with object, tuple and enum types defined in the standard library or a third-party library without -further configuration. +further configuration, given that all fields of the object are accessible at the +code point where NimYAML's facilities are invoked. Scalar Types ------------ @@ -113,7 +115,7 @@ For an object or tuple type to be directly usable with NimYAML, the following conditions must be met: - Every type contained in the object/tuple must be supported -- All fields of an object type must be accessible from the code position where +- All fields of an object type must be accessible from the code position where you call NimYAML. If an object has non-public member fields, it can only be processed in the module where it is defined. - The object may not have a generic parameter @@ -141,7 +143,7 @@ For example, this type: type AnimalKind = enum akCat, akDog - + Animal = object name: string case kind: AnimalKind @@ -175,7 +177,7 @@ list in order to load it: .. code-block:: nim import yaml - + type ContainerKind = enum ckInt, ckString, ckNone @@ -187,9 +189,9 @@ list in order to load it: strVal: string of ckNone: discard - + markAsImplicit(Container) - + var list: seq[Container] s = newFileStream("in.yaml") @@ -232,7 +234,7 @@ otherwise, it would be loaded as ``nil``. As you might have noticed in the example above, the YAML tag of a ``seq`` depends on its generic type parameter. The same applies to ``Table``. So, a table that maps ``int8`` to string sequences would be presented with the tag -``!nim:tables:Table(nim:system:int8,nim:system:seq(tag:yaml.org,2002:string))``. +``!nim:tables:Table(nim:system:int8,nim:system:seq(tag:yaml.org,2002:string))``. These tags are generated on the fly based on the types you instantiate ``Table`` or ``seq`` with.