1 //===--- YAMLParser.h - Simple YAML parser --------------------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This is a YAML 1.2 parser.
12 // See http://www.yaml.org/spec/1.2/spec.html for the full standard.
14 // This currently does not implement the following:
15 // * Multi-line literal folding.
18 // * BOMs anywhere other than the first Unicode scalar value in the file.
20 // The most important class here is Stream. This represents a YAML stream with
21 // 0, 1, or many documents.
24 // StringRef input = getInput();
25 // yaml::Stream stream(input, sm);
27 // for (yaml::document_iterator di = stream.begin(), de = stream.end();
29 // yaml::Node *n = di->getRoot();
31 // // Do something with n...
36 //===----------------------------------------------------------------------===//
38 #ifndef LLVM_SUPPORT_YAMLPARSER_H
39 #define LLVM_SUPPORT_YAMLPARSER_H
41 #include "llvm/ADT/OwningPtr.h"
42 #include "llvm/ADT/SmallString.h"
43 #include "llvm/ADT/StringRef.h"
44 #include "llvm/Support/Allocator.h"
45 #include "llvm/Support/SMLoc.h"
57 class document_iterator;
63 /// @brief Dump all the tokens in this stream to OS.
64 /// @returns true if there was an error, false otherwise.
65 bool dumpTokens(StringRef Input, raw_ostream &);
67 /// @brief Scans all tokens in input without outputting anything. This is used
68 /// for benchmarking the tokenizer.
69 /// @returns true if there was an error, false otherwise.
70 bool scanTokens(StringRef Input);
72 /// @brief Escape \a Input for a double quoted scalar.
73 std::string escape(StringRef Input);
75 /// @brief This class represents a YAML stream potentially containing multiple
79 /// @brief This keeps a reference to the string referenced by \p Input.
80 Stream(StringRef Input, SourceMgr &);
82 /// @brief This takes ownership of \p InputBuffer.
83 Stream(MemoryBuffer *InputBuffer, SourceMgr &);
86 document_iterator begin();
87 document_iterator end();
95 void printError(Node *N, const Twine &Msg);
98 OwningPtr<Scanner> scanner;
99 OwningPtr<Document> CurrentDoc;
101 friend class Document;
103 /// @brief Validate a %YAML x.x directive.
104 void handleYAMLDirective(const Token &);
107 /// @brief Abstract base class for all Nodes.
119 Node(unsigned int Type, OwningPtr<Document>&, StringRef Anchor);
121 /// @brief Get the value of the anchor attached to this node. If it does not
122 /// have one, getAnchor().size() will be 0.
123 StringRef getAnchor() const { return Anchor; }
125 SMRange getSourceRange() const { return SourceRange; }
126 void setSourceRange(SMRange SR) { SourceRange = SR; }
128 // These functions forward to Document and Scanner.
131 Node *parseBlockNode();
132 BumpPtrAllocator &getAllocator();
133 void setError(const Twine &Message, Token &Location) const;
136 virtual void skip() {}
138 unsigned int getType() const { return TypeID; }
140 void *operator new ( size_t Size
141 , BumpPtrAllocator &Alloc
142 , size_t Alignment = 16) throw() {
143 return Alloc.Allocate(Size, Alignment);
146 void operator delete(void *Ptr, BumpPtrAllocator &Alloc, size_t) throw() {
147 Alloc.Deallocate(Ptr);
151 OwningPtr<Document> &Doc;
154 void operator delete(void *) throw() {}
163 /// @brief A null value.
167 class NullNode : public Node {
169 NullNode(OwningPtr<Document> &D) : Node(NK_Null, D, StringRef()) {}
171 static inline bool classof(const Node *N) {
172 return N->getType() == NK_Null;
176 /// @brief A scalar node is an opaque datum that can be presented as a
177 /// series of zero or more Unicode scalar values.
181 class ScalarNode : public Node {
183 ScalarNode(OwningPtr<Document> &D, StringRef Anchor, StringRef Val)
184 : Node(NK_Scalar, D, Anchor)
186 SMLoc Start = SMLoc::getFromPointer(Val.begin());
187 SMLoc End = SMLoc::getFromPointer(Val.end());
188 SourceRange = SMRange(Start, End);
191 // Return Value without any escaping or folding or other fun YAML stuff. This
192 // is the exact bytes that are contained in the file (after conversion to
194 StringRef getRawValue() const { return Value; }
196 /// @brief Gets the value of this node as a StringRef.
198 /// @param Storage is used to store the content of the returned StringRef iff
199 /// it requires any modification from how it appeared in the source.
200 /// This happens with escaped characters and multi-line literals.
201 StringRef getValue(SmallVectorImpl<char> &Storage) const;
203 static inline bool classof(const Node *N) {
204 return N->getType() == NK_Scalar;
210 StringRef unescapeDoubleQuoted( StringRef UnquotedValue
211 , StringRef::size_type Start
212 , SmallVectorImpl<char> &Storage) const;
215 /// @brief A key and value pair. While not technically a Node under the YAML
216 /// representation graph, it is easier to treat them this way.
218 /// TODO: Consider making this not a child of Node.
222 class KeyValueNode : public Node {
224 KeyValueNode(OwningPtr<Document> &D)
225 : Node(NK_KeyValue, D, StringRef())
230 /// @brief Parse and return the key.
232 /// This may be called multiple times.
234 /// @returns The key, or nullptr if failed() == true.
237 /// @brief Parse and return the value.
239 /// This may be called multiple times.
241 /// @returns The value, or nullptr if failed() == true.
244 virtual void skip() LLVM_OVERRIDE {
249 static inline bool classof(const Node *N) {
250 return N->getType() == NK_KeyValue;
258 /// @brief This is an iterator abstraction over YAML collections shared by both
259 /// sequences and maps.
261 /// BaseT must have a ValueT* member named CurrentEntry and a member function
262 /// increment() which must set CurrentEntry to 0 to create an end iterator.
263 template <class BaseT, class ValueT>
264 class basic_collection_iterator
265 : public std::iterator<std::forward_iterator_tag, ValueT> {
267 basic_collection_iterator() : Base(0) {}
268 basic_collection_iterator(BaseT *B) : Base(B) {}
270 ValueT *operator ->() const {
271 assert(Base && Base->CurrentEntry && "Attempted to access end iterator!");
272 return Base->CurrentEntry;
275 ValueT &operator *() const {
276 assert(Base && Base->CurrentEntry &&
277 "Attempted to dereference end iterator!");
278 return *Base->CurrentEntry;
281 operator ValueT*() const {
282 assert(Base && Base->CurrentEntry && "Attempted to access end iterator!");
283 return Base->CurrentEntry;
286 bool operator !=(const basic_collection_iterator &Other) const {
287 if(Base != Other.Base)
289 return (Base && Other.Base) && Base->CurrentEntry
290 != Other.Base->CurrentEntry;
293 basic_collection_iterator &operator++() {
294 assert(Base && "Attempted to advance iterator past end!");
296 // Create an end iterator.
297 if (Base->CurrentEntry == 0)
306 // The following two templates are used for both MappingNode and Sequence Node.
307 template <class CollectionType>
308 typename CollectionType::iterator begin(CollectionType &C) {
309 assert(C.IsAtBeginning && "You may only iterate over a collection once!");
310 C.IsAtBeginning = false;
311 typename CollectionType::iterator ret(&C);
316 template <class CollectionType>
317 void skip(CollectionType &C) {
318 // TODO: support skipping from the middle of a parsed collection ;/
319 assert((C.IsAtBeginning || C.IsAtEnd) && "Cannot skip mid parse!");
321 for (typename CollectionType::iterator i = begin(C), e = C.end();
326 /// @brief Represents a YAML map created from either a block map for a flow map.
328 /// This parses the YAML stream as increment() is called.
333 class MappingNode : public Node {
338 MT_Inline ///< An inline mapping node is used for "[key: value]".
341 MappingNode(OwningPtr<Document> &D, StringRef Anchor, MappingType MT)
342 : Node(NK_Mapping, D, Anchor)
344 , IsAtBeginning(true)
349 friend class basic_collection_iterator<MappingNode, KeyValueNode>;
350 typedef basic_collection_iterator<MappingNode, KeyValueNode> iterator;
351 template <class T> friend typename T::iterator yaml::begin(T &);
352 template <class T> friend void yaml::skip(T &);
355 return yaml::begin(*this);
358 iterator end() { return iterator(); }
360 virtual void skip() LLVM_OVERRIDE {
364 static inline bool classof(const Node *N) {
365 return N->getType() == NK_Mapping;
372 KeyValueNode *CurrentEntry;
377 /// @brief Represents a YAML sequence created from either a block sequence for a
380 /// This parses the YAML stream as increment() is called.
385 class SequenceNode : public Node {
396 // As a BlockMappingEntry and BlockEnd are not created in this case.
400 SequenceNode(OwningPtr<Document> &D, StringRef Anchor, SequenceType ST)
401 : Node(NK_Sequence, D, Anchor)
403 , IsAtBeginning(true)
405 , WasPreviousTokenFlowEntry(true) // Start with an imaginary ','.
409 friend class basic_collection_iterator<SequenceNode, Node>;
410 typedef basic_collection_iterator<SequenceNode, Node> iterator;
411 template <class T> friend typename T::iterator yaml::begin(T &);
412 template <class T> friend void yaml::skip(T &);
417 return yaml::begin(*this);
420 iterator end() { return iterator(); }
422 virtual void skip() LLVM_OVERRIDE {
426 static inline bool classof(const Node *N) {
427 return N->getType() == NK_Sequence;
431 SequenceType SeqType;
434 bool WasPreviousTokenFlowEntry;
438 /// @brief Represents an alias to a Node with an anchor.
442 class AliasNode : public Node {
444 AliasNode(OwningPtr<Document> &D, StringRef Val)
445 : Node(NK_Alias, D, StringRef()), Name(Val) {}
447 StringRef getName() const { return Name; }
450 static inline bool classof(const Node *N) {
451 return N->getType() == NK_Alias;
458 /// @brief A YAML Stream is a sequence of Documents. A document contains a root
462 /// @brief Root for parsing a node. Returns a single node.
463 Node *parseBlockNode();
465 Document(Stream &ParentStream);
467 /// @brief Finish parsing the current document and return true if there are
468 /// more. Return false otherwise.
471 /// @brief Parse and return the root level node.
475 return Root = parseBlockNode();
480 friend class document_iterator;
482 /// @brief Stream to read tokens from.
485 /// @brief Used to allocate nodes to. All are destroyed without calling their
486 /// destructor when the document is destroyed.
487 BumpPtrAllocator NodeAllocator;
489 /// @brief The root node. Used to support skipping a partially parsed
495 void setError(const Twine &Message, Token &Location) const;
498 void handleTagDirective(const Token &Tag) {
502 /// @brief Parse %BLAH directives and return true if any were encountered.
503 bool parseDirectives();
505 /// @brief Consume the next token and error if it is not \a TK.
506 bool expectToken(int TK);
509 /// @brief Iterator abstraction for Documents over a Stream.
510 class document_iterator {
512 document_iterator() : Doc(0) {}
513 document_iterator(OwningPtr<Document> &D) : Doc(&D) {}
515 bool operator ==(const document_iterator &Other) {
516 if (isAtEnd() || Other.isAtEnd())
517 return isAtEnd() && Other.isAtEnd();
519 return Doc == Other.Doc;
521 bool operator !=(const document_iterator &Other) {
522 return !(*this == Other);
525 document_iterator operator ++() {
526 assert(Doc != 0 && "incrementing iterator past the end.");
527 if (!(*Doc)->skip()) {
530 Stream &S = (*Doc)->stream;
531 Doc->reset(new Document(S));
536 Document &operator *() {
540 OwningPtr<Document> &operator ->() {
545 bool isAtEnd() const {
546 return !Doc || !*Doc;
549 OwningPtr<Document> *Doc;