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 Stream(StringRef Input, SourceMgr &);
83 document_iterator begin();
84 document_iterator end();
92 void printError(Node *N, const Twine &Msg);
95 OwningPtr<Scanner> scanner;
96 OwningPtr<Document> CurrentDoc;
98 friend class Document;
100 /// @brief Validate a %YAML x.x directive.
101 void handleYAMLDirective(const Token &);
104 /// @brief Abstract base class for all Nodes.
116 Node(unsigned int Type, OwningPtr<Document>&, StringRef Anchor);
118 /// @brief Get the value of the anchor attached to this node. If it does not
119 /// have one, getAnchor().size() will be 0.
120 StringRef getAnchor() const { return Anchor; }
122 SMRange getSourceRange() const { return SourceRange; }
123 void setSourceRange(SMRange SR) { SourceRange = SR; }
125 // These functions forward to Document and Scanner.
128 Node *parseBlockNode();
129 BumpPtrAllocator &getAllocator();
130 void setError(const Twine &Message, Token &Location) const;
133 virtual void skip() {}
135 unsigned int getType() const { return TypeID; }
136 static inline bool classof(const Node *) { return true; }
138 void *operator new ( size_t Size
139 , BumpPtrAllocator &Alloc
140 , size_t Alignment = 16) throw() {
141 return Alloc.Allocate(Size, Alignment);
144 void operator delete(void *Ptr, BumpPtrAllocator &Alloc, size_t) throw() {
145 Alloc.Deallocate(Ptr);
149 OwningPtr<Document> &Doc;
152 void operator delete(void *) throw() {}
161 /// @brief A null value.
165 class NullNode : public Node {
167 NullNode(OwningPtr<Document> &D) : Node(NK_Null, D, StringRef()) {}
169 static inline bool classof(const NullNode *) { return true; }
170 static inline bool classof(const Node *N) {
171 return N->getType() == NK_Null;
175 /// @brief A scalar node is an opaque datum that can be presented as a
176 /// series of zero or more Unicode scalar values.
180 class ScalarNode : public Node {
182 ScalarNode(OwningPtr<Document> &D, StringRef Anchor, StringRef Val)
183 : Node(NK_Scalar, D, Anchor)
185 SMLoc Start = SMLoc::getFromPointer(Val.begin());
186 SMLoc End = SMLoc::getFromPointer(Val.end() - 1);
187 SourceRange = SMRange(Start, End);
190 // Return Value without any escaping or folding or other fun YAML stuff. This
191 // is the exact bytes that are contained in the file (after conversion to
193 StringRef getRawValue() const { return Value; }
195 /// @brief Gets the value of this node as a StringRef.
197 /// @param Storage is used to store the content of the returned StringRef iff
198 /// it requires any modification from how it appeared in the source.
199 /// This happens with escaped characters and multi-line literals.
200 StringRef getValue(SmallVectorImpl<char> &Storage) const;
202 static inline bool classof(const ScalarNode *) { return true; }
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() {
249 static inline bool classof(const KeyValueNode *) { return true; }
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() {
365 static inline bool classof(const MappingNode *) { return true; }
366 static inline bool classof(const Node *N) {
367 return N->getType() == NK_Mapping;
374 KeyValueNode *CurrentEntry;
379 /// @brief Represents a YAML sequence created from either a block sequence for a
382 /// This parses the YAML stream as increment() is called.
387 class SequenceNode : public Node {
398 // As a BlockMappingEntry and BlockEnd are not created in this case.
402 SequenceNode(OwningPtr<Document> &D, StringRef Anchor, SequenceType ST)
403 : Node(NK_Sequence, D, Anchor)
405 , IsAtBeginning(true)
407 , WasPreviousTokenFlowEntry(true) // Start with an imaginary ','.
411 friend class basic_collection_iterator<SequenceNode, Node>;
412 typedef basic_collection_iterator<SequenceNode, Node> iterator;
413 template <class T> friend typename T::iterator yaml::begin(T &);
414 template <class T> friend void yaml::skip(T &);
419 return yaml::begin(*this);
422 iterator end() { return iterator(); }
424 virtual void skip() {
428 static inline bool classof(const SequenceNode *) { return true; }
429 static inline bool classof(const Node *N) {
430 return N->getType() == NK_Sequence;
434 SequenceType SeqType;
437 bool WasPreviousTokenFlowEntry;
441 /// @brief Represents an alias to a Node with an anchor.
445 class AliasNode : public Node {
447 AliasNode(OwningPtr<Document> &D, StringRef Val)
448 : Node(NK_Alias, D, StringRef()), Name(Val) {}
450 StringRef getName() const { return Name; }
453 static inline bool classof(const ScalarNode *) { return true; }
454 static inline bool classof(const Node *N) {
455 return N->getType() == NK_Alias;
462 /// @brief A YAML Stream is a sequence of Documents. A document contains a root
466 /// @brief Root for parsing a node. Returns a single node.
467 Node *parseBlockNode();
469 Document(Stream &ParentStream);
471 /// @brief Finish parsing the current document and return true if there are
472 /// more. Return false otherwise.
475 /// @brief Parse and return the root level node.
479 return Root = parseBlockNode();
484 friend class document_iterator;
486 /// @brief Stream to read tokens from.
489 /// @brief Used to allocate nodes to. All are destroyed without calling their
490 /// destructor when the document is destroyed.
491 BumpPtrAllocator NodeAllocator;
493 /// @brief The root node. Used to support skipping a partially parsed
499 void setError(const Twine &Message, Token &Location) const;
502 void handleTagDirective(const Token &Tag) {
506 /// @brief Parse %BLAH directives and return true if any were encountered.
507 bool parseDirectives();
509 /// @brief Consume the next token and error if it is not \a TK.
510 bool expectToken(int TK);
513 /// @brief Iterator abstraction for Documents over a Stream.
514 class document_iterator {
516 document_iterator() : Doc(0) {}
517 document_iterator(OwningPtr<Document> &D) : Doc(&D) {}
519 bool operator ==(const document_iterator &Other) {
520 if (isAtEnd() || Other.isAtEnd())
521 return isAtEnd() && Other.isAtEnd();
523 return *Doc == *Other.Doc;
525 bool operator !=(const document_iterator &Other) {
526 return !(*this == Other);
529 document_iterator operator ++() {
530 assert(Doc != 0 && "incrementing iterator past the end.");
531 if (!(*Doc)->skip()) {
534 Stream &S = (*Doc)->stream;
535 Doc->reset(new Document(S));
540 Document &operator *() {
544 OwningPtr<Document> &operator ->() {
549 bool isAtEnd() const {
550 return Doc == 0 || *Doc == 0;
553 OwningPtr<Document> *Doc;