diff --git a/config.nims b/config.nims index a0943b5..6ca0db1 100644 --- a/config.nims +++ b/config.nims @@ -23,7 +23,7 @@ task documentation, "Generate documentation": exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml" exec r"nim doc2 -o:docout/serialization.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml/serialization.nim" exec r"nim rst2html -o:docout/index.html doc/index.txt" - exec "cp doc/docutils.css doc/style.css doc/testing.html docout" + exec "cp doc/docutils.css doc/style.css doc/testing.html doc/processing.svg docout" setCommand "nop" task bench, "Benchmarking": diff --git a/doc/index.txt b/doc/index.txt index 79916c3..e8608fb 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -2,4 +2,18 @@ NimYAML ======= -TBD: General information here. Possibly move text from yaml.html. Eat pizza. \ No newline at end of file +Overview +======== + +**NimYAML** is a pure YAML implementation for Nim. It is able to read from and +write to YAML character streams, and to serialize from and construct to native +Nim types. It exclusively supports +`YAML 1.2 <#http://www.yaml.org/spec/1.2/spec.html>`_. NimYAML exposes all +processing steps defined by the YAML specification to the user, so it is +possible to customize the processing pipeline. The following diagram gives an +overview of NimYAML's features based on the YAML processing pipeline. The items +and terminology YAML defines is shown in black, NimYAML's implementation is +shown in red. + +.. image:: processing.svg + :align: center \ No newline at end of file diff --git a/doc/processing.svg b/doc/processing.svg new file mode 100644 index 0000000..3e1d610 --- /dev/null +++ b/doc/processing.svg @@ -0,0 +1,154 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Application + YAML + + + + + Native + Nim Types + + + + + Representation + not implemented + + + + + Serialization + + YamlStream + + + + + + Presentation + + Stream + + + + + + + + represent + + + + + serialize + + + + + + present + + + + + + construct + + + + + compose + + + + + + parse + + + + + + + + represent + + + + construct + + + + + + + dump + + + + load + + + + \ No newline at end of file diff --git a/yaml.nim b/yaml.nim index b255be8..31e24f4 100644 --- a/yaml.nim +++ b/yaml.nim @@ -338,9 +338,6 @@ proc registerUri*(tagLib: TagLibrary, uri: string): TagId {.raises: [].} proc uri*(tagLib: TagLibrary, id: TagId): string {.raises: [KeyError].} ## retrieve the URI a ``TagId`` maps to. -# these should be consts, but the Nim VM still has problems handling tables -# properly, so we use let instead. - proc initFailsafeTagLibrary*(): TagLibrary {.raises: [].} ## Contains only: ## - ``!`` @@ -366,16 +363,32 @@ proc initExtendedTagLibrary*(): TagLibrary {.raises: [].} ## - ``!!yaml`` proc guessType*(scalar: string): TypeHint {.raises: [].} + ## Parse scalar string according to the RegEx table documented at + ## `TypeHint <#TypeHind>`_. proc newYamlParser*(tagLib: TagLibrary = initExtendedTagLibrary(), callback: WarningCallback = nil): YamlParser {.raises: [].} + ## Creates a YAML parser. if ``callback`` is not ``nil``, it will be called + ## whenever the parser yields a warning. proc getLineNumber*(p: YamlParser): int {.raises: [].} + ## Get the line number (1-based) of the recently yielded parser token. + ## Useful for error reporting at later loading stages. + proc getColNumber*(p: YamlParser): int {.raises: [].} + ## Get the column number (1-based) of the recently yielded parser token. + ## Useful for error reporting at later parsing stages. + proc getLineContent*(p: YamlParser, marker: bool = true): string {.raises: [].} + ## Get the content of the input line containing the recently yielded parser + ## token. Useful for error reporting at later parsing stages. The line will + ## be terminated by ``"\n"``. If ``marker`` is ``true``, a second line will + ## be returned containing a ``^`` at the position of the recent parser + ## token. proc parse*(p: YamlParser, s: Stream): YamlStream {.raises: [IOError, YamlParserError].} + ## Parse the given stream as YAML character stream. proc constructJson*(s: YamlStream): seq[JsonNode] {.raises: [YamlConstructionError, YamlConstructionStreamError].}