1  ========================
  2  Migrating to NimYAML 2.x
  3  ========================
  4  
  5  NimYAML 2.0.0 introduces some breaking changes, existing code likely needs to be updated.
  6  This document details the changes and describes what needs to be done to migrate existing code.
  7  
  8  Motivation
  9  ==========
 10  
 11  NimYAML 2.0.0 is a release made for Nim 2.0.
 12  It drops support for earlier Nim versions and introduces features added in Nim 2.0, mainly default values for object fields.
 13  
 14  Another goal of NimYAML 2.0.0 was to make dumping YAML simpler and more useful.
 15  Previously, the default style for writing out YAML used exotic features like directives (e.g. ``%YAML 1.2``) and tags.
 16  This style has originally been chosen to closely follow the YAML specification's intentions of using YAML to share data between applications.
 17  However, the major usage for YAML today is configuration files.
 18  To better cater to this use-case, the dumping API has been redesigned to emit less talkative YAML by default.
 19  
 20  Finally, the signatures of API functions for dumping have been modified so that you can define your desired dumping style once in a ``Dumper`` object and then use that everywhere.
 21  This demotes exotic features like custom tag handles from direct parameters of API functions to fields in the ``Dumper`` object.
 22  This design also enables NimYAML to introduce more dumper options in the future without altering the API.
 23  
 24  Module Changes
 25  ==============
 26  
 27  ``import yaml`` now only imports the high-level API for loading and dumping.
 28  You need to manually import lower-level APIs if you need them.
 29  
 30  ``yaml/serialization`` has been split into:
 31  
 32   * ``yaml/loading``, which provides ``load`` etc
 33   * ``yaml/dumping``, which provides ``dump`` etc
 34   * ``yaml/native``, which provides the lower level ``contstruct``, ``represent`` etc
 35  
 36  All of these are imported automatically by doing ``import yaml``.
 37  
 38  Dumping API
 39  ===========
 40  
 41  NimYAML 2.0.0 introduces the new object ``Dumper``, which holds configuration for dumping values to YAML.
 42  The dumping API must now be called on an instance of ``Dumper``.
 43  The previous additional arguments to the ``dump`` proc are now part of ``Dumper``.
 44  
 45  ``yaml/dumping`` provides several procs that return common dumper presets.
 46  These presets were previously the values of ``PresentationStyle``, which has been removed.
 47  
 48  Example code for old API:
 49  
 50  .. code-block:: nim
 51    var value = # some value
 52    var s = newFileStream("out.yaml", fmWrite)
 53    
 54    #simple dump
 55    dump(value, s)
 56    
 57    # dump with options
 58    dump(value, s, tagStyle = tsAll, options =
 59      defineOptions(style = psBlockOnly, outputVersion = ov1_2))
 60  
 61  Same code for new API:
 62  
 63  .. code-block:: nim
 64    var value = # some value
 65    var s = newFileStream("out.yaml", fmWrite)
 66    var dumper = Dumper()
 67    
 68    # simple dump
 69    dumper.dump(value, s)
 70    
 71    # dump with options
 72    dumper.setBlockOnlyStyle()
 73    dumper.presentation.outputVersion = ov1_2
 74    dumper.dump(value, s)
 75  
 76  The previous ``PresentationOptions`` now live in ``dumper.presentation``.
 77  There are also ``SeralizationOptions`` in ``dumper.serialization``.
 78  A preset (like ``setBlockOnlyStyle``) sets values for both option objects.
 79  You can modify the options afterwards to your liking.
 80  
 81  The new API makes use of Nim 2 default values for object fields.
 82  Hence ``defineOptions`` is gone, you can instead use the constructor of ``PresentationOptions``.
 83  
 84  Changes to Default Output Style
 85  ===============================
 86  
 87  Previously, the default output style included
 88  
 89  .. code-block:: yaml
 90    %YAML 1.2
 91    %TAG !n! tag:nimyaml.org,2016:
 92    ---
 93  
 94  All of this is gone. By default, ``---`` is only emitted if the root node has an anchor or tag.
 95  You can emit the ``%YAML`` directive by setting ``outputVersion`` (see above).
 96  You can emit the ``%TAG`` directive via
 97  
 98  .. code-block:: nim
 99    dumper.serialization.handles = initNimYamlTagHandle()
100  
101  Previously, the root node had a YAML tag. Now, the tag isn't emitted anymore by default.
102  You can enable it via
103  
104  .. code-block:: nim
105    dumper.serialization.tagStyle = tsRootOnly
106  
107  Changes to the ``construct`` and ``represent`` procs
108  ====================================================
109  
110  This mainly concerns custom constructors and representers.
111  The required signature of ``constructObject`` and ``representObject`` procs changed.
112  
113  Old signatures:
114  
115  .. code-block:: nim
116    proc constructObject*(
117      s: var YamlStream,
118      c: ConstructionContext,
119      result: var MyObject,
120    ) {.raises: [YamlConstructionError, YamlStreamError].}
121  
122    proc representObject*(
123      value: MyObject,
124      ts   : TagStyle,
125      c    : SerializationContext,
126      tag  : TagId,
127    ): {.raises: [YamlSerializationError].}
128  
129  New signatures:
130  
131  .. code-block:: nim
132    proc constructObject*(
133      ctx   : var ConstructionContext,
134      result: var MyObject,
135    ) {.raises: [YamlConstructionError, YamlStreamError].}
136    
137    proc representObject*(
138      ctx  : var SerializationContext,
139      value: MyObject,
140      tag  : TagId,
141    ): {.raises: [YamlSerializationError].}
142  
143  For ``constructObject``, the input ``YamlStream`` can now be found in ``ctx.input``.
144