Lines Matching full:yaml
2 YAML I/O
8 Introduction to YAML
11 YAML is a human readable data serialization language. The full YAML language
12 spec can be read at `yaml.org
13 <http://www.yaml.org/spec/1.2/spec.html#Introduction>`_. The simplest form of
14 yaml is just "scalars", "mappings", and "sequences". A scalar is any number
18 .. code-block:: yaml
27 .. code-block:: yaml
37 .. code-block:: yaml
53 verbose, so YAML offers an alternate syntax for sequences called a "Flow
58 .. code-block:: yaml
69 Introduction to YAML I/O
72 The use of indenting makes the YAML easy for a human to read and understand,
73 but having a program read and write YAML involves a lot of tedious details.
74 The YAML I/O library structures and simplifies reading and writing YAML
77 YAML I/O assumes you have some "native" data structures which you want to be
78 able to dump as YAML and recreate from YAML. The first step is to try
79 writing example YAML for your data structures. You may find after looking at
80 possible YAML representations that a direct mapping of your data structures
81 to YAML is not very readable. Often the fields are not in the order that
83 locations, making it hard for a human to write such YAML correctly.
87 go into the design of your YAML encoding. But, you may not want to change
88 your existing native data structures. Therefore, when writing out YAML
89 there may be a normalization step, and when reading YAML there would be a
92 YAML I/O uses a non-invasive, traits based design. YAML I/O defines some
99 using llvm::yaml::ScalarEnumerationTraits;
100 using llvm::yaml::IO;
110 As with all YAML I/O template specializations, the ScalarEnumerationTraits is used for
111 both reading and writing YAML. That is, the mapping between in-memory enum
112 values and the YAML string representation is only in one place.
113 This assures that the code for writing and parsing of YAML stays in sync.
115 To specify a YAML mappings, you define a specialization on
116 llvm::yaml::MappingTraits.
122 using llvm::yaml::MappingTraits;
123 using llvm::yaml::IO;
134 A YAML sequence is automatically inferred if you data type has begin()/end()
136 (such as std::vector<>) will automatically translate to YAML sequences.
139 programmatically use YAML I/O to write a YAML document:
143 using llvm::yaml::Output;
160 .. code-block:: yaml
167 And you can also read such YAML documents with the following code:
171 using llvm::yaml::Input;
189 One other feature of YAML is the ability to define multiple documents in a
190 single file. That is why reading YAML produces a vector of your document type.
197 When parsing a YAML document, if the input does not match your schema (as
198 expressed in your XxxTraits<> specializations). YAML I/O
202 .. code-block:: yaml
209 Has a key (shoe-size) that is not defined in the schema. YAML I/O will
212 .. code-block:: yaml
214 YAML:2:2: error: unknown key 'shoe-size'
224 YAML scalars are just strings (i.e. not a sequence or mapping). The YAML I/O
225 library provides support for translating between YAML scalars and specific
231 The following types have built-in support in YAML I/O:
248 in sequence. When reading, YAML I/O will validate that the string found
254 Given that YAML I/O is trait based, the selection of how to convert your data
255 to YAML is based on the type of your data. But in C++ type matching, typedefs
257 unsigned int, to YAML I/O both types look exactly like unsigned int. To
258 facilitate make unique type names, YAML I/O provides a macro which is used
270 is that you can now specify traits on them to get different YAML conversions.
274 An example use of a unique type is that YAML I/O provides fixed sized unsigned
275 integers that are written with YAML I/O as hexadecimal instead of the decimal
283 You can use llvm::yaml::Hex32 instead of uint32_t and the only different will
284 be that when YAML I/O writes out that type it will be formatted in hexadecimal.
289 YAML I/O supports translating between in-memory enumerations and a set of string
290 values in YAML documents. This is done by specializing ScalarEnumerationTraits<>
314 using llvm::yaml::ScalarEnumerationTraits;
315 using llvm::yaml::MappingTraits;
316 using llvm::yaml::IO;
335 When reading YAML, if the string found does not match any of the strings
337 When writing YAML, if the value being written does not match any of the values
344 meaning. This is often used in a "flags" field. YAML I/O has support for
364 using llvm::yaml::ScalarBitSetTraits;
365 using llvm::yaml::MappingTraits;
366 using llvm::yaml::IO;
391 With the above, YAML I/O (when writing) will test mask each value in the
395 the above schema, a same valid YAML document is:
397 .. code-block:: yaml
434 YAML I/O (when writing) will apply the enumeration mask to the flags field,
443 some epoch), but in YAML it would be much nicer to express that integer in
444 some time format (e.g. 4-May-2012 10:30pm). YAML I/O has a way to support
446 your data type. When writing, YAML I/O will provide the native type and
448 YAML I/O will provide an llvm::StringRef of scalar and your specialization
454 using llvm::yaml::ScalarTraits;
455 using llvm::yaml::IO;
475 YAML block scalars are string literals that are represented in YAML using the
478 .. code-block:: yaml
484 The YAML I/O library provides support for translating between YAML block scalars
488 supported by YAML I/O and use the ordinary scalar notation by default.
491 ScalarTraits specialization - YAML I/O will provide the native type and your
500 using llvm::yaml::BlockScalarTraits;
501 using llvm::yaml::IO;
526 To be translated to or from a YAML mapping for your type T you must specialize
527 llvm::yaml::MappingTraits on T and implement the "void mapping(IO &io, T&)"
533 using llvm::yaml::MappingTraits;
534 using llvm::yaml::IO;
561 bind the struct's fields to YAML key names. For example:
565 using llvm::yaml::MappingTraits;
566 using llvm::yaml::IO;
596 but you've decided the normalized YAML for should be in x,y coordinates. That
597 is, you want the yaml to look like:
599 .. code-block:: yaml
605 coordinates to x,y coordinates when writing YAML and denormalizes x,y
606 coordinates into polar when reading YAML.
610 using llvm::yaml::MappingTraits;
611 using llvm::yaml::IO;
641 When writing YAML, the local variable "keys" will be a stack allocated
646 When reading YAML, the local variable "keys" will be a stack allocated instance
648 methods will find the matching key in the YAML document and fill in the x and y
659 when reading YAML. It never destroys the normalized object. The denormalize()
666 required to exist when parsing YAML documents, otherwise YAML I/O will issue an
670 exist in the YAML document being read. So what value is put in the field
677 it is the value that mapOptional() should set that field to if the YAML document
681 and third parameter to mapOptional). When YAML I/O generates a YAML document,
689 When writing out a YAML document, the keys are written in the order that the
692 the YAML document would find natural. This may be different that the order
695 When reading in a YAML document, the keys in the document can be in any order,
700 switch how the flags are converted to and from YAML based on the cpu.
705 using llvm::yaml::MappingTraits;
706 using llvm::yaml::IO;
717 // flags must come after cpu for this to work when reading yaml
729 The YAML syntax supports tags as a way to specify the type of a node before
730 it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses
731 static typing, so there are limits to how you can use tags with the YAML I/O
732 model. Recently, we added support to YAML I/O for checking/setting the optional
737 what the tag should be. This will also add that tag when writing yaml.
742 Sometimes in a yaml map, each key/value pair is valid, but the combination is
744 semantic errors. To support semantic level checking, YAML I/O allows
747 When parsing yaml, the ``validate()`` method is call *after* all key/values in
750 When writing yaml, the ``validate()`` method is called *before* the yaml
757 using llvm::yaml::MappingTraits;
758 using llvm::yaml::IO;
779 A YAML "flow mapping" is a mapping that uses the inline notation
780 (e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be
781 written in YAML using flow mapping, your MappingTraits specialization should
786 using llvm::yaml::MappingTraits;
787 using llvm::yaml::IO;
808 To be translated to or from a YAML sequence for your type T you must specialize
809 llvm::yaml::SequenceTraits on T and implement two methods:
823 When parsing YAML, the element() method may be called with an index one bigger
831 A YAML "flow sequence" is a sequence that when written to YAML it uses the
833 be written in YAML as a flow sequence, your SequenceTraits specialization should
843 // The existence of this member causes YAML I/O to use a flow sequence
848 structures, then when converted to YAML, a flow sequence of integers
856 Since a common source of sequences is std::vector<>, YAML I/O provides macros:
858 can be used to easily specify SequenceTraits<> on a std::vector type. YAML
874 YAML allows you to define multiple "documents" in a single YAML file. Each
876 is denoted with a left aligned "..." token. Many users of YAML will never
877 have need for multiple documents. The top level node in their YAML schema
894 When an llvm::yaml::Input or llvm::yaml::Output object is created their
914 The llvm::yaml::Output class is used to generate a YAML document from your
926 to write your native data as YAML. One thing to recall is that a YAML file
928 streaming as YAML is a mapping, scalar, or sequence, then Output assumes you
938 using llvm::yaml::Output;
947 .. code-block:: yaml
954 On the other hand, if the top level data structure you are streaming as YAML
961 using llvm::yaml::Output;
970 .. code-block:: yaml
983 The llvm::yaml::Input class is used to parse YAML document(s) into your native
985 object you need a StringRef to the entire YAML file, and optionally a context
995 the document(s). If you expect there might be multiple YAML documents in
999 any syntax errors in the YAML be calling the error() method on the Input
1005 using llvm::yaml::Input;
1009 // Parse the YAML file
1021 using llvm::yaml::Input;
1027 // Parse the YAML file