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