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;
589 bind the struct's fields to YAML key names. For example:
593 using llvm::yaml::MappingTraits;
594 using llvm::yaml::IO;
624 but you've decided the normalized YAML for should be in x,y coordinates. That
625 is, you want the yaml to look like:
627 .. code-block:: yaml
633 coordinates to x,y coordinates when writing YAML and denormalizes x,y
634 coordinates into polar when reading YAML.
638 using llvm::yaml::MappingTraits;
639 using llvm::yaml::IO;
669 When writing YAML, the local variable "keys" will be a stack allocated
674 When reading YAML, the local variable "keys" will be a stack allocated instance
676 methods will find the matching key in the YAML document and fill in the x and y
687 when reading YAML. It never destroys the normalized object. The denormalize()
694 required to exist when parsing YAML documents, otherwise YAML I/O will issue an
698 exist in the YAML document being read. So what value is put in the field
705 it is the value that mapOptional() should set that field to if the YAML document
709 and third parameter to mapOptional). When YAML I/O generates a YAML document,
717 When writing out a YAML document, the keys are written in the order that the
720 the YAML document would find natural. This may be different that the order
723 When reading in a YAML document, the keys in the document can be in any order,
728 switch how the flags are converted to and from YAML based on the cpu.
733 using llvm::yaml::MappingTraits;
734 using llvm::yaml::IO;
745 // flags must come after cpu for this to work when reading yaml
757 The YAML syntax supports tags as a way to specify the type of a node before
758 it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses
759 static typing, so there are limits to how you can use tags with the YAML I/O
760 model. Recently, we added support to YAML I/O for checking/setting the optional
765 what the tag should be. This will also add that tag when writing yaml.
770 Sometimes in a YAML map, each key/value pair is valid, but the combination is
772 semantic errors. To support semantic level checking, YAML I/O allows
775 When parsing YAML, the ``validate()`` method is call *after* all key/values in
778 When writing YAML, the ``validate()`` method is called *before* the YAML
785 using llvm::yaml::MappingTraits;
786 using llvm::yaml::IO;
807 A YAML "flow mapping" is a mapping that uses the inline notation
808 (e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be
809 written in YAML using flow mapping, your MappingTraits specialization should
814 using llvm::yaml::MappingTraits;
815 using llvm::yaml::IO;
836 To be translated to or from a YAML sequence for your type T you must specialize
837 llvm::yaml::SequenceTraits on T and implement two methods:
851 When parsing YAML, the element() method may be called with an index one bigger
859 A YAML "flow sequence" is a sequence that when written to YAML it uses the
861 be written in YAML as a flow sequence, your SequenceTraits specialization should
871 // The existence of this member causes YAML I/O to use a flow sequence
876 structures, then when converted to YAML, a flow sequence of integers
884 Since a common source of sequences is std::vector<>, YAML I/O provides macros:
886 can be used to easily specify SequenceTraits<> on a std::vector type. YAML
902 YAML allows you to define multiple "documents" in a single YAML file. Each
904 is denoted with a left aligned "..." token. Many users of YAML will never
905 have need for multiple documents. The top level node in their YAML schema
922 When an llvm::yaml::Input or llvm::yaml::Output object is created their
942 The llvm::yaml::Output class is used to generate a YAML document from your
954 to write your native data as YAML. One thing to recall is that a YAML file
956 streaming as YAML is a mapping, scalar, or sequence, then Output assumes you
966 using llvm::yaml::Output;
975 .. code-block:: yaml
982 On the other hand, if the top level data structure you are streaming as YAML
989 using llvm::yaml::Output;
998 .. code-block:: yaml
1011 The llvm::yaml::Input class is used to parse YAML document(s) into your native
1013 object you need a StringRef to the entire YAML file, and optionally a context
1023 the document(s). If you expect there might be multiple YAML documents in
1027 any syntax errors in the YAML be calling the error() method on the Input
1033 using llvm::yaml::Input;
1037 // Parse the YAML file
1049 using llvm::yaml::Input;
1055 // Parse the YAML file