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_YAML_PARSER_H
39 #define LLVM_SUPPORT_YAML_PARSER_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"
58 class document_iterator;
64 /// @brief Dump all the tokens in this stream to OS.
65 /// @returns true if there was an error, false otherwise.
66 bool dumpTokens(StringRef Input, raw_ostream &);
68 /// @brief Scans all tokens in input without outputting anything. This is used
69 /// for benchmarking the tokenizer.
70 /// @returns true if there was an error, false otherwise.
71 bool scanTokens(StringRef Input);
73 /// @brief Escape \a Input for a double quoted scalar.
74 std::string escape(StringRef Input);
76 /// @brief This class represents a YAML stream potentially containing multiple
80 /// @brief This keeps a reference to the string referenced by \p Input.
81 Stream(StringRef Input, SourceMgr &);
83 /// @brief This takes ownership of \p InputBuffer.
84 Stream(MemoryBuffer *InputBuffer, SourceMgr &);
87 document_iterator begin();
88 document_iterator end();
96 void printError(Node *N, const Twine &Msg);
99 OwningPtr<Scanner> scanner;
100 OwningPtr<Document> CurrentDoc;
102 friend class Document;
104 /// @brief Validate a %YAML x.x directive.
105 void handleYAMLDirective(const Token &);
108 /// @brief Abstract base class for all Nodes.
120 Node(unsigned int Type, OwningPtr<Document>&, StringRef Anchor);
122 /// @brief Get the value of the anchor attached to this node. If it does not
123 /// have one, getAnchor().size() will be 0.
124 StringRef getAnchor() const { return Anchor; }
126 SMRange getSourceRange() const { return SourceRange; }
127 void setSourceRange(SMRange SR) { SourceRange = SR; }
129 // These functions forward to Document and Scanner.
132 Node *parseBlockNode();
133 BumpPtrAllocator &getAllocator();
134 void setError(const Twine &Message, Token &Location) const;
137 virtual void skip() {}
139 unsigned int getType() const { return TypeID; }
141 void *operator new ( size_t Size
142 , BumpPtrAllocator &Alloc
143 , size_t Alignment = 16) throw() {
144 return Alloc.Allocate(Size, Alignment);
147 void operator delete(void *Ptr, BumpPtrAllocator &Alloc, size_t) throw() {
148 Alloc.Deallocate(Ptr);
152 OwningPtr<Document> &Doc;
155 void operator delete(void *) throw() {}
164 /// @brief A null value.
168 class NullNode : public Node {
170 NullNode(OwningPtr<Document> &D) : Node(NK_Null, D, StringRef()) {}
172 static inline bool classof(const Node *N) {
173 return N->getType() == NK_Null;
177 /// @brief A scalar node is an opaque datum that can be presented as a
178 /// series of zero or more Unicode scalar values.
182 class ScalarNode : public Node {
184 ScalarNode(OwningPtr<Document> &D, StringRef Anchor, StringRef Val)
185 : Node(NK_Scalar, D, Anchor)
187 SMLoc Start = SMLoc::getFromPointer(Val.begin());
188 SMLoc End = SMLoc::getFromPointer(Val.end() - 1);
189 SourceRange = SMRange(Start, End);
192 // Return Value without any escaping or folding or other fun YAML stuff. This
193 // is the exact bytes that are contained in the file (after conversion to
195 StringRef getRawValue() const { return Value; }
197 /// @brief Gets the value of this node as a StringRef.
199 /// @param Storage is used to store the content of the returned StringRef iff
200 /// it requires any modification from how it appeared in the source.
201 /// This happens with escaped characters and multi-line literals.
202 StringRef getValue(SmallVectorImpl<char> &Storage) const;
204 static inline bool classof(const Node *N) {
205 return N->getType() == NK_Scalar;
211 StringRef unescapeDoubleQuoted( StringRef UnquotedValue
212 , StringRef::size_type Start
213 , SmallVectorImpl<char> &Storage) const;
216 /// @brief A key and value pair. While not technically a Node under the YAML
217 /// representation graph, it is easier to treat them this way.
219 /// TODO: Consider making this not a child of Node.
223 class KeyValueNode : public Node {
225 KeyValueNode(OwningPtr<Document> &D)
226 : Node(NK_KeyValue, D, StringRef())
231 /// @brief Parse and return the key.
233 /// This may be called multiple times.
235 /// @returns The key, or nullptr if failed() == true.
238 /// @brief Parse and return the value.
240 /// This may be called multiple times.
242 /// @returns The value, or nullptr if failed() == true.
245 virtual void skip() LLVM_OVERRIDE {
250 static inline bool classof(const Node *N) {
251 return N->getType() == NK_KeyValue;
259 /// @brief This is an iterator abstraction over YAML collections shared by both
260 /// sequences and maps.
262 /// BaseT must have a ValueT* member named CurrentEntry and a member function
263 /// increment() which must set CurrentEntry to 0 to create an end iterator.
264 template <class BaseT, class ValueT>
265 class basic_collection_iterator
266 : public std::iterator<std::forward_iterator_tag, ValueT> {
268 basic_collection_iterator() : Base(0) {}
269 basic_collection_iterator(BaseT *B) : Base(B) {}
271 ValueT *operator ->() const {
272 assert(Base && Base->CurrentEntry && "Attempted to access end iterator!");
273 return Base->CurrentEntry;
276 ValueT &operator *() const {
277 assert(Base && Base->CurrentEntry &&
278 "Attempted to dereference end iterator!");
279 return *Base->CurrentEntry;
282 operator ValueT*() const {
283 assert(Base && Base->CurrentEntry && "Attempted to access end iterator!");
284 return Base->CurrentEntry;
287 bool operator !=(const basic_collection_iterator &Other) const {
288 if(Base != Other.Base)
290 return (Base && Other.Base) && Base->CurrentEntry
291 != Other.Base->CurrentEntry;
294 basic_collection_iterator &operator++() {
295 assert(Base && "Attempted to advance iterator past end!");
297 // Create an end iterator.
298 if (Base->CurrentEntry == 0)
307 // The following two templates are used for both MappingNode and Sequence Node.
308 template <class CollectionType>
309 typename CollectionType::iterator begin(CollectionType &C) {
310 assert(C.IsAtBeginning && "You may only iterate over a collection once!");
311 C.IsAtBeginning = false;
312 typename CollectionType::iterator ret(&C);
317 template <class CollectionType>
318 void skip(CollectionType &C) {
319 // TODO: support skipping from the middle of a parsed collection ;/
320 assert((C.IsAtBeginning || C.IsAtEnd) && "Cannot skip mid parse!");
322 for (typename CollectionType::iterator i = begin(C), e = C.end();
327 /// @brief Represents a YAML map created from either a block map for a flow map.
329 /// This parses the YAML stream as increment() is called.
334 class MappingNode : public Node {
339 MT_Inline ///< An inline mapping node is used for "[key: value]".
342 MappingNode(OwningPtr<Document> &D, StringRef Anchor, MappingType MT)
343 : Node(NK_Mapping, D, Anchor)
345 , IsAtBeginning(true)
350 friend class basic_collection_iterator<MappingNode, KeyValueNode>;
351 typedef basic_collection_iterator<MappingNode, KeyValueNode> iterator;
352 template <class T> friend typename T::iterator yaml::begin(T &);
353 template <class T> friend void yaml::skip(T &);
356 return yaml::begin(*this);
359 iterator end() { return iterator(); }
361 virtual void skip() LLVM_OVERRIDE {
365 static inline bool classof(const Node *N) {
366 return N->getType() == NK_Mapping;
373 KeyValueNode *CurrentEntry;
378 /// @brief Represents a YAML sequence created from either a block sequence for a
381 /// This parses the YAML stream as increment() is called.
386 class SequenceNode : public Node {
397 // As a BlockMappingEntry and BlockEnd are not created in this case.
401 SequenceNode(OwningPtr<Document> &D, StringRef Anchor, SequenceType ST)
402 : Node(NK_Sequence, D, Anchor)
404 , IsAtBeginning(true)
406 , WasPreviousTokenFlowEntry(true) // Start with an imaginary ','.
410 friend class basic_collection_iterator<SequenceNode, Node>;
411 typedef basic_collection_iterator<SequenceNode, Node> iterator;
412 template <class T> friend typename T::iterator yaml::begin(T &);
413 template <class T> friend void yaml::skip(T &);
418 return yaml::begin(*this);
421 iterator end() { return iterator(); }
423 virtual void skip() LLVM_OVERRIDE {
427 static inline bool classof(const Node *N) {
428 return N->getType() == NK_Sequence;
432 SequenceType SeqType;
435 bool WasPreviousTokenFlowEntry;
439 /// @brief Represents an alias to a Node with an anchor.
443 class AliasNode : public Node {
445 AliasNode(OwningPtr<Document> &D, StringRef Val)
446 : Node(NK_Alias, D, StringRef()), Name(Val) {}
448 StringRef getName() const { return Name; }
451 static inline bool classof(const Node *N) {
452 return N->getType() == NK_Alias;
459 /// @brief A YAML Stream is a sequence of Documents. A document contains a root
463 /// @brief Root for parsing a node. Returns a single node.
464 Node *parseBlockNode();
466 Document(Stream &ParentStream);
468 /// @brief Finish parsing the current document and return true if there are
469 /// more. Return false otherwise.
472 /// @brief Parse and return the root level node.
476 return Root = parseBlockNode();
481 friend class document_iterator;
483 /// @brief Stream to read tokens from.
486 /// @brief Used to allocate nodes to. All are destroyed without calling their
487 /// destructor when the document is destroyed.
488 BumpPtrAllocator NodeAllocator;
490 /// @brief The root node. Used to support skipping a partially parsed
496 void setError(const Twine &Message, Token &Location) const;
499 void handleTagDirective(const Token &Tag) {
503 /// @brief Parse %BLAH directives and return true if any were encountered.
504 bool parseDirectives();
506 /// @brief Consume the next token and error if it is not \a TK.
507 bool expectToken(int TK);
510 /// @brief Iterator abstraction for Documents over a Stream.
511 class document_iterator {
513 document_iterator() : Doc(0) {}
514 document_iterator(OwningPtr<Document> &D) : Doc(&D) {}
516 bool operator ==(const document_iterator &Other) {
517 if (isAtEnd() || Other.isAtEnd())
518 return isAtEnd() && Other.isAtEnd();
520 return *Doc == *Other.Doc;
522 bool operator !=(const document_iterator &Other) {
523 return !(*this == Other);
526 document_iterator operator ++() {
527 assert(Doc != 0 && "incrementing iterator past the end.");
528 if (!(*Doc)->skip()) {
531 Stream &S = (*Doc)->stream;
532 Doc->reset(new Document(S));
537 Document &operator *() {
541 OwningPtr<Document> &operator ->() {
546 bool isAtEnd() const {
547 return Doc == 0 || *Doc == 0;
550 OwningPtr<Document> *Doc;