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;
474 YAML block scalars are string literals that are represented in YAML using the
477 .. code-block:: yaml
483 The YAML I/O library provides support for translating between YAML block scalars
487 supported by YAML I/O and use the ordinary scalar notation by default.
490 ScalarTraits specialization - YAML I/O will provide the native type and your
499 using llvm::yaml::BlockScalarTraits;
500 using llvm::yaml::IO;
525 To be translated to or from a YAML mapping for your type T you must specialize
526 llvm::yaml::MappingTraits on T and implement the "void mapping(IO &io, T&)"
532 using llvm::yaml::MappingTraits;
533 using llvm::yaml::IO;
560 bind the struct's fields to YAML key names. For example:
564 using llvm::yaml::MappingTraits;
565 using llvm::yaml::IO;
595 but you've decided the normalized YAML for should be in x,y coordinates. That
596 is, you want the yaml to look like:
598 .. code-block:: yaml
604 coordinates to x,y coordinates when writing YAML and denormalizes x,y
605 coordinates into polar when reading YAML.
609 using llvm::yaml::MappingTraits;
610 using llvm::yaml::IO;
640 When writing YAML, the local variable "keys" will be a stack allocated
645 When reading YAML, the local variable "keys" will be a stack allocated instance
647 methods will find the matching key in the YAML document and fill in the x and y
658 when reading YAML. It never destroys the normalized object. The denormalize()
665 required to exist when parsing YAML documents, otherwise YAML I/O will issue an
669 exist in the YAML document being read. So what value is put in the field
676 it is the value that mapOptional() should set that field to if the YAML document
680 and third parameter to mapOptional). When YAML I/O generates a YAML document,
688 When writing out a YAML document, the keys are written in the order that the
691 the YAML document would find natural. This may be different that the order
694 When reading in a YAML document, the keys in the document can be in any order,
699 switch how the flags are converted to and from YAML based on the cpu.
704 using llvm::yaml::MappingTraits;
705 using llvm::yaml::IO;
716 // flags must come after cpu for this to work when reading yaml
728 The YAML syntax supports tags as a way to specify the type of a node before
729 it is parsed. This allows dynamic types of nodes. But the YAML I/O model uses
730 static typing, so there are limits to how you can use tags with the YAML I/O
731 model. Recently, we added support to YAML I/O for checking/setting the optional
736 what the tag should be. This will also add that tag when writing yaml.
741 Sometimes in a yaml map, each key/value pair is valid, but the combination is
743 semantic errors. To support semantic level checking, YAML I/O allows
746 When parsing yaml, the ``validate()`` method is call *after* all key/values in
749 When writing yaml, the ``validate()`` method is called *before* the yaml
756 using llvm::yaml::MappingTraits;
757 using llvm::yaml::IO;
778 A YAML "flow mapping" is a mapping that uses the inline notation
779 (e.g { x: 1, y: 0 } ) when written to YAML. To specify that a type should be
780 written in YAML using flow mapping, your MappingTraits specialization should
785 using llvm::yaml::MappingTraits;
786 using llvm::yaml::IO;
807 To be translated to or from a YAML sequence for your type T you must specialize
808 llvm::yaml::SequenceTraits on T and implement two methods:
822 When parsing YAML, the element() method may be called with an index one bigger
830 A YAML "flow sequence" is a sequence that when written to YAML it uses the
832 be written in YAML as a flow sequence, your SequenceTraits specialization should
842 // The existence of this member causes YAML I/O to use a flow sequence
847 structures, then when converted to YAML, a flow sequence of integers
855 Since a common source of sequences is std::vector<>, YAML I/O provides macros:
857 can be used to easily specify SequenceTraits<> on a std::vector type. YAML
873 YAML allows you to define multiple "documents" in a single YAML file. Each
875 is denoted with a left aligned "..." token. Many users of YAML will never
876 have need for multiple documents. The top level node in their YAML schema
893 When an llvm::yaml::Input or llvm::yaml::Output object is created their
913 The llvm::yaml::Output class is used to generate a YAML document from your
925 to write your native data as YAML. One thing to recall is that a YAML file
927 streaming as YAML is a mapping, scalar, or sequence, then Output assumes you
937 using llvm::yaml::Output;
946 .. code-block:: yaml
953 On the other hand, if the top level data structure you are streaming as YAML
960 using llvm::yaml::Output;
969 .. code-block:: yaml
982 The llvm::yaml::Input class is used to parse YAML document(s) into your native
984 object you need a StringRef to the entire YAML file, and optionally a context
994 the document(s). If you expect there might be multiple YAML documents in
998 any syntax errors in the YAML be calling the error() method on the Input
1004 using llvm::yaml::Input;
1008 // Parse the YAML file
1020 using llvm::yaml::Input;
1026 // Parse the YAML file