diff options
author | Alex Lorenz <arphaman@gmail.com> | 2015-05-14 23:08:22 +0000 |
---|---|---|
committer | Alex Lorenz <arphaman@gmail.com> | 2015-05-14 23:08:22 +0000 |
commit | 29a3c1d580dad764452c8d448f2e2ae1c90f0674 (patch) | |
tree | ddc6eda6911433c052664a37896dc28eee2f3db6 /docs/YamlIO.rst | |
parent | a8adbcb9de5ba60a6b5677c64cd64491806f5881 (diff) |
YAML: Add support for literal block scalar I/O.
This commit gives the users of the YAML Traits I/O library
the ability to serialize scalars using the YAML literal block
scalar notation by allowing them to implement a specialization
of the `BlockScalarTraits` struct for their custom types.
Reviewers: Duncan P. N. Exon Smith
Differential Revision: http://reviews.llvm.org/D9613
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@237404 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/YamlIO.rst')
-rw-r--r-- | docs/YamlIO.rst | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/docs/YamlIO.rst b/docs/YamlIO.rst index ab8b19ac2a50..aa4bae35d1a4 100644 --- a/docs/YamlIO.rst +++ b/docs/YamlIO.rst @@ -467,6 +467,56 @@ looks like: // Determine if this scalar needs quotes. static bool mustQuote(StringRef) { return true; } }; + +Block Scalars +------------- + +YAML block scalars are string literals that are represented in YAML using the +literal block notation, just like the example shown below: + +.. code-block:: yaml + + text: | + First line + Second line + +The YAML I/O library provides support for translating between YAML block scalars +and specific C++ types by allowing you to specialize BlockScalarTraits<> on +your data type. The library doesn't provide any built-in support for block +scalar I/O for types like std::string and llvm::StringRef as they are already +supported by YAML I/O and use the ordinary scalar notation by default. + +BlockScalarTraits specializations are very similar to the +ScalarTraits specialization - YAML I/O will provide the native type and your +specialization must create a temporary llvm::StringRef when writing, and +it will also provide an llvm::StringRef that has the value of that block scalar +and your specialization must convert that to your native data type when reading. +An example of a custom type with an appropriate specialization of +BlockScalarTraits is shown below: + +.. code-block:: c++ + + using llvm::yaml::BlockScalarTraits; + using llvm::yaml::IO; + + struct MyStringType { + std::string Str; + }; + + template <> + struct BlockScalarTraits<MyStringType> { + static void output(const MyStringType &Value, void *Ctxt, + llvm::raw_ostream &OS) { + OS << Value.Str; + } + + static StringRef input(StringRef Scalar, void *Ctxt, + MyStringType &Value) { + Value.Str = Scalar.str(); + return StringRef(); + } + }; + Mappings |