Skip to content

Commit

Permalink
YAML: Add support for literal block scalar I/O.
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@hyp
hyp committed May 14, 2015
1 parent a8adbcb commit 29a3c1d
Show file tree
Hide file tree
Showing 4 changed files with 313 additions and 1 deletion.
50 changes: 50 additions & 0 deletions docs/YamlIO.rst
View file
Expand Up @@ -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
Expand Down
98 changes: 97 additions & 1 deletion include/llvm/Support/YAMLTraits.h
View file
Expand Up @@ -121,6 +121,35 @@ struct ScalarTraits {
};


/// This class should be specialized by type that requires custom conversion
/// to/from a YAML literal block scalar. For example:
///
/// template <>
/// struct BlockScalarTraits<MyType> {
/// static void output(const MyType &Value, void*, llvm::raw_ostream &Out)
/// {
/// // stream out custom formatting
/// Out << 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 BlockScalarTraits {
// Must provide:
//
// Function to write the value as a string:
// static void output(const T &Value, void *ctx, 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:
///
Expand Down Expand Up @@ -224,6 +253,26 @@ struct has_ScalarTraits
};


// Test if BlockScalarTraits<T> is defined on type T.
template <class T>
struct has_BlockScalarTraits
{
typedef StringRef (*Signature_input)(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<BlockScalarTraits<T>>(nullptr, nullptr)) == 1);
};


// Test if MappingTraits<T> is defined on type T.
template <class T>
struct has_MappingTraits
Expand Down Expand Up @@ -410,6 +459,7 @@ struct missingTraits : public std::integral_constant<bool,
!has_ScalarEnumerationTraits<T>::value
&& !has_ScalarBitSetTraits<T>::value
&& !has_ScalarTraits<T>::value
&& !has_BlockScalarTraits<T>::value
&& !has_MappingTraits<T>::value
&& !has_SequenceTraits<T>::value
&& !has_DocumentListTraits<T>::value > {};
Expand Down Expand Up @@ -462,6 +512,7 @@ class IO {
virtual void endBitSetScalar() = 0;

virtual void scalarString(StringRef &, bool) = 0;
virtual void blockScalarString(StringRef &) = 0;

virtual void setError(const Twine &) = 0;

Expand Down Expand Up @@ -646,6 +697,24 @@ yamlize(IO &io, T &Val, bool) {
}
}

template <typename T>
typename std::enable_if<has_BlockScalarTraits<T>::value, void>::type
yamlize(IO &YamlIO, T &Val, bool) {
if (YamlIO.outputting()) {
std::string Storage;
llvm::raw_string_ostream Buffer(Storage);
BlockScalarTraits<T>::output(Val, YamlIO.getContext(), Buffer);
StringRef Str = Buffer.str();
YamlIO.blockScalarString(Str);
} else {
StringRef Str;
YamlIO.blockScalarString(Str);
StringRef Result =
BlockScalarTraits<T>::input(Str, YamlIO.getContext(), Val);
if (!Result.empty())
YamlIO.setError(llvm::Twine(Result));
}
}

template<typename T>
typename std::enable_if<validatedMappingTraits<T>::value, void>::type
Expand Down Expand Up @@ -937,6 +1006,7 @@ class Input : public IO {
bool bitSetMatch(const char *, bool ) override;
void endBitSetScalar() override;
void scalarString(StringRef &, bool) override;
void blockScalarString(StringRef &) override;
void setError(const Twine &message) override;
bool canElideEmptySequence() override;

Expand Down Expand Up @@ -968,7 +1038,8 @@ class Input : public IO {
StringRef value() const { return _value; }

static inline bool classof(const HNode *n) {
return ScalarNode::classof(n->_node);
return ScalarNode::classof(n->_node) ||
BlockScalarNode::classof(n->_node);
}
static inline bool classof(const ScalarHNode *) { return true; }
protected:
Expand Down Expand Up @@ -1067,6 +1138,7 @@ class Output : public IO {
bool bitSetMatch(const char *, bool ) override;
void endBitSetScalar() override;
void scalarString(StringRef &, bool) override;
void blockScalarString(StringRef &) override;
void setError(const Twine &message) override;
bool canElideEmptySequence() override;
public:
Expand Down Expand Up @@ -1208,6 +1280,16 @@ operator>>(Input &yin, T &docSeq) {
return yin;
}

// Define non-member operator>> so that Input can stream in a block scalar.
template <typename T>
inline
typename std::enable_if<has_BlockScalarTraits<T>::value, Input &>::type
operator>>(Input &In, T &Val) {
if (In.setCurrentDocument())
yamlize(In, Val, true);
return In;
}

// Provide better error message about types missing a trait specialization
template <typename T>
inline
Expand Down Expand Up @@ -1263,6 +1345,20 @@ operator<<(Output &yout, T &seq) {
return yout;
}

// Define non-member operator<< so that Output can stream out a block scalar.
template <typename T>
inline
typename std::enable_if<has_BlockScalarTraits<T>::value, Output &>::type
operator<<(Output &Out, T &Val) {
Out.beginDocuments();
if (Out.preflightDocument(0)) {
yamlize(Out, Val, true);
Out.postflightDocument();
}
Out.endDocuments();
return Out;
}

// Provide better error message about types missing a trait specialization
template <typename T>
inline
Expand Down
26 changes: 26 additions & 0 deletions lib/Support/YAMLTraits.cpp
View file
Expand Up @@ -14,6 +14,7 @@
#include "llvm/Support/Errc.h"
#include "llvm/Support/ErrorHandling.h"
#include "llvm/Support/Format.h"
#include "llvm/Support/LineIterator.h"
#include "llvm/Support/YAMLParser.h"
#include "llvm/Support/raw_ostream.h"
#include <cctype>
Expand Down Expand Up @@ -309,6 +310,8 @@ void Input::scalarString(StringRef &S, bool) {
}
}

void Input::blockScalarString(StringRef &S) { scalarString(S, false); }

void Input::setError(HNode *hnode, const Twine &message) {
assert(hnode && "HNode must not be NULL");
this->setError(hnode->_node, message);
Expand All @@ -331,6 +334,11 @@ std::unique_ptr<Input::HNode> Input::createHNodes(Node *N) {
KeyStr = StringRef(Buf, Len);
}
return llvm::make_unique<ScalarHNode>(N, KeyStr);
} else if (BlockScalarNode *BSN = dyn_cast<BlockScalarNode>(N)) {
StringRef Value = BSN->getValue();
char *Buf = StringAllocator.Allocate<char>(Value.size());
memcpy(Buf, Value.data(), Value.size());
return llvm::make_unique<ScalarHNode>(N, StringRef(Buf, Value.size()));
} else if (SequenceNode *SQ = dyn_cast<SequenceNode>(N)) {
auto SQHNode = llvm::make_unique<SequenceHNode>(N);
for (Node &SN : *SQ) {
Expand Down Expand Up @@ -609,6 +617,24 @@ void Output::scalarString(StringRef &S, bool MustQuote) {
this->outputUpToEndOfLine("'"); // Ending single quote.
}

void Output::blockScalarString(StringRef &S) {
if (!StateStack.empty())
newLineCheck();
output(" |");
outputNewLine();

unsigned Indent = StateStack.empty() ? 1 : StateStack.size();

auto Buffer = MemoryBuffer::getMemBuffer(S, "", false);
for (line_iterator Lines(*Buffer, false); !Lines.is_at_end(); ++Lines) {
for (unsigned I = 0; I < Indent; ++I) {
output(" ");
}
output(*Lines);
outputNewLine();
}
}

void Output::setError(const Twine &message) {
}

Expand Down

0 comments on commit 29a3c1d

Please sign in to comment.