xref: /aosp_15_r20/external/llvm/docs/YamlIO.rst (revision 9880d6810fe72a1726cb53787c6711e909410d58)
1*9880d681SAndroid Build Coastguard Worker=====================
2*9880d681SAndroid Build Coastguard WorkerYAML I/O
3*9880d681SAndroid Build Coastguard Worker=====================
4*9880d681SAndroid Build Coastguard Worker
5*9880d681SAndroid Build Coastguard Worker.. contents::
6*9880d681SAndroid Build Coastguard Worker   :local:
7*9880d681SAndroid Build Coastguard Worker
8*9880d681SAndroid Build Coastguard WorkerIntroduction to YAML
9*9880d681SAndroid Build Coastguard Worker====================
10*9880d681SAndroid Build Coastguard Worker
11*9880d681SAndroid Build Coastguard WorkerYAML is a human readable data serialization language.  The full YAML language
12*9880d681SAndroid Build Coastguard Workerspec can be read at `yaml.org
13*9880d681SAndroid Build Coastguard Worker<http://www.yaml.org/spec/1.2/spec.html#Introduction>`_.  The simplest form of
14*9880d681SAndroid Build Coastguard Workeryaml is just "scalars", "mappings", and "sequences".  A scalar is any number
15*9880d681SAndroid Build Coastguard Workeror string.  The pound/hash symbol (#) begins a comment line.   A mapping is
16*9880d681SAndroid Build Coastguard Workera set of key-value pairs where the key ends with a colon.  For example:
17*9880d681SAndroid Build Coastguard Worker
18*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
19*9880d681SAndroid Build Coastguard Worker
20*9880d681SAndroid Build Coastguard Worker     # a mapping
21*9880d681SAndroid Build Coastguard Worker     name:      Tom
22*9880d681SAndroid Build Coastguard Worker     hat-size:  7
23*9880d681SAndroid Build Coastguard Worker
24*9880d681SAndroid Build Coastguard WorkerA sequence is a list of items where each item starts with a leading dash ('-').
25*9880d681SAndroid Build Coastguard WorkerFor example:
26*9880d681SAndroid Build Coastguard Worker
27*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
28*9880d681SAndroid Build Coastguard Worker
29*9880d681SAndroid Build Coastguard Worker     # a sequence
30*9880d681SAndroid Build Coastguard Worker     - x86
31*9880d681SAndroid Build Coastguard Worker     - x86_64
32*9880d681SAndroid Build Coastguard Worker     - PowerPC
33*9880d681SAndroid Build Coastguard Worker
34*9880d681SAndroid Build Coastguard WorkerYou can combine mappings and sequences by indenting.  For example a sequence
35*9880d681SAndroid Build Coastguard Workerof mappings in which one of the mapping values is itself a sequence:
36*9880d681SAndroid Build Coastguard Worker
37*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
38*9880d681SAndroid Build Coastguard Worker
39*9880d681SAndroid Build Coastguard Worker     # a sequence of mappings with one key's value being a sequence
40*9880d681SAndroid Build Coastguard Worker     - name:      Tom
41*9880d681SAndroid Build Coastguard Worker       cpus:
42*9880d681SAndroid Build Coastguard Worker        - x86
43*9880d681SAndroid Build Coastguard Worker        - x86_64
44*9880d681SAndroid Build Coastguard Worker     - name:      Bob
45*9880d681SAndroid Build Coastguard Worker       cpus:
46*9880d681SAndroid Build Coastguard Worker        - x86
47*9880d681SAndroid Build Coastguard Worker     - name:      Dan
48*9880d681SAndroid Build Coastguard Worker       cpus:
49*9880d681SAndroid Build Coastguard Worker        - PowerPC
50*9880d681SAndroid Build Coastguard Worker        - x86
51*9880d681SAndroid Build Coastguard Worker
52*9880d681SAndroid Build Coastguard WorkerSometime sequences are known to be short and the one entry per line is too
53*9880d681SAndroid Build Coastguard Workerverbose, so YAML offers an alternate syntax for sequences called a "Flow
54*9880d681SAndroid Build Coastguard WorkerSequence" in which you put comma separated sequence elements into square
55*9880d681SAndroid Build Coastguard Workerbrackets.  The above example could then be simplified to :
56*9880d681SAndroid Build Coastguard Worker
57*9880d681SAndroid Build Coastguard Worker
58*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
59*9880d681SAndroid Build Coastguard Worker
60*9880d681SAndroid Build Coastguard Worker     # a sequence of mappings with one key's value being a flow sequence
61*9880d681SAndroid Build Coastguard Worker     - name:      Tom
62*9880d681SAndroid Build Coastguard Worker       cpus:      [ x86, x86_64 ]
63*9880d681SAndroid Build Coastguard Worker     - name:      Bob
64*9880d681SAndroid Build Coastguard Worker       cpus:      [ x86 ]
65*9880d681SAndroid Build Coastguard Worker     - name:      Dan
66*9880d681SAndroid Build Coastguard Worker       cpus:      [ PowerPC, x86 ]
67*9880d681SAndroid Build Coastguard Worker
68*9880d681SAndroid Build Coastguard Worker
69*9880d681SAndroid Build Coastguard WorkerIntroduction to YAML I/O
70*9880d681SAndroid Build Coastguard Worker========================
71*9880d681SAndroid Build Coastguard Worker
72*9880d681SAndroid Build Coastguard WorkerThe use of indenting makes the YAML easy for a human to read and understand,
73*9880d681SAndroid Build Coastguard Workerbut having a program read and write YAML involves a lot of tedious details.
74*9880d681SAndroid Build Coastguard WorkerThe YAML I/O library structures and simplifies reading and writing YAML
75*9880d681SAndroid Build Coastguard Workerdocuments.
76*9880d681SAndroid Build Coastguard Worker
77*9880d681SAndroid Build Coastguard WorkerYAML I/O assumes you have some "native" data structures which you want to be
78*9880d681SAndroid Build Coastguard Workerable to dump as YAML and recreate from YAML.  The first step is to try
79*9880d681SAndroid Build Coastguard Workerwriting example YAML for your data structures. You may find after looking at
80*9880d681SAndroid Build Coastguard Workerpossible YAML representations that a direct mapping of your data structures
81*9880d681SAndroid Build Coastguard Workerto YAML is not very readable.  Often the fields are not in the order that
82*9880d681SAndroid Build Coastguard Workera human would find readable.  Or the same information is replicated in multiple
83*9880d681SAndroid Build Coastguard Workerlocations, making it hard for a human to write such YAML correctly.
84*9880d681SAndroid Build Coastguard Worker
85*9880d681SAndroid Build Coastguard WorkerIn relational database theory there is a design step called normalization in
86*9880d681SAndroid Build Coastguard Workerwhich you reorganize fields and tables.  The same considerations need to
87*9880d681SAndroid Build Coastguard Workergo into the design of your YAML encoding.  But, you may not want to change
88*9880d681SAndroid Build Coastguard Workeryour existing native data structures.  Therefore, when writing out YAML
89*9880d681SAndroid Build Coastguard Workerthere may be a normalization step, and when reading YAML there would be a
90*9880d681SAndroid Build Coastguard Workercorresponding denormalization step.
91*9880d681SAndroid Build Coastguard Worker
92*9880d681SAndroid Build Coastguard WorkerYAML I/O uses a non-invasive, traits based design.  YAML I/O defines some
93*9880d681SAndroid Build Coastguard Workerabstract base templates.  You specialize those templates on your data types.
94*9880d681SAndroid Build Coastguard WorkerFor instance, if you have an enumerated type FooBar you could specialize
95*9880d681SAndroid Build Coastguard WorkerScalarEnumerationTraits on that type and define the enumeration() method:
96*9880d681SAndroid Build Coastguard Worker
97*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
98*9880d681SAndroid Build Coastguard Worker
99*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::ScalarEnumerationTraits;
100*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
101*9880d681SAndroid Build Coastguard Worker
102*9880d681SAndroid Build Coastguard Worker    template <>
103*9880d681SAndroid Build Coastguard Worker    struct ScalarEnumerationTraits<FooBar> {
104*9880d681SAndroid Build Coastguard Worker      static void enumeration(IO &io, FooBar &value) {
105*9880d681SAndroid Build Coastguard Worker      ...
106*9880d681SAndroid Build Coastguard Worker      }
107*9880d681SAndroid Build Coastguard Worker    };
108*9880d681SAndroid Build Coastguard Worker
109*9880d681SAndroid Build Coastguard Worker
110*9880d681SAndroid Build Coastguard WorkerAs with all YAML I/O template specializations, the ScalarEnumerationTraits is used for
111*9880d681SAndroid Build Coastguard Workerboth reading and writing YAML. That is, the mapping between in-memory enum
112*9880d681SAndroid Build Coastguard Workervalues and the YAML string representation is only in one place.
113*9880d681SAndroid Build Coastguard WorkerThis assures that the code for writing and parsing of YAML stays in sync.
114*9880d681SAndroid Build Coastguard Worker
115*9880d681SAndroid Build Coastguard WorkerTo specify a YAML mappings, you define a specialization on
116*9880d681SAndroid Build Coastguard Workerllvm::yaml::MappingTraits.
117*9880d681SAndroid Build Coastguard WorkerIf your native data structure happens to be a struct that is already normalized,
118*9880d681SAndroid Build Coastguard Workerthen the specialization is simple.  For example:
119*9880d681SAndroid Build Coastguard Worker
120*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
121*9880d681SAndroid Build Coastguard Worker
122*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
123*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
124*9880d681SAndroid Build Coastguard Worker
125*9880d681SAndroid Build Coastguard Worker    template <>
126*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Person> {
127*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Person &info) {
128*9880d681SAndroid Build Coastguard Worker        io.mapRequired("name",         info.name);
129*9880d681SAndroid Build Coastguard Worker        io.mapOptional("hat-size",     info.hatSize);
130*9880d681SAndroid Build Coastguard Worker      }
131*9880d681SAndroid Build Coastguard Worker    };
132*9880d681SAndroid Build Coastguard Worker
133*9880d681SAndroid Build Coastguard Worker
134*9880d681SAndroid Build Coastguard WorkerA YAML sequence is automatically inferred if you data type has begin()/end()
135*9880d681SAndroid Build Coastguard Workeriterators and a push_back() method.  Therefore any of the STL containers
136*9880d681SAndroid Build Coastguard Worker(such as std::vector<>) will automatically translate to YAML sequences.
137*9880d681SAndroid Build Coastguard Worker
138*9880d681SAndroid Build Coastguard WorkerOnce you have defined specializations for your data types, you can
139*9880d681SAndroid Build Coastguard Workerprogrammatically use YAML I/O to write a YAML document:
140*9880d681SAndroid Build Coastguard Worker
141*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
142*9880d681SAndroid Build Coastguard Worker
143*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::Output;
144*9880d681SAndroid Build Coastguard Worker
145*9880d681SAndroid Build Coastguard Worker    Person tom;
146*9880d681SAndroid Build Coastguard Worker    tom.name = "Tom";
147*9880d681SAndroid Build Coastguard Worker    tom.hatSize = 8;
148*9880d681SAndroid Build Coastguard Worker    Person dan;
149*9880d681SAndroid Build Coastguard Worker    dan.name = "Dan";
150*9880d681SAndroid Build Coastguard Worker    dan.hatSize = 7;
151*9880d681SAndroid Build Coastguard Worker    std::vector<Person> persons;
152*9880d681SAndroid Build Coastguard Worker    persons.push_back(tom);
153*9880d681SAndroid Build Coastguard Worker    persons.push_back(dan);
154*9880d681SAndroid Build Coastguard Worker
155*9880d681SAndroid Build Coastguard Worker    Output yout(llvm::outs());
156*9880d681SAndroid Build Coastguard Worker    yout << persons;
157*9880d681SAndroid Build Coastguard Worker
158*9880d681SAndroid Build Coastguard WorkerThis would write the following:
159*9880d681SAndroid Build Coastguard Worker
160*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
161*9880d681SAndroid Build Coastguard Worker
162*9880d681SAndroid Build Coastguard Worker     - name:      Tom
163*9880d681SAndroid Build Coastguard Worker       hat-size:  8
164*9880d681SAndroid Build Coastguard Worker     - name:      Dan
165*9880d681SAndroid Build Coastguard Worker       hat-size:  7
166*9880d681SAndroid Build Coastguard Worker
167*9880d681SAndroid Build Coastguard WorkerAnd you can also read such YAML documents with the following code:
168*9880d681SAndroid Build Coastguard Worker
169*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
170*9880d681SAndroid Build Coastguard Worker
171*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::Input;
172*9880d681SAndroid Build Coastguard Worker
173*9880d681SAndroid Build Coastguard Worker    typedef std::vector<Person> PersonList;
174*9880d681SAndroid Build Coastguard Worker    std::vector<PersonList> docs;
175*9880d681SAndroid Build Coastguard Worker
176*9880d681SAndroid Build Coastguard Worker    Input yin(document.getBuffer());
177*9880d681SAndroid Build Coastguard Worker    yin >> docs;
178*9880d681SAndroid Build Coastguard Worker
179*9880d681SAndroid Build Coastguard Worker    if ( yin.error() )
180*9880d681SAndroid Build Coastguard Worker      return;
181*9880d681SAndroid Build Coastguard Worker
182*9880d681SAndroid Build Coastguard Worker    // Process read document
183*9880d681SAndroid Build Coastguard Worker    for ( PersonList &pl : docs ) {
184*9880d681SAndroid Build Coastguard Worker      for ( Person &person : pl ) {
185*9880d681SAndroid Build Coastguard Worker        cout << "name=" << person.name;
186*9880d681SAndroid Build Coastguard Worker      }
187*9880d681SAndroid Build Coastguard Worker    }
188*9880d681SAndroid Build Coastguard Worker
189*9880d681SAndroid Build Coastguard WorkerOne other feature of YAML is the ability to define multiple documents in a
190*9880d681SAndroid Build Coastguard Workersingle file.  That is why reading YAML produces a vector of your document type.
191*9880d681SAndroid Build Coastguard Worker
192*9880d681SAndroid Build Coastguard Worker
193*9880d681SAndroid Build Coastguard Worker
194*9880d681SAndroid Build Coastguard WorkerError Handling
195*9880d681SAndroid Build Coastguard Worker==============
196*9880d681SAndroid Build Coastguard Worker
197*9880d681SAndroid Build Coastguard WorkerWhen parsing a YAML document, if the input does not match your schema (as
198*9880d681SAndroid Build Coastguard Workerexpressed in your XxxTraits<> specializations).  YAML I/O
199*9880d681SAndroid Build Coastguard Workerwill print out an error message and your Input object's error() method will
200*9880d681SAndroid Build Coastguard Workerreturn true. For instance the following document:
201*9880d681SAndroid Build Coastguard Worker
202*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
203*9880d681SAndroid Build Coastguard Worker
204*9880d681SAndroid Build Coastguard Worker     - name:      Tom
205*9880d681SAndroid Build Coastguard Worker       shoe-size: 12
206*9880d681SAndroid Build Coastguard Worker     - name:      Dan
207*9880d681SAndroid Build Coastguard Worker       hat-size:  7
208*9880d681SAndroid Build Coastguard Worker
209*9880d681SAndroid Build Coastguard WorkerHas a key (shoe-size) that is not defined in the schema.  YAML I/O will
210*9880d681SAndroid Build Coastguard Workerautomatically generate this error:
211*9880d681SAndroid Build Coastguard Worker
212*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
213*9880d681SAndroid Build Coastguard Worker
214*9880d681SAndroid Build Coastguard Worker    YAML:2:2: error: unknown key 'shoe-size'
215*9880d681SAndroid Build Coastguard Worker      shoe-size:       12
216*9880d681SAndroid Build Coastguard Worker      ^~~~~~~~~
217*9880d681SAndroid Build Coastguard Worker
218*9880d681SAndroid Build Coastguard WorkerSimilar errors are produced for other input not conforming to the schema.
219*9880d681SAndroid Build Coastguard Worker
220*9880d681SAndroid Build Coastguard Worker
221*9880d681SAndroid Build Coastguard WorkerScalars
222*9880d681SAndroid Build Coastguard Worker=======
223*9880d681SAndroid Build Coastguard Worker
224*9880d681SAndroid Build Coastguard WorkerYAML scalars are just strings (i.e. not a sequence or mapping).  The YAML I/O
225*9880d681SAndroid Build Coastguard Workerlibrary provides support for translating between YAML scalars and specific
226*9880d681SAndroid Build Coastguard WorkerC++ types.
227*9880d681SAndroid Build Coastguard Worker
228*9880d681SAndroid Build Coastguard Worker
229*9880d681SAndroid Build Coastguard WorkerBuilt-in types
230*9880d681SAndroid Build Coastguard Worker--------------
231*9880d681SAndroid Build Coastguard WorkerThe following types have built-in support in YAML I/O:
232*9880d681SAndroid Build Coastguard Worker
233*9880d681SAndroid Build Coastguard Worker* bool
234*9880d681SAndroid Build Coastguard Worker* float
235*9880d681SAndroid Build Coastguard Worker* double
236*9880d681SAndroid Build Coastguard Worker* StringRef
237*9880d681SAndroid Build Coastguard Worker* std::string
238*9880d681SAndroid Build Coastguard Worker* int64_t
239*9880d681SAndroid Build Coastguard Worker* int32_t
240*9880d681SAndroid Build Coastguard Worker* int16_t
241*9880d681SAndroid Build Coastguard Worker* int8_t
242*9880d681SAndroid Build Coastguard Worker* uint64_t
243*9880d681SAndroid Build Coastguard Worker* uint32_t
244*9880d681SAndroid Build Coastguard Worker* uint16_t
245*9880d681SAndroid Build Coastguard Worker* uint8_t
246*9880d681SAndroid Build Coastguard Worker
247*9880d681SAndroid Build Coastguard WorkerThat is, you can use those types in fields of MappingTraits or as element type
248*9880d681SAndroid Build Coastguard Workerin sequence.  When reading, YAML I/O will validate that the string found
249*9880d681SAndroid Build Coastguard Workeris convertible to that type and error out if not.
250*9880d681SAndroid Build Coastguard Worker
251*9880d681SAndroid Build Coastguard Worker
252*9880d681SAndroid Build Coastguard WorkerUnique types
253*9880d681SAndroid Build Coastguard Worker------------
254*9880d681SAndroid Build Coastguard WorkerGiven that YAML I/O is trait based, the selection of how to convert your data
255*9880d681SAndroid Build Coastguard Workerto YAML is based on the type of your data.  But in C++ type matching, typedefs
256*9880d681SAndroid Build Coastguard Workerdo not generate unique type names.  That means if you have two typedefs of
257*9880d681SAndroid Build Coastguard Workerunsigned int, to YAML I/O both types look exactly like unsigned int.  To
258*9880d681SAndroid Build Coastguard Workerfacilitate make unique type names, YAML I/O provides a macro which is used
259*9880d681SAndroid Build Coastguard Workerlike a typedef on built-in types, but expands to create a class with conversion
260*9880d681SAndroid Build Coastguard Workeroperators to and from the base type.  For example:
261*9880d681SAndroid Build Coastguard Worker
262*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
263*9880d681SAndroid Build Coastguard Worker
264*9880d681SAndroid Build Coastguard Worker    LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFooFlags)
265*9880d681SAndroid Build Coastguard Worker    LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyBarFlags)
266*9880d681SAndroid Build Coastguard Worker
267*9880d681SAndroid Build Coastguard WorkerThis generates two classes MyFooFlags and MyBarFlags which you can use in your
268*9880d681SAndroid Build Coastguard Workernative data structures instead of uint32_t. They are implicitly
269*9880d681SAndroid Build Coastguard Workerconverted to and from uint32_t.  The point of creating these unique types
270*9880d681SAndroid Build Coastguard Workeris that you can now specify traits on them to get different YAML conversions.
271*9880d681SAndroid Build Coastguard Worker
272*9880d681SAndroid Build Coastguard WorkerHex types
273*9880d681SAndroid Build Coastguard Worker---------
274*9880d681SAndroid Build Coastguard WorkerAn example use of a unique type is that YAML I/O provides fixed sized unsigned
275*9880d681SAndroid Build Coastguard Workerintegers that are written with YAML I/O as hexadecimal instead of the decimal
276*9880d681SAndroid Build Coastguard Workerformat used by the built-in integer types:
277*9880d681SAndroid Build Coastguard Worker
278*9880d681SAndroid Build Coastguard Worker* Hex64
279*9880d681SAndroid Build Coastguard Worker* Hex32
280*9880d681SAndroid Build Coastguard Worker* Hex16
281*9880d681SAndroid Build Coastguard Worker* Hex8
282*9880d681SAndroid Build Coastguard Worker
283*9880d681SAndroid Build Coastguard WorkerYou can use llvm::yaml::Hex32 instead of uint32_t and the only different will
284*9880d681SAndroid Build Coastguard Workerbe that when YAML I/O writes out that type it will be formatted in hexadecimal.
285*9880d681SAndroid Build Coastguard Worker
286*9880d681SAndroid Build Coastguard Worker
287*9880d681SAndroid Build Coastguard WorkerScalarEnumerationTraits
288*9880d681SAndroid Build Coastguard Worker-----------------------
289*9880d681SAndroid Build Coastguard WorkerYAML I/O supports translating between in-memory enumerations and a set of string
290*9880d681SAndroid Build Coastguard Workervalues in YAML documents. This is done by specializing ScalarEnumerationTraits<>
291*9880d681SAndroid Build Coastguard Workeron your enumeration type and define a enumeration() method.
292*9880d681SAndroid Build Coastguard WorkerFor instance, suppose you had an enumeration of CPUs and a struct with it as
293*9880d681SAndroid Build Coastguard Workera field:
294*9880d681SAndroid Build Coastguard Worker
295*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
296*9880d681SAndroid Build Coastguard Worker
297*9880d681SAndroid Build Coastguard Worker    enum CPUs {
298*9880d681SAndroid Build Coastguard Worker      cpu_x86_64  = 5,
299*9880d681SAndroid Build Coastguard Worker      cpu_x86     = 7,
300*9880d681SAndroid Build Coastguard Worker      cpu_PowerPC = 8
301*9880d681SAndroid Build Coastguard Worker    };
302*9880d681SAndroid Build Coastguard Worker
303*9880d681SAndroid Build Coastguard Worker    struct Info {
304*9880d681SAndroid Build Coastguard Worker      CPUs      cpu;
305*9880d681SAndroid Build Coastguard Worker      uint32_t  flags;
306*9880d681SAndroid Build Coastguard Worker    };
307*9880d681SAndroid Build Coastguard Worker
308*9880d681SAndroid Build Coastguard WorkerTo support reading and writing of this enumeration, you can define a
309*9880d681SAndroid Build Coastguard WorkerScalarEnumerationTraits specialization on CPUs, which can then be used
310*9880d681SAndroid Build Coastguard Workeras a field type:
311*9880d681SAndroid Build Coastguard Worker
312*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
313*9880d681SAndroid Build Coastguard Worker
314*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::ScalarEnumerationTraits;
315*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
316*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
317*9880d681SAndroid Build Coastguard Worker
318*9880d681SAndroid Build Coastguard Worker    template <>
319*9880d681SAndroid Build Coastguard Worker    struct ScalarEnumerationTraits<CPUs> {
320*9880d681SAndroid Build Coastguard Worker      static void enumeration(IO &io, CPUs &value) {
321*9880d681SAndroid Build Coastguard Worker        io.enumCase(value, "x86_64",  cpu_x86_64);
322*9880d681SAndroid Build Coastguard Worker        io.enumCase(value, "x86",     cpu_x86);
323*9880d681SAndroid Build Coastguard Worker        io.enumCase(value, "PowerPC", cpu_PowerPC);
324*9880d681SAndroid Build Coastguard Worker      }
325*9880d681SAndroid Build Coastguard Worker    };
326*9880d681SAndroid Build Coastguard Worker
327*9880d681SAndroid Build Coastguard Worker    template <>
328*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Info> {
329*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Info &info) {
330*9880d681SAndroid Build Coastguard Worker        io.mapRequired("cpu",       info.cpu);
331*9880d681SAndroid Build Coastguard Worker        io.mapOptional("flags",     info.flags, 0);
332*9880d681SAndroid Build Coastguard Worker      }
333*9880d681SAndroid Build Coastguard Worker    };
334*9880d681SAndroid Build Coastguard Worker
335*9880d681SAndroid Build Coastguard WorkerWhen reading YAML, if the string found does not match any of the strings
336*9880d681SAndroid Build Coastguard Workerspecified by enumCase() methods, an error is automatically generated.
337*9880d681SAndroid Build Coastguard WorkerWhen writing YAML, if the value being written does not match any of the values
338*9880d681SAndroid Build Coastguard Workerspecified by the enumCase() methods, a runtime assertion is triggered.
339*9880d681SAndroid Build Coastguard Worker
340*9880d681SAndroid Build Coastguard Worker
341*9880d681SAndroid Build Coastguard WorkerBitValue
342*9880d681SAndroid Build Coastguard Worker--------
343*9880d681SAndroid Build Coastguard WorkerAnother common data structure in C++ is a field where each bit has a unique
344*9880d681SAndroid Build Coastguard Workermeaning.  This is often used in a "flags" field.  YAML I/O has support for
345*9880d681SAndroid Build Coastguard Workerconverting such fields to a flow sequence.   For instance suppose you
346*9880d681SAndroid Build Coastguard Workerhad the following bit flags defined:
347*9880d681SAndroid Build Coastguard Worker
348*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
349*9880d681SAndroid Build Coastguard Worker
350*9880d681SAndroid Build Coastguard Worker    enum {
351*9880d681SAndroid Build Coastguard Worker      flagsPointy = 1
352*9880d681SAndroid Build Coastguard Worker      flagsHollow = 2
353*9880d681SAndroid Build Coastguard Worker      flagsFlat   = 4
354*9880d681SAndroid Build Coastguard Worker      flagsRound  = 8
355*9880d681SAndroid Build Coastguard Worker    };
356*9880d681SAndroid Build Coastguard Worker
357*9880d681SAndroid Build Coastguard Worker    LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFlags)
358*9880d681SAndroid Build Coastguard Worker
359*9880d681SAndroid Build Coastguard WorkerTo support reading and writing of MyFlags, you specialize ScalarBitSetTraits<>
360*9880d681SAndroid Build Coastguard Workeron MyFlags and provide the bit values and their names.
361*9880d681SAndroid Build Coastguard Worker
362*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
363*9880d681SAndroid Build Coastguard Worker
364*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::ScalarBitSetTraits;
365*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
366*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
367*9880d681SAndroid Build Coastguard Worker
368*9880d681SAndroid Build Coastguard Worker    template <>
369*9880d681SAndroid Build Coastguard Worker    struct ScalarBitSetTraits<MyFlags> {
370*9880d681SAndroid Build Coastguard Worker      static void bitset(IO &io, MyFlags &value) {
371*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "hollow",  flagHollow);
372*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "flat",    flagFlat);
373*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "round",   flagRound);
374*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "pointy",  flagPointy);
375*9880d681SAndroid Build Coastguard Worker      }
376*9880d681SAndroid Build Coastguard Worker    };
377*9880d681SAndroid Build Coastguard Worker
378*9880d681SAndroid Build Coastguard Worker    struct Info {
379*9880d681SAndroid Build Coastguard Worker      StringRef   name;
380*9880d681SAndroid Build Coastguard Worker      MyFlags     flags;
381*9880d681SAndroid Build Coastguard Worker    };
382*9880d681SAndroid Build Coastguard Worker
383*9880d681SAndroid Build Coastguard Worker    template <>
384*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Info> {
385*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Info& info) {
386*9880d681SAndroid Build Coastguard Worker        io.mapRequired("name",  info.name);
387*9880d681SAndroid Build Coastguard Worker        io.mapRequired("flags", info.flags);
388*9880d681SAndroid Build Coastguard Worker       }
389*9880d681SAndroid Build Coastguard Worker    };
390*9880d681SAndroid Build Coastguard Worker
391*9880d681SAndroid Build Coastguard WorkerWith the above, YAML I/O (when writing) will test mask each value in the
392*9880d681SAndroid Build Coastguard Workerbitset trait against the flags field, and each that matches will
393*9880d681SAndroid Build Coastguard Workercause the corresponding string to be added to the flow sequence.  The opposite
394*9880d681SAndroid Build Coastguard Workeris done when reading and any unknown string values will result in a error. With
395*9880d681SAndroid Build Coastguard Workerthe above schema, a same valid YAML document is:
396*9880d681SAndroid Build Coastguard Worker
397*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
398*9880d681SAndroid Build Coastguard Worker
399*9880d681SAndroid Build Coastguard Worker    name:    Tom
400*9880d681SAndroid Build Coastguard Worker    flags:   [ pointy, flat ]
401*9880d681SAndroid Build Coastguard Worker
402*9880d681SAndroid Build Coastguard WorkerSometimes a "flags" field might contains an enumeration part
403*9880d681SAndroid Build Coastguard Workerdefined by a bit-mask.
404*9880d681SAndroid Build Coastguard Worker
405*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
406*9880d681SAndroid Build Coastguard Worker
407*9880d681SAndroid Build Coastguard Worker    enum {
408*9880d681SAndroid Build Coastguard Worker      flagsFeatureA = 1,
409*9880d681SAndroid Build Coastguard Worker      flagsFeatureB = 2,
410*9880d681SAndroid Build Coastguard Worker      flagsFeatureC = 4,
411*9880d681SAndroid Build Coastguard Worker
412*9880d681SAndroid Build Coastguard Worker      flagsCPUMask = 24,
413*9880d681SAndroid Build Coastguard Worker
414*9880d681SAndroid Build Coastguard Worker      flagsCPU1 = 8,
415*9880d681SAndroid Build Coastguard Worker      flagsCPU2 = 16
416*9880d681SAndroid Build Coastguard Worker    };
417*9880d681SAndroid Build Coastguard Worker
418*9880d681SAndroid Build Coastguard WorkerTo support reading and writing such fields, you need to use the maskedBitSet()
419*9880d681SAndroid Build Coastguard Workermethod and provide the bit values, their names and the enumeration mask.
420*9880d681SAndroid Build Coastguard Worker
421*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
422*9880d681SAndroid Build Coastguard Worker
423*9880d681SAndroid Build Coastguard Worker    template <>
424*9880d681SAndroid Build Coastguard Worker    struct ScalarBitSetTraits<MyFlags> {
425*9880d681SAndroid Build Coastguard Worker      static void bitset(IO &io, MyFlags &value) {
426*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "featureA",  flagsFeatureA);
427*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "featureB",  flagsFeatureB);
428*9880d681SAndroid Build Coastguard Worker        io.bitSetCase(value, "featureC",  flagsFeatureC);
429*9880d681SAndroid Build Coastguard Worker        io.maskedBitSetCase(value, "CPU1",  flagsCPU1, flagsCPUMask);
430*9880d681SAndroid Build Coastguard Worker        io.maskedBitSetCase(value, "CPU2",  flagsCPU2, flagsCPUMask);
431*9880d681SAndroid Build Coastguard Worker      }
432*9880d681SAndroid Build Coastguard Worker    };
433*9880d681SAndroid Build Coastguard Worker
434*9880d681SAndroid Build Coastguard WorkerYAML I/O (when writing) will apply the enumeration mask to the flags field,
435*9880d681SAndroid Build Coastguard Workerand compare the result and values from the bitset. As in case of a regular
436*9880d681SAndroid Build Coastguard Workerbitset, each that matches will cause the corresponding string to be added
437*9880d681SAndroid Build Coastguard Workerto the flow sequence.
438*9880d681SAndroid Build Coastguard Worker
439*9880d681SAndroid Build Coastguard WorkerCustom Scalar
440*9880d681SAndroid Build Coastguard Worker-------------
441*9880d681SAndroid Build Coastguard WorkerSometimes for readability a scalar needs to be formatted in a custom way. For
442*9880d681SAndroid Build Coastguard Workerinstance your internal data structure may use a integer for time (seconds since
443*9880d681SAndroid Build Coastguard Workersome epoch), but in YAML it would be much nicer to express that integer in
444*9880d681SAndroid Build Coastguard Workersome time format (e.g. 4-May-2012 10:30pm).  YAML I/O has a way to support
445*9880d681SAndroid Build Coastguard Workercustom formatting and parsing of scalar types by specializing ScalarTraits<> on
446*9880d681SAndroid Build Coastguard Workeryour data type.  When writing, YAML I/O will provide the native type and
447*9880d681SAndroid Build Coastguard Workeryour specialization must create a temporary llvm::StringRef.  When reading,
448*9880d681SAndroid Build Coastguard WorkerYAML I/O will provide an llvm::StringRef of scalar and your specialization
449*9880d681SAndroid Build Coastguard Workermust convert that to your native data type.  An outline of a custom scalar type
450*9880d681SAndroid Build Coastguard Workerlooks like:
451*9880d681SAndroid Build Coastguard Worker
452*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
453*9880d681SAndroid Build Coastguard Worker
454*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::ScalarTraits;
455*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
456*9880d681SAndroid Build Coastguard Worker
457*9880d681SAndroid Build Coastguard Worker    template <>
458*9880d681SAndroid Build Coastguard Worker    struct ScalarTraits<MyCustomType> {
459*9880d681SAndroid Build Coastguard Worker      static void output(const MyCustomType &value, void*,
460*9880d681SAndroid Build Coastguard Worker                         llvm::raw_ostream &out) {
461*9880d681SAndroid Build Coastguard Worker        out << value;  // do custom formatting here
462*9880d681SAndroid Build Coastguard Worker      }
463*9880d681SAndroid Build Coastguard Worker      static StringRef input(StringRef scalar, void*, MyCustomType &value) {
464*9880d681SAndroid Build Coastguard Worker        // do custom parsing here.  Return the empty string on success,
465*9880d681SAndroid Build Coastguard Worker        // or an error message on failure.
466*9880d681SAndroid Build Coastguard Worker        return StringRef();
467*9880d681SAndroid Build Coastguard Worker      }
468*9880d681SAndroid Build Coastguard Worker      // Determine if this scalar needs quotes.
469*9880d681SAndroid Build Coastguard Worker      static bool mustQuote(StringRef) { return true; }
470*9880d681SAndroid Build Coastguard Worker    };
471*9880d681SAndroid Build Coastguard Worker
472*9880d681SAndroid Build Coastguard WorkerBlock Scalars
473*9880d681SAndroid Build Coastguard Worker-------------
474*9880d681SAndroid Build Coastguard Worker
475*9880d681SAndroid Build Coastguard WorkerYAML block scalars are string literals that are represented in YAML using the
476*9880d681SAndroid Build Coastguard Workerliteral block notation, just like the example shown below:
477*9880d681SAndroid Build Coastguard Worker
478*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
479*9880d681SAndroid Build Coastguard Worker
480*9880d681SAndroid Build Coastguard Worker    text: |
481*9880d681SAndroid Build Coastguard Worker      First line
482*9880d681SAndroid Build Coastguard Worker      Second line
483*9880d681SAndroid Build Coastguard Worker
484*9880d681SAndroid Build Coastguard WorkerThe YAML I/O library provides support for translating between YAML block scalars
485*9880d681SAndroid Build Coastguard Workerand specific C++ types by allowing you to specialize BlockScalarTraits<> on
486*9880d681SAndroid Build Coastguard Workeryour data type. The library doesn't provide any built-in support for block
487*9880d681SAndroid Build Coastguard Workerscalar I/O for types like std::string and llvm::StringRef as they are already
488*9880d681SAndroid Build Coastguard Workersupported by YAML I/O and use the ordinary scalar notation by default.
489*9880d681SAndroid Build Coastguard Worker
490*9880d681SAndroid Build Coastguard WorkerBlockScalarTraits specializations are very similar to the
491*9880d681SAndroid Build Coastguard WorkerScalarTraits specialization - YAML I/O will provide the native type and your
492*9880d681SAndroid Build Coastguard Workerspecialization must create a temporary llvm::StringRef when writing, and
493*9880d681SAndroid Build Coastguard Workerit will also provide an llvm::StringRef that has the value of that block scalar
494*9880d681SAndroid Build Coastguard Workerand your specialization must convert that to your native data type when reading.
495*9880d681SAndroid Build Coastguard WorkerAn example of a custom type with an appropriate specialization of
496*9880d681SAndroid Build Coastguard WorkerBlockScalarTraits is shown below:
497*9880d681SAndroid Build Coastguard Worker
498*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
499*9880d681SAndroid Build Coastguard Worker
500*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::BlockScalarTraits;
501*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
502*9880d681SAndroid Build Coastguard Worker
503*9880d681SAndroid Build Coastguard Worker    struct MyStringType {
504*9880d681SAndroid Build Coastguard Worker      std::string Str;
505*9880d681SAndroid Build Coastguard Worker    };
506*9880d681SAndroid Build Coastguard Worker
507*9880d681SAndroid Build Coastguard Worker    template <>
508*9880d681SAndroid Build Coastguard Worker    struct BlockScalarTraits<MyStringType> {
509*9880d681SAndroid Build Coastguard Worker      static void output(const MyStringType &Value, void *Ctxt,
510*9880d681SAndroid Build Coastguard Worker                         llvm::raw_ostream &OS) {
511*9880d681SAndroid Build Coastguard Worker        OS << Value.Str;
512*9880d681SAndroid Build Coastguard Worker      }
513*9880d681SAndroid Build Coastguard Worker
514*9880d681SAndroid Build Coastguard Worker      static StringRef input(StringRef Scalar, void *Ctxt,
515*9880d681SAndroid Build Coastguard Worker                             MyStringType &Value) {
516*9880d681SAndroid Build Coastguard Worker        Value.Str = Scalar.str();
517*9880d681SAndroid Build Coastguard Worker        return StringRef();
518*9880d681SAndroid Build Coastguard Worker      }
519*9880d681SAndroid Build Coastguard Worker    };
520*9880d681SAndroid Build Coastguard Worker
521*9880d681SAndroid Build Coastguard Worker
522*9880d681SAndroid Build Coastguard Worker
523*9880d681SAndroid Build Coastguard WorkerMappings
524*9880d681SAndroid Build Coastguard Worker========
525*9880d681SAndroid Build Coastguard Worker
526*9880d681SAndroid Build Coastguard WorkerTo be translated to or from a YAML mapping for your type T you must specialize
527*9880d681SAndroid Build Coastguard Workerllvm::yaml::MappingTraits on T and implement the "void mapping(IO &io, T&)"
528*9880d681SAndroid Build Coastguard Workermethod. If your native data structures use pointers to a class everywhere,
529*9880d681SAndroid Build Coastguard Workeryou can specialize on the class pointer.  Examples:
530*9880d681SAndroid Build Coastguard Worker
531*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
532*9880d681SAndroid Build Coastguard Worker
533*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
534*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
535*9880d681SAndroid Build Coastguard Worker
536*9880d681SAndroid Build Coastguard Worker    // Example of struct Foo which is used by value
537*9880d681SAndroid Build Coastguard Worker    template <>
538*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Foo> {
539*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Foo &foo) {
540*9880d681SAndroid Build Coastguard Worker        io.mapOptional("size",      foo.size);
541*9880d681SAndroid Build Coastguard Worker      ...
542*9880d681SAndroid Build Coastguard Worker      }
543*9880d681SAndroid Build Coastguard Worker    };
544*9880d681SAndroid Build Coastguard Worker
545*9880d681SAndroid Build Coastguard Worker    // Example of struct Bar which is natively always a pointer
546*9880d681SAndroid Build Coastguard Worker    template <>
547*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Bar*> {
548*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Bar *&bar) {
549*9880d681SAndroid Build Coastguard Worker        io.mapOptional("size",    bar->size);
550*9880d681SAndroid Build Coastguard Worker      ...
551*9880d681SAndroid Build Coastguard Worker      }
552*9880d681SAndroid Build Coastguard Worker    };
553*9880d681SAndroid Build Coastguard Worker
554*9880d681SAndroid Build Coastguard Worker
555*9880d681SAndroid Build Coastguard WorkerNo Normalization
556*9880d681SAndroid Build Coastguard Worker----------------
557*9880d681SAndroid Build Coastguard Worker
558*9880d681SAndroid Build Coastguard WorkerThe mapping() method is responsible, if needed, for normalizing and
559*9880d681SAndroid Build Coastguard Workerdenormalizing. In a simple case where the native data structure requires no
560*9880d681SAndroid Build Coastguard Workernormalization, the mapping method just uses mapOptional() or mapRequired() to
561*9880d681SAndroid Build Coastguard Workerbind the struct's fields to YAML key names.  For example:
562*9880d681SAndroid Build Coastguard Worker
563*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
564*9880d681SAndroid Build Coastguard Worker
565*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
566*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
567*9880d681SAndroid Build Coastguard Worker
568*9880d681SAndroid Build Coastguard Worker    template <>
569*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Person> {
570*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Person &info) {
571*9880d681SAndroid Build Coastguard Worker        io.mapRequired("name",         info.name);
572*9880d681SAndroid Build Coastguard Worker        io.mapOptional("hat-size",     info.hatSize);
573*9880d681SAndroid Build Coastguard Worker      }
574*9880d681SAndroid Build Coastguard Worker    };
575*9880d681SAndroid Build Coastguard Worker
576*9880d681SAndroid Build Coastguard Worker
577*9880d681SAndroid Build Coastguard WorkerNormalization
578*9880d681SAndroid Build Coastguard Worker----------------
579*9880d681SAndroid Build Coastguard Worker
580*9880d681SAndroid Build Coastguard WorkerWhen [de]normalization is required, the mapping() method needs a way to access
581*9880d681SAndroid Build Coastguard Workernormalized values as fields. To help with this, there is
582*9880d681SAndroid Build Coastguard Workera template MappingNormalization<> which you can then use to automatically
583*9880d681SAndroid Build Coastguard Workerdo the normalization and denormalization.  The template is used to create
584*9880d681SAndroid Build Coastguard Workera local variable in your mapping() method which contains the normalized keys.
585*9880d681SAndroid Build Coastguard Worker
586*9880d681SAndroid Build Coastguard WorkerSuppose you have native data type
587*9880d681SAndroid Build Coastguard WorkerPolar which specifies a position in polar coordinates (distance, angle):
588*9880d681SAndroid Build Coastguard Worker
589*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
590*9880d681SAndroid Build Coastguard Worker
591*9880d681SAndroid Build Coastguard Worker    struct Polar {
592*9880d681SAndroid Build Coastguard Worker      float distance;
593*9880d681SAndroid Build Coastguard Worker      float angle;
594*9880d681SAndroid Build Coastguard Worker    };
595*9880d681SAndroid Build Coastguard Worker
596*9880d681SAndroid Build Coastguard Workerbut you've decided the normalized YAML for should be in x,y coordinates. That
597*9880d681SAndroid Build Coastguard Workeris, you want the yaml to look like:
598*9880d681SAndroid Build Coastguard Worker
599*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
600*9880d681SAndroid Build Coastguard Worker
601*9880d681SAndroid Build Coastguard Worker    x:   10.3
602*9880d681SAndroid Build Coastguard Worker    y:   -4.7
603*9880d681SAndroid Build Coastguard Worker
604*9880d681SAndroid Build Coastguard WorkerYou can support this by defining a MappingTraits that normalizes the polar
605*9880d681SAndroid Build Coastguard Workercoordinates to x,y coordinates when writing YAML and denormalizes x,y
606*9880d681SAndroid Build Coastguard Workercoordinates into polar when reading YAML.
607*9880d681SAndroid Build Coastguard Worker
608*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
609*9880d681SAndroid Build Coastguard Worker
610*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
611*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
612*9880d681SAndroid Build Coastguard Worker
613*9880d681SAndroid Build Coastguard Worker    template <>
614*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Polar> {
615*9880d681SAndroid Build Coastguard Worker
616*9880d681SAndroid Build Coastguard Worker      class NormalizedPolar {
617*9880d681SAndroid Build Coastguard Worker      public:
618*9880d681SAndroid Build Coastguard Worker        NormalizedPolar(IO &io)
619*9880d681SAndroid Build Coastguard Worker          : x(0.0), y(0.0) {
620*9880d681SAndroid Build Coastguard Worker        }
621*9880d681SAndroid Build Coastguard Worker        NormalizedPolar(IO &, Polar &polar)
622*9880d681SAndroid Build Coastguard Worker          : x(polar.distance * cos(polar.angle)),
623*9880d681SAndroid Build Coastguard Worker            y(polar.distance * sin(polar.angle)) {
624*9880d681SAndroid Build Coastguard Worker        }
625*9880d681SAndroid Build Coastguard Worker        Polar denormalize(IO &) {
626*9880d681SAndroid Build Coastguard Worker          return Polar(sqrt(x*x+y*y), arctan(x,y));
627*9880d681SAndroid Build Coastguard Worker        }
628*9880d681SAndroid Build Coastguard Worker
629*9880d681SAndroid Build Coastguard Worker        float        x;
630*9880d681SAndroid Build Coastguard Worker        float        y;
631*9880d681SAndroid Build Coastguard Worker      };
632*9880d681SAndroid Build Coastguard Worker
633*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Polar &polar) {
634*9880d681SAndroid Build Coastguard Worker        MappingNormalization<NormalizedPolar, Polar> keys(io, polar);
635*9880d681SAndroid Build Coastguard Worker
636*9880d681SAndroid Build Coastguard Worker        io.mapRequired("x",    keys->x);
637*9880d681SAndroid Build Coastguard Worker        io.mapRequired("y",    keys->y);
638*9880d681SAndroid Build Coastguard Worker      }
639*9880d681SAndroid Build Coastguard Worker    };
640*9880d681SAndroid Build Coastguard Worker
641*9880d681SAndroid Build Coastguard WorkerWhen writing YAML, the local variable "keys" will be a stack allocated
642*9880d681SAndroid Build Coastguard Workerinstance of NormalizedPolar, constructed from the supplied polar object which
643*9880d681SAndroid Build Coastguard Workerinitializes it x and y fields.  The mapRequired() methods then write out the x
644*9880d681SAndroid Build Coastguard Workerand y values as key/value pairs.
645*9880d681SAndroid Build Coastguard Worker
646*9880d681SAndroid Build Coastguard WorkerWhen reading YAML, the local variable "keys" will be a stack allocated instance
647*9880d681SAndroid Build Coastguard Workerof NormalizedPolar, constructed by the empty constructor.  The mapRequired
648*9880d681SAndroid Build Coastguard Workermethods will find the matching key in the YAML document and fill in the x and y
649*9880d681SAndroid Build Coastguard Workerfields of the NormalizedPolar object keys. At the end of the mapping() method
650*9880d681SAndroid Build Coastguard Workerwhen the local keys variable goes out of scope, the denormalize() method will
651*9880d681SAndroid Build Coastguard Workerautomatically be called to convert the read values back to polar coordinates,
652*9880d681SAndroid Build Coastguard Workerand then assigned back to the second parameter to mapping().
653*9880d681SAndroid Build Coastguard Worker
654*9880d681SAndroid Build Coastguard WorkerIn some cases, the normalized class may be a subclass of the native type and
655*9880d681SAndroid Build Coastguard Workercould be returned by the denormalize() method, except that the temporary
656*9880d681SAndroid Build Coastguard Workernormalized instance is stack allocated.  In these cases, the utility template
657*9880d681SAndroid Build Coastguard WorkerMappingNormalizationHeap<> can be used instead.  It just like
658*9880d681SAndroid Build Coastguard WorkerMappingNormalization<> except that it heap allocates the normalized object
659*9880d681SAndroid Build Coastguard Workerwhen reading YAML.  It never destroys the normalized object.  The denormalize()
660*9880d681SAndroid Build Coastguard Workermethod can this return "this".
661*9880d681SAndroid Build Coastguard Worker
662*9880d681SAndroid Build Coastguard Worker
663*9880d681SAndroid Build Coastguard WorkerDefault values
664*9880d681SAndroid Build Coastguard Worker--------------
665*9880d681SAndroid Build Coastguard WorkerWithin a mapping() method, calls to io.mapRequired() mean that that key is
666*9880d681SAndroid Build Coastguard Workerrequired to exist when parsing YAML documents, otherwise YAML I/O will issue an
667*9880d681SAndroid Build Coastguard Workererror.
668*9880d681SAndroid Build Coastguard Worker
669*9880d681SAndroid Build Coastguard WorkerOn the other hand, keys registered with io.mapOptional() are allowed to not
670*9880d681SAndroid Build Coastguard Workerexist in the YAML document being read.  So what value is put in the field
671*9880d681SAndroid Build Coastguard Workerfor those optional keys?
672*9880d681SAndroid Build Coastguard WorkerThere are two steps to how those optional fields are filled in. First, the
673*9880d681SAndroid Build Coastguard Workersecond parameter to the mapping() method is a reference to a native class.  That
674*9880d681SAndroid Build Coastguard Workernative class must have a default constructor.  Whatever value the default
675*9880d681SAndroid Build Coastguard Workerconstructor initially sets for an optional field will be that field's value.
676*9880d681SAndroid Build Coastguard WorkerSecond, the mapOptional() method has an optional third parameter.  If provided
677*9880d681SAndroid Build Coastguard Workerit is the value that mapOptional() should set that field to if the YAML document
678*9880d681SAndroid Build Coastguard Workerdoes not have that key.
679*9880d681SAndroid Build Coastguard Worker
680*9880d681SAndroid Build Coastguard WorkerThere is one important difference between those two ways (default constructor
681*9880d681SAndroid Build Coastguard Workerand third parameter to mapOptional). When YAML I/O generates a YAML document,
682*9880d681SAndroid Build Coastguard Workerif the mapOptional() third parameter is used, if the actual value being written
683*9880d681SAndroid Build Coastguard Workeris the same as (using ==) the default value, then that key/value is not written.
684*9880d681SAndroid Build Coastguard Worker
685*9880d681SAndroid Build Coastguard Worker
686*9880d681SAndroid Build Coastguard WorkerOrder of Keys
687*9880d681SAndroid Build Coastguard Worker--------------
688*9880d681SAndroid Build Coastguard Worker
689*9880d681SAndroid Build Coastguard WorkerWhen writing out a YAML document, the keys are written in the order that the
690*9880d681SAndroid Build Coastguard Workercalls to mapRequired()/mapOptional() are made in the mapping() method. This
691*9880d681SAndroid Build Coastguard Workergives you a chance to write the fields in an order that a human reader of
692*9880d681SAndroid Build Coastguard Workerthe YAML document would find natural.  This may be different that the order
693*9880d681SAndroid Build Coastguard Workerof the fields in the native class.
694*9880d681SAndroid Build Coastguard Worker
695*9880d681SAndroid Build Coastguard WorkerWhen reading in a YAML document, the keys in the document can be in any order,
696*9880d681SAndroid Build Coastguard Workerbut they are processed in the order that the calls to mapRequired()/mapOptional()
697*9880d681SAndroid Build Coastguard Workerare made in the mapping() method.  That enables some interesting
698*9880d681SAndroid Build Coastguard Workerfunctionality.  For instance, if the first field bound is the cpu and the second
699*9880d681SAndroid Build Coastguard Workerfield bound is flags, and the flags are cpu specific, you can programmatically
700*9880d681SAndroid Build Coastguard Workerswitch how the flags are converted to and from YAML based on the cpu.
701*9880d681SAndroid Build Coastguard WorkerThis works for both reading and writing. For example:
702*9880d681SAndroid Build Coastguard Worker
703*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
704*9880d681SAndroid Build Coastguard Worker
705*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
706*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
707*9880d681SAndroid Build Coastguard Worker
708*9880d681SAndroid Build Coastguard Worker    struct Info {
709*9880d681SAndroid Build Coastguard Worker      CPUs        cpu;
710*9880d681SAndroid Build Coastguard Worker      uint32_t    flags;
711*9880d681SAndroid Build Coastguard Worker    };
712*9880d681SAndroid Build Coastguard Worker
713*9880d681SAndroid Build Coastguard Worker    template <>
714*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Info> {
715*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Info &info) {
716*9880d681SAndroid Build Coastguard Worker        io.mapRequired("cpu",       info.cpu);
717*9880d681SAndroid Build Coastguard Worker        // flags must come after cpu for this to work when reading yaml
718*9880d681SAndroid Build Coastguard Worker        if ( info.cpu == cpu_x86_64 )
719*9880d681SAndroid Build Coastguard Worker          io.mapRequired("flags",  *(My86_64Flags*)info.flags);
720*9880d681SAndroid Build Coastguard Worker        else
721*9880d681SAndroid Build Coastguard Worker          io.mapRequired("flags",  *(My86Flags*)info.flags);
722*9880d681SAndroid Build Coastguard Worker     }
723*9880d681SAndroid Build Coastguard Worker    };
724*9880d681SAndroid Build Coastguard Worker
725*9880d681SAndroid Build Coastguard Worker
726*9880d681SAndroid Build Coastguard WorkerTags
727*9880d681SAndroid Build Coastguard Worker----
728*9880d681SAndroid Build Coastguard Worker
729*9880d681SAndroid Build Coastguard WorkerThe YAML syntax supports tags as a way to specify the type of a node before
730*9880d681SAndroid Build Coastguard Workerit is parsed. This allows dynamic types of nodes.  But the YAML I/O model uses
731*9880d681SAndroid Build Coastguard Workerstatic typing, so there are limits to how you can use tags with the YAML I/O
732*9880d681SAndroid Build Coastguard Workermodel. Recently, we added support to YAML I/O for checking/setting the optional
733*9880d681SAndroid Build Coastguard Workertag on a map. Using this functionality it is even possbile to support different
734*9880d681SAndroid Build Coastguard Workermappings, as long as they are convertable.
735*9880d681SAndroid Build Coastguard Worker
736*9880d681SAndroid Build Coastguard WorkerTo check a tag, inside your mapping() method you can use io.mapTag() to specify
737*9880d681SAndroid Build Coastguard Workerwhat the tag should be.  This will also add that tag when writing yaml.
738*9880d681SAndroid Build Coastguard Worker
739*9880d681SAndroid Build Coastguard WorkerValidation
740*9880d681SAndroid Build Coastguard Worker----------
741*9880d681SAndroid Build Coastguard Worker
742*9880d681SAndroid Build Coastguard WorkerSometimes in a yaml map, each key/value pair is valid, but the combination is
743*9880d681SAndroid Build Coastguard Workernot.  This is similar to something having no syntax errors, but still having
744*9880d681SAndroid Build Coastguard Workersemantic errors.  To support semantic level checking, YAML I/O allows
745*9880d681SAndroid Build Coastguard Workeran optional ``validate()`` method in a MappingTraits template specialization.
746*9880d681SAndroid Build Coastguard Worker
747*9880d681SAndroid Build Coastguard WorkerWhen parsing yaml, the ``validate()`` method is call *after* all key/values in
748*9880d681SAndroid Build Coastguard Workerthe map have been processed. Any error message returned by the ``validate()``
749*9880d681SAndroid Build Coastguard Workermethod during input will be printed just a like a syntax error would be printed.
750*9880d681SAndroid Build Coastguard WorkerWhen writing yaml, the ``validate()`` method is called *before* the yaml
751*9880d681SAndroid Build Coastguard Workerkey/values  are written.  Any error during output will trigger an ``assert()``
752*9880d681SAndroid Build Coastguard Workerbecause it is a programming error to have invalid struct values.
753*9880d681SAndroid Build Coastguard Worker
754*9880d681SAndroid Build Coastguard Worker
755*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
756*9880d681SAndroid Build Coastguard Worker
757*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
758*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
759*9880d681SAndroid Build Coastguard Worker
760*9880d681SAndroid Build Coastguard Worker    struct Stuff {
761*9880d681SAndroid Build Coastguard Worker      ...
762*9880d681SAndroid Build Coastguard Worker    };
763*9880d681SAndroid Build Coastguard Worker
764*9880d681SAndroid Build Coastguard Worker    template <>
765*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Stuff> {
766*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Stuff &stuff) {
767*9880d681SAndroid Build Coastguard Worker      ...
768*9880d681SAndroid Build Coastguard Worker      }
769*9880d681SAndroid Build Coastguard Worker      static StringRef validate(IO &io, Stuff &stuff) {
770*9880d681SAndroid Build Coastguard Worker        // Look at all fields in 'stuff' and if there
771*9880d681SAndroid Build Coastguard Worker        // are any bad values return a string describing
772*9880d681SAndroid Build Coastguard Worker        // the error.  Otherwise return an empty string.
773*9880d681SAndroid Build Coastguard Worker        return StringRef();
774*9880d681SAndroid Build Coastguard Worker      }
775*9880d681SAndroid Build Coastguard Worker    };
776*9880d681SAndroid Build Coastguard Worker
777*9880d681SAndroid Build Coastguard WorkerFlow Mapping
778*9880d681SAndroid Build Coastguard Worker------------
779*9880d681SAndroid Build Coastguard WorkerA YAML "flow mapping" is a mapping that uses the inline notation
780*9880d681SAndroid Build Coastguard Worker(e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be
781*9880d681SAndroid Build Coastguard Workerwritten in YAML using flow mapping, your MappingTraits specialization should
782*9880d681SAndroid Build Coastguard Workeradd "static const bool flow = true;". For instance:
783*9880d681SAndroid Build Coastguard Worker
784*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
785*9880d681SAndroid Build Coastguard Worker
786*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::MappingTraits;
787*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::IO;
788*9880d681SAndroid Build Coastguard Worker
789*9880d681SAndroid Build Coastguard Worker    struct Stuff {
790*9880d681SAndroid Build Coastguard Worker      ...
791*9880d681SAndroid Build Coastguard Worker    };
792*9880d681SAndroid Build Coastguard Worker
793*9880d681SAndroid Build Coastguard Worker    template <>
794*9880d681SAndroid Build Coastguard Worker    struct MappingTraits<Stuff> {
795*9880d681SAndroid Build Coastguard Worker      static void mapping(IO &io, Stuff &stuff) {
796*9880d681SAndroid Build Coastguard Worker        ...
797*9880d681SAndroid Build Coastguard Worker      }
798*9880d681SAndroid Build Coastguard Worker
799*9880d681SAndroid Build Coastguard Worker      static const bool flow = true;
800*9880d681SAndroid Build Coastguard Worker    }
801*9880d681SAndroid Build Coastguard Worker
802*9880d681SAndroid Build Coastguard WorkerFlow mappings are subject to line wrapping according to the Output object
803*9880d681SAndroid Build Coastguard Workerconfiguration.
804*9880d681SAndroid Build Coastguard Worker
805*9880d681SAndroid Build Coastguard WorkerSequence
806*9880d681SAndroid Build Coastguard Worker========
807*9880d681SAndroid Build Coastguard Worker
808*9880d681SAndroid Build Coastguard WorkerTo be translated to or from a YAML sequence for your type T you must specialize
809*9880d681SAndroid Build Coastguard Workerllvm::yaml::SequenceTraits on T and implement two methods:
810*9880d681SAndroid Build Coastguard Worker``size_t size(IO &io, T&)`` and
811*9880d681SAndroid Build Coastguard Worker``T::value_type& element(IO &io, T&, size_t indx)``.  For example:
812*9880d681SAndroid Build Coastguard Worker
813*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
814*9880d681SAndroid Build Coastguard Worker
815*9880d681SAndroid Build Coastguard Worker  template <>
816*9880d681SAndroid Build Coastguard Worker  struct SequenceTraits<MySeq> {
817*9880d681SAndroid Build Coastguard Worker    static size_t size(IO &io, MySeq &list) { ... }
818*9880d681SAndroid Build Coastguard Worker    static MySeqEl &element(IO &io, MySeq &list, size_t index) { ... }
819*9880d681SAndroid Build Coastguard Worker  };
820*9880d681SAndroid Build Coastguard Worker
821*9880d681SAndroid Build Coastguard WorkerThe size() method returns how many elements are currently in your sequence.
822*9880d681SAndroid Build Coastguard WorkerThe element() method returns a reference to the i'th element in the sequence.
823*9880d681SAndroid Build Coastguard WorkerWhen parsing YAML, the element() method may be called with an index one bigger
824*9880d681SAndroid Build Coastguard Workerthan the current size.  Your element() method should allocate space for one
825*9880d681SAndroid Build Coastguard Workermore element (using default constructor if element is a C++ object) and returns
826*9880d681SAndroid Build Coastguard Workera reference to that new allocated space.
827*9880d681SAndroid Build Coastguard Worker
828*9880d681SAndroid Build Coastguard Worker
829*9880d681SAndroid Build Coastguard WorkerFlow Sequence
830*9880d681SAndroid Build Coastguard Worker-------------
831*9880d681SAndroid Build Coastguard WorkerA YAML "flow sequence" is a sequence that when written to YAML it uses the
832*9880d681SAndroid Build Coastguard Workerinline notation (e.g [ foo, bar ] ).  To specify that a sequence type should
833*9880d681SAndroid Build Coastguard Workerbe written in YAML as a flow sequence, your SequenceTraits specialization should
834*9880d681SAndroid Build Coastguard Workeradd "static const bool flow = true;".  For instance:
835*9880d681SAndroid Build Coastguard Worker
836*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
837*9880d681SAndroid Build Coastguard Worker
838*9880d681SAndroid Build Coastguard Worker  template <>
839*9880d681SAndroid Build Coastguard Worker  struct SequenceTraits<MyList> {
840*9880d681SAndroid Build Coastguard Worker    static size_t size(IO &io, MyList &list) { ... }
841*9880d681SAndroid Build Coastguard Worker    static MyListEl &element(IO &io, MyList &list, size_t index) { ... }
842*9880d681SAndroid Build Coastguard Worker
843*9880d681SAndroid Build Coastguard Worker    // The existence of this member causes YAML I/O to use a flow sequence
844*9880d681SAndroid Build Coastguard Worker    static const bool flow = true;
845*9880d681SAndroid Build Coastguard Worker  };
846*9880d681SAndroid Build Coastguard Worker
847*9880d681SAndroid Build Coastguard WorkerWith the above, if you used MyList as the data type in your native data
848*9880d681SAndroid Build Coastguard Workerstructures, then when converted to YAML, a flow sequence of integers
849*9880d681SAndroid Build Coastguard Workerwill be used (e.g. [ 10, -3, 4 ]).
850*9880d681SAndroid Build Coastguard Worker
851*9880d681SAndroid Build Coastguard WorkerFlow sequences are subject to line wrapping according to the Output object
852*9880d681SAndroid Build Coastguard Workerconfiguration.
853*9880d681SAndroid Build Coastguard Worker
854*9880d681SAndroid Build Coastguard WorkerUtility Macros
855*9880d681SAndroid Build Coastguard Worker--------------
856*9880d681SAndroid Build Coastguard WorkerSince a common source of sequences is std::vector<>, YAML I/O provides macros:
857*9880d681SAndroid Build Coastguard WorkerLLVM_YAML_IS_SEQUENCE_VECTOR() and LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR() which
858*9880d681SAndroid Build Coastguard Workercan be used to easily specify SequenceTraits<> on a std::vector type.  YAML
859*9880d681SAndroid Build Coastguard WorkerI/O does not partial specialize SequenceTraits on std::vector<> because that
860*9880d681SAndroid Build Coastguard Workerwould force all vectors to be sequences.  An example use of the macros:
861*9880d681SAndroid Build Coastguard Worker
862*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
863*9880d681SAndroid Build Coastguard Worker
864*9880d681SAndroid Build Coastguard Worker  std::vector<MyType1>;
865*9880d681SAndroid Build Coastguard Worker  std::vector<MyType2>;
866*9880d681SAndroid Build Coastguard Worker  LLVM_YAML_IS_SEQUENCE_VECTOR(MyType1)
867*9880d681SAndroid Build Coastguard Worker  LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(MyType2)
868*9880d681SAndroid Build Coastguard Worker
869*9880d681SAndroid Build Coastguard Worker
870*9880d681SAndroid Build Coastguard Worker
871*9880d681SAndroid Build Coastguard WorkerDocument List
872*9880d681SAndroid Build Coastguard Worker=============
873*9880d681SAndroid Build Coastguard Worker
874*9880d681SAndroid Build Coastguard WorkerYAML allows you to define multiple "documents" in a single YAML file.  Each
875*9880d681SAndroid Build Coastguard Workernew document starts with a left aligned "---" token.  The end of all documents
876*9880d681SAndroid Build Coastguard Workeris denoted with a left aligned "..." token.  Many users of YAML will never
877*9880d681SAndroid Build Coastguard Workerhave need for multiple documents.  The top level node in their YAML schema
878*9880d681SAndroid Build Coastguard Workerwill be a mapping or sequence. For those cases, the following is not needed.
879*9880d681SAndroid Build Coastguard WorkerBut for cases where you do want multiple documents, you can specify a
880*9880d681SAndroid Build Coastguard Workertrait for you document list type.  The trait has the same methods as
881*9880d681SAndroid Build Coastguard WorkerSequenceTraits but is named DocumentListTraits.  For example:
882*9880d681SAndroid Build Coastguard Worker
883*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
884*9880d681SAndroid Build Coastguard Worker
885*9880d681SAndroid Build Coastguard Worker  template <>
886*9880d681SAndroid Build Coastguard Worker  struct DocumentListTraits<MyDocList> {
887*9880d681SAndroid Build Coastguard Worker    static size_t size(IO &io, MyDocList &list) { ... }
888*9880d681SAndroid Build Coastguard Worker    static MyDocType element(IO &io, MyDocList &list, size_t index) { ... }
889*9880d681SAndroid Build Coastguard Worker  };
890*9880d681SAndroid Build Coastguard Worker
891*9880d681SAndroid Build Coastguard Worker
892*9880d681SAndroid Build Coastguard WorkerUser Context Data
893*9880d681SAndroid Build Coastguard Worker=================
894*9880d681SAndroid Build Coastguard WorkerWhen an llvm::yaml::Input or llvm::yaml::Output object is created their
895*9880d681SAndroid Build Coastguard Workerconstructors take an optional "context" parameter.  This is a pointer to
896*9880d681SAndroid Build Coastguard Workerwhatever state information you might need.
897*9880d681SAndroid Build Coastguard Worker
898*9880d681SAndroid Build Coastguard WorkerFor instance, in a previous example we showed how the conversion type for a
899*9880d681SAndroid Build Coastguard Workerflags field could be determined at runtime based on the value of another field
900*9880d681SAndroid Build Coastguard Workerin the mapping. But what if an inner mapping needs to know some field value
901*9880d681SAndroid Build Coastguard Workerof an outer mapping?  That is where the "context" parameter comes in. You
902*9880d681SAndroid Build Coastguard Workercan set values in the context in the outer map's mapping() method and
903*9880d681SAndroid Build Coastguard Workerretrieve those values in the inner map's mapping() method.
904*9880d681SAndroid Build Coastguard Worker
905*9880d681SAndroid Build Coastguard WorkerThe context value is just a void*.  All your traits which use the context
906*9880d681SAndroid Build Coastguard Workerand operate on your native data types, need to agree what the context value
907*9880d681SAndroid Build Coastguard Workeractually is.  It could be a pointer to an object or struct which your various
908*9880d681SAndroid Build Coastguard Workertraits use to shared context sensitive information.
909*9880d681SAndroid Build Coastguard Worker
910*9880d681SAndroid Build Coastguard Worker
911*9880d681SAndroid Build Coastguard WorkerOutput
912*9880d681SAndroid Build Coastguard Worker======
913*9880d681SAndroid Build Coastguard Worker
914*9880d681SAndroid Build Coastguard WorkerThe llvm::yaml::Output class is used to generate a YAML document from your
915*9880d681SAndroid Build Coastguard Workerin-memory data structures, using traits defined on your data types.
916*9880d681SAndroid Build Coastguard WorkerTo instantiate an Output object you need an llvm::raw_ostream, an optional
917*9880d681SAndroid Build Coastguard Workercontext pointer and an optional wrapping column:
918*9880d681SAndroid Build Coastguard Worker
919*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
920*9880d681SAndroid Build Coastguard Worker
921*9880d681SAndroid Build Coastguard Worker      class Output : public IO {
922*9880d681SAndroid Build Coastguard Worker      public:
923*9880d681SAndroid Build Coastguard Worker        Output(llvm::raw_ostream &, void *context = NULL, int WrapColumn = 70);
924*9880d681SAndroid Build Coastguard Worker
925*9880d681SAndroid Build Coastguard WorkerOnce you have an Output object, you can use the C++ stream operator on it
926*9880d681SAndroid Build Coastguard Workerto write your native data as YAML. One thing to recall is that a YAML file
927*9880d681SAndroid Build Coastguard Workercan contain multiple "documents".  If the top level data structure you are
928*9880d681SAndroid Build Coastguard Workerstreaming as YAML is a mapping, scalar, or sequence, then Output assumes you
929*9880d681SAndroid Build Coastguard Workerare generating one document and wraps the mapping output
930*9880d681SAndroid Build Coastguard Workerwith  "``---``" and trailing "``...``".
931*9880d681SAndroid Build Coastguard Worker
932*9880d681SAndroid Build Coastguard WorkerThe WrapColumn parameter will cause the flow mappings and sequences to
933*9880d681SAndroid Build Coastguard Workerline-wrap when they go over the supplied column. Pass 0 to completely
934*9880d681SAndroid Build Coastguard Workersuppress the wrapping.
935*9880d681SAndroid Build Coastguard Worker
936*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
937*9880d681SAndroid Build Coastguard Worker
938*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::Output;
939*9880d681SAndroid Build Coastguard Worker
940*9880d681SAndroid Build Coastguard Worker    void dumpMyMapDoc(const MyMapType &info) {
941*9880d681SAndroid Build Coastguard Worker      Output yout(llvm::outs());
942*9880d681SAndroid Build Coastguard Worker      yout << info;
943*9880d681SAndroid Build Coastguard Worker    }
944*9880d681SAndroid Build Coastguard Worker
945*9880d681SAndroid Build Coastguard WorkerThe above could produce output like:
946*9880d681SAndroid Build Coastguard Worker
947*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
948*9880d681SAndroid Build Coastguard Worker
949*9880d681SAndroid Build Coastguard Worker     ---
950*9880d681SAndroid Build Coastguard Worker     name:      Tom
951*9880d681SAndroid Build Coastguard Worker     hat-size:  7
952*9880d681SAndroid Build Coastguard Worker     ...
953*9880d681SAndroid Build Coastguard Worker
954*9880d681SAndroid Build Coastguard WorkerOn the other hand, if the top level data structure you are streaming as YAML
955*9880d681SAndroid Build Coastguard Workerhas a DocumentListTraits specialization, then Output walks through each element
956*9880d681SAndroid Build Coastguard Workerof your DocumentList and generates a "---" before the start of each element
957*9880d681SAndroid Build Coastguard Workerand ends with a "...".
958*9880d681SAndroid Build Coastguard Worker
959*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
960*9880d681SAndroid Build Coastguard Worker
961*9880d681SAndroid Build Coastguard Worker    using llvm::yaml::Output;
962*9880d681SAndroid Build Coastguard Worker
963*9880d681SAndroid Build Coastguard Worker    void dumpMyMapDoc(const MyDocListType &docList) {
964*9880d681SAndroid Build Coastguard Worker      Output yout(llvm::outs());
965*9880d681SAndroid Build Coastguard Worker      yout << docList;
966*9880d681SAndroid Build Coastguard Worker    }
967*9880d681SAndroid Build Coastguard Worker
968*9880d681SAndroid Build Coastguard WorkerThe above could produce output like:
969*9880d681SAndroid Build Coastguard Worker
970*9880d681SAndroid Build Coastguard Worker.. code-block:: yaml
971*9880d681SAndroid Build Coastguard Worker
972*9880d681SAndroid Build Coastguard Worker     ---
973*9880d681SAndroid Build Coastguard Worker     name:      Tom
974*9880d681SAndroid Build Coastguard Worker     hat-size:  7
975*9880d681SAndroid Build Coastguard Worker     ---
976*9880d681SAndroid Build Coastguard Worker     name:      Tom
977*9880d681SAndroid Build Coastguard Worker     shoe-size:  11
978*9880d681SAndroid Build Coastguard Worker     ...
979*9880d681SAndroid Build Coastguard Worker
980*9880d681SAndroid Build Coastguard WorkerInput
981*9880d681SAndroid Build Coastguard Worker=====
982*9880d681SAndroid Build Coastguard Worker
983*9880d681SAndroid Build Coastguard WorkerThe llvm::yaml::Input class is used to parse YAML document(s) into your native
984*9880d681SAndroid Build Coastguard Workerdata structures. To instantiate an Input
985*9880d681SAndroid Build Coastguard Workerobject you need a StringRef to the entire YAML file, and optionally a context
986*9880d681SAndroid Build Coastguard Workerpointer:
987*9880d681SAndroid Build Coastguard Worker
988*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
989*9880d681SAndroid Build Coastguard Worker
990*9880d681SAndroid Build Coastguard Worker      class Input : public IO {
991*9880d681SAndroid Build Coastguard Worker      public:
992*9880d681SAndroid Build Coastguard Worker        Input(StringRef inputContent, void *context=NULL);
993*9880d681SAndroid Build Coastguard Worker
994*9880d681SAndroid Build Coastguard WorkerOnce you have an Input object, you can use the C++ stream operator to read
995*9880d681SAndroid Build Coastguard Workerthe document(s).  If you expect there might be multiple YAML documents in
996*9880d681SAndroid Build Coastguard Workerone file, you'll need to specialize DocumentListTraits on a list of your
997*9880d681SAndroid Build Coastguard Workerdocument type and stream in that document list type.  Otherwise you can
998*9880d681SAndroid Build Coastguard Workerjust stream in the document type.  Also, you can check if there was
999*9880d681SAndroid Build Coastguard Workerany syntax errors in the YAML be calling the error() method on the Input
1000*9880d681SAndroid Build Coastguard Workerobject.  For example:
1001*9880d681SAndroid Build Coastguard Worker
1002*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
1003*9880d681SAndroid Build Coastguard Worker
1004*9880d681SAndroid Build Coastguard Worker     // Reading a single document
1005*9880d681SAndroid Build Coastguard Worker     using llvm::yaml::Input;
1006*9880d681SAndroid Build Coastguard Worker
1007*9880d681SAndroid Build Coastguard Worker     Input yin(mb.getBuffer());
1008*9880d681SAndroid Build Coastguard Worker
1009*9880d681SAndroid Build Coastguard Worker     // Parse the YAML file
1010*9880d681SAndroid Build Coastguard Worker     MyDocType theDoc;
1011*9880d681SAndroid Build Coastguard Worker     yin >> theDoc;
1012*9880d681SAndroid Build Coastguard Worker
1013*9880d681SAndroid Build Coastguard Worker     // Check for error
1014*9880d681SAndroid Build Coastguard Worker     if ( yin.error() )
1015*9880d681SAndroid Build Coastguard Worker       return;
1016*9880d681SAndroid Build Coastguard Worker
1017*9880d681SAndroid Build Coastguard Worker
1018*9880d681SAndroid Build Coastguard Worker.. code-block:: c++
1019*9880d681SAndroid Build Coastguard Worker
1020*9880d681SAndroid Build Coastguard Worker     // Reading multiple documents in one file
1021*9880d681SAndroid Build Coastguard Worker     using llvm::yaml::Input;
1022*9880d681SAndroid Build Coastguard Worker
1023*9880d681SAndroid Build Coastguard Worker     LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(std::vector<MyDocType>)
1024*9880d681SAndroid Build Coastguard Worker
1025*9880d681SAndroid Build Coastguard Worker     Input yin(mb.getBuffer());
1026*9880d681SAndroid Build Coastguard Worker
1027*9880d681SAndroid Build Coastguard Worker     // Parse the YAML file
1028*9880d681SAndroid Build Coastguard Worker     std::vector<MyDocType> theDocList;
1029*9880d681SAndroid Build Coastguard Worker     yin >> theDocList;
1030*9880d681SAndroid Build Coastguard Worker
1031*9880d681SAndroid Build Coastguard Worker     // Check for error
1032*9880d681SAndroid Build Coastguard Worker     if ( yin.error() )
1033*9880d681SAndroid Build Coastguard Worker       return;
1034*9880d681SAndroid Build Coastguard Worker
1035*9880d681SAndroid Build Coastguard Worker
1036