diff options
| -rw-r--r-- | docs/YamlIO.rst | 862 | ||||
| -rw-r--r-- | docs/userguides.rst | 5 | ||||
| -rw-r--r-- | include/llvm/Support/YAMLTraits.h | 1114 | ||||
| -rw-r--r-- | lib/Support/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | lib/Support/YAMLTraits.cpp | 881 | ||||
| -rw-r--r-- | unittests/Support/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | unittests/Support/YAMLIOTest.cpp | 1288 |
7 files changed, 4152 insertions, 0 deletions
diff --git a/docs/YamlIO.rst b/docs/YamlIO.rst new file mode 100644 index 0000000000..b009b67ef4 --- /dev/null +++ b/docs/YamlIO.rst @@ -0,0 +1,862 @@ +.. _yamlio: + +===================== +YAML I/O +===================== + +.. contents:: + :local: + +Introduction to YAML +==================== + +YAML is a human readable data serialization language. The full YAML language +spec can be read at `yaml.org +<http://www.yaml.org/spec/1.2/spec.html#Introduction>`_. The simplest form of +yaml is just "scalars", "mappings", and "sequences". A scalar is any number +or string. The pound/hash symbol (#) begins a comment line. A mapping is +a set of key-value pairs where the key ends with a colon. For example: + +.. code-block:: yaml + + # a mapping + name: Tom + hat-size: 7 + +A sequence is a list of items where each item starts with a leading dash ('-'). +For example: + +.. code-block:: yaml + + # a sequence + - x86 + - x86_64 + - PowerPC + +You can combine mappings and sequences by indenting. For example a sequence +of mappings in which one of the mapping values is itself a sequence: + +.. code-block:: yaml + + # a sequence of mappings with one key's value being a sequence + - name: Tom + cpus: + - x86 + - x86_64 + - name: Bob + cpus: + - x86 + - name: Dan + cpus: + - PowerPC + - x86 + +Sometime sequences are known to be short and the one entry per line is too +verbose, so YAML offers an alternate syntax for sequences called a "Flow +Sequence" in which you put comma separated sequence elements into square +brackets. The above example could then be simplified to : + + +.. code-block:: yaml + + # a sequence of mappings with one key's value being a flow sequence + - name: Tom + cpus: [ x86, x86_64 ] + - name: Bob + cpus: [ x86 ] + - name: Dan + cpus: [ PowerPC, x86 ] + + +Introduction to YAML I/O +======================== + +The use of indenting makes the YAML easy for a human to read and understand, +but having a program read and write YAML involves a lot of tedious details. +The YAML I/O library structures and simplifies reading and writing YAML +documents. + +YAML I/O assumes you have some "native" data structures which you want to be +able to dump as YAML and recreate from YAML. The first step is to try +writing example YAML for your data structures. You may find after looking at +possible YAML representations that a direct mapping of your data structures +to YAML is not very readable. Often the fields are not in the order that +a human would find readable. Or the same information is replicated in multiple +locations, making it hard for a human to write such YAML correctly. + +In relational database theory there is a design step called normalization in +which you reorganize fields and tables. The same considerations need to +go into the design of your YAML encoding. But, you may not want to change +your exisiting native data structures. Therefore, when writing out YAML +there may be a normalization step, and when reading YAML there would be a +corresponding denormalization step. + +YAML I/O uses a non-invasive, traits based design. YAML I/O defines some +abstract base templates. You specialize those templates on your data types. +For instance, if you have an eumerated type FooBar you could specialize +ScalarEnumerationTraits on that type and define the enumeration() method: + +.. code-block:: c++ + + using llvm::yaml::ScalarEnumerationTraits; + using llvm::yaml::IO; + + template <> + struct ScalarEnumerationTraits<FooBar> { + static void enumeration(IO &io, FooBar &value) { + ... + } + }; + + +As with all YAML I/O template specializations, the ScalarEnumerationTraits is used for +both reading and writing YAML. That is, the mapping between in-memory enum +values and the YAML string representation is only in place. +This assures that the code for writing and parsing of YAML stays in sync. + +To specify a YAML mappings, you define a specialization on +llvm::yaml::MapppingTraits. +If your native data structure happens to be a struct that is already normalized, +then the specialization is simple. For example: + +.. code-block:: c++ + + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + template <> + struct MapppingTraits<Person> { + static void mapping(IO &io, Person &info) { + io.mapRequired("name", info.name); + io.mapOptional("hat-size", info.hatSize); + } + }; + + +A YAML sequence is automatically infered if you data type has begin()/end() +iterators and a push_back() method. Therefore any of the STL containers +(such as std::vector<>) will automatically translate to YAML sequences. + +Once you have defined specializations for your data types, you can +programmatically use YAML I/O to write a YAML document: + +.. code-block:: c++ + + using llvm::yaml::Output; + + Person tom; + tom.name = "Tom"; + tom.hatSize = 8; + Person dan; + dan.name = "Dan"; + dan.hatSize = 7; + std::vector<Person> persons; + persons.push_back(tom); + persons.push_back(dan); + + Output yout(llvm::outs()); + yout << persons; + +This would write the following: + +.. code-block:: yaml + + - name: Tom + hat-size: 8 + - name: Dan + hat-size: 7 + +And you can also read such YAML documents with the following code: + +.. code-block:: c++ + + using llvm::yaml::Input; + + typedef std::vector<Person> PersonList; + std::vector<PersonList> docs; + + Input yin(document.getBuffer()); + yin >> docs; + + if ( yin.error() ) + return; + + // Process read document + for ( PersonList &pl : docs ) { + for ( Person &person : pl ) { + cout << "name=" << person.name; + } + } + +One other feature of YAML is the ability to define multiple documents in a +single file. That is why reading YAML produces a vector of your document type. + + + +Error Handling +============== + +When parsing a YAML document, if the input does not match your schema (as +expressed in your XxxTraits<> specializations). YAML I/O +will print out an error message and your Input object's error() method will +return true. For instance the following document: + +.. code-block:: yaml + + - name: Tom + shoe-size: 12 + - name: Dan + hat-size: 7 + +Has a key (shoe-size) that is not defined in the schema. YAML I/O will +automatically generate this error: + +.. code-block:: yaml + + YAML:2:2: error: unknown key 'shoe-size' + shoe-size: 12 + ^~~~~~~~~ + +Similar errors are produced for other input not conforming to the schema. + + +Scalars +======= + +YAML scalars are just strings (i.e. not a sequence or mapping). The YAML I/O +library provides support for translating between YAML scalars and specific +C++ types. + + +Built-in types +-------------- +The following types have built-in support in YAML I/O: + +* bool +* float +* double +* StringRef +* int64_t +* int32_t +* int16_t +* int8_t +* uint64_t +* uint32_t +* uint16_t +* uint8_t + +That is, you can use those types in fields of MapppingTraits or as element type +in sequence. When reading, YAML I/O will validate that the string found +is convertible to that type and error out if not. + + +Unique types +------------ +Given that YAML I/O is trait based, the selection of how to convert your data +to YAML is based on the type of your data. But in C++ type matching, typedefs +do not generate unique type names. That means if you have two typedefs of +unsigned int, to YAML I/O both types look exactly like unsigned int. To +facilitate make unique type names, YAML I/O provides a macro which is used +like a typedef on built-in types, but expands to create a class with conversion +operators to and from the base type. For example: + +.. code-block:: c++ + + LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyFooFlags) + LLVM_YAML_STRONG_TYPEDEF(uint32_t, MyBarFlags) + +This generates two classes MyFooFlags and MyBarFlags which you can use in your +native data structures instead of uint32_t. They are implicitly +converted to and from uint32_t. The point of creating these unique types +is that you can now specify traits on them to get different YAML conversions. + +Hex types +--------- +An example use of a unique type is that YAML I/O provides fixed sized unsigned +integers that are written with YAML I/O as hexadecimal instead of the decimal +format used by the built-in integer types: + +* Hex64 +* Hex32 +* Hex16 +* Hex8 + +You can use llvm::yaml::Hex32 instead of uint32_t and the only different will +be that when YAML I/O writes out that type it will be formatted in hexadecimal. + + +ScalarEnumerationTraits +----------------------- +YAML I/O supports translating between in-memory enumerations and a set of string +values in YAML documents. This is done by specializing ScalarEnumerationTraits<> +on your enumeration type and define a enumeration() method. +For instance, suppose you had an enumeration of CPUs and a struct with it as +a field: + +.. code-block:: c++ + + enum CPUs { + cpu_x86_64 = 5, + cpu_x86 = 7, + cpu_PowerPC = 8 + }; + + struct Info { + CPUs cpu; + uint32_t flags; + }; + +To support reading and writing of this enumeration, you can define a +ScalarEnumerationTraits specialization on CPUs, which can then be used +as a field type: + +.. code-block:: c++ + + using llvm::yaml::ScalarEnumerationTraits; + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + template <> + struct ScalarEnumerationTraits<CPUs> { + static void enumeration(IO &io, CPUs &value) { + io.enumCase(value, "x86_64", cpu_x86_64); + io.enumCase(value, "x86", cpu_x86); + io.enumCase(value, "PowerPC", cpu_PowerPC); + } + }; + + template <> + struct MapppingTraits<Info> { + static void mapping(IO &io, Info &info) { + io.mapRequired("cpu", info.cpu); + io.mapOptional("flags", info.flags, 0); + } + }; + +When reading YAML, if the string found does not match any of the the strings +specified by enumCase() methods, an error is automatically generated. +When writing YAML, if the value being written does not match any of the values +specified by the enumCase() methods, a runtime assertion is triggered. + + +BitValue +-------- +Another common data structure in C++ is a field where each bit has a unique +meaning. This is often used in a "flags" field. YAML I/O has support for +converting such fields to a flow sequence. For instance suppose you +had the following bit flags defined: + +.. code-block:: c++ + + enum { + flagsPointy = 1 + flagsHollow = 2 + flagsFlat = 4 + flagsRound = 8 + }; + + LLVM_YAML_UNIQUE_TYPE(MyFlags, uint32_t) + +To support reading and writing of MyFlags, you specialize ScalarBitSetTraits<> +on MyFlags and provide the bit values and their names. + +.. code-block:: c++ + + using llvm::yaml::ScalarBitSetTraits; + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + template <> + struct ScalarBitSetTraits<MyFlags> { + static void bitset(IO &io, MyFlags &value) { + io.bitSetCase(value, "hollow", flagHollow); + io.bitSetCase(value, "flat", flagFlat); + io.bitSetCase(value, "round", flagRound); + io.bitSetCase(value, "pointy", flagPointy); + } + }; + + struct Info { + StringRef name; + MyFlags flags; + }; + + template <> + struct MapppingTraits<Info> { + static void mapping(IO &io, Info& info) { + io.mapRequired("name", info.name); + io.mapRequired("flags", info.flags); + } + }; + +With the above, YAML I/O (when writing) will test mask each value in the +bitset trait against the flags field, and each that matches will +cause the corresponding string to be added to the flow sequence. The opposite +is done when reading and any unknown string values will result in a error. With +the above schema, a same valid YAML document is: + +.. code-block:: yaml + + name: Tom + flags: [ pointy, flat ] + + +Custom Scalar +------------- +Sometimes for readability a scalar needs to be formatted in a custom way. For +instance your internal data structure may use a integer for time (seconds since +some epoch), but in YAML it would be much nicer to express that integer in +some time format (e.g. 4-May-2012 10:30pm). YAML I/O has a way to support +custom formatting and parsing of scalar types by specializing ScalarTraits<> on +your data type. When writing, YAML I/O will provide the native type and +your specialization must create a temporary llvm::StringRef. When reading, +YAML I/O will provide a llvm::StringRef of scalar and your specialization +must convert that to your native data type. An outline of a custom scalar type +looks like: + +.. code-block:: c++ + + using llvm::yaml::ScalarTraits; + using llvm::yaml::IO; + + template <> + struct ScalarTraits<MyCustomType> { + static void output(const T &value, llvm::raw_ostream &out) { + out << value; // do custom formatting here + } + static StringRef input(StringRef scalar, T &value) { + // do custom parsing here. Return the empty string on success, + // or an error message on failure. + return StringRef(); + } + }; + + +Mappings +======== + +To be translated to or from a YAML mapping for your type T you must specialize +llvm::yaml::MapppingTraits on T and implement the "void mapping(IO &io, T&)" +method. If your native data structures use pointers to a class everywhere, +you can specialize on the class pointer. Examples: + +.. code-block:: c++ + + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + // Example of struct Foo which is used by value + template <> + struct MapppingTraits<Foo> { + static void mapping(IO &io, Foo &foo) { + io.mapOptional("size", foo.size); + ... + } + }; + + // Example of struct Bar which is natively always a pointer + template <> + struct MapppingTraits<Bar*> { + static void mapping(IO &io, Bar *&bar) { + io.mapOptional("size", bar->size); + ... + } + }; + + +No Normalization +---------------- + +The mapping() method is responsible, if needed, for normalizing and +denormalizing. In a simple case where the native data structure requires no +normalization, the mapping method just uses mapOptional() or mapRequired() to +bind the struct's fields to YAML key names. For example: + +.. code-block:: c++ + + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + template <> + struct MapppingTraits<Person> { + static void mapping(IO &io, Person &info) { + io.mapRequired("name", info.name); + io.mapOptional("hat-size", info.hatSize); + } + }; + + +Normalization +---------------- + +When [de]normalization is required, the mapping() method needs a way to access +normalized values as fields. To help with this, there is +a template MappingNormalization<> which you can then use to automatically +do the normalization and denormalization. The template is used to create +a local variable in your mapping() method which contains the normalized keys. + +Suppose you have native data type +Polar which specifies a position in polar coordinates (distance, angle): + +.. code-block:: c++ + + struct Polar { + float distance; + float angle; + }; + +but you've decided the normalized YAML for should be in x,y coordinates. That +is, you want the yaml to look like: + +.. code-block:: yaml + + x: 10.3 + y: -4.7 + +You can support this by defining a MapppingTraits that normalizes the polar +coordinates to x,y coordinates when writing YAML and denormalizes x,y +coordindates into polar when reading YAML. + +.. code-block:: c++ + + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + template <> + struct MapppingTraits<Polar> { + + class NormalizedPolar { + public: + NormalizedPolar(IO &io) + : x(0.0), y(0.0) { + } + NormalizedPolar(IO &, Polar &polar) + : x(polar.distance * cos(polar.angle)), + y(polar.distance * sin(polar.angle)) { + } + Polar denormalize(IO &) { + return Polar(sqrt(x*x+y*y, arctan(x,y)); + } + + float x; + float y; + }; + + static void mapping(IO &io, Polar &polar) { + MappingNormalization<NormalizedPolar, Polar> keys(io, polar); + + io.mapRequired("x", keys->x); + io.mapRequired("y", keys->y); + } + }; + +When writing YAML, the local variable "keys" will be a stack allocated +instance of NormalizedPolar, constructed from the suppled polar object which +initializes it x and y fields. The mapRequired() methods then write out the x +and y values as key/value pairs. + +When reading YAML, the local variable "keys" will be a stack allocated instance +of NormalizedPolar, constructed by the empty constructor. The mapRequired +methods will find the matching key in the YAML document and fill in the x and y +fields of the NormalizedPolar object keys. At the end of the mapping() method +when the local keys variable goes out of scope, the denormalize() method will +automatically be called to convert the read values back to polar coordinates, +and then assigned back to the second parameter to mapping(). + +In some cases, the normalized class may be a subclass of the native type and +could be returned by the denormalize() method, except that the temporary +normalized instance is stack allocated. In these cases, the utility template +MappingNormalizationHeap<> can be used instead. It just like +MappingNormalization<> except that it heap allocates the normalized object +when reading YAML. It never destroyes the normalized object. The denormalize() +method can this return "this". + + +Default values +-------------- +Within a mapping() method, calls to io.mapRequired() mean that that key is +required to exist when parsing YAML documents, otherwise YAML I/O will issue an +error. + +On the other hand, keys registered with io.mapOptional() are allowed to not +exist in the YAML document being read. So what value is put in the field +for those optional keys? +There are two steps to how those optional fields are filled in. First, the +second parameter to the mapping() method is a reference to a native class. That +native class must have a default constructor. Whatever value the default +constructor initially sets for an optional field will be that field's value. +Second, the mapOptional() method has an optional third parameter. If provided +it is the value that mapOptional() should set that field to if the YAML document +does not have that key. + +There is one important difference between those two ways (default constructor +and third parameter to mapOptional). When YAML I/O generates a YAML document, +if the mapOptional() third parameter is used, if the actual value being written +is the same as (using ==) the default value, then that key/value is not written. + + +Order of Keys +-------------- + +When writing out a YAML document, the keys are written in the order that the +calls to mapRequired()/mapOptional() are made in the mapping() method. This +gives you a chance to write the fields in an order that a human reader of +the YAML document would find natural. This may be different that the order +of the fields in the native class. + +When reading in a YAML document, the keys in the document can be in any order, +but they are processed in the order that the calls to mapRequired()/mapOptional() +are made in the mapping() method. That enables some interesting +functionality. For instance, if the first field bound is the cpu and the second +field bound is flags, and the flags are cpu specific, you can programmatically +switch how the flags are converted to and from YAML based on the cpu. +This works for both reading and writing. For example: + +.. code-block:: c++ + + using llvm::yaml::MapppingTraits; + using llvm::yaml::IO; + + struct Info { + CPUs cpu; + uint32_t flags; + }; + + template <> + struct MapppingTraits<Info> { + static void mapping(IO &io, Info &info) { + io.mapRequired("cpu", info.cpu); + // flags must come after cpu for this to work when reading yaml + if ( info.cpu == cpu_x86_64 ) + io.mapRequired("flags", *(My86_64Flags*)info.flags); + else + io.mapRequired("flags", *(My86Flags*)info.flags); + } + }; + + +Sequence +======== + +To be translated to or from a YAML sequence for your type T you must specialize +llvm::yaml::SequenceTraits on T and implement two methods: +“size_t size(IO &io, T&)” and “T::value_type& element(IO &io, T&, size_t indx)”. +For example: + +.. code-block:: c++ + + template <> + struct SequenceTraits<MySeq> { + static size_t size(IO &io, MySeq &list) { ... } + static MySeqEl element(IO &io, MySeq &list, size_t index) { ... } + }; + +The size() method returns how many elements are currently in your sequence. +The element() method returns a reference to the i'th element in the sequence. +When parsing YAML, the element() method may be called with an index one bigger +than the current size. Your element() method should allocate space for one +more element (using default constructor if element is a C++ object) and returns +a reference to that new allocated space. + + +Flow Sequence +------------- +A YAML "flow sequence" is a sequence that when written to YAML it uses the +inline notation (e.g [ foo, bar ] ). To specify that a sequence type should +be written in YAML as a flow sequence, your SequenceTraits specialization should +add "static const bool flow = true;". For instance: + +.. code-block:: c++ + + template <> + struct SequenceTraits<MyList> { + static size_t size(IO &io, MyList &list) { ... } + static MyListEl element(IO &io, MyList &list, size_t index) { ... } + + // The existence of this member causes YAML I/O to use a flow sequence + static const bool flow = true; + }; + +With the above, if you used MyList as the data type in your native data +strucutures, then then when converted to YAML, a flow sequence of integers +will be used (e.g. [ 10, -3, 4 ]). + + +Utility Macros +-------------- +Since a common source of sequences is std::vector<>, YAML I/O provids macros: +LLVM_YAML_IS_SEQUENCE_VECTOR() and LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR() which +can be used to easily specify SequenceTraits<> on a std::vector type. YAML +I/O does not partial specialize SequenceTraits on std::vector<> because that +would force all vectors to be sequences. An example use of the macros: + +.. code-block:: c++ + + std::vector<MyType1>; + std::vector<MyType2>; + LLVM_YAML_IS_SEQUENCE_VECTOR(MyType1) + LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(MyType2) + + + +Document List +============= + +YAML allows you to define multiple "documents" in a single YAML file. Each +new document starts with a left aligned "---" token. The end of all documents +is denoted with a left aligned "..." token. Many users of YAML will never +have need for multiple documents. The top level node in their YAML schema +will be a mapping or sequence. For those cases, the following is not needed. +But for cases where you do want multiple documents, you can specify a +trait for you document list type. The trait has the same methods as +SequenceTraits but is named DocumentListTraits. For example: + +.. code-block:: c++ + + template <> + struct DocumentListTraits<MyDocList> { + static size_t size(IO &io, MyDocList &list) { ... } + static MyDocType element(IO &io, MyDocList &list, size_t index) { ... } + }; + + +User Context Data +================= +When an llvm::yaml::Input or llvm::yaml::Output object is created their +constructors take an optional "context" parameter. This is a pointer to +whatever state information you might need. + +For instance, in a previous example we showed how the conversion type for a +flags field could be determined at runtime based on the value of another field +in the mapping. But what if an inner mapping needs to know some field value +of an outer mapping? That is where the "context" parameter comes in. You +can set values in the context in the outer map's mapping() method and +retrieve those values in the inner map's mapping() method. + +The context value is just a void*. All your traits which use the context +and operate on your native data types, need to agree what the context value +actually is. It could be a pointer to an object or struct which your various +traits use to shared context sensitive information. + + +Output +====== + +The llvm::yaml::Output class is used to generate a YAML document from your +in-memory data structures, using traits defined on your data types. +To instantiate an Output object you need an llvm::raw_ostream, and optionally +a context pointer: + +.. code-block:: c++ + + class Output : public IO { + public: + Output(llvm::raw_ostream &, void *context=NULL); + +Once you have an Output object, you can use the C++ stream operator on it +to write your native data as YAML. One thing to recall is that a YAML file +can contain multiple "documents". If the top level data structure you are +streaming as YAML is a mapping, scalar, or sequence, then Output assumes you +are generating one document and wraps the mapping output +with "``---``" and trailing "``...``". + +.. code-block:: c++ + + using llvm::yaml::Output; + + void dumpMyMapDoc(const MyMapType &info) { + Output yout(llvm::outs()); + yout << info; + } + +The above could produce output like: + +.. code-block:: yaml + + --- + name: Tom + hat-size: 7 + ... + +On the other hand, if the top level data structure you are streaming as YAML +has a DocumentListTraits specialization, then Output walks through each element +of your DocumentList and generates a "---" before the start of each element +and ends with a "...". + +.. code-block:: c++ + + using llvm::yaml::Output; + + void dumpMyMapDoc(const MyDocListType &docList) { + Output yout(llvm::outs()); + yout << docList; + } + +The above could produce output like: + +.. code-block:: yaml + + --- + name: Tom + hat-size: 7 + --- + name: Tom + shoe-size: 11 + ... + +Input +===== + +The llvm::yaml::Input class is used to parse YAML document(s) into your native +data structures. To instantiate an Input +object you need a StringRef to the entire YAML file, and optionally a context +pointer: + +.. code-block:: c++ + + class Input : public IO { + public: + Input(StringRef inputContent, void *context=NULL); + +Once you have an Input object, you can use the C++ stream operator to read +the document(s). If you expect there might be multiple YAML documents in +one file, you'll need to specialize DocumentListTraits on a list of your +document type and stream in that document list type. Otherwise you can +just stream in the document type. Also, you can check if there was +any syntax errors in the YAML be calling the error() method on the Input +object. For example: + +.. code-block:: c++ + + // Reading a single document + using llvm::yaml::Input; + + Input yin(mb.getBuffer()); + + // Parse the YAML file + MyDocType theDoc; + yin >> theDoc; + + // Check for error + if ( yin.error() ) + return; + + +.. code-block:: c++ + + // Reading multiple documents in one file + using llvm::yaml::Input; + + LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(std::vector<MyDocType>) + + Input yin(mb.getBuffer()); + + // Parse the YAML file + std::vector<MyDocType> theDocList; + yin >> theDocList; + + // Check for error + if ( yin.error() ) + return; + + diff --git a/docs/userguides.rst b/docs/userguides.rst index 56eaf0886c..7e4e3b7bc0 100644 --- a/docs/userguides.rst +++ b/docs/userguides.rst @@ -24,6 +24,7 @@ User Guides tutorial/index ReleaseNotes Passes + YamlIO * :ref:`getting_started` @@ -100,6 +101,10 @@ User Guides Instructions for adding new builder to LLVM buildbot master. +* :ref:`yamlio` + + A reference guide for using LLVM's YAML I/O library. + * **IRC** -- You can probably find help on the unofficial LLVM IRC. We often are on irc.oftc.net in the #llvm channel. If you are using the diff --git a/include/llvm/Support/YAMLTraits.h b/include/llvm/Support/YAMLTraits.h new file mode 100644 index 0000000000..4376165e53 --- /dev/null +++ b/include/llvm/Support/YAMLTraits.h @@ -0,0 +1,1114 @@ +//===- llvm/Supporrt/YAMLTraits.h -------------------------------*- C++ -*-===// +// +// The LLVM Linker +// +// This file is distributed under the University of Illinois Open Source +// License. See LICENSE.TXT for details. +// +//===----------------------------------------------------------------------===// + +#ifndef LLVM_YAML_TRAITS_H_ +#define LLVM_YAML_TRAITS_H_ + + +#include "llvm/ADT/DenseMap.h" +#include "llvm/ADT/DenseMapInfo.h" +#include "llvm/ADT/SmallVector.h" +#include "llvm/ADT/StringExtras.h" +#include "llvm/ADT/StringRef.h" +#include "llvm/ADT/StringSwitch.h" +#include "llvm/ADT/Twine.h" +#include "llvm/Support/Compiler.h" +#include "llvm/Support/SourceMgr.h" +#include "llvm/Support/system_error.h" +#include "llvm/Support/type_traits.h" +#include "llvm/Support/YAMLParser.h" +#include "llvm/Support/raw_ostream.h" + + +namespace llvm { +namespace yaml { + + +/// This class should be specialized by any type that needs to be converted +/// to/from a YAML mapping. For example: +/// +/// struct ScalarBitSetTraits<MyStruct> { +/// static void mapping(IO &io, MyStruct &s) { +/// io.mapRequired("name", s.name); +/// io.mapRequired("size", s.size); +/// io.mapOptional("age", s.age); +/// } +/// }; +template<class T> +struct MappingTraits { + // Must provide: + // static void mapping(IO &io, T &fields); +}; + + +/// This class should be specialized by any integral type that converts +/// to/from a YAML scalar where there is a one-to-one mapping between +/// in-memory values and a string in YAML. For example: +/// +/// struct ScalarEnumerationTraits<Colors> { +/// static void enumeration(IO &io, Colors &value) { +/// io.enumCase(value, "red", cRed); +/// io.enumCase(value, "blue", cBlue); +/// io.enumCase(value, "green", cGreen); +/// } +/// }; +template<typename T> +struct ScalarEnumerationTraits { + // Must provide: + // static void enumeration(IO &io, T &value); +}; + + +/// This class should be specialized by any integer type that is a union +/// of bit values and the YAML representation is a flow sequence of +/// strings. For example: +/// +/// struct ScalarBitSetTraits<MyFlags> { +/// static void bitset(IO &io, MyFlags &value) { +/// io.bitSetCase(value, "big", flagBig); +/// io.bitSetCase(value, "flat", flagFlat); +/// io.bitSetCase(value, "round", flagRound); +/// } +/// }; +template<typename T> +struct ScalarBitSetTraits { + // Must provide: + // static void bitset(IO &io, T &value); +}; + + +/// This class should be specialized by type that requires custom conversion +/// to/from a yaml scalar. For example: +/// +/// template<> +/// struct ScalarTraits<MyType> { +/// static void output(const MyType &val, void*, llvm::raw_ostream &out) { +/// // stream out custom formatting +/// out << llvm::format("%x", val); +/// } +/// static StringRef input(StringRef scalar, void*, MyType &value) { +/// // parse scalar and set `value` +/// // return empty string on success, or error string +/// return StringRef(); +/// } +/// }; +template<typename T> +struct ScalarTraits { + // Must provide: + // + // Function to write the value as a string: + //static void output(const T &value, void *ctxt, llvm::raw_ostream &out); + // + // Function to convert a string to a value. Returns the empty + // StringRef on success or an error string if string is malformed: + //static StringRef input(StringRef scalar, void *ctxt, T &value); +}; + + +/// This class should be specialized by any type that needs to be converted +/// to/from a YAML sequence. For example: +/// +/// template<> +/// struct SequenceTraits< std::vector<MyType> > { +/// static size_t size(IO &io, std::vector<MyType> &seq) { +/// return seq.size(); +/// } +/// static MyType& element(IO &, std::vector<MyType> &seq, size_t index) { +/// if ( index >= seq.size() ) +/// seq.resize(index+1); +/// return seq[index]; +/// } +/// }; +template<typename T> +struct SequenceTraits { + // Must provide: + // static size_t size(IO &io, T &seq); + // static T::value_type& element(IO &io, T &seq, size_t index); + // + // The following is option and will cause generated YAML to use + // a flow sequence (e.g. [a,b,c]). + // static const bool flow = true; +}; + + +/// This class should be specialized by any type that needs to be converted +/// to/from a list of YAML documents. +template<typename T> +struct DocumentListTraits { + // Must provide: + // static size_t size(IO &io, T &seq); + // static T::value_type& element(IO &io, T &seq, size_t index); +}; + + +// Only used by compiler if both template types are the same +template <typename T, T> +struct SameType; + +// Only used for better diagnostics of missing traits +template <typename T> +struct MissingTrait; + + + +// Test if ScalarEnumerationTraits<T> is defined on type T. +template <class T> +struct has_ScalarEnumerationTraits +{ + typedef void (*Signature_enumeration)(class IO&, T&); + + template <typename U> + static char test(SameType<Signature_enumeration, &U::enumeration>*); + + template <typename U> + static double test(...); + +public: + static bool const value = (sizeof(test<ScalarEnumerationTraits<T> >(0)) == 1); +}; + + +// Test if ScalarBitSetTraits<T> is defined on type T. +template <class T> +struct has_ScalarBitSetTraits +{ + typedef void (*Signature_bitset)(class IO&, T&); + + template <typename U> + static char test(SameType<Signature_bitset, &U::bitset>*); + + template <typename U> + static double test(...); + +public: + static bool const value = (sizeof(test<ScalarBitSetTraits<T> >(0)) == 1); +}; + + +// Test if ScalarTraits<T> is defined on type T. +template <class T> +struct has_ScalarTraits +{ + typedef llvm::StringRef (*Signature_input)(llvm::StringRef, void*, T&); + typedef void (*Signature_output)(const T&, void*, llvm::raw_ostream&); + + template <typename U> + static char test(SameType<Signature_input, &U::input>*, + SameType<Signature_output, &U::output>*); + + template <typename U> + static double test(...); + +public: + static bool const value = (sizeof(test<ScalarTraits<T> >(0,0)) == 1); +}; + + +// Test if MappingTraits<T> is defined on type T. +template <class T> +struct has_MappingTraits +{ + typedef void (*Signature_mapping)(class IO&, T&); + + template <typename U> + static char test(SameType<Signature_mapping, &U::mapping>*); + + template <typename U> + static double test(...); + +public: + static bool const value = (sizeof(test<MappingTraits<T> >(0)) == 1); +}; + + +// Test if SequenceTraits<T> is defined on type T +// and SequenceTraits<T>::flow is *not* defined. +template <class T> +struct has_SequenceTraits +{ + typedef size_t (*Signature_size)(class IO&, T&); + + template <typename U> + static char test(SameType<Signature_size, &U::size>*); + + template <typename U> + static double test(...); + + template <typename U> static + char flowtest( char[sizeof(&U::flow)] ) ; + + template <typename U> + static double flowtest(...); + +public: + static bool const value = (sizeof(test<SequenceTraits<T> >(0)) == 1) + && (sizeof(flowtest<T>(0)) != 1); +}; + + +// Test if SequenceTraits<T> is defined on type T +// and SequenceTraits<T>::flow is defined. +template <class T> +struct has_FlowSequenceTraits +{ + typedef size_t (*Signature_size)(class IO&, T&); + + template <typename U> + static char test(SameType<Signature_size, &U::size>*); + + template <typename U> + static double test(...); + + template <typename U> static + char flowtest( char[sizeof(&U::flow)] ) ; + + template <typename U> + static double flowtest(...); + +public: + static bool const value = (sizeof(test<SequenceTraits<T> >(0)) == 1) + && (sizeof(flowtest<T>(0)) == 1); +}; + + +// Test if DocumentListTraits<T> is defined on type T +template <class T> +struct has_DocumentListTraits +{ + typedef size_t (*Signature_size)(class IO&, T&); + + template <typename U> + static char test(SameType<Signature_size, &U::size>*); + + template <typename U> + static double test(...); + +public: + static bool const value = (sizeof(test<DocumentListTraits<T> >(0)) == 1); +}; + + + + +template<typename T> +struct missingTraits : public llvm::integral_constant<bool, + !has_ScalarEnumerationTraits<T>::value + && !has_ScalarBitSetTraits<T>::value + && !has_ScalarTraits<T>::value + && !has_MappingTraits<T>::value + && !has_SequenceTraits<T>::value + && !has_FlowSequenceTraits<T>::value + && !has_DocumentListTraits<T>::value > {}; + + +// Base class for Input and Output. +class IO { +public: + + IO(void *Ctxt=NULL); + virtual ~IO(); + + virtual bool outputting() = 0; + + virtual unsigned beginSequence() = 0; + virtual bool preflightElement(unsigned, void *&) = 0; + virtual void postflightElement(void*) = 0; + virtual void endSequence() = 0; + + virtual unsigned beginFlowSequence() = 0; + virtual bool preflightFlowElement(unsigned, void *&) = 0; + virtual void postflightFlowElement(void*) = 0; + virtual void endFlowSequence() = 0; + + virtual void beginMapping() = 0; + virtual void endMapping() = 0; + virtual bool preflightKey(const char*, bool, bool, bool &, void *&) = 0; + virtual void postflightKey(void*) = 0; + + virtual void beginEnumScalar() = 0; + virtual bool matchEnumScalar(const char*, bool) = 0; + virtual void endEnumScalar() = 0; + + virtual bool beginBitSetScalar(bool &) = 0; + virtual bool bitSetMatch(const char*, bool) = 0; + virtual void endBitSetScalar() = 0; + + virtual void scalarString(StringRef &) = 0; + + virtual void setError(const Twine &) = 0; + + template <typename T> + void enumCase(T &Val, const char* Str, const T ConstVal) { + if ( matchEnumScalar(Str, (Val == ConstVal)) ) { + Val = ConstVal; + } + } + + // allow anonymous enum values to be used with LLVM_YAML_STRONG_TYPEDEF + template <typename T> + void enumCase(T &Val, const char* Str, const uint32_t ConstVal) { + if ( matchEnumScalar(Str, (Val == static_cast<T>(ConstVal))) ) { + Val = ConstVal; + } + } + + template <typename T> + void bitSetCase(T &Val, const char* Str, const T ConstVal) { + if ( bitSetMatch(Str, ((Val & ConstVal) == ConstVal)) ) { + Val = Val | ConstVal; + } + } + + // allow anonymous enum values to be used with LLVM_YAML_STRONG_TYPEDEF + template <typename T> + void bitSetCase(T &Val, const char* Str, const uint32_t ConstVal) { + if ( bitSetMatch(Str, ((Val & ConstVal) == ConstVal)) ) { + Val = Val | ConstVal; + } + } + + void *getContext(); + void setContext(void *); + + template <typename T> + void mapRequired(const char* Key, T& Val) { + this->processKey(Key, Val, true); + } + + template <typename T> + typename llvm::enable_if_c<has_SequenceTraits<T>::value,void>::type + mapOptional(const char* Key, T& Val) { + // omit key/value instead of outputting empty sequence + if ( this->outputting() && !(Val.begin() != Val.end()) ) + return; + this->processKey(Key, Val, false); + } + + template <typename T> + typename llvm::enable_if_c<!has_SequenceTraits<T>::value,void>::type + mapOptional(const char* Key, T& Val) { + this->processKey(Key, Val, false); + } + + template <typename T> + void mapOptional(const char* Key, T& Val, const T& Default) { + this->processKeyWithDefault(Key, Val, Default, false); + } + + +private: + template <typename T> + void processKeyWithDefault(const char *Key, T &Val, const T& DefaultValue, + bool Required) { + void *SaveInfo; + bool UseDefault; + const bool sameAsDefault = (Val == DefaultValue); + if ( this->preflightKey(Key, Required, sameAsDefault, UseDefault, + SaveInfo) ) { + yamlize(*this, Val, Required); + this->postflightKey(SaveInfo); + } + else { + if ( UseDefault ) + Val = DefaultValue; + } + } + + template <typename T> + void processKey(const char *Key, T &Val, bool Required) { + void *SaveInfo; + bool UseDefault; + if ( this->preflightKey(Key, Required, false, UseDefault, SaveInfo) ) { + yamlize(*this, Val, Required); + this->postflightKey(SaveInfo); + } + } + +private: + void *Ctxt; +}; + + + +template<typename T> +typename llvm::enable_if_c<has_ScalarEnumerationTraits<T>::value,void>::type +yamlize(IO &io, T &Val, bool) { + io.beginEnumScalar(); + ScalarEnumerationTraits<T>::enumeration(io, Val); + io.endEnumScalar(); +} + +template<typename T> +typename llvm::enable_if_c<has_ScalarBitSetTraits<T>::value,void>::type +yamlize(IO &io, T &Val, bool) { + bool DoClear; + if ( io.beginBitSetScalar(DoClear) ) { + if ( DoClear ) + Val = static_cast<T>(0); + ScalarBitSetTraits<T>::bitset(io, Val); + io.endBitSetScalar(); + } +} + + +template<typename T> +typename llvm::enable_if_c<has_ScalarTraits<T>::value,void>::type +yamlize(IO &io, T &Val, bool) { + if ( io.outputting() ) { + std::string Storage; + llvm::raw_string_ostream Buffer(Storage); + ScalarTraits<T>::output(Val, io.getContext(), Buffer); + StringRef Str = Buffer.str(); + io.scalarString(Str); + } + else { + StringRef Str; + io.scalarString(Str); + StringRef Result = ScalarTraits<T>::input(Str, io.getContext(), Val); + if ( !Result.empty() ) { + io.setError(llvm::Twine(Result)); + } + } +} + + +template<typename T> +typename llvm::enable_if_c<has_MappingTraits<T>::value, void>::type +yamlize(IO &io, T &Val, bool) { + io.beginMapping(); + MappingTraits<T>::mapping(io, Val); + io.endMapping(); +} + +#ifndef BUILDING_YAMLIO +template<typename T> +typename llvm::enable_if_c<missingTraits<T>::value, void>::type +yamlize(IO &io, T &Val, bool) { + char missing_yaml_trait_for_type[sizeof(MissingTrait<T>)]; +} +#endif + +template<typename T> +typename llvm::enable_if_c<has_SequenceTraits<T>::value,void>::type +yamlize(IO &io, T &Seq, bool) { + unsigned incount = io.beginSequence(); + unsigned count = io.outputting() ? SequenceTraits<T>::size(io, Seq) : incount; + for(unsigned i=0; i < count; ++i) { + void *SaveInfo; + if ( io.preflightElement(i, SaveInfo) ) { + yamlize(io, SequenceTraits<T>::element(io, Seq, i), true); + io.postflightElement(SaveInfo); + } + } + io.endSequence(); +} + +template<typename T> +typename llvm::enable_if_c<has_FlowSequenceTraits<T>::value,void>::type +yamlize(IO &io, T &Seq, bool) { + unsigned incount = io.beginFlowSequence(); + unsigned count = io.outputting() ? SequenceTraits<T>::size(io, Seq) : incount; + for(unsigned i=0; i < count; ++i) { + void *SaveInfo; + if ( io.preflightFlowElement(i, SaveInfo) ) { + yamlize(io, SequenceTraits<T>::element(io, Seq, i), true); + io.postflightFlowElement(SaveInfo); + } + } + io.endFlowSequence(); +} + + + +// Clients of YAML I/O only see declaration of the traits for built-in +// types. The implementation is in the LLVM Support library. Without +// this #ifdef, every client would get a copy of the implementation of +// these traits. +#ifndef BUILDING_YAMLIO +template<> +struct ScalarTraits<bool> { + static void output(const bool &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, bool &); +}; + +template<> +struct ScalarTraits<StringRef> { + static void output(const StringRef &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, StringRef &); +}; + +template<> +struct ScalarTraits<uint8_t> { + static void output(const uint8_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, uint8_t &); +}; + +template<> +struct ScalarTraits<uint16_t> { + static void output(const uint16_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, uint16_t &); +}; + +template<> +struct ScalarTraits<uint32_t> { + static void output(const uint32_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, uint32_t &); +}; + +template<> +struct ScalarTraits<uint64_t> { + static void output(const uint64_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, uint64_t &); +}; + +template<> +struct ScalarTraits<int8_t> { + static void output(const int8_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, int8_t &); +}; + +template<> +struct ScalarTraits<int16_t> { + static void output(const int16_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, int16_t &); +}; + +template<> +struct ScalarTraits<int32_t> { + static void output(const int32_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, int32_t &); +}; + +template<> +struct ScalarTraits<int64_t> { + static void output(const int64_t &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, int64_t &); +}; + +template<> +struct ScalarTraits<float> { + static void output(const float &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, float &); +}; + +template<> +struct ScalarTraits<double> { + static void output(const double &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, double &); +}; +#endif + + + +// Utility for use within MappingTraits<>::mapping() method +// to [de]normalize an object for use with YAML conversion. +template <typename TNorm, typename TFinal> +struct MappingNormalization { + MappingNormalization(IO &i_o, TFinal &Obj) + : io(i_o), BufPtr(NULL), Result(Obj) { + if ( io.outputting() ) { + BufPtr = new (&Buffer) TNorm(io, Obj); + } + else { + BufPtr = new (&Buffer) TNorm(io); + } + } + + ~MappingNormalization() { + if ( ! io.outputting() ) { + Result = BufPtr->denormalize(io); + } + BufPtr->~TNorm(); + } + + TNorm* operator->() { return BufPtr; } + +private: + typedef typename llvm::AlignedCharArrayUnion<TNorm> Storage; + + Storage Buffer; + IO &io; + TNorm *BufPtr; + TFinal &Result; +}; + + + +// Utility for use within MappingTraits<>::mapping() method +// to [de]normalize an object for use with YAML conversion. +template <typename TNorm, typename TFinal> +struct MappingNormalizationHeap { + MappingNormalizationHeap(IO &i_o, TFinal &Obj) + : io(i_o), BufPtr(NULL), Result(Obj) { + if ( io.outputting() ) { + BufPtr = new (&Buffer) TNorm(io, Obj); + } + else { + BufPtr = new TNorm(io); + } + } + + ~MappingNormalizationHeap() { + if ( io.outputting() ) { + BufPtr->~TNorm(); + } + else { + Result = BufPtr->denormalize(io); + } + } + + TNorm* operator->() { return BufPtr; } + +private: + typedef typename llvm::AlignedCharArrayUnion<TNorm> Storage; + + Storage Buffer; + IO &io; + TNorm *BufPtr; + TFinal &Result; +}; + + + +/// +/// The Input class is used to parse a yaml document into in-memory structs +/// and vectors. +/// +/// It works by using YAMLParser to do a syntax parse of the entire yaml +/// document, then the Input class builds a graph of HNodes which wraps +/// each yaml Node. The extra layer is buffering. The low level yaml +/// parser only lets you look at each node once. The buffering layer lets +/// you search and interate multiple times. This is necessary because +/// the mapRequired() method calls may not be in the same order +/// as the keys in the document. +/// +class Input : public IO { +public: + // Construct a yaml Input object from a StringRef and optional user-data. + Input(StringRef InputContent, void *Ctxt=NULL); + + // Check if there was an syntax or semantic error during parsing. + llvm::error_code error(); + + // To set alternate error reporting. + void setDiagHandler(llvm::SourceMgr::DiagHandlerTy Handler, void *Ctxt = 0); + +private: + virtual bool outputting(); + virtual void beginMapping(); + virtual void endMapping(); + virtual bool preflightKey(const char *, bool, bool, bool &, void *&); + virtual void postflightKey(void *); + virtual unsigned beginSequence(); + virtual void endSequence(); + virtual bool preflightElement(unsigned index, void *&); + virtual void postflightElement(void *); + virtual unsigned beginFlowSequence(); + virtual bool preflightFlowElement(unsigned , void *&); + virtual void postflightFlowElement(void *); + virtual void endFlowSequence(); + virtual void beginEnumScalar(); + virtual bool matchEnumScalar(const char*, bool); + virtual void endEnumScalar(); + virtual bool beginBitSetScalar(bool &); + virtual bool bitSetMatch(const char *, bool ); + virtual void endBitSetScalar(); + virtual void scalarString(StringRef &); + virtual void setError(const Twine &message); + + class HNode { + public: + HNode(Node *n) : _node(n) { } + static inline bool classof(const HNode *) { return true; } + + Node *_node; + }; + + class EmptyHNode : public HNode { + public: + EmptyHNode(Node *n) : HNode(n) { } + static inline bool classof(const HNode *n) { + return NullNode::classof(n->_node); + } + static inline bool classof(const EmptyHNode *) { return true; } + }; + + class ScalarHNode : public HNode { + public: + ScalarHNode(Node *n, StringRef s) : HNode(n), _value(s) { } + + StringRef value() const { return _value; } + + static inline bool classof(const HNode *n) { + return ScalarNode::classof(n->_node); + } + static inline bool classof(const ScalarHNode *) { return true; } + protected: + StringRef _value; + }; + + class MapHNode : public HNode { + public: + MapHNode(Node *n) : HNode(n) { } + + static inline bool classof(const HNode *n) { + return MappingNode::classof(n->_node); + } + static inline bool classof(const MapHNode *) { return true; } + + struct StrMappingInfo { + static StringRef getEmptyKey() { return StringRef(); } + static StringRef getTombstoneKey() { return StringRef(" ", 0); } + static unsigned getHashValue(StringRef const val) { + return llvm::HashString(val); } + static bool isEqual(StringRef const lhs, + StringRef const rhs) { return lhs.equals(rhs); } + }; + typedef llvm::DenseMap<StringRef, HNode*, StrMappingInfo> NameToNode; + + bool isValidKey(StringRef key); + + NameToNode Mapping; + llvm::SmallVector<const char*, 6> ValidKeys; + }; + + class SequenceHNode : public HNode { + public: + SequenceHNode(Node *n) : HNode(n) { } + + static inline bool classof(const HNode *n) { + return SequenceNode::classof(n->_node); + } + static inline bool classof(const SequenceHNode *) { return true; } + + std::vector<HNode*> Entries; + }; + + Input::HNode *createHNodes(Node *node); + void setError(HNode *hnode, const Twine &message); + void setError(Node *node, const Twine &message); + + +public: + // These are only used by operator>>. They could be private + // if those templated things could be made friends. + bool setCurrentDocument(); + void nextDocument(); + +private: + llvm::yaml::Stream *Strm; + llvm::SourceMgr SrcMgr; + llvm::error_code EC; + llvm::BumpPtrAllocator Allocator; + llvm::yaml::document_iterator DocIterator; + std::vector<bool> BitValuesUsed; + HNode *CurrentNode; + bool ScalarMatchFound; +}; + + + + +/// +/// The Output class is used to generate a yaml document from in-memory structs +/// and vectors. +/// +class Output : public IO { +public: + Output(llvm::raw_ostream &, void *Ctxt=NULL); + virtual ~Output(); + + virtual bool outputting(); + virtual void beginMapping(); + virtual void endMapping(); + virtual bool preflightKey(const char *key, bool, bool, bool &, void *&); + virtual void postflightKey(void *); + virtual unsigned beginSequence(); + virtual void endSequence(); + virtual bool preflightElement(unsigned, void *&); + virtual void postflightElement(void *); + virtual unsigned beginFlowSequence(); + virtual bool preflightFlowElement(unsigned, void *&); + virtual void postflightFlowElement(void *); + virtual void endFlowSequence(); + virtual void beginEnumScalar(); + virtual bool matchEnumScalar(const char*, bool); + virtual void endEnumScalar(); + virtual bool beginBitSetScalar(bool &); + virtual bool bitSetMatch(const char *, bool ); + virtual void endBitSetScalar(); + virtual void scalarString(StringRef &); + virtual void setError(const Twine &message); + +public: + // These are only used by operator<<. They could be private + // if that templated operator could be made a friend. + void beginDocuments(); + bool preflightDocument(unsigned); + void postflightDocument(); + void endDocuments(); + +private: + void output(StringRef s); + void outputUpToEndOfLine(StringRef s); + void newLineCheck(); + void outputNewLine(); + void paddedKey(StringRef key); + + enum InState { inSeq, inFlowSeq, inMapFirstKey, inMapOtherKey }; + + llvm::raw_ostream &Out; + SmallVector<InState, 8> StateStack; + int Column; + int ColumnAtFlowStart; + bool NeedBitValueComma; + bool NeedFlowSequenceComma; + bool EnumerationMatchFound; + bool NeedsNewLine; +}; + + + + +/// YAML I/O does conversion based on types. But often native data types +/// are just a typedef of built in intergral types (e.g. int). But the C++ +/// type matching system sees through the typedef and all the typedefed types +/// look like a built in type. This will cause the generic YAML I/O conversion +/// to be used. To provide better control over the YAML conversion, you can +/// use this macro instead of typedef. It will create a class with one field +/// and automatic conversion operators to and from the base type. +/// Based on BOOST_STRONG_TYPEDEF +#define LLVM_YAML_STRONG_TYPEDEF(_base, _type) \ + struct _type { \ + _type() { } \ + _type(const _base v) : value(v) { } \ + _type(const _type &v) : value(v.value) {} \ + _type &operator=(const _type &rhs) { value = rhs.value; return *this; }\ + _type &operator=(const _base &rhs) { value = rhs; return *this; } \ + operator const _base & () const { return value; } \ + bool operator==(const _type &rhs) const { return value == rhs.value; } \ + bool operator==(const _base &rhs) const { return value == rhs; } \ + bool operator<(const _type &rhs) const { return value < rhs.value; } \ + _base value; \ + }; + + + +/// +/// Use these types instead of uintXX_t in any mapping to have +/// its yaml output formatted as hexadecimal. +/// +LLVM_YAML_STRONG_TYPEDEF(uint8_t, Hex8) +LLVM_YAML_STRONG_TYPEDEF(uint16_t, Hex16) +LLVM_YAML_STRONG_TYPEDEF(uint32_t, Hex32) +LLVM_YAML_STRONG_TYPEDEF(uint64_t, Hex64) + + +// Clients of YAML I/O only see declaration of the traits for Hex* +// types. The implementation is in the LLVM Support library. Without +// this #ifdef, every client would get a copy of the implementation of +// these traits. +#ifndef BUILDING_YAMLIO +template<> +struct ScalarTraits<Hex8> { + static void output(const Hex8 &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, Hex8 &); +}; + +template<> +struct ScalarTraits<Hex16> { + static void output(const Hex16 &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, Hex16 &); +}; + +template<> +struct ScalarTraits<Hex32> { + static void output(const Hex32 &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, Hex32 &); +}; + +template<> +struct ScalarTraits<Hex64> { + static void output(const Hex64 &, void*, llvm::raw_ostream &); + static llvm::StringRef input(llvm::StringRef , void*, Hex64 &); +}; +#endif + + +// Define non-member operator>> so that Input can stream in a document list. +template <typename T> +inline +typename llvm::enable_if_c<has_DocumentListTraits<T>::value,Input &>::type +operator>>(Input &yin, T &docList) { + int i = 0; + while ( yin.setCurrentDocument() ) { + yamlize(yin, DocumentListTraits<T>::element(yin, docList, i), true); + if ( yin.error() ) + return yin; + yin.nextDocument(); + ++i; + } + return yin; +} + +// Define non-member operator>> so that Input can stream in a map as a document. +template <typename T> +inline +typename llvm::enable_if_c<has_MappingTraits<T>::value,Input &>::type +operator>>(Input &yin, T &docMap) { + yin.setCurrentDocument(); + yamlize(yin, docMap, true); + return yin; +} + +// Define non-member operator>> so that Input can stream in a sequence as +// a document. +template <typename T> +inline +typename llvm::enable_if_c<has_SequenceTraits<T>::value,Input &>::type +operator>>(Input &yin, T &docSeq) { + yin.setCurrentDocument(); + yamlize(yin, docSeq, true); + return yin; +} + +#ifndef BUILDING_YAMLIO +// Provide better error message about types missing a trait specialization +template <typename T> +inline +typename llvm::enable_if_c<missingTraits<T>::value,Input &>::type +operator>>(Input &yin, T &docSeq) { + char missing_yaml_trait_for_type[sizeof(MissingTrait<T>)]; + return yin; +} +#endif + + +// Define non-member operator<< so that Output can stream out document list. +template <typename T> +inline +typename llvm::enable_if_c<has_DocumentListTraits<T>::value,Output &>::type +operator<<(Output &yout, T &docList) { + yout.beginDocuments(); + const size_t count = DocumentListTraits<T>::size(yout, docList); + for(size_t i=0; i < count; ++i) { + if ( yout.preflightDocument(i) ) { + yamlize(yout, DocumentListTraits<T>::element(yout, docList, i), true); + yout.postflightDocument(); + } + } + yout.endDocuments(); + return yout; +} + +// Define non-member operator<< so that Output can stream out a map. +template <typename T> +inline +typename llvm::enable_if_c<has_MappingTraits<T>::value,Output &>::type +operator<<(Output &yout, T &map) { + yout.beginDocuments(); + if ( yout.preflightDocument(0) ) { + yamlize(yout, map, true); + yout.postflightDocument(); + } + yout.endDocuments(); + return yout; +} + +// Define non-member operator<< so that Output can stream out a sequence. +template <typename T> +inline +typename llvm::enable_if_c<has_SequenceTraits<T>::value,Output &>::type +operator<<(Output &yout, T &seq) { + yout.beginDocuments(); + if ( yout.preflightDocument(0) ) { + yamlize(yout, seq, true); + yout.postflightDocument(); + } + yout.endDocuments(); + return yout; +} + +#ifndef BUILDING_YAMLIO +// Provide better error message about types missing a trait specialization +template <typename T> +inline +typename llvm::enable_if_c<missingTraits<T>::value,Output &>::type +operator<<(Output &yout, T &seq) { + char missing_yaml_trait_for_type[sizeof(MissingTrait<T>)]; + return yout; +} +#endif + + +} // namespace yaml +} // namespace llvm + + +/// Utility for declaring that a std::vector of a particular type +/// should be considered a YAML sequence. +#define LLVM_YAML_IS_SEQUENCE_VECTOR(_type) \ + namespace llvm { \ + namespace yaml { \ + template<> \ + struct SequenceTraits< std::vector<_type> > { \ + static size_t size(IO &io, std::vector<_type> &seq) { \ + return seq.size(); \ + } \ + static _type& element(IO &io, std::vector<_type> &seq, size_t index) {\ + if ( index >= seq.size() ) \ + seq.resize(index+1); \ + return seq[index]; \ + } \ + }; \ + } \ + } + +/// Utility for declaring that a std::vector of a particular type +/// should be considered a YAML flow sequence. +#define LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(_type) \ + namespace llvm { \ + namespace yaml { \ + template<> \ + struct SequenceTraits< std::vector<_type> > { \ + static size_t size(IO &io, std::vector<_type> &seq) { \ + return seq.size(); \ + } \ + static _type& element(IO &io, std::vector<_type> &seq, size_t index) {\ + if ( index >= seq.size() ) \ + seq.resize(index+1); \ + return seq[index]; \ + } \ + static const bool flow = true; \ + }; \ + } \ + } + +/// Utility for declaring that a std::vector of a particular type +/// should be considered a YAML document list. +#define LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(_type) \ + namespace llvm { \ + namespace yaml { \ + template<> \ + struct DocumentListTraits< std::vector<_type> > { \ + static size_t size(IO &io, std::vector<_type> &seq) { \ + return seq.size(); \ + } \ + static _type& element(IO &io, std::vector<_type> &seq, size_t index) {\ + if ( index >= seq.size() ) \ + seq.resize(index+1); \ + return seq[index]; \ + } \ + }; \ + } \ + } + + + +#endif // LLVM_YAML_TRAITS_H_ diff --git a/lib/Support/CMakeLists.txt b/lib/Support/CMakeLists.txt index 6af0f4a6c9..f294a175e7 100644 --- a/lib/Support/CMakeLists.txt +++ b/lib/Support/CMakeLists.txt @@ -50,6 +50,7 @@ add_llvm_library(LLVMSupport Triple.cpp Twine.cpp YAMLParser.cpp + YAMLTraits.cpp raw_os_ostream.cpp raw_ostream.cpp regcomp.c diff --git a/lib/Support/YAMLTraits.cpp b/lib/Support/YAMLTraits.cpp new file mode 100644 index 0000000000..e2be15be50 --- /dev/null +++ b/lib/Support/YAMLTraits.cpp @@ -0,0 +1,881 @@ +//===- lib/Support/YAMLTraits.cpp -----------------------------------------===// +// +// The LLVM Linker +// +// This file is distributed under the University of Illinois Open Source +// License. See LICENSE.TXT for details. +// +//===----------------------------------------------------------------------===// + +#define BUILDING_YAMLIO +#include "llvm/Support/YAMLTraits.h" + +#include "llvm/ADT/Twine.h" +#include "llvm/Support/Casting.h" +#include "llvm/Support/ErrorHandling.h" +#include "llvm/Support/format.h" +#include "llvm/Support/raw_ostream.h" +#include "llvm/Support/YAMLParser.h" + +#include <cstring> + +namespace llvm { +namespace yaml { + + + +//===----------------------------------------------------------------------===// +// IO +//===----------------------------------------------------------------------===// + +IO::IO(void *Context) : Ctxt(Context) { +} + +IO::~IO() { +} + +void *IO::getContext() { + return Ctxt; +} + +void IO::setContext(void *Context) { + Ctxt = Context; +} + + +//===----------------------------------------------------------------------===// +// Input +//===----------------------------------------------------------------------===// + +Input::Input(StringRef InputContent, void *Ctxt) + : IO(Ctxt), CurrentNode(NULL) { + Strm = new Stream(InputContent, SrcMgr); + DocIterator = Strm->begin(); +} + + +llvm::error_code Input::error() { + return EC; +} + +void Input::setDiagHandler(llvm::SourceMgr::DiagHandlerTy Handler, void *Ctxt) { + SrcMgr.setDiagHandler(Handler, Ctxt); +} + +bool Input::outputting() { + return false; +} + +bool Input::setCurrentDocument() { + if ( DocIterator != Strm->end() ) { + Node *N = DocIterator->getRoot(); + if (llvm::isa<NullNode>(N)) { + // Empty files are allowed and ignored + ++DocIterator; + return setCurrentDocument(); + } + CurrentNode = this->createHNodes(N); + return true; + } + return false; +} + +void Input::nextDocument() { + ++DocIterator; +} + +void Input::beginMapping() { + if ( EC ) + return; + MapHNode *MN = llvm::dyn_cast<MapHNode>(CurrentNode); + if ( MN ) { + MN->ValidKeys.clear(); + } +} + +bool Input::preflightKey(const char *Key, bool Required, bool, + bool &UseDefault, void *&SaveInfo) { + UseDefault = false; + if ( EC ) + return false; + MapHNode *MN = llvm::dyn_cast<MapHNode>(CurrentNode); + if ( !MN ) { + setError(CurrentNode, "not a mapping"); + return false; + } + MN->ValidKeys.push_back(Key); + HNode *Value = MN->Mapping[Key]; + if ( !Value ) { + if ( Required ) + setError(CurrentNode, Twine("missing required key '") + Key + "'"); + else + UseDefault = true; + return false; + } + SaveInfo = CurrentNode; + CurrentNode = Value; + return true; +} + +void Input::postflightKey(void *saveInfo) { + CurrentNode = reinterpret_cast<HNode*>(saveInfo); +} + +void Input::endMapping() { + if ( EC ) + return; + MapHNode *MN = llvm::dyn_cast<MapHNode>(CurrentNode); + if ( !MN ) + return; + for (MapHNode::NameToNode::iterator i=MN->Mapping.begin(), + End=MN->Mapping.end(); i != End; ++i) { + if ( ! MN->isValidKey(i->first) ) { + setError(i->second, Twine("unknown key '") + i->first + "'" ); + break; + } + } +} + + +unsigned Input::beginSequence() { + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + return SQ->Entries.size(); + } + return 0; +} +void Input::endSequence() { +} +bool Input::preflightElement(unsigned Index, void *&SaveInfo) { + if ( EC ) + return false; + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + SaveInfo = CurrentNode; + CurrentNode = SQ->Entries[Index]; + return true; + } + return false; +} +void Input::postflightElement(void *SaveInfo) { + CurrentNode = reinterpret_cast<HNode*>(SaveInfo); +} + +unsigned Input::beginFlowSequence() { + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + return SQ->Entries.size(); + } + return 0; +} +bool Input::preflightFlowElement(unsigned index, void *&SaveInfo) { + if ( EC ) + return false; + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + SaveInfo = CurrentNode; + CurrentNode = SQ->Entries[index]; + return true; + } + return false; +} +void Input::postflightFlowElement(void *SaveInfo) { + CurrentNode = reinterpret_cast<HNode*>(SaveInfo); +} +void Input::endFlowSequence() { +} + + +void Input::beginEnumScalar() { + ScalarMatchFound = false; +} + +bool Input::matchEnumScalar(const char *Str, bool) { + if ( ScalarMatchFound ) + return false; + if ( ScalarHNode *SN = llvm::dyn_cast<ScalarHNode>(CurrentNode) ) { + if ( SN->value().equals(Str) ) { + ScalarMatchFound = true; + return true; + } + } + return false; +} + +void Input::endEnumScalar() { + if ( !ScalarMatchFound ) { + setError(CurrentNode, "unknown enumerated scalar"); + } +} + + + +bool Input::beginBitSetScalar(bool &DoClear) { + BitValuesUsed.clear(); + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + BitValuesUsed.insert(BitValuesUsed.begin(), SQ->Entries.size(), false); + } + else { + setError(CurrentNode, "expected sequence of bit values"); + } + DoClear = true; + return true; +} + +bool Input::bitSetMatch(const char *Str, bool) { + if ( EC ) + return false; + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + unsigned Index = 0; + for (std::vector<HNode*>::iterator i=SQ->Entries.begin(), + End=SQ->Entries.end(); i != End; ++i) { + if ( ScalarHNode *SN = llvm::dyn_cast<ScalarHNode>(*i) ) { + if ( SN->value().equals(Str) ) { + BitValuesUsed[Index] = true; + return true; + } + } + else { + setError(CurrentNode, "unexpected scalar in sequence of bit values"); + } + ++Index; + } + } + else { + setError(CurrentNode, "expected sequence of bit values"); + } + return false; +} + +void Input::endBitSetScalar() { + if ( EC ) + return; + if ( SequenceHNode *SQ = llvm::dyn_cast<SequenceHNode>(CurrentNode) ) { + assert(BitValuesUsed.size() == SQ->Entries.size()); + for ( unsigned i=0; i < SQ->Entries.size(); ++i ) { + if ( !BitValuesUsed[i] ) { + setError(SQ->Entries[i], "unknown bit value"); + return; + } + } + } +} + + +void Input::scalarString(StringRef &S) { + if ( ScalarHNode *SN = llvm::dyn_cast<ScalarHNode>(CurrentNode) ) { + S = SN->value(); + } + else { + setError(CurrentNode, "unexpected scalar"); + } +} + +void Input::setError(HNode *hnode, const Twine &message) { + this->setError(hnode->_node, message); +} + +void Input::setError(Node *node, const Twine &message) { + Strm->printError(node, message); + EC = make_error_code(errc::invalid_argument); +} + +Input::HNode *Input::createHNodes(Node *N) { + llvm::SmallString<128> StringStorage; + if ( ScalarNode *SN = llvm::dyn_cast<ScalarNode>(N) ) { + StringRef KeyStr = SN->getValue(StringStorage); + if ( !StringStorage.empty() ) { + // Copy string to permanent storage + unsigned Len = StringStorage.size(); + char* Buf = Allocator.Allocate<char>(Len); + memcpy(Buf, &StringStorage[0], Len); + KeyStr = StringRef(Buf, Len); + } + return new (Allocator) ScalarHNode(N, KeyStr); + } + else if ( SequenceNode *SQ = llvm::dyn_cast<SequenceNode>(N) ) { + SequenceHNode *SQHNode = new (Allocator) SequenceHNode(N); + for (SequenceNode::iterator i=SQ->begin(),End=SQ->end(); i != End; ++i ) { + HNode *Entry = this->createHNodes(i); + if ( EC ) + break; + SQHNode->Entries.push_back(Entry); + } + return SQHNode; + } + else if ( MappingNode *Map = llvm::dyn_cast<MappingNode>(N) ) { + MapHNode *mapHNode = new (Allocator) MapHNode(N); + for (MappingNode::iterator i=Map->begin(), End=Map->end(); i != End; ++i ) { + ScalarNode *KeyScalar = llvm::dyn_cast<ScalarNode>(i->getKey()); + StringStorage.clear(); + llvm::StringRef KeyStr = KeyScalar->getValue(StringStorage); + if ( !StringStorage.empty() ) { + // Copy string to permanent storage + unsigned Len = StringStorage.size(); + char* Buf = Allocator.Allocate<char>(Len); + memcpy(Buf, &StringStorage[0], Len); + KeyStr = StringRef(Buf, Len); + } + HNode *ValueHNode = this->createHNodes(i->getValue()); + if ( EC ) + break; + mapHNode->Mapping[KeyStr] = ValueHNode; + } + return mapHNode; + } + else if ( llvm::isa<NullNode>(N) ) { + return new (Allocator) EmptyHNode(N); + } + else { + setError(N, "unknown node kind"); + return NULL; + } +} + + +bool Input::MapHNode::isValidKey(StringRef Key) { + for (SmallVector<const char*, 6>::iterator i=ValidKeys.begin(), + End=ValidKeys.end(); i != End; ++i) { + if ( Key.equals(*i) ) + return true; + } + return false; +} + +void Input::setError(const Twine &Message) { + this->setError(CurrentNode, Message); +} + + +//===----------------------------------------------------------------------===// +// Output +//===----------------------------------------------------------------------===// + +Output::Output(llvm::raw_ostream &yout, void *context) + : IO(context), Out(yout), Column(0), ColumnAtFlowStart(0), + NeedBitValueComma(false), NeedFlowSequenceComma(false), + EnumerationMatchFound(false), NeedsNewLine(false) { +} + +Output::~Output() { +} + +bool Output::outputting() { + return true; +} + +void Output::beginMapping() { + StateStack.push_back(inMapFirstKey); + NeedsNewLine = true; +} + +void Output::endMapping() { + StateStack.pop_back(); +} + + +bool Output::preflightKey(const char *Key, bool Required, bool SameAsDefault, + bool &UseDefault, void *&) { + UseDefault = false; + if ( Required || !SameAsDefault ) { + this->newLineCheck(); + this->paddedKey(Key); + return true; + } + return false; +} + +void Output::postflightKey(void*) { + if ( StateStack.back() == inMapFirstKey ) { + StateStack.pop_back(); + StateStack.push_back(inMapOtherKey); + } +} + +void Output::beginDocuments() { + this->outputUpToEndOfLine("---"); +} + +bool Output::preflightDocument(unsigned index) { + if ( index > 0 ) + this->outputUpToEndOfLine("\n---"); + return true; +} + +void Output::postflightDocument() { +} + +void Output::endDocuments() { + output("\n...\n"); +} + +unsigned Output::beginSequence() { + StateStack.push_back(inSeq); + NeedsNewLine = true; + return 0; +} +void Output::endSequence() { + StateStack.pop_back(); +} +bool Output::preflightElement(unsigned , void *&) { + return true; +} +void Output::postflightElement(void*) { +} + +unsigned Output::beginFlowSequence() { + this->newLineCheck(); + StateStack.push_back(inFlowSeq); + ColumnAtFlowStart = Column; + output("[ "); + NeedFlowSequenceComma = false; + return 0; +} +void Output::endFlowSequence() { + StateStack.pop_back(); + this->outputUpToEndOfLine(" ]"); +} +bool Output::preflightFlowElement(unsigned , void *&) { + if ( NeedFlowSequenceComma ) + output(", "); + if ( Column > 70 ) { + output("\n"); + for(int i=0; i < ColumnAtFlowStart; ++i) + output(" "); + Column = ColumnAtFlowStart; + output(" "); + } + return true; +} +void Output::postflightFlowElement(void*) { + NeedFlowSequenceComma = true; +} + + + +void Output::beginEnumScalar() { + EnumerationMatchFound = false; +} + +bool Output::matchEnumScalar(const char *Str, bool Match) { + if ( Match && !EnumerationMatchFound ) { + this->newLineCheck(); + this->outputUpToEndOfLine(Str); + EnumerationMatchFound = true; + } + return false; +} + +void Output::endEnumScalar() { + if ( !EnumerationMatchFound ) + llvm_unreachable("bad runtime enum value"); +} + + + +bool Output::beginBitSetScalar(bool &DoClear) { + this->newLineCheck(); + output("[ "); + NeedBitValueComma = false; + DoClear = false; + return true; +} + +bool Output::bitSetMatch(const char *Str, bool Matches) { + if ( Matches ) { + if ( NeedBitValueComma ) + output(", "); + this->output(Str); + NeedBitValueComma = true; + } + return false; +} + +void Output::endBitSetScalar() { + this->outputUpToEndOfLine(" ]"); +} + +void Output::scalarString(StringRef &S) { + this->newLineCheck(); + if (S.find('\n') == StringRef::npos) { + // No embedded new-line chars, just print string. + this->outputUpToEndOfLine(S); + return; + } + unsigned i = 0; + unsigned j = 0; + unsigned End = S.size(); + output("'"); // Starting single quote. + const char *Base = S.data(); + while (j < End) { + // Escape a single quote by doubling it. + if (S[j] == '\'') { + output(StringRef(&Base[i], j - i + 1)); + output("'"); + i = j + 1; + } + ++j; + } + output(StringRef(&Base[i], j - i)); + this->outputUpToEndOfLine("'"); // Ending single quote. +} + +void Output::setError(const Twine &message) { +} + + +void Output::output(StringRef s) { + Column += s.size(); + Out << s; +} + +void Output::outputUpToEndOfLine(StringRef s) { + this->output(s); + if ( StateStack.back() != inFlowSeq ) + NeedsNewLine = true; +} + +void Output::outputNewLine() { + Out << "\n"; + Column = 0; +} + +// if seq at top, indent as if map, then add "- " +// if seq in middle, use "- " if firstKey, else use " " +// + +void Output::newLineCheck() { + if ( ! NeedsNewLine ) + return; + NeedsNewLine = false; + + this->outputNewLine(); + + assert(StateStack.size() > 0); + unsigned Indent = StateStack.size() - 1; + bool OutputDash = false; + + if ( StateStack.back() == inSeq ) { + OutputDash = true; + } + else if ( (StateStack.size() > 1) + && (StateStack.back() == inMapFirstKey) + && (StateStack[StateStack.size()-2] == inSeq) ) { + --Indent; + OutputDash = true; + } + + for (unsigned i=0; i < Indent; ++i) { + output(" "); + } + if ( OutputDash ) { + output("- "); + } + +} + +void Output::paddedKey(StringRef key) { + output(key); + output(":"); + const char *spaces = " "; + if ( key.size() < strlen(spaces) ) + output(&spaces[key.size()]); + else + output(" "); +} + +//===----------------------------------------------------------------------===// +// traits for built-in types +//===----------------------------------------------------------------------===// + +template<> +struct ScalarTraits<bool> { + static void output(const bool &Val, void*, llvm::raw_ostream &Out) { + Out << ( Val ? "true" : "false"); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, bool &Val) { + if ( Scalar.equals("true") ) { + Val = true; + return StringRef(); + } + else if ( Scalar.equals("false") ) { + Val = false; + return StringRef(); + } + return "invalid boolean"; + } +}; + + +template<> +struct ScalarTraits<StringRef> { + static void output(const StringRef &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, StringRef &Val){ + Val = Scalar; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<uint8_t> { + static void output(const uint8_t &Val, void*, llvm::raw_ostream &Out) { + // use temp uin32_t because ostream thinks uint8_t is a character + uint32_t Num = Val; + Out << Num; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, uint8_t &Val) { + uint64_t n; + if ( getAsUnsignedInteger(Scalar, 0, n) ) + return "invalid number"; + if ( n > 0xFF ) + return "out of range number"; + Val = n; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<uint16_t> { + static void output(const uint16_t &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, uint16_t &Val) { + uint64_t n; + if ( getAsUnsignedInteger(Scalar, 0, n) ) + return "invalid number"; + if ( n > 0xFFFF ) + return "out of range number"; + Val = n; + return StringRef(); + } +}; + +template<> +struct ScalarTraits<uint32_t> { + static void output(const uint32_t &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, uint32_t &Val) { + uint64_t n; + if ( getAsUnsignedInteger(Scalar, 0, n) ) + return "invalid number"; + if ( n > 0xFFFFFFFFUL ) + return "out of range number"; + Val = n; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<uint64_t> { + static void output(const uint64_t &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, uint64_t &Val) { + if ( getAsUnsignedInteger(Scalar, 0, Val) ) + return "invalid number"; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<int8_t> { + static void output(const int8_t &Val, void*, llvm::raw_ostream &Out) { + // use temp in32_t because ostream thinks int8_t is a character + int32_t Num = Val; + Out << Num; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, int8_t &Val) { + int64_t n; + if ( getAsSignedInteger(Scalar, 0, n) ) + return "invalid number"; + if ( (n > 127) || (n < -128) ) + return "out of range number"; + Val = n; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<int16_t> { + static void output(const int16_t &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, int16_t &Val) { + int64_t n; + if ( getAsSignedInteger(Scalar, 0, n) ) + return "invalid number"; + if ( (n > INT16_MAX) || (n < INT16_MIN) ) + return "out of range number"; + Val = n; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<int32_t> { + static void output(const int32_t &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, int32_t &Val) { + int64_t n; + if ( getAsSignedInteger(Scalar, 0, n) ) + return "invalid number"; + if ( (n > INT32_MAX) || (n < INT32_MIN) ) + return "out of range number"; + Val = n; + return StringRef(); + } +}; + +template<> +struct ScalarTraits<int64_t> { + static void output(const int64_t &Val, void*, llvm::raw_ostream &Out) { + Out << Val; + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, int64_t &Val) { + if ( getAsSignedInteger(Scalar, 0, Val) ) + return "invalid number"; + return StringRef(); + } +}; + +template<> +struct ScalarTraits<double> { + static void output(const double &Val, void*, llvm::raw_ostream &Out) { + Out << format("%g", Val); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, double &Val) { + SmallString<32> buff(Scalar.begin(), Scalar.end()); + char *end; + Val = strtod(buff.c_str(), &end); + if ( *end != '\0' ) + return "invalid floating point number"; + return StringRef(); + } +}; + +template<> +struct ScalarTraits<float> { + static void output(const float &Val, void*, llvm::raw_ostream &Out) { + Out << format("%g", Val); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, float &Val) { + SmallString<32> buff(Scalar.begin(), Scalar.end()); + char *end; + Val = strtod(buff.c_str(), &end); + if ( *end != '\0' ) + return "invalid floating point number"; + return StringRef(); + } +}; + + + +template<> +struct ScalarTraits<Hex8> { + static void output(const Hex8 &Val, void*, llvm::raw_ostream &Out) { + uint8_t Num = Val; + Out << format("0x%02X", Num); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, Hex8 &Val) { + uint64_t n; + if ( getAsUnsignedInteger(Scalar, 0, n) ) + return "invalid hex8 number"; + if ( n > 0xFF ) + return "out of range hex8 number"; + Val = n; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<Hex16> { + static void output(const Hex16 &Val, void*, llvm::raw_ostream &Out) { + uint16_t Num = Val; + Out << format("0x%04X", Num); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, Hex16 &Val) { + uint64_t n; + if ( getAsUnsignedInteger(Scalar, 0, n) ) + return "invalid hex16 number"; + if ( n > 0xFFFF ) + return "out of range hex16 number"; + Val = n; + return StringRef(); + } +}; + +template<> +struct ScalarTraits<Hex32> { + static void output(const Hex32 &Val, void*, llvm::raw_ostream &Out) { + uint32_t Num = Val; + Out << format("0x%08X", Num); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, Hex32 &Val) { + uint64_t n; + if ( getAsUnsignedInteger(Scalar, 0, n) ) + return "invalid hex32 number"; + if ( n > 0xFFFFFFFFUL ) + return "out of range hex32 number"; + Val = n; + return StringRef(); + } +}; + + +template<> +struct ScalarTraits<Hex64> { + static void output(const Hex64 &Val, void*, llvm::raw_ostream &Out) { + uint64_t Num = Val; + Out << format("0x%016llX", Num); + } + static llvm::StringRef input(llvm::StringRef Scalar, void*, Hex64 &Val) { + uint64_t Num; + if ( getAsUnsignedInteger(Scalar, 0, Num) ) + return "invalid hex64 number"; + Val = Num; + return StringRef(); + } +}; + + + + +// We want all the ScalarTrait specialized on built-in types +// to be instantiated here. +template <typename T> +struct ForceUse { + ForceUse() : oproc(ScalarTraits<T>::output), iproc(ScalarTraits<T>::input) {} + void (*oproc)(const T &, void*, llvm::raw_ostream &); + llvm::StringRef (*iproc)(llvm::StringRef, void*, T &); +}; + +static ForceUse<bool> Dummy1; +static ForceUse<llvm::StringRef> Dummy2; +static ForceUse<uint8_t> Dummy3; +static ForceUse<uint16_t> Dummy4; +static ForceUse<uint32_t> Dummy5; +static ForceUse<uint64_t> Dummy6; +static ForceUse<int8_t> Dummy7; +static ForceUse<int16_t> Dummy8; +static ForceUse<int32_t> Dummy9; +static ForceUse<int64_t> Dummy10; +static ForceUse<float> Dummy11; +static ForceUse<double> Dummy12; +static ForceUse<Hex8> Dummy13; +static ForceUse<Hex16> Dummy14; +static ForceUse<Hex32> Dummy15; +static ForceUse<Hex64> Dummy16; + + + +} // namespace yaml +} // namespace llvm + + diff --git a/unittests/Support/CMakeLists.txt b/unittests/Support/CMakeLists.txt index 09a0ea50d7..f6a5949cdb 100644 --- a/unittests/Support/CMakeLists.txt +++ b/unittests/Support/CMakeLists.txt @@ -24,6 +24,7 @@ add_llvm_unittest(SupportTests SwapByteOrderTest.cpp TimeValue.cpp ValueHandleTest.cpp + YAMLIOTest.cpp YAMLParserTest.cpp formatted_raw_ostream_test.cpp raw_ostream_test.cpp diff --git a/unittests/Support/YAMLIOTest.cpp b/unittests/Support/YAMLIOTest.cpp new file mode 100644 index 0000000000..c24114a695 --- /dev/null +++ b/unittests/Support/YAMLIOTest.cpp @@ -0,0 +1,1288 @@ +//===- unittest/Support/YAMLIOTest.cpp ------------------------------------===// +// +// The LLVM Compiler Infrastructure +// +// This file is distributed under the University of Illinois Open Source +// License. See LICENSE.TXT for details. +// +//===----------------------------------------------------------------------===// + +#include "llvm/ADT/SmallString.h" +#include "llvm/ADT/Twine.h" +#include "llvm/Support/Casting.h" +#include "llvm/Support/Format.h" +#include "llvm/Support/YAMLTraits.h" +#include "gtest/gtest.h" + + +using llvm::yaml::Input; +using llvm::yaml::Output; +using llvm::yaml::IO; +using llvm::yaml::MappingTraits; +using llvm::yaml::MappingNormalization; +using llvm::yaml::ScalarTraits; +using llvm::yaml::Hex8; +using llvm::yaml::Hex16; +using llvm::yaml::Hex32; +using llvm::yaml::Hex64; + + +//===----------------------------------------------------------------------===// +// Test MappingTraits +//===----------------------------------------------------------------------===// + +struct FooBar { + int foo; + int bar; +}; +typedef std::vector<FooBar> FooBarSequence; + +LLVM_YAML_IS_SEQUENCE_VECTOR(FooBar) + + +namespace llvm { +namespace yaml { + template <> + struct MappingTraits<FooBar> { + static void mapping(IO &io, FooBar& fb) { + io.mapRequired("foo", fb.foo); + io.mapRequired("bar", fb.bar); + } + }; +} +} + + +// +// Test the reading of a yaml mapping +// +TEST(YAMLIO, TestMapRead) { + FooBar doc; + Input yin("---\nfoo: 3\nbar: 5\n...\n"); + yin >> doc; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(doc.foo, 3); + EXPECT_EQ(doc.bar,5); +} + + +// +// Test the reading of a yaml sequence of mappings +// +TEST(YAMLIO, TestSequenceMapRead) { + FooBarSequence seq; + Input yin("---\n - foo: 3\n bar: 5\n - foo: 7\n bar: 9\n...\n"); + yin >> seq; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(seq.size(), 2UL); + FooBar& map1 = seq[0]; + FooBar& map2 = seq[1]; + EXPECT_EQ(map1.foo, 3); + EXPECT_EQ(map1.bar, 5); + EXPECT_EQ(map2.foo, 7); + EXPECT_EQ(map2.bar, 9); +} + + +// +// Test writing then reading back a sequence of mappings +// +TEST(YAMLIO, TestSequenceMapWriteAndRead) { + std::string intermediate; + { + FooBar entry1; + entry1.foo = 10; + entry1.bar = -3; + FooBar entry2; + entry2.foo = 257; + entry2.bar = 0; + FooBarSequence seq; + seq.push_back(entry1); + seq.push_back(entry2); + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << seq; + } + + { + Input yin(intermediate); + FooBarSequence seq2; + yin >> seq2; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(seq2.size(), 2UL); + FooBar& map1 = seq2[0]; + FooBar& map2 = seq2[1]; + EXPECT_EQ(map1.foo, 10); + EXPECT_EQ(map1.bar, -3); + EXPECT_EQ(map2.foo, 257); + EXPECT_EQ(map2.bar, 0); + } +} + + +//===----------------------------------------------------------------------===// +// Test built-in types +//===----------------------------------------------------------------------===// + +struct BuiltInTypes { + llvm::StringRef str; + uint64_t u64; + uint32_t u32; + uint16_t u16; + uint8_t u8; + bool b; + int64_t s64; + int32_t s32; + int16_t s16; + int8_t s8; + float f; + double d; + Hex8 h8; + Hex16 h16; + Hex32 h32; + Hex64 h64; +}; + +namespace llvm { +namespace yaml { + template <> + struct MappingTraits<BuiltInTypes> { + static void mapping(IO &io, BuiltInTypes& bt) { + io.mapRequired("str", bt.str); + io.mapRequired("u64", bt.u64); + io.mapRequired("u32", bt.u32); + io.mapRequired("u16", bt.u16); + io.mapRequired("u8", bt.u8); + io.mapRequired("b", bt.b); + io.mapRequired("s64", bt.s64); + io.mapRequired("s32", bt.s32); + io.mapRequired("s16", bt.s16); + io.mapRequired("s8", bt.s8); + io.mapRequired("f", bt.f); + io.mapRequired("d", bt.d); + io.mapRequired("h8", bt.h8); + io.mapRequired("h16", bt.h16); + io.mapRequired("h32", bt.h32); + io.mapRequired("h64", bt.h64); + } + }; +} +} + + +// +// Test the reading of all built-in scalar conversions +// +TEST(YAMLIO, TestReadBuiltInTypes) { + BuiltInTypes map; + Input yin("---\n" + "str: hello there\n" + "u64: 5000000000\n" + "u32: 4000000000\n" + "u16: 65000\n" + "u8: 255\n" + "b: false\n" + "s64: -5000000000\n" + "s32: -2000000000\n" + "s16: -32000\n" + "s8: -127\n" + "f: 137.125\n" + "d: -2.8625\n" + "h8: 0xFF\n" + "h16: 0x8765\n" + "h32: 0xFEDCBA98\n" + "h64: 0xFEDCBA9876543210\n" + "...\n"); + yin >> map; + + EXPECT_FALSE(yin.error()); + EXPECT_TRUE(map.str.equals("hello there")); + EXPECT_EQ(map.u64, 5000000000ULL); + EXPECT_EQ(map.u32, 4000000000); + EXPECT_EQ(map.u16, 65000); + EXPECT_EQ(map.u8, 255); + EXPECT_EQ(map.b, false); + EXPECT_EQ(map.s64, -5000000000LL); + EXPECT_EQ(map.s32, -2000000000L); + EXPECT_EQ(map.s16, -32000); + EXPECT_EQ(map.s8, -127); + EXPECT_EQ(map.f, 137.125); + EXPECT_EQ(map.d, -2.8625); + EXPECT_EQ(map.h8, Hex8(255)); + EXPECT_EQ(map.h16, Hex16(0x8765)); + EXPECT_EQ(map.h32, Hex32(0xFEDCBA98)); + EXPECT_EQ(map.h64, Hex64(0xFEDCBA9876543210LL)); +} + + +// +// Test writing then reading back all built-in scalar types +// +TEST(YAMLIO, TestReadWriteBuiltInTypes) { + std::string intermediate; + { + BuiltInTypes map; + map.str = "one two"; + map.u64 = 6000000000; + map.u32 = 3000000000; + map.u16 = 50000; + map.u8 = 254; + map.b = true; + map.s64 = -6000000000; + map.s32 = -2000000000; + map.s16 = -32000; + map.s8 = -128; + map.f = 3.25; + map.d = -2.8625; + map.h8 = 254; + map.h16 = 50000; + map.h32 = 3000000000; + map.h64 = 6000000000LL; + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << map; + } + + { + Input yin(intermediate); + BuiltInTypes map; + yin >> map; + + EXPECT_FALSE(yin.error()); + EXPECT_TRUE(map.str.equals("one two")); + EXPECT_EQ(map.u64, 6000000000ULL); + EXPECT_EQ(map.u32, 3000000000UL); + EXPECT_EQ(map.u16, 50000); + EXPECT_EQ(map.u8, 254); + EXPECT_EQ(map.b, true); + EXPECT_EQ(map.s64, -6000000000LL); + EXPECT_EQ(map.s32, -2000000000L); + EXPECT_EQ(map.s16, -32000); + EXPECT_EQ(map.s8, -128); + EXPECT_EQ(map.f, 3.25); + EXPECT_EQ(map.d, -2.8625); + EXPECT_EQ(map.h8, Hex8(254)); + EXPECT_EQ(map.h16, Hex16(50000)); + EXPECT_EQ(map.h32, Hex32(3000000000)); + EXPECT_EQ(map.h64, Hex64(6000000000LL)); + } +} + + + +//===----------------------------------------------------------------------===// +// Test ScalarEnumerationTraits +//===----------------------------------------------------------------------===// + +enum Colors { + cRed, + cBlue, + cGreen, + cYellow +}; + +struct ColorMap { + Colors c1; + Colors c2; + Colors c3; + Colors c4; + Colors c5; + Colors c6; +}; + +namespace llvm { +namespace yaml { + template <> + struct ScalarEnumerationTraits<Colors> { + static void enumeration(IO &io, Colors &value) { + io.enumCase(value, "red", cRed); + io.enumCase(value, "blue", cBlue); + io.enumCase(value, "green", cGreen); + io.enumCase(value, "yellow",cYellow); + } + }; + template <> + struct MappingTraits<ColorMap> { + static void mapping(IO &io, ColorMap& c) { + io.mapRequired("c1", c.c1); + io.mapRequired("c2", c.c2); + io.mapRequired("c3", c.c3); + io.mapOptional("c4", c.c4, cBlue); // supplies default + io.mapOptional("c5", c.c5, cYellow); // supplies default + io.mapOptional("c6", c.c6, cRed); // supplies default + } + }; +} +} + + +// +// Test reading enumerated scalars +// +TEST(YAMLIO, TestEnumRead) { + ColorMap map; + Input yin("---\n" + "c1: blue\n" + "c2: red\n" + "c3: green\n" + "c5: yellow\n" + "...\n"); + yin >> map; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(cBlue, map.c1); + EXPECT_EQ(cRed, map.c2); + EXPECT_EQ(cGreen, map.c3); + EXPECT_EQ(cBlue, map.c4); // tests default + EXPECT_EQ(cYellow,map.c5); // tests overridden + EXPECT_EQ(cRed, map.c6); // tests default +} + + + +//===----------------------------------------------------------------------===// +// Test ScalarBitSetTraits +//===----------------------------------------------------------------------===// + +enum MyFlags { + flagNone = 0, + flagBig = 1 << 0, + flagFlat = 1 << 1, + flagRound = 1 << 2, + flagPointy = 1 << 3 +}; +inline MyFlags operator|(MyFlags a, MyFlags b) { + return static_cast<MyFlags>( + static_cast<uint32_t>(a) | static_cast<uint32_t>(b)); +} + +struct FlagsMap { + MyFlags f1; + MyFlags f2; + MyFlags f3; + MyFlags f4; +}; + + +namespace llvm { +namespace yaml { + template <> + struct ScalarBitSetTraits<MyFlags> { + static void bitset(IO &io, MyFlags &value) { + io.bitSetCase(value, "big", flagBig); + io.bitSetCase(value, "flat", flagFlat); + io.bitSetCase(value, "round", flagRound); + io.bitSetCase(value, "pointy",flagPointy); + } + }; + template <> + struct MappingTraits<FlagsMap> { + static void mapping(IO &io, FlagsMap& c) { + io.mapRequired("f1", c.f1); + io.mapRequired("f2", c.f2); + io.mapRequired("f3", c.f3); + io.mapOptional("f4", c.f4, MyFlags(flagRound)); + } + }; +} +} + + +// +// Test reading flow sequence representing bit-mask values +// +TEST(YAMLIO, TestFlagsRead) { + FlagsMap map; + Input yin("---\n" + "f1: [ big ]\n" + "f2: [ round, flat ]\n" + "f3: []\n" + "...\n"); + yin >> map; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(flagBig, map.f1); + EXPECT_EQ(flagRound|flagFlat, map.f2); + EXPECT_EQ(flagNone, map.f3); // check empty set + EXPECT_EQ(flagRound, map.f4); // check optional key +} + + +// +// Test writing then reading back bit-mask values +// +TEST(YAMLIO, TestReadWriteFlags) { + std::string intermediate; + { + FlagsMap map; + map.f1 = flagBig; + map.f2 = flagRound | flagFlat; + map.f3 = flagNone; + map.f4 = flagNone; + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << map; + } + + { + Input yin(intermediate); + FlagsMap map2; + yin >> map2; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(flagBig, map2.f1); + EXPECT_EQ(flagRound|flagFlat, map2.f2); + EXPECT_EQ(flagNone, map2.f3); + //EXPECT_EQ(flagRound, map2.f4); // check optional key + } +} + + + +//===----------------------------------------------------------------------===// +// Test ScalarTraits +//===----------------------------------------------------------------------===// + +struct MyCustomType { + int length; + int width; +}; + +struct MyCustomTypeMap { + MyCustomType f1; + MyCustomType f2; + int f3; +}; + + +namespace llvm { +namespace yaml { + template <> + struct MappingTraits<MyCustomTypeMap> { + static void mapping(IO &io, MyCustomTypeMap& s) { + io.mapRequired("f1", s.f1); + io.mapRequired("f2", s.f2); + io.mapRequired("f3", s.f3); + } + }; + // MyCustomType is formatted as a yaml scalar. A value of + // {length=3, width=4} would be represented in yaml as "3 by 4". + template<> + struct ScalarTraits<MyCustomType> { + static void output(const MyCustomType &value, void* ctxt, llvm::raw_ostream &out) { + out << llvm::format("%d by %d", value.length, value.width); + } + static StringRef input(StringRef scalar, void* ctxt, MyCustomType &value) { + size_t byStart = scalar.find("by"); + if ( byStart != StringRef::npos ) { + StringRef lenStr = scalar.slice(0, byStart); + lenStr = lenStr.rtrim(); + if ( lenStr.getAsInteger(0, value.length) ) { + return "malformed length"; + } + StringRef widthStr = scalar.drop_front(byStart+2); + widthStr = widthStr.ltrim(); + if ( widthStr.getAsInteger(0, value.width) ) { + return "malformed width"; + } + return StringRef(); + } + else { + return "malformed by"; + } + } + }; +} +} + + +// +// Test writing then reading back custom values +// +TEST(YAMLIO, TestReadWriteMyCustomType) { + std::string intermediate; + { + MyCustomTypeMap map; + map.f1.length = 1; + map.f1.width = 4; + map.f2.length = 100; + map.f2.width = 400; + map.f3 = 10; + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << map; + } + + { + Input yin(intermediate); + MyCustomTypeMap map2; + yin >> map2; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(1, map2.f1.length); + EXPECT_EQ(4, map2.f1.width); + EXPECT_EQ(100, map2.f2.length); + EXPECT_EQ(400, map2.f2.width); + EXPECT_EQ(10, map2.f3); + } +} + + +//===----------------------------------------------------------------------===// +// Test flow sequences +//===----------------------------------------------------------------------===// + +LLVM_YAML_STRONG_TYPEDEF(int, MyNumber) +LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(MyNumber) +LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(llvm::StringRef) + +namespace llvm { +namespace yaml { + template<> + struct ScalarTraits<MyNumber> { + static void output(const MyNumber &value, void *, llvm::raw_ostream &out) { + out << value; + } + + static StringRef input(StringRef scalar, void *, MyNumber &value) { + int64_t n; + if ( getAsSignedInteger(scalar, 0, n) ) + return "invalid number"; + value = n; + return StringRef(); + } + }; +} +} + +struct NameAndNumbers { + llvm::StringRef name; + std::vector<llvm::StringRef> strings; + std::vector<MyNumber> single; + std::vector<MyNumber> numbers; +}; + +namespace llvm { +namespace yaml { + template <> + struct MappingTraits<NameAndNumbers> { + static void mapping(IO &io, NameAndNumbers& nn) { + io.mapRequired("name", nn.name); + io.mapRequired("strings", nn.strings); + io.mapRequired("single", nn.single); + io.mapRequired("numbers", nn.numbers); + } + }; +} +} + + +// +// Test writing then reading back custom values +// +TEST(YAMLIO, TestReadWriteMyFlowSequence) { + std::string intermediate; + { + NameAndNumbers map; + map.name = "hello"; + map.strings.push_back(llvm::StringRef("one")); + map.strings.push_back(llvm::StringRef("two")); + map.single.push_back(1); + map.numbers.push_back(10); + map.numbers.push_back(-30); + map.numbers.push_back(1024); + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << map; + } + + { + Input yin(intermediate); + NameAndNumbers map2; + yin >> map2; + + EXPECT_FALSE(yin.error()); + EXPECT_TRUE(map2.name.equals("hello")); + EXPECT_EQ(map2.strings.size(), 2UL); + EXPECT_TRUE(map2.strings[0].equals("one")); + EXPECT_TRUE(map2.strings[1].equals("two")); + EXPECT_EQ(map2.single.size(), 1UL); + EXPECT_EQ(1, map2.single[0]); + EXPECT_EQ(map2.numbers.size(), 3UL); + EXPECT_EQ(10, map2.numbers[0]); + EXPECT_EQ(-30, map2.numbers[1]); + EXPECT_EQ(1024, map2.numbers[2]); + } +} + + +//===----------------------------------------------------------------------===// +// Test normalizing/denormalizing +//===----------------------------------------------------------------------===// + +LLVM_YAML_STRONG_TYPEDEF(uint32_t, TotalSeconds) + +typedef std::vector<TotalSeconds> SecondsSequence; + +LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(TotalSeconds) + + +namespace llvm { +namespace yaml { + template <> + struct MappingTraits<TotalSeconds> { + + class NormalizedSeconds { + public: + NormalizedSeconds(IO &io) + : hours(0), minutes(0), seconds(0) { + } + NormalizedSeconds(IO &, TotalSeconds &secs) + : hours(secs/3600), + minutes((secs - (hours*3600))/60), + seconds(secs % 60) { + } + TotalSeconds denormalize(IO &) { + return TotalSeconds(hours*3600 + minutes*60 + seconds); + } + + uint32_t hours; + uint8_t minutes; + uint8_t seconds; + }; + + static void mapping(IO &io, TotalSeconds &secs) { + MappingNormalization<NormalizedSeconds, TotalSeconds> keys(io, secs); + + io.mapOptional("hours", keys->hours, (uint32_t)0); + io.mapOptional("minutes", keys->minutes, (uint8_t)0); + io.mapRequired("seconds", keys->seconds); + } + }; +} +} + + +// +// Test the reading of a yaml sequence of mappings +// +TEST(YAMLIO, TestReadMySecondsSequence) { + SecondsSequence seq; + Input yin("---\n - hours: 1\n seconds: 5\n - seconds: 59\n...\n"); + yin >> seq; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(seq.size(), 2UL); + EXPECT_EQ(seq[0], 3605U); + EXPECT_EQ(seq[1], 59U); +} + + +// +// Test writing then reading back custom values +// +TEST(YAMLIO, TestReadWriteMySecondsSequence) { + std::string intermediate; + { + SecondsSequence seq; + seq.push_back(4000); + seq.push_back(500); + seq.push_back(59); + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << seq; + } + { + Input yin(intermediate); + SecondsSequence seq2; + yin >> seq2; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(seq2.size(), 3UL); + EXPECT_EQ(seq2[0], 4000U); + EXPECT_EQ(seq2[1], 500U); + EXPECT_EQ(seq2[2], 59U); + } +} + + +//===----------------------------------------------------------------------===// +// Test dynamic typing +//===----------------------------------------------------------------------===// + +enum AFlags { + a1, + a2, + a3 +}; + +enum BFlags { + b1, + b2, + b3 +}; + +enum Kind { + kindA, + kindB +}; + +struct KindAndFlags { + KindAndFlags() : kind(kindA), flags(0) { } + KindAndFlags(Kind k, uint32_t f) : kind(k), flags(f) { } + Kind kind; + uint32_t flags; +}; + +typedef std::vector<KindAndFlags> KindAndFlagsSequence; + +LLVM_YAML_IS_FLOW_SEQUENCE_VECTOR(KindAndFlags) + +namespace llvm { +namespace yaml { + template <> + struct ScalarEnumerationTraits<AFlags> { + static void enumeration(IO &io, AFlags &value) { + io.enumCase(value, "a1", a1); + io.enumCase(value, "a2", a2); + io.enumCase(value, "a3", a3); + } + }; + template <> + struct ScalarEnumerationTraits<BFlags> { + static void enumeration(IO &io, BFlags &value) { + io.enumCase(value, "b1", b1); + io.enumCase(value, "b2", b2); + io.enumCase(value, "b3", b3); + } + }; + template <> + struct ScalarEnumerationTraits<Kind> { + static void enumeration(IO &io, Kind &value) { + io.enumCase(value, "A", kindA); + io.enumCase(value, "B", kindB); + } + }; + template <> + struct MappingTraits<KindAndFlags> { + static void mapping(IO &io, KindAndFlags& kf) { + io.mapRequired("kind", kf.kind); + // type of flags field varies depending on kind field + if ( kf.kind == kindA ) + io.mapRequired("flags", *((AFlags*)&kf.flags)); + else + io.mapRequired("flags", *((BFlags*)&kf.flags)); + } + }; +} +} + + +// +// Test the reading of a yaml sequence dynamic types +// +TEST(YAMLIO, TestReadKindAndFlagsSequence) { + KindAndFlagsSequence seq; + Input yin("---\n - kind: A\n flags: a2\n - kind: B\n flags: b1\n...\n"); + yin >> seq; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(seq.size(), 2UL); + EXPECT_EQ(seq[0].kind, kindA); + EXPECT_EQ(seq[0].flags, a2); + EXPECT_EQ(seq[1].kind, kindB); + EXPECT_EQ(seq[1].flags, b1); +} + +// +// Test writing then reading back dynamic types +// +TEST(YAMLIO, TestReadWriteKindAndFlagsSequence) { + std::string intermediate; + { + KindAndFlagsSequence seq; + seq.push_back(KindAndFlags(kindA,a1)); + seq.push_back(KindAndFlags(kindB,b1)); + seq.push_back(KindAndFlags(kindA,a2)); + seq.push_back(KindAndFlags(kindB,b2)); + seq.push_back(KindAndFlags(kindA,a3)); + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << seq; + } + { + Input yin(intermediate); + KindAndFlagsSequence seq2; + yin >> seq2; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(seq2.size(), 5UL); + EXPECT_EQ(seq2[0].kind, kindA); + EXPECT_EQ(seq2[0].flags, a1); + EXPECT_EQ(seq2[1].kind, kindB); + EXPECT_EQ(seq2[1].flags, b1); + EXPECT_EQ(seq2[2].kind, kindA); + EXPECT_EQ(seq2[2].flags, a2); + EXPECT_EQ(seq2[3].kind, kindB); + EXPECT_EQ(seq2[3].flags, b2); + EXPECT_EQ(seq2[4].kind, kindA); + EXPECT_EQ(seq2[4].flags, a3); + } +} + + +//===----------------------------------------------------------------------===// +// Test document list +//===----------------------------------------------------------------------===// + +struct FooBarMap { + int foo; + int bar; +}; +typedef std::vector<FooBarMap> FooBarMapDocumentList; + +LLVM_YAML_IS_DOCUMENT_LIST_VECTOR(FooBarMap) + + +namespace llvm { +namespace yaml { + template <> + struct MappingTraits<FooBarMap> { + static void mapping(IO &io, FooBarMap& fb) { + io.mapRequired("foo", fb.foo); + io.mapRequired("bar", fb.bar); + } + }; +} +} + + +// +// Test the reading of a yaml mapping +// +TEST(YAMLIO, TestDocRead) { + FooBarMap doc; + Input yin("---\nfoo: 3\nbar: 5\n...\n"); + yin >> doc; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(doc.foo, 3); + EXPECT_EQ(doc.bar,5); +} + + + +// +// Test writing then reading back a sequence of mappings +// +TEST(YAMLIO, TestSequenceDocListWriteAndRead) { + std::string intermediate; + { + FooBarMap doc1; + doc1.foo = 10; + doc1.bar = -3; + FooBarMap doc2; + doc2.foo = 257; + doc2.bar = 0; + std::vector<FooBarMap> docList; + docList.push_back(doc1); + docList.push_back(doc2); + + llvm::raw_string_ostream ostr(intermediate); + Output yout(ostr); + yout << docList; + } + + + { + Input yin(intermediate); + std::vector<FooBarMap> docList2; + yin >> docList2; + + EXPECT_FALSE(yin.error()); + EXPECT_EQ(docList2.size(), 2UL); + FooBarMap& map1 = docList2[0]; + FooBarMap& map2 = docList2[1]; + EXPECT_EQ(map1.foo, 10); + EXPECT_EQ(map1.bar, -3); + EXPECT_EQ(map2.foo, 257); + EXPECT_EQ(map2.bar, 0); + } +} + + +//===----------------------------------------------------------------------===// +// Test error handling +//===----------------------------------------------------------------------===// + + + +static void suppressErrorMessages(const llvm::SMDiagnostic &, void *) { +} + + +// +// Test error handling of unknown enumerated scalar +// +TEST(YAMLIO, TestColorsReadError) { + ColorMap map; + Input yin("---\n" + "c1: blue\n" + "c2: purple\n" + "c3: green\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> map; + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling of flow sequence with unknown value +// +TEST(YAMLIO, TestFlagsReadError) { + FlagsMap map; + Input yin("---\n" + "f1: [ big ]\n" + "f2: [ round, hollow ]\n" + "f3: []\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> map; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in uint8_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(uint8_t) +TEST(YAMLIO, TestReadBuiltInTypesUint8Error) { + std::vector<uint8_t> seq; + Input yin("---\n" + "- 255\n" + "- 0\n" + "- 257\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in uint16_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(uint16_t) +TEST(YAMLIO, TestReadBuiltInTypesUint16Error) { + std::vector<uint16_t> seq; + Input yin("---\n" + "- 65535\n" + "- 0\n" + "- 66000\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in uint32_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(uint32_t) +TEST(YAMLIO, TestReadBuiltInTypesUint32Error) { + std::vector<uint32_t> seq; + Input yin("---\n" + "- 4000000000\n" + "- 0\n" + "- 5000000000\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in uint64_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(uint64_t) +TEST(YAMLIO, TestReadBuiltInTypesUint64Error) { + std::vector<uint64_t> seq; + Input yin("---\n" + "- 18446744073709551615\n" + "- 0\n" + "- 19446744073709551615\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in int8_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(int8_t) +TEST(YAMLIO, TestReadBuiltInTypesint8OverError) { + std::vector<int8_t> seq; + Input yin("---\n" + "- -128\n" + "- 0\n" + "- 127\n" + "- 128\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in int8_t type +// +TEST(YAMLIO, TestReadBuiltInTypesint8UnderError) { + std::vector<int8_t> seq; + Input yin("---\n" + "- -128\n" + "- 0\n" + "- 127\n" + "- -129\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in int16_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(int16_t) +TEST(YAMLIO, TestReadBuiltInTypesint16UnderError) { + std::vector<int16_t> seq; + Input yin("---\n" + "- 32767\n" + "- 0\n" + "- -32768\n" + "- -32769\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in int16_t type +// +TEST(YAMLIO, TestReadBuiltInTypesint16OverError) { + std::vector<int16_t> seq; + Input yin("---\n" + "- 32767\n" + "- 0\n" + "- -32768\n" + "- 32768\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in int32_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(int32_t) +TEST(YAMLIO, TestReadBuiltInTypesint32UnderError) { + std::vector<int32_t> seq; + Input yin("---\n" + "- 2147483647\n" + "- 0\n" + "- -2147483648\n" + "- -2147483649\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in int32_t type +// +TEST(YAMLIO, TestReadBuiltInTypesint32OverError) { + std::vector<int32_t> seq; + Input yin("---\n" + "- 2147483647\n" + "- 0\n" + "- -2147483648\n" + "- 2147483649\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in int64_t type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(int64_t) +TEST(YAMLIO, TestReadBuiltInTypesint64UnderError) { + std::vector<int64_t> seq; + Input yin("---\n" + "- -9223372036854775808\n" + "- 0\n" + "- 9223372036854775807\n" + "- -9223372036854775809\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in int64_t type +// +TEST(YAMLIO, TestReadBuiltInTypesint64OverError) { + std::vector<int64_t> seq; + Input yin("---\n" + "- -9223372036854775808\n" + "- 0\n" + "- 9223372036854775807\n" + "- 9223372036854775809\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in float type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(float) +TEST(YAMLIO, TestReadBuiltInTypesFloatError) { + std::vector<float> seq; + Input yin("---\n" + "- 0.0\n" + "- 1000.1\n" + "- -123.456\n" + "- 1.2.3\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in float type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(double) +TEST(YAMLIO, TestReadBuiltInTypesDoubleError) { + std::vector<double> seq; + Input yin("---\n" + "- 0.0\n" + "- 1000.1\n" + "- -123.456\n" + "- 1.2.3\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in Hex8 type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(Hex8) +TEST(YAMLIO, TestReadBuiltInTypesHex8Error) { + std::vector<Hex8> seq; + Input yin("---\n" + "- 0x12\n" + "- 0xFE\n" + "- 0x123\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + +// +// Test error handling reading built-in Hex16 type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(Hex16) +TEST(YAMLIO, TestReadBuiltInTypesHex16Error) { + std::vector<Hex16> seq; + Input yin("---\n" + "- 0x0012\n" + "- 0xFEFF\n" + "- 0x12345\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in Hex32 type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(Hex32) +TEST(YAMLIO, TestReadBuiltInTypesHex32Error) { + std::vector<Hex32> seq; + Input yin("---\n" + "- 0x0012\n" + "- 0xFEFF0000\n" + "- 0x1234556789\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + +// +// Test error handling reading built-in Hex64 type +// +LLVM_YAML_IS_SEQUENCE_VECTOR(Hex64) +TEST(YAMLIO, TestReadBuiltInTypesHex64Error) { + std::vector<Hex64> seq; + Input yin("---\n" + "- 0x0012\n" + "- 0xFFEEDDCCBBAA9988\n" + "- 0x12345567890ABCDEF0\n" + "...\n"); + yin.setDiagHandler(suppressErrorMessages); + yin >> seq; + + EXPECT_TRUE(yin.error()); +} + + |