1062 lines · plain
1=====================2YAML I/O3=====================4 5.. contents::6 :local:7 8Introduction to YAML9====================10 11YAML is a human-readable data serialization language. The full YAML language12spec can be read at `yaml.org13<http://www.yaml.org/spec/1.2/spec.html#Introduction>`_. The simplest form of14YAML is just "scalars", "mappings", and "sequences". A scalar is any number15or string. The pound/hash symbol (``#``) begins a comment line. A mapping is16a set of key-value pairs where the key ends with a colon. For example:17 18.. code-block:: yaml19 20 # a mapping21 name: Tom22 hat-size: 723 24A sequence is a list of items where each item starts with a leading dash (``-``).25For example:26 27.. code-block:: yaml28 29 # a sequence30 - x8631 - x86_6432 - PowerPC33 34You can combine mappings and sequences by indenting. For example a sequence35of mappings in which one of the mapping values is itself a sequence:36 37.. code-block:: yaml38 39 # a sequence of mappings with one key's value being a sequence40 - name: Tom41 cpus:42 - x8643 - x86_6444 - name: Bob45 cpus:46 - x8647 - name: Dan48 cpus:49 - PowerPC50 - x8651 52Sometimes sequences are known to be short and the one entry per line is too53verbose, so YAML offers an alternative syntax for sequences called a "Flow54Sequence" in which you put comma separated sequence elements into square55brackets. The above example could then be simplified to:56 57 58.. code-block:: yaml59 60 # a sequence of mappings with one key's value being a flow sequence61 - name: Tom62 cpus: [ x86, x86_64 ]63 - name: Bob64 cpus: [ x86 ]65 - name: Dan66 cpus: [ PowerPC, x86 ]67 68 69Introduction to YAML I/O70========================71 72The use of indenting makes the YAML easy for a human to read and understand,73but having a program read and write YAML involves a lot of tedious details.74The YAML I/O library structures and simplifies reading and writing YAML75documents.76 77YAML I/O assumes you have some "native" data structures which you want to be78able to dump as YAML and recreate from YAML. The first step is to try79writing example YAML for your data structures. You may find after looking at80possible YAML representations that a direct mapping of your data structures81to YAML is not very readable. Often, the fields are not in an order that82a human would find readable. Or the same information is replicated in multiple83locations, making it hard for a human to write such YAML correctly.84 85In relational database theory there is a design step called normalization in86which you reorganize fields and tables. The same considerations need to87go into the design of your YAML encoding. But, you may not want to change88your existing native data structures. Therefore, when writing out YAML,89there may be a normalization step, and when reading YAML there would be a90corresponding denormalization step.91 92YAML I/O uses a non-invasive, traits-based design. YAML I/O defines some93abstract base templates. You specialize those templates on your data types.94For instance, if you have an enumerated type ``FooBar`` you could specialize95``ScalarEnumerationTraits`` on that type and define the ``enumeration()`` method:96 97.. code-block:: c++98 99 using llvm::yaml::ScalarEnumerationTraits;100 using llvm::yaml::IO;101 102 template <>103 struct ScalarEnumerationTraits<FooBar> {104 static void enumeration(IO &io, FooBar &value) {105 ...106 }107 };108 109 110As with all YAML I/O template specializations, the ``ScalarEnumerationTraits`` is used for111both reading and writing YAML. That is, the mapping between in-memory enum112values and the YAML string representation is only in one place.113This assures that the code for writing and parsing of YAML stays in sync.114 115To specify YAML mappings, you define a specialization on116``llvm::yaml::MappingTraits``.117If your native data structure happens to be a struct that is already normalized,118then the specialization is simple. For example:119 120.. code-block:: c++121 122 using llvm::yaml::MappingTraits;123 using llvm::yaml::IO;124 125 template <>126 struct MappingTraits<Person> {127 static void mapping(IO &io, Person &info) {128 io.mapRequired("name", info.name);129 io.mapOptional("hat-size", info.hatSize);130 }131 };132 133 134A YAML sequence is automatically inferred if your data type has ``begin()``/``end()``135iterators and a ``push_back()`` method. Therefore any of the STL containers136(such as ``std::vector<>``) will automatically translate to YAML sequences.137 138Once you have defined specializations for your data types, you can139programmatically use YAML I/O to write a YAML document:140 141.. code-block:: c++142 143 using llvm::yaml::Output;144 145 Person tom;146 tom.name = "Tom";147 tom.hatSize = 8;148 Person dan;149 dan.name = "Dan";150 dan.hatSize = 7;151 std::vector<Person> persons;152 persons.push_back(tom);153 persons.push_back(dan);154 155 Output yout(llvm::outs());156 yout << persons;157 158This would write the following:159 160.. code-block:: yaml161 162 - name: Tom163 hat-size: 8164 - name: Dan165 hat-size: 7166 167And you can also read such YAML documents with the following code:168 169.. code-block:: c++170 171 using llvm::yaml::Input;172 173 typedef std::vector<Person> PersonList;174 std::vector<PersonList> docs;175 176 Input yin(document.getBuffer());177 yin >> docs;178 179 if ( yin.error() )180 return;181 182 // Process read document183 for ( PersonList &pl : docs ) {184 for ( Person &person : pl ) {185 cout << "name=" << person.name;186 }187 }188 189One other feature of YAML is the ability to define multiple documents in a190single file. That is why reading YAML produces a vector of your document type.191 192 193 194Error Handling195==============196 197When parsing a YAML document, if the input does not match your schema (as198expressed in your ``XxxTraits<>`` specializations). YAML I/O199will print out an error message and your Input object's ``error()`` method will200return true. For instance, the following document:201 202.. code-block:: yaml203 204 - name: Tom205 shoe-size: 12206 - name: Dan207 hat-size: 7208 209Has a key (shoe-size) that is not defined in the schema. YAML I/O will210automatically generate this error:211 212.. code-block:: yaml213 214 YAML:2:2: error: unknown key 'shoe-size'215 shoe-size: 12216 ^~~~~~~~~217 218Similar errors are produced for other input not conforming to the schema.219 220 221Scalars222=======223 224YAML scalars are just strings (i.e., not a sequence or mapping). The YAML I/O225library provides support for translating between YAML scalars and specific226C++ types.227 228 229Built-in types230--------------231The following types have built-in support in YAML I/O:232 233* ``bool``234* ``float``235* ``double``236* ``StringRef``237* ``std::string``238* ``int64_t``239* ``int32_t``240* ``int16_t``241* ``int8_t``242* ``uint64_t``243* ``uint32_t``244* ``uint16_t``245* ``uint8_t``246 247That is, you can use those types in fields of ``MappingTraits`` or as the element type248in a sequence. When reading, YAML I/O will validate that the string found249is convertible to that type and error out if not.250 251 252Unique types253------------254Given that YAML I/O is trait based, the selection of how to convert your data255to YAML is based on the type of your data. But in C++ type matching, typedefs256do not generate unique type names. That means if you have two typedefs of257unsigned int, to YAML I/O both types look exactly like unsigned int. To258facilitate making unique type names, YAML I/O provides a macro which is used259like a typedef on built-in types, but expands to create a class with conversion260operators to and from the base type. For example:261 262.. code-block:: c++263 264 LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFooFlags)265 LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyBarFlags)266 267This generates two classes ``MyFooFlags`` and ``MyBarFlags`` which you can use in your268native data structures instead of ``uint32_t``. They are implicitly269converted to and from ``uint32_t``. The point of creating these unique types270is that you can now specify traits on them to get different YAML conversions.271 272Hex types273---------274An example use of a unique type is that YAML I/O provides fixed-sized unsigned275integers that are written with YAML I/O as hexadecimal instead of the decimal276format used by the built-in integer types:277 278* ``Hex64``279* ``Hex32``280* ``Hex16``281* ``Hex8``282 283You can use ``llvm::yaml::Hex32`` instead of ``uint32_t``. The only difference will284be that when YAML I/O writes out that type it will be formatted in hexadecimal.285 286 287ScalarEnumerationTraits288-----------------------289YAML I/O supports translating between in-memory enumerations and a set of string290values in YAML documents. This is done by specializing ``ScalarEnumerationTraits<>``291on your enumeration type and defining an ``enumeration()`` method.292For instance, suppose you had an enumeration of CPUs and a struct with it as293a field:294 295.. code-block:: c++296 297 enum CPUs {298 cpu_x86_64 = 5,299 cpu_x86 = 7,300 cpu_PowerPC = 8301 };302 303 struct Info {304 CPUs cpu;305 uint32_t flags;306 };307 308To support reading and writing of this enumeration, you can define a309``ScalarEnumerationTraits`` specialization on CPUs, which can then be used310as a field type:311 312.. code-block:: c++313 314 using llvm::yaml::ScalarEnumerationTraits;315 using llvm::yaml::MappingTraits;316 using llvm::yaml::IO;317 318 template <>319 struct ScalarEnumerationTraits<CPUs> {320 static void enumeration(IO &io, CPUs &value) {321 io.enumCase(value, "x86_64", cpu_x86_64);322 io.enumCase(value, "x86", cpu_x86);323 io.enumCase(value, "PowerPC", cpu_PowerPC);324 }325 };326 327 template <>328 struct MappingTraits<Info> {329 static void mapping(IO &io, Info &info) {330 io.mapRequired("cpu", info.cpu);331 io.mapOptional("flags", info.flags, 0);332 }333 };334 335When reading YAML, if the string found does not match any of the strings336specified by ``enumCase()`` methods, an error is automatically generated.337When writing YAML, if the value being written does not match any of the values338specified by the ``enumCase()`` methods, a runtime assertion is triggered.339 340 341BitValue342--------343Another common data structure in C++ is a field where each bit has a unique344meaning. This is often used in a "flags" field. YAML I/O has support for345converting such fields to a flow sequence. For instance suppose you346had the following bit flags defined:347 348.. code-block:: c++349 350 enum {351 flagsPointy = 1352 flagsHollow = 2353 flagsFlat = 4354 flagsRound = 8355 };356 357 LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFlags)358 359To support reading and writing of ``MyFlags``, you specialize ``ScalarBitSetTraits<>``360on ``MyFlags`` and provide the bit values and their names.361 362.. code-block:: c++363 364 using llvm::yaml::ScalarBitSetTraits;365 using llvm::yaml::MappingTraits;366 using llvm::yaml::IO;367 368 template <>369 struct ScalarBitSetTraits<MyFlags> {370 static void bitset(IO &io, MyFlags &value) {371 io.bitSetCase(value, "hollow", flagHollow);372 io.bitSetCase(value, "flat", flagFlat);373 io.bitSetCase(value, "round", flagRound);374 io.bitSetCase(value, "pointy", flagPointy);375 }376 };377 378 struct Info {379 StringRef name;380 MyFlags flags;381 };382 383 template <>384 struct MappingTraits<Info> {385 static void mapping(IO &io, Info& info) {386 io.mapRequired("name", info.name);387 io.mapRequired("flags", info.flags);388 }389 };390 391With the above, YAML I/O (when writing) will test mask each value in the392bitset trait against the flags field, and each that matches will393cause the corresponding string to be added to the flow sequence. The opposite394is done when reading and any unknown string values will result in an error. With395the above schema, a same valid YAML document is:396 397.. code-block:: yaml398 399 name: Tom400 flags: [ pointy, flat ]401 402Sometimes a "flags" field might contain an enumeration part403defined by a bit-mask.404 405.. code-block:: c++406 407 enum {408 flagsFeatureA = 1,409 flagsFeatureB = 2,410 flagsFeatureC = 4,411 412 flagsCPUMask = 24,413 414 flagsCPU1 = 8,415 flagsCPU2 = 16416 };417 418To support reading and writing such fields, you need to use the ``maskedBitSet()``419method and provide the bit values, their names and the enumeration mask.420 421.. code-block:: c++422 423 template <>424 struct ScalarBitSetTraits<MyFlags> {425 static void bitset(IO &io, MyFlags &value) {426 io.bitSetCase(value, "featureA", flagsFeatureA);427 io.bitSetCase(value, "featureB", flagsFeatureB);428 io.bitSetCase(value, "featureC", flagsFeatureC);429 io.maskedBitSetCase(value, "CPU1", flagsCPU1, flagsCPUMask);430 io.maskedBitSetCase(value, "CPU2", flagsCPU2, flagsCPUMask);431 }432 };433 434YAML I/O (when writing) will apply the enumeration mask to the flags field,435and compare the result and values from the bitset. As in case of a regular436bitset, each that matches will cause the corresponding string to be added437to the flow sequence.438 439Custom Scalar440-------------441Sometimes, for readability, a scalar needs to be formatted in a custom way. For442instance, your internal data structure may use an integer for time (seconds since443some epoch), but in YAML it would be much nicer to express that integer in444some time format (e.g., ``4-May-2012 10:30pm``). YAML I/O has a way to support445custom formatting and parsing of scalar types by specializing ``ScalarTraits<>`` on446your data type. When writing, YAML I/O will provide the native type and447your specialization must create a temporary ``llvm::StringRef``. When reading,448YAML I/O will provide an ``llvm::StringRef`` of scalar and your specialization449must convert that to your native data type. An outline of a custom scalar type450looks like:451 452.. code-block:: c++453 454 using llvm::yaml::ScalarTraits;455 using llvm::yaml::IO;456 457 template <>458 struct ScalarTraits<MyCustomType> {459 static void output(const MyCustomType &value, void*,460 llvm::raw_ostream &out) {461 out << value; // do custom formatting here462 }463 static StringRef input(StringRef scalar, void*, MyCustomType &value) {464 // do custom parsing here. Return the empty string on success,465 // or an error message on failure.466 return StringRef();467 }468 // Determine if this scalar needs quotes.469 static QuotingType mustQuote(StringRef) { return QuotingType::Single; }470 };471 472Block Scalars473-------------474 475YAML block scalars are string literals that are represented in YAML using the476literal block notation, just like the example shown below:477 478.. code-block:: yaml479 480 text: |481 First line482 Second line483 484The YAML I/O library provides support for translating between YAML block scalars485and specific C++ types by allowing you to specialize ``BlockScalarTraits<>`` on486your data type. The library doesn't provide any built-in support for block487scalar I/O for types like ``std::string`` and ``llvm::StringRef`` as they are already488supported by YAML I/O and use the ordinary scalar notation by default.489 490``BlockScalarTraits`` specializations are very similar to the491``ScalarTraits`` specialization - YAML I/O will provide the native type and your492specialization must create a temporary ``llvm::StringRef`` when writing, and493it will also provide an ``llvm::StringRef`` that has the value of that block scalar494and your specialization must convert that to your native data type when reading.495An example of a custom type with an appropriate specialization of496``BlockScalarTraits`` is shown below:497 498.. code-block:: c++499 500 using llvm::yaml::BlockScalarTraits;501 using llvm::yaml::IO;502 503 struct MyStringType {504 std::string Str;505 };506 507 template <>508 struct BlockScalarTraits<MyStringType> {509 static void output(const MyStringType &Value, void *Ctxt,510 llvm::raw_ostream &OS) {511 OS << Value.Str;512 }513 514 static StringRef input(StringRef Scalar, void *Ctxt,515 MyStringType &Value) {516 Value.Str = Scalar.str();517 return StringRef();518 }519 };520 521 522 523Mappings524========525 526To be translated to or from a YAML mapping for your type ``T``, you must specialize527``llvm::yaml::MappingTraits`` on ``T`` and implement the ``void mapping(IO &io, T&)``528method. If your native data structures use pointers to a class everywhere,529you can specialize on the class pointer. Examples:530 531.. code-block:: c++532 533 using llvm::yaml::MappingTraits;534 using llvm::yaml::IO;535 536 // Example of struct Foo which is used by value537 template <>538 struct MappingTraits<Foo> {539 static void mapping(IO &io, Foo &foo) {540 io.mapOptional("size", foo.size);541 ...542 }543 };544 545 // Example of struct Bar which is natively always a pointer546 template <>547 struct MappingTraits<Bar*> {548 static void mapping(IO &io, Bar *&bar) {549 io.mapOptional("size", bar->size);550 ...551 }552 };553 554There are circumstances where we want to allow the entire mapping to be555read as an enumeration. For example, say some configuration option556started as an enumeration. Then it got more complex so it is now a557mapping. But it is necessary to support the old configuration files.558In that case, add a function ``enumInput`` like for559``ScalarEnumerationTraits::enumeration``. Examples:560 561.. code-block:: c++562 563 struct FooBarEnum {564 int Foo;565 int Bar;566 bool operator==(const FooBarEnum &R) const {567 return Foo == R.Foo && Bar == R.Bar;568 }569 };570 571 template <> struct MappingTraits<FooBarEnum> {572 static void enumInput(IO &io, FooBarEnum &Val) {573 io.enumCase(Val, "OnlyFoo", FooBarEnum({1, 0}));574 io.enumCase(Val, "OnlyBar", FooBarEnum({0, 1}));575 }576 static void mapping(IO &io, FooBarEnum &Val) {577 io.mapOptional("Foo", Val.Foo);578 io.mapOptional("Bar", Val.Bar);579 }580 };581 582 583No Normalization584----------------585 586The ``mapping()`` method is responsible, if needed, for normalizing and587denormalizing. In a simple case where the native data structure requires no588normalization, the mapping method just uses ``mapOptional()`` or ``mapRequired()`` to589bind the struct's fields to YAML key names. For example:590 591.. code-block:: c++592 593 using llvm::yaml::MappingTraits;594 using llvm::yaml::IO;595 596 template <>597 struct MappingTraits<Person> {598 static void mapping(IO &io, Person &info) {599 io.mapRequired("name", info.name);600 io.mapOptional("hat-size", info.hatSize);601 }602 };603 604 605Normalization606----------------607 608When [de]normalization is required, the ``mapping()`` method needs a way to access609normalized values as fields. To help with this, there is610a template ``MappingNormalization<>`` which you can then use to automatically611do the normalization and denormalization. The template is used to create612a local variable in your ``mapping()`` method which contains the normalized keys.613 614Suppose you have native data type615Polar which specifies a position in polar coordinates (distance, angle):616 617.. code-block:: c++618 619 struct Polar {620 float distance;621 float angle;622 };623 624but you've decided the normalized YAML form should be in x,y coordinates. That625is, you want the yaml to look like:626 627.. code-block:: yaml628 629 x: 10.3630 y: -4.7631 632You can support this by defining a ``MappingTraits`` that normalizes the polar633coordinates to x,y coordinates when writing YAML and denormalizes x,y634coordinates into polar when reading YAML.635 636.. code-block:: c++637 638 using llvm::yaml::MappingTraits;639 using llvm::yaml::IO;640 641 template <>642 struct MappingTraits<Polar> {643 644 class NormalizedPolar {645 public:646 NormalizedPolar(IO &io)647 : x(0.0), y(0.0) {648 }649 NormalizedPolar(IO &, Polar &polar)650 : x(polar.distance * cos(polar.angle)),651 y(polar.distance * sin(polar.angle)) {652 }653 Polar denormalize(IO &) {654 return Polar(sqrt(x*x+y*y), arctan(x,y));655 }656 657 float x;658 float y;659 };660 661 static void mapping(IO &io, Polar &polar) {662 MappingNormalization<NormalizedPolar, Polar> keys(io, polar);663 664 io.mapRequired("x", keys->x);665 io.mapRequired("y", keys->y);666 }667 };668 669When writing YAML, the local variable "keys" will be a stack allocated670instance of ``NormalizedPolar``, constructed from the supplied polar object which671initializes it x and y fields. The ``mapRequired()`` methods then write out the x672and y values as key/value pairs.673 674When reading YAML, the local variable "keys" will be a stack allocated instance675of ``NormalizedPolar``, constructed by the empty constructor. The ``mapRequired()``676methods will find the matching key in the YAML document and fill in the x and y677fields of the ``NormalizedPolar`` object keys. At the end of the ``mapping()`` method678when the local keys variable goes out of scope, the ``denormalize()`` method will679automatically be called to convert the read values back to polar coordinates,680and then assigned back to the second parameter to ``mapping()``.681 682In some cases, the normalized class may be a subclass of the native type and683could be returned by the ``denormalize()`` method, except that the temporary684normalized instance is stack allocated. In these cases, the utility template685``MappingNormalizationHeap<>`` can be used instead. It just like686``MappingNormalization<>`` except that it heap allocates the normalized object687when reading YAML. It never destroys the normalized object. The ``denormalize()``688method can this return ``this``.689 690 691Default values692--------------693Within a ``mapping()`` method, calls to ``io.mapRequired()`` mean that that key is694required to exist when parsing YAML documents; otherwise, YAML I/O will issue an695error.696 697On the other hand, keys registered with ``io.mapOptional()`` are allowed to not698exist in the YAML document being read. So what value is put in the field699for those optional keys?700There are two steps to how those optional fields are filled in. First, the701second parameter to the ``mapping()`` method is a reference to a native class. That702native class must have a default constructor. Whatever value the default703constructor initially sets for an optional field will be that field's value.704Second, the ``mapOptional()`` method has an optional third parameter. If provided705it is the value that ``mapOptional()`` should set that field to if the YAML document706does not have that key.707 708There is one important difference between those two ways (default constructor709and third parameter to ``mapOptional()``). When YAML I/O generates a YAML document,710if the ``mapOptional()`` third parameter is used, if the actual value being written711is the same as (using ``==``) the default value, then that key/value is not written.712 713 714Order of Keys715--------------716 717When writing out a YAML document, the keys are written in the order that the718calls to ``mapRequired()``/``mapOptional()`` are made in the ``mapping()`` method. This719gives you a chance to write the fields in an order that a human reader of720the YAML document would find natural. This may be different that the order721of the fields in the native class.722 723When reading in a YAML document, the keys in the document can be in any order,724but they are processed in the order that the calls to ``mapRequired()``/``mapOptional()``725are made in the ``mapping()`` method. That enables some interesting726functionality. For instance, if the first field bound is the cpu and the second727field bound is flags, and the flags are cpu specific, you can programmatically728switch how the flags are converted to and from YAML based on the cpu.729This works for both reading and writing. For example:730 731.. code-block:: c++732 733 using llvm::yaml::MappingTraits;734 using llvm::yaml::IO;735 736 struct Info {737 CPUs cpu;738 uint32_t flags;739 };740 741 template <>742 struct MappingTraits<Info> {743 static void mapping(IO &io, Info &info) {744 io.mapRequired("cpu", info.cpu);745 // flags must come after cpu for this to work when reading yaml746 if ( info.cpu == cpu_x86_64 )747 io.mapRequired("flags", *(My86_64Flags*)info.flags);748 else749 io.mapRequired("flags", *(My86Flags*)info.flags);750 }751 };752 753 754Tags755----756 757The YAML syntax supports tags as a way to specify the type of a node before758it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses759static typing, so there are limits to how you can use tags with the YAML I/O760model. Recently, we added support to YAML I/O for checking/setting the optional761tag on a map. Using this functionality it is even possible to support different762mappings, as long as they are convertible.763 764To check a tag, inside your ``mapping()`` method you can use ``io.mapTag()`` to specify765what the tag should be. This will also add that tag when writing YAML.766 767Validation768----------769 770Sometimes in a YAML map, each key/value pair is valid, but the combination is771not. This is similar to something having no syntax errors, but still having772semantic errors. To support semantic-level checking, YAML I/O allows773an optional ``validate()`` method in a MappingTraits template specialization.774 775When parsing YAML, the ``validate()`` method is called *after* all key/values in776the map have been processed. Any error message returned by the ``validate()``777method during input will be printed just like a syntax error would be printed.778When writing YAML, the ``validate()`` method is called *before* the YAML779key/values are written. Any error during output will trigger an ``assert()``780because it is a programming error to have invalid struct values.781 782 783.. code-block:: c++784 785 using llvm::yaml::MappingTraits;786 using llvm::yaml::IO;787 788 struct Stuff {789 ...790 };791 792 template <>793 struct MappingTraits<Stuff> {794 static void mapping(IO &io, Stuff &stuff) {795 ...796 }797 static std::string validate(IO &io, Stuff &stuff) {798 // Look at all fields in 'stuff' and if there799 // are any bad values return a string describing800 // the error. Otherwise return an empty string.801 return std::string{};802 }803 };804 805Flow Mapping806------------807A YAML "flow mapping" is a mapping that uses the inline notation808(e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be809written in YAML using flow mapping, your MappingTraits specialization should810add ``static constexpr bool flow = true;``. For instance:811 812.. code-block:: c++813 814 using llvm::yaml::MappingTraits;815 using llvm::yaml::IO;816 817 struct Stuff {818 ...819 };820 821 template <>822 struct MappingTraits<Stuff> {823 static void mapping(IO &io, Stuff &stuff) {824 ...825 }826 827 static constexpr bool flow = true;828 }829 830Flow mappings are subject to line wrapping according to the ``Output`` object831configuration.832 833Sequence834========835 836To be translated to or from a YAML sequence for your type ``T``, you must specialize837``llvm::yaml::SequenceTraits`` on ``T`` and implement two methods:838``size_t size(IO &io, T&)`` and839``T::value_type& element(IO &io, T&, size_t indx)``. For example:840 841.. code-block:: c++842 843 template <>844 struct SequenceTraits<MySeq> {845 static size_t size(IO &io, MySeq &list) { ... }846 static MySeqEl &element(IO &io, MySeq &list, size_t index) { ... }847 };848 849The ``size()`` method returns how many elements are currently in your sequence.850The ``element()`` method returns a reference to the i'th element in the sequence.851When parsing YAML, the ``element()`` method may be called with an index one bigger852than the current size. Your ``element()`` method should allocate space for one853more element (using default constructor if element is a C++ object) and return854a reference to that new allocated space.855 856 857Flow Sequence858-------------859A YAML "flow sequence" is a sequence that when written to YAML it uses the860inline notation (e.g., ``[ foo, bar ]`` ). To specify that a sequence type should861be written in YAML as a flow sequence, your SequenceTraits specialization should862add ``static constexpr bool flow = true;``. For instance:863 864.. code-block:: c++865 866 template <>867 struct SequenceTraits<MyList> {868 static size_t size(IO &io, MyList &list) { ... }869 static MyListEl &element(IO &io, MyList &list, size_t index) { ... }870 871 // The existence of this member causes YAML I/O to use a flow sequence872 static constexpr bool flow = true;873 };874 875With the above, if you used ``MyList`` as the data type in your native data876structures, then when converted to YAML, a flow sequence of integers877will be used (e.g., ``[ 10, -3, 4 ]``).878 879Flow sequences are subject to line wrapping according to the Output object880configuration.881 882Utility Macros883--------------884Since a common source of sequences is ``std::vector<>``, YAML I/O provides macros:885``LLVM_YAML_IS_SEQUENCE_VECTOR()`` and ``LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR()`` which886can be used to easily specify ``SequenceTraits<>`` on a ``std::vector`` type. YAML887I/O does not partial specialize ``SequenceTraits`` on ``std::vector<>`` because that888would force all vectors to be sequences. An example use of the macros:889 890.. code-block:: c++891 892 std::vector<MyType1>;893 std::vector<MyType2>;894 LLVM_YAML_IS_SEQUENCE_VECTOR(MyType1)895 LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(MyType2)896 897 898 899Document List900=============901 902YAML allows you to define multiple "documents" in a single YAML file. Each903new document starts with a left aligned ``---`` token. The end of all documents904is denoted with a left aligned ``...`` token. Many users of YAML will never905have need for multiple documents. The top level node in their YAML schema906will be a mapping or sequence. For those cases, the following is not needed.907But for cases where you do want multiple documents, you can specify a908trait for you document list type. The trait has the same methods as909``SequenceTraits`` but is named ``DocumentListTraits``. For example:910 911.. code-block:: c++912 913 template <>914 struct DocumentListTraits<MyDocList> {915 static size_t size(IO &io, MyDocList &list) { ... }916 static MyDocType element(IO &io, MyDocList &list, size_t index) { ... }917 };918 919 920User Context Data921=================922When an ``llvm::yaml::Input`` or ``llvm::yaml::Output`` object is created, its923constructor takes an optional "context" parameter. This is a pointer to924whatever state information you might need.925 926For instance, in a previous example we showed how the conversion type for a927flags field could be determined at runtime based on the value of another field928in the mapping. But what if an inner mapping needs to know some field value929of an outer mapping? That is where the "context" parameter comes in. You930can set values in the context in the outer map's ``mapping()`` method and931retrieve those values in the inner map's ``mapping()`` method.932 933The context value is just a ``void*``. All your traits which use the context934and operate on your native data types, need to agree what the context value935actually is. It could be a pointer to an object or struct which your various936traits use to share context sensitive information.937 938 939Output940======941 942The ``llvm::yaml::Output`` class is used to generate a YAML document from your943in-memory data structures, using traits defined on your data types.944To instantiate an ``Output`` object you need an ``llvm::raw_ostream``, an optional945context pointer and an optional wrapping column:946 947.. code-block:: c++948 949 class Output : public IO {950 public:951 Output(llvm::raw_ostream &, void *context = NULL, int WrapColumn = 70);952 953Once you have an ``Output`` object, you can use the C++ stream operator on it954to write your native data as YAML. One thing to recall is that a YAML file955can contain multiple "documents". If the top level data structure you are956streaming as YAML is a mapping, scalar, or sequence, then ``Output`` assumes you957are generating one document and wraps the mapping output958with ``---`` and trailing ``...``.959 960The ``WrapColumn`` parameter will cause the flow mappings and sequences to961line-wrap when they go over the supplied column. Pass 0 to completely962suppress the wrapping.963 964.. code-block:: c++965 966 using llvm::yaml::Output;967 968 void dumpMyMapDoc(const MyMapType &info) {969 Output yout(llvm::outs());970 yout << info;971 }972 973The above could produce output like:974 975.. code-block:: yaml976 977 ---978 name: Tom979 hat-size: 7980 ...981 982On the other hand, if the top level data structure you are streaming as YAML983has a ``DocumentListTraits`` specialization, then Output walks through each element984of your DocumentList and generates a ``---`` before the start of each element985and ends with a ``...``.986 987.. code-block:: c++988 989 using llvm::yaml::Output;990 991 void dumpMyMapDoc(const MyDocListType &docList) {992 Output yout(llvm::outs());993 yout << docList;994 }995 996The above could produce output like:997 998.. code-block:: yaml999 1000 ---1001 name: Tom1002 hat-size: 71003 ---1004 name: Tom1005 shoe-size: 111006 ...1007 1008Input1009=====1010 1011The ``llvm::yaml::Input`` class is used to parse YAML document(s) into your native1012data structures. To instantiate an ``Input``1013object you need a ``StringRef`` to the entire YAML file, and optionally a context1014pointer:1015 1016.. code-block:: c++1017 1018 class Input : public IO {1019 public:1020 Input(StringRef inputContent, void *context=NULL);1021 1022Once you have an ``Input`` object, you can use the C++ stream operator to read1023the document(s). If you expect there might be multiple YAML documents in1024one file, you'll need to specialize ``DocumentListTraits`` on a list of your1025document type and stream in that document list type. Otherwise, you can1026just stream in the document type. Also, you can check if there was1027any syntax errors in the YAML by calling the ``error()`` method on the ``Input``1028object. For example:1029 1030.. code-block:: c++1031 1032 // Reading a single document1033 using llvm::yaml::Input;1034 1035 Input yin(mb.getBuffer());1036 1037 // Parse the YAML file1038 MyDocType theDoc;1039 yin >> theDoc;1040 1041 // Check for error1042 if ( yin.error() )1043 return;1044 1045 1046.. code-block:: c++1047 1048 // Reading multiple documents in one file1049 using llvm::yaml::Input;1050 1051 LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(MyDocType)1052 1053 Input yin(mb.getBuffer());1054 1055 // Parse the YAML file1056 std::vector<MyDocType> theDocList;1057 yin >> theDocList;1058 1059 // Check for error1060 if ( yin.error() )1061 return;1062