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