/ yaml.nim
yaml.nim
1 # NimYAML - YAML implementation in Nim 2 # (c) Copyright 2015-2023 Felix Krause 3 # 4 # See the file "copying.txt", included in this 5 # distribution, for details about the copyright. 6 7 ## .. importdoc:: 8 ## yaml/loading.nim, yaml/dumping.nim, yaml/annotations.nim, yaml/taglib.nim, 9 ## yaml/style.nim, yaml/dom.nim, yaml/tojson.nim, 10 ## yaml/parser.nim, yaml/presenter.nim, yaml/data.nim, yaml/stream.nim 11 ## 12 ## This is the root module of NimYAML, a package that provides facilities to 13 ## generate and interpret `YAML <http://yaml.org>`_ character streams. Importing 14 ## this package will import NimYAML's high level loading & dumping API. 15 ## Additional APIs must be imported explicitly. 16 ## 17 ## There is no code in this package, all functionality is available via the 18 ## exported sub-packages. You can import parts of the API by importing 19 ## certain sub-packages only. 20 ## 21 ## High Level Loading & Dumping 22 ## ============================ 23 ## 24 ## .. code-block:: 25 ## 26 ## import yaml 27 ## # or alternatively: 28 ## import yaml / [loading, dumping, annotations, taglib, dom] 29 ## 30 ## Enables you to load YAML data directly into native Nim types and reversely 31 ## dump native Nim types into YAML documents. This API corresponds to the full 32 ## **Load** / **Dump** process as defined in the 33 ## `YAML specification <https://yaml.org/spec/1.2.2/#31-processes>`_. 34 ## 35 ## The module `module yaml/loading`_ provides the `load`_ and `loadAs`_ procs 36 ## which load a single YAML document into a native Nim value. 37 ## 38 ## The `module yaml/dumping`_ provides the `Dumper`_ object together with its 39 ## `dump`_ methods that serialize a given Nim value into YAML. 40 ## 41 ## The `module yaml/annotations`_ provides various pragmas that allow you to 42 ## define how certain aspects of your types are to be serialized, e.g. whether 43 ## ``Optional`` fields may be omitted. 44 ## 45 ## The `module yaml/taglib`_ provides facilities that customize the YAML tags 46 ## that are generated for your types. The primary usage for tags in the context 47 ## of NimYAML is to define the type of a value in a heterogeneous collection node. 48 ## 49 ## The following additional APIs extend the basic high-level API: 50 ## 51 ## DOM API 52 ## ------- 53 ## 54 ## *Also exported by default, no import necessary* 55 ## 56 ## The `module yaml/dom`_ enables you to load YAML into `YamlNode`_ objects and 57 ## dump those back into YAML. This gives you a structured view of your YAML 58 ## stream. The DOM API provides the types and their handling, which can then 59 ## be used via the loading & dumping API. 60 ## 61 ## You can use ``YamlNode`` objects inside other objects to hold subtrees of 62 ## the input YAML, or you can load the whole YAML into a ``YamlNode``. 63 ## 64 ## ``YamlNode`` corresponds to the **Representation (Node Graph)** stage 65 ## defined in the 66 ## `YAML specification <https://yaml.org/spec/1.2.2/#31-processes>`_. 67 ## 68 ## Style API 69 ## --------- 70 ## 71 ## .. code-block:: 72 ## 73 ## # needs explicit import to use: 74 ## import yaml/style 75 ## 76 ## The `module yaml/style`_ lets you define the preferred YAML node style of 77 ## your objects and fields, giving you a greater control over how your 78 ## generated YAML looks. 79 ## 80 ## JSON API 81 ## -------- 82 ## 83 ## .. code-block:: 84 ## 85 ## # needs explicit import to use: 86 ## import yaml/tojson 87 ## 88 ## The `module yaml/tojson`_ enables you to load YAML input into the stdlib's 89 ## ``JsonNode`` structure. This can be useful for other libraries that expect 90 ## JSON input. Mind that the loading & dumping API is able to read & write 91 ## JSON files (since YAML is a superset of JSON), you don't need the JSON 92 ## API for that. 93 ## 94 ## 95 ## Low Level Event Handling 96 ## ======================== 97 ## 98 ## NimYAML exposes lower-level APIs that allow you to access the different 99 ## steps used for YAML loading & dumping. These APIs have at their core a 100 ## `YamlStream`_ which is an object that supplies a stream of `Event`_. 101 ## This corresponds to the **Serialization (Event Tree)** stage defined in the 102 ## `YAML specification <https://yaml.org/spec/1.2.2/#31-processes>`_. 103 ## 104 ## Parsing & Presenting API 105 ## ------------------------ 106 ## 107 ## .. code-block:: 108 ## 109 ## # needs explicit import to use: 110 ## import yaml / [parser, presenter, stream, data] 111 ## 112 ## Provides `parse`_, a proc that feeds a ``YamlStream`` from YAML input, 113 ## and `present`_, which consumes a ``YamlStream`` and writes out YAML. 114 ## You can use a `BufferYamlStream`_ to supply manually generated events. 115 ## 116 ## Native API 117 ## ---------- 118 ## 119 ## .. code-block:: 120 ## 121 ## # needs explicit import to use: 122 ## import yaml/native 123 ## 124 ## This part of the API takes care of generating Nim values from a 125 ## ``YamlStream`` via `construct`_, and transforming them back into a 126 ## ``YamlStream`` via `represent`_. This complements the Event API. 127 ## 128 ## Typically, you'd only access this API when defining custom constructors 129 ## and representers. 130 ## 131 ## 132 ## Hints API 133 ## --------- 134 ## 135 ## .. code-block:: 136 ## 137 ## # needs explicit import to use: 138 ## import yaml/hints 139 ## 140 ## Provides type guessing, i.e. figuring out which type would be appropriate 141 ## for a certain YAML scalar. 142 143 # top level API 144 import yaml / [annotations, loading, dumping, taglib] 145 export annotations, loading, dumping, taglib 146 147 when not defined(gcArc) or defined(gcOrc): 148 # YAML DOM may contain cycles and therefore will leak memory if used with 149 # ARC but without ORC. In that case it won't be available. 150 import yaml/dom 151 export dom