1===================== 2YAML I/O 3===================== 4 5.. contents:: 6 :local: 7 8Introduction to YAML 9==================== 10 11YAML is a human readable data serialization language. The full YAML language 12spec can be read at `yaml.org 13<http://www.yaml.org/spec/1.2/spec.html#Introduction>`_. The simplest form of 14yaml is just "scalars", "mappings", and "sequences". A scalar is any number 15or string. The pound/hash symbol (#) begins a comment line. A mapping is 16a set of key-value pairs where the key ends with a colon. For example: 17 18.. code-block:: yaml 19 20 # a mapping 21 name: Tom 22 hat-size: 7 23 24A sequence is a list of items where each item starts with a leading dash ('-'). 25For example: 26 27.. code-block:: yaml 28 29 # a sequence 30 - x86 31 - x86_64 32 - PowerPC 33 34You can combine mappings and sequences by indenting. For example a sequence 35of mappings in which one of the mapping values is itself a sequence: 36 37.. code-block:: yaml 38 39 # a sequence of mappings with one key's value being a sequence 40 - name: Tom 41 cpus: 42 - x86 43 - x86_64 44 - name: Bob 45 cpus: 46 - x86 47 - name: Dan 48 cpus: 49 - PowerPC 50 - x86 51 52Sometime sequences are known to be short and the one entry per line is too 53verbose, so YAML offers an alternate syntax for sequences called a "Flow 54Sequence" in which you put comma separated sequence elements into square 55brackets. The above example could then be simplified to : 56 57 58.. code-block:: yaml 59 60 # a sequence of mappings with one key's value being a flow sequence 61 - name: Tom 62 cpus: [ x86, x86_64 ] 63 - name: Bob 64 cpus: [ x86 ] 65 - name: Dan 66 cpus: [ PowerPC, x86 ] 67 68 69Introduction to YAML I/O 70======================== 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 YAML 75documents. 76 77YAML I/O assumes you have some "native" data structures which you want to be 78able to dump as YAML and recreate from YAML. The first step is to try 79writing example YAML for your data structures. You may find after looking at 80possible YAML representations that a direct mapping of your data structures 81to YAML is not very readable. Often the fields are not in the order that 82a human would find readable. Or the same information is replicated in multiple 83locations, making it hard for a human to write such YAML correctly. 84 85In relational database theory there is a design step called normalization in 86which you reorganize fields and tables. The same considerations need to 87go into the design of your YAML encoding. But, you may not want to change 88your existing native data structures. Therefore, when writing out YAML 89there may be a normalization step, and when reading YAML there would be a 90corresponding denormalization step. 91 92YAML I/O uses a non-invasive, traits based design. YAML I/O defines some 93abstract base templates. You specialize those templates on your data types. 94For instance, if you have an enumerated type FooBar you could specialize 95ScalarEnumerationTraits 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 for 111both reading and writing YAML. That is, the mapping between in-memory enum 112values 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 a YAML mappings, you define a specialization on 116llvm::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 you data type has begin()/end() 135iterators and a push_back() method. Therefore any of the STL containers 136(such as std::vector<>) will automatically translate to YAML sequences. 137 138Once you have defined specializations for your data types, you can 139programmatically 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:: yaml 161 162 - name: Tom 163 hat-size: 8 164 - name: Dan 165 hat-size: 7 166 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 document 183 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 a 190single file. That is why reading YAML produces a vector of your document type. 191 192 193 194Error Handling 195============== 196 197When parsing a YAML document, if the input does not match your schema (as 198expressed in your XxxTraits<> specializations). YAML I/O 199will print out an error message and your Input object's error() method will 200return true. For instance the following document: 201 202.. code-block:: yaml 203 204 - name: Tom 205 shoe-size: 12 206 - name: Dan 207 hat-size: 7 208 209Has a key (shoe-size) that is not defined in the schema. YAML I/O will 210automatically generate this error: 211 212.. code-block:: yaml 213 214 YAML:2:2: error: unknown key 'shoe-size' 215 shoe-size: 12 216 ^~~~~~~~~ 217 218Similar errors are produced for other input not conforming to the schema. 219 220 221Scalars 222======= 223 224YAML scalars are just strings (i.e. not a sequence or mapping). The YAML I/O 225library provides support for translating between YAML scalars and specific 226C++ types. 227 228 229Built-in types 230-------------- 231The following types have built-in support in YAML I/O: 232 233* bool 234* float 235* double 236* StringRef 237* int64_t 238* int32_t 239* int16_t 240* int8_t 241* uint64_t 242* uint32_t 243* uint16_t 244* uint8_t 245 246That is, you can use those types in fields of MappingTraits or as element type 247in sequence. When reading, YAML I/O will validate that the string found 248is convertible to that type and error out if not. 249 250 251Unique types 252------------ 253Given that YAML I/O is trait based, the selection of how to convert your data 254to YAML is based on the type of your data. But in C++ type matching, typedefs 255do not generate unique type names. That means if you have two typedefs of 256unsigned int, to YAML I/O both types look exactly like unsigned int. To 257facilitate make unique type names, YAML I/O provides a macro which is used 258like a typedef on built-in types, but expands to create a class with conversion 259operators to and from the base type. For example: 260 261.. code-block:: c++ 262 263 LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFooFlags) 264 LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyBarFlags) 265 266This generates two classes MyFooFlags and MyBarFlags which you can use in your 267native data structures instead of uint32_t. They are implicitly 268converted to and from uint32_t. The point of creating these unique types 269is that you can now specify traits on them to get different YAML conversions. 270 271Hex types 272--------- 273An example use of a unique type is that YAML I/O provides fixed sized unsigned 274integers that are written with YAML I/O as hexadecimal instead of the decimal 275format used by the built-in integer types: 276 277* Hex64 278* Hex32 279* Hex16 280* Hex8 281 282You can use llvm::yaml::Hex32 instead of uint32_t and the only different will 283be that when YAML I/O writes out that type it will be formatted in hexadecimal. 284 285 286ScalarEnumerationTraits 287----------------------- 288YAML I/O supports translating between in-memory enumerations and a set of string 289values in YAML documents. This is done by specializing ScalarEnumerationTraits<> 290on your enumeration type and define a enumeration() method. 291For instance, suppose you had an enumeration of CPUs and a struct with it as 292a field: 293 294.. code-block:: c++ 295 296 enum CPUs { 297 cpu_x86_64 = 5, 298 cpu_x86 = 7, 299 cpu_PowerPC = 8 300 }; 301 302 struct Info { 303 CPUs cpu; 304 uint32_t flags; 305 }; 306 307To support reading and writing of this enumeration, you can define a 308ScalarEnumerationTraits specialization on CPUs, which can then be used 309as a field type: 310 311.. code-block:: c++ 312 313 using llvm::yaml::ScalarEnumerationTraits; 314 using llvm::yaml::MappingTraits; 315 using llvm::yaml::IO; 316 317 template <> 318 struct ScalarEnumerationTraits<CPUs> { 319 static void enumeration(IO &io, CPUs &value) { 320 io.enumCase(value, "x86_64", cpu_x86_64); 321 io.enumCase(value, "x86", cpu_x86); 322 io.enumCase(value, "PowerPC", cpu_PowerPC); 323 } 324 }; 325 326 template <> 327 struct MappingTraits<Info> { 328 static void mapping(IO &io, Info &info) { 329 io.mapRequired("cpu", info.cpu); 330 io.mapOptional("flags", info.flags, 0); 331 } 332 }; 333 334When reading YAML, if the string found does not match any of the the strings 335specified by enumCase() methods, an error is automatically generated. 336When writing YAML, if the value being written does not match any of the values 337specified by the enumCase() methods, a runtime assertion is triggered. 338 339 340BitValue 341-------- 342Another common data structure in C++ is a field where each bit has a unique 343meaning. This is often used in a "flags" field. YAML I/O has support for 344converting such fields to a flow sequence. For instance suppose you 345had the following bit flags defined: 346 347.. code-block:: c++ 348 349 enum { 350 flagsPointy = 1 351 flagsHollow = 2 352 flagsFlat = 4 353 flagsRound = 8 354 }; 355 356 LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFlags) 357 358To support reading and writing of MyFlags, you specialize ScalarBitSetTraits<> 359on MyFlags and provide the bit values and their names. 360 361.. code-block:: c++ 362 363 using llvm::yaml::ScalarBitSetTraits; 364 using llvm::yaml::MappingTraits; 365 using llvm::yaml::IO; 366 367 template <> 368 struct ScalarBitSetTraits<MyFlags> { 369 static void bitset(IO &io, MyFlags &value) { 370 io.bitSetCase(value, "hollow", flagHollow); 371 io.bitSetCase(value, "flat", flagFlat); 372 io.bitSetCase(value, "round", flagRound); 373 io.bitSetCase(value, "pointy", flagPointy); 374 } 375 }; 376 377 struct Info { 378 StringRef name; 379 MyFlags flags; 380 }; 381 382 template <> 383 struct MappingTraits<Info> { 384 static void mapping(IO &io, Info& info) { 385 io.mapRequired("name", info.name); 386 io.mapRequired("flags", info.flags); 387 } 388 }; 389 390With the above, YAML I/O (when writing) will test mask each value in the 391bitset trait against the flags field, and each that matches will 392cause the corresponding string to be added to the flow sequence. The opposite 393is done when reading and any unknown string values will result in a error. With 394the above schema, a same valid YAML document is: 395 396.. code-block:: yaml 397 398 name: Tom 399 flags: [ pointy, flat ] 400 401 402Custom Scalar 403------------- 404Sometimes for readability a scalar needs to be formatted in a custom way. For 405instance your internal data structure may use a integer for time (seconds since 406some epoch), but in YAML it would be much nicer to express that integer in 407some time format (e.g. 4-May-2012 10:30pm). YAML I/O has a way to support 408custom formatting and parsing of scalar types by specializing ScalarTraits<> on 409your data type. When writing, YAML I/O will provide the native type and 410your specialization must create a temporary llvm::StringRef. When reading, 411YAML I/O will provide an llvm::StringRef of scalar and your specialization 412must convert that to your native data type. An outline of a custom scalar type 413looks like: 414 415.. code-block:: c++ 416 417 using llvm::yaml::ScalarTraits; 418 using llvm::yaml::IO; 419 420 template <> 421 struct ScalarTraits<MyCustomType> { 422 static void output(const T &value, llvm::raw_ostream &out) { 423 out << value; // do custom formatting here 424 } 425 static StringRef input(StringRef scalar, T &value) { 426 // do custom parsing here. Return the empty string on success, 427 // or an error message on failure. 428 return StringRef(); 429 } 430 }; 431 432 433Mappings 434======== 435 436To be translated to or from a YAML mapping for your type T you must specialize 437llvm::yaml::MappingTraits on T and implement the "void mapping(IO &io, T&)" 438method. If your native data structures use pointers to a class everywhere, 439you can specialize on the class pointer. Examples: 440 441.. code-block:: c++ 442 443 using llvm::yaml::MappingTraits; 444 using llvm::yaml::IO; 445 446 // Example of struct Foo which is used by value 447 template <> 448 struct MappingTraits<Foo> { 449 static void mapping(IO &io, Foo &foo) { 450 io.mapOptional("size", foo.size); 451 ... 452 } 453 }; 454 455 // Example of struct Bar which is natively always a pointer 456 template <> 457 struct MappingTraits<Bar*> { 458 static void mapping(IO &io, Bar *&bar) { 459 io.mapOptional("size", bar->size); 460 ... 461 } 462 }; 463 464 465No Normalization 466---------------- 467 468The mapping() method is responsible, if needed, for normalizing and 469denormalizing. In a simple case where the native data structure requires no 470normalization, the mapping method just uses mapOptional() or mapRequired() to 471bind the struct's fields to YAML key names. For example: 472 473.. code-block:: c++ 474 475 using llvm::yaml::MappingTraits; 476 using llvm::yaml::IO; 477 478 template <> 479 struct MappingTraits<Person> { 480 static void mapping(IO &io, Person &info) { 481 io.mapRequired("name", info.name); 482 io.mapOptional("hat-size", info.hatSize); 483 } 484 }; 485 486 487Normalization 488---------------- 489 490When [de]normalization is required, the mapping() method needs a way to access 491normalized values as fields. To help with this, there is 492a template MappingNormalization<> which you can then use to automatically 493do the normalization and denormalization. The template is used to create 494a local variable in your mapping() method which contains the normalized keys. 495 496Suppose you have native data type 497Polar which specifies a position in polar coordinates (distance, angle): 498 499.. code-block:: c++ 500 501 struct Polar { 502 float distance; 503 float angle; 504 }; 505 506but you've decided the normalized YAML for should be in x,y coordinates. That 507is, you want the yaml to look like: 508 509.. code-block:: yaml 510 511 x: 10.3 512 y: -4.7 513 514You can support this by defining a MappingTraits that normalizes the polar 515coordinates to x,y coordinates when writing YAML and denormalizes x,y 516coordinates into polar when reading YAML. 517 518.. code-block:: c++ 519 520 using llvm::yaml::MappingTraits; 521 using llvm::yaml::IO; 522 523 template <> 524 struct MappingTraits<Polar> { 525 526 class NormalizedPolar { 527 public: 528 NormalizedPolar(IO &io) 529 : x(0.0), y(0.0) { 530 } 531 NormalizedPolar(IO &, Polar &polar) 532 : x(polar.distance * cos(polar.angle)), 533 y(polar.distance * sin(polar.angle)) { 534 } 535 Polar denormalize(IO &) { 536 return Polar(sqrt(x*x+y*y), arctan(x,y)); 537 } 538 539 float x; 540 float y; 541 }; 542 543 static void mapping(IO &io, Polar &polar) { 544 MappingNormalization<NormalizedPolar, Polar> keys(io, polar); 545 546 io.mapRequired("x", keys->x); 547 io.mapRequired("y", keys->y); 548 } 549 }; 550 551When writing YAML, the local variable "keys" will be a stack allocated 552instance of NormalizedPolar, constructed from the supplied polar object which 553initializes it x and y fields. The mapRequired() methods then write out the x 554and y values as key/value pairs. 555 556When reading YAML, the local variable "keys" will be a stack allocated instance 557of NormalizedPolar, constructed by the empty constructor. The mapRequired 558methods will find the matching key in the YAML document and fill in the x and y 559fields of the NormalizedPolar object keys. At the end of the mapping() method 560when the local keys variable goes out of scope, the denormalize() method will 561automatically be called to convert the read values back to polar coordinates, 562and then assigned back to the second parameter to mapping(). 563 564In some cases, the normalized class may be a subclass of the native type and 565could be returned by the denormalize() method, except that the temporary 566normalized instance is stack allocated. In these cases, the utility template 567MappingNormalizationHeap<> can be used instead. It just like 568MappingNormalization<> except that it heap allocates the normalized object 569when reading YAML. It never destroys the normalized object. The denormalize() 570method can this return "this". 571 572 573Default values 574-------------- 575Within a mapping() method, calls to io.mapRequired() mean that that key is 576required to exist when parsing YAML documents, otherwise YAML I/O will issue an 577error. 578 579On the other hand, keys registered with io.mapOptional() are allowed to not 580exist in the YAML document being read. So what value is put in the field 581for those optional keys? 582There are two steps to how those optional fields are filled in. First, the 583second parameter to the mapping() method is a reference to a native class. That 584native class must have a default constructor. Whatever value the default 585constructor initially sets for an optional field will be that field's value. 586Second, the mapOptional() method has an optional third parameter. If provided 587it is the value that mapOptional() should set that field to if the YAML document 588does not have that key. 589 590There is one important difference between those two ways (default constructor 591and third parameter to mapOptional). When YAML I/O generates a YAML document, 592if the mapOptional() third parameter is used, if the actual value being written 593is the same as (using ==) the default value, then that key/value is not written. 594 595 596Order of Keys 597-------------- 598 599When writing out a YAML document, the keys are written in the order that the 600calls to mapRequired()/mapOptional() are made in the mapping() method. This 601gives you a chance to write the fields in an order that a human reader of 602the YAML document would find natural. This may be different that the order 603of the fields in the native class. 604 605When reading in a YAML document, the keys in the document can be in any order, 606but they are processed in the order that the calls to mapRequired()/mapOptional() 607are made in the mapping() method. That enables some interesting 608functionality. For instance, if the first field bound is the cpu and the second 609field bound is flags, and the flags are cpu specific, you can programmatically 610switch how the flags are converted to and from YAML based on the cpu. 611This works for both reading and writing. For example: 612 613.. code-block:: c++ 614 615 using llvm::yaml::MappingTraits; 616 using llvm::yaml::IO; 617 618 struct Info { 619 CPUs cpu; 620 uint32_t flags; 621 }; 622 623 template <> 624 struct MappingTraits<Info> { 625 static void mapping(IO &io, Info &info) { 626 io.mapRequired("cpu", info.cpu); 627 // flags must come after cpu for this to work when reading yaml 628 if ( info.cpu == cpu_x86_64 ) 629 io.mapRequired("flags", *(My86_64Flags*)info.flags); 630 else 631 io.mapRequired("flags", *(My86Flags*)info.flags); 632 } 633 }; 634 635 636Tags 637---- 638 639The YAML syntax supports tags as a way to specify the type of a node before 640it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses 641static typing, so there are limits to how you can use tags with the YAML I/O 642model. Recently, we added support to YAML I/O for checking/setting the optional 643tag on a map. Using this functionality it is even possbile to support differnt 644mappings, as long as they are convertable. 645 646To check a tag, inside your mapping() method you can use io.mapTag() to specify 647what the tag should be. This will also add that tag when writing yaml. 648 649 650Sequence 651======== 652 653To be translated to or from a YAML sequence for your type T you must specialize 654llvm::yaml::SequenceTraits on T and implement two methods: 655``size_t size(IO &io, T&)`` and 656``T::value_type& element(IO &io, T&, size_t indx)``. For example: 657 658.. code-block:: c++ 659 660 template <> 661 struct SequenceTraits<MySeq> { 662 static size_t size(IO &io, MySeq &list) { ... } 663 static MySeqEl &element(IO &io, MySeq &list, size_t index) { ... } 664 }; 665 666The size() method returns how many elements are currently in your sequence. 667The element() method returns a reference to the i'th element in the sequence. 668When parsing YAML, the element() method may be called with an index one bigger 669than the current size. Your element() method should allocate space for one 670more element (using default constructor if element is a C++ object) and returns 671a reference to that new allocated space. 672 673 674Flow Sequence 675------------- 676A YAML "flow sequence" is a sequence that when written to YAML it uses the 677inline notation (e.g [ foo, bar ] ). To specify that a sequence type should 678be written in YAML as a flow sequence, your SequenceTraits specialization should 679add "static const bool flow = true;". For instance: 680 681.. code-block:: c++ 682 683 template <> 684 struct SequenceTraits<MyList> { 685 static size_t size(IO &io, MyList &list) { ... } 686 static MyListEl &element(IO &io, MyList &list, size_t index) { ... } 687 688 // The existence of this member causes YAML I/O to use a flow sequence 689 static const bool flow = true; 690 }; 691 692With the above, if you used MyList as the data type in your native data 693structures, then then when converted to YAML, a flow sequence of integers 694will be used (e.g. [ 10, -3, 4 ]). 695 696 697Utility Macros 698-------------- 699Since a common source of sequences is std::vector<>, YAML I/O provides macros: 700LLVM_YAML_IS_SEQUENCE_VECTOR() and LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR() which 701can be used to easily specify SequenceTraits<> on a std::vector type. YAML 702I/O does not partial specialize SequenceTraits on std::vector<> because that 703would force all vectors to be sequences. An example use of the macros: 704 705.. code-block:: c++ 706 707 std::vector<MyType1>; 708 std::vector<MyType2>; 709 LLVM_YAML_IS_SEQUENCE_VECTOR(MyType1) 710 LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(MyType2) 711 712 713 714Document List 715============= 716 717YAML allows you to define multiple "documents" in a single YAML file. Each 718new document starts with a left aligned "---" token. The end of all documents 719is denoted with a left aligned "..." token. Many users of YAML will never 720have need for multiple documents. The top level node in their YAML schema 721will be a mapping or sequence. For those cases, the following is not needed. 722But for cases where you do want multiple documents, you can specify a 723trait for you document list type. The trait has the same methods as 724SequenceTraits but is named DocumentListTraits. For example: 725 726.. code-block:: c++ 727 728 template <> 729 struct DocumentListTraits<MyDocList> { 730 static size_t size(IO &io, MyDocList &list) { ... } 731 static MyDocType element(IO &io, MyDocList &list, size_t index) { ... } 732 }; 733 734 735User Context Data 736================= 737When an llvm::yaml::Input or llvm::yaml::Output object is created their 738constructors take an optional "context" parameter. This is a pointer to 739whatever state information you might need. 740 741For instance, in a previous example we showed how the conversion type for a 742flags field could be determined at runtime based on the value of another field 743in the mapping. But what if an inner mapping needs to know some field value 744of an outer mapping? That is where the "context" parameter comes in. You 745can set values in the context in the outer map's mapping() method and 746retrieve those values in the inner map's mapping() method. 747 748The context value is just a void*. All your traits which use the context 749and operate on your native data types, need to agree what the context value 750actually is. It could be a pointer to an object or struct which your various 751traits use to shared context sensitive information. 752 753 754Output 755====== 756 757The llvm::yaml::Output class is used to generate a YAML document from your 758in-memory data structures, using traits defined on your data types. 759To instantiate an Output object you need an llvm::raw_ostream, and optionally 760a context pointer: 761 762.. code-block:: c++ 763 764 class Output : public IO { 765 public: 766 Output(llvm::raw_ostream &, void *context=NULL); 767 768Once you have an Output object, you can use the C++ stream operator on it 769to write your native data as YAML. One thing to recall is that a YAML file 770can contain multiple "documents". If the top level data structure you are 771streaming as YAML is a mapping, scalar, or sequence, then Output assumes you 772are generating one document and wraps the mapping output 773with "``---``" and trailing "``...``". 774 775.. code-block:: c++ 776 777 using llvm::yaml::Output; 778 779 void dumpMyMapDoc(const MyMapType &info) { 780 Output yout(llvm::outs()); 781 yout << info; 782 } 783 784The above could produce output like: 785 786.. code-block:: yaml 787 788 --- 789 name: Tom 790 hat-size: 7 791 ... 792 793On the other hand, if the top level data structure you are streaming as YAML 794has a DocumentListTraits specialization, then Output walks through each element 795of your DocumentList and generates a "---" before the start of each element 796and ends with a "...". 797 798.. code-block:: c++ 799 800 using llvm::yaml::Output; 801 802 void dumpMyMapDoc(const MyDocListType &docList) { 803 Output yout(llvm::outs()); 804 yout << docList; 805 } 806 807The above could produce output like: 808 809.. code-block:: yaml 810 811 --- 812 name: Tom 813 hat-size: 7 814 --- 815 name: Tom 816 shoe-size: 11 817 ... 818 819Input 820===== 821 822The llvm::yaml::Input class is used to parse YAML document(s) into your native 823data structures. To instantiate an Input 824object you need a StringRef to the entire YAML file, and optionally a context 825pointer: 826 827.. code-block:: c++ 828 829 class Input : public IO { 830 public: 831 Input(StringRef inputContent, void *context=NULL); 832 833Once you have an Input object, you can use the C++ stream operator to read 834the document(s). If you expect there might be multiple YAML documents in 835one file, you'll need to specialize DocumentListTraits on a list of your 836document type and stream in that document list type. Otherwise you can 837just stream in the document type. Also, you can check if there was 838any syntax errors in the YAML be calling the error() method on the Input 839object. For example: 840 841.. code-block:: c++ 842 843 // Reading a single document 844 using llvm::yaml::Input; 845 846 Input yin(mb.getBuffer()); 847 848 // Parse the YAML file 849 MyDocType theDoc; 850 yin >> theDoc; 851 852 // Check for error 853 if ( yin.error() ) 854 return; 855 856 857.. code-block:: c++ 858 859 // Reading multiple documents in one file 860 using llvm::yaml::Input; 861 862 LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(std::vector<MyDocType>) 863 864 Input yin(mb.getBuffer()); 865 866 // Parse the YAML file 867 std::vector<MyDocType> theDocList; 868 yin >> theDocList; 869 870 // Check for error 871 if ( yin.error() ) 872 return; 873 874 875