redsnow 0.1.6 → 0.2.0

data/ext/snowcrash/src/Section.cc

@@ -0,0 +1,42 @@
+//
+//  Section.cc
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 5/14/14.
+//  Copyright (c) 2014 Apiary Inc. All rights reserved.
+//
+
+#include "Section.h"
+
+using namespace snowcrash;
+
+std::string snowcrash::SectionName(const SectionType& section) {
+
+    switch (section) {
+        case ModelSectionType:
+        case ModelBodySectionType:
+            return "model";
+            
+        case RequestSectionType:
+        case RequestBodySectionType:
+            return "request";
+            
+        case ResponseSectionType:
+        case ResponseBodySectionType:
+            return "response";
+            
+        case BodySectionType:
+        case DanglingBodySectionType:
+            return "message-body";
+            
+        case SchemaSectionType:
+        case DanglingSchemaSectionType:
+            return "message-schema";
+            
+        case HeadersSectionType:
+            return "headers";
+            
+        default:
+            return "section";
+    }
+}

data/ext/snowcrash/src/Section.h

@@ -0,0 +1,47 @@
+//
+//  Section.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 11/1/13.
+//  Copyright (c) 2013 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_SECTION_H
+#define SNOWCRASH_SECTION_H
+
+#include <string>
+
+namespace snowcrash {
+    
+    /**
+     *  API Blueprint Sections Types.
+     */
+    enum SectionType {
+        UndefinedSectionType,           /// < Undefined section
+        BlueprintSectionType,           /// < Blueprint overview
+        ResourceGroupSectionType,       /// < Resource group
+        ResourceSectionType,            /// < Resource
+        ActionSectionType,              /// < Action
+        RequestSectionType,             /// < Request
+        RequestBodySectionType,         /// < Request & Payload body combined (abbrev)
+        ResponseSectionType,            /// < Response
+        ResponseBodySectionType,        /// < Response & Body combined (abbrev)
+        ModelSectionType,               /// < Model
+        ModelBodySectionType,           /// < Model & Body combined (abbrev)
+        BodySectionType,                /// < Payload Body
+        DanglingBodySectionType,        /// < Dangling Body (unrecognised section considered to be Body)
+        SchemaSectionType,              /// < Payload Schema
+        DanglingSchemaSectionType,      /// < Dangling Schema (unrecognised section considered to be Schema)
+        HeadersSectionType,             /// < Headers
+        ForeignSectionType,             /// < Foreign, unexpected section
+        ParametersSectionType,          /// < Parameters
+        ParameterSectionType,           /// < One Parameter definition
+        ValuesSectionType,              /// < Value enumeration
+        ValueSectionType                /// < One Value
+    };
+    
+    /** \return Human readable name for given %SectionType */
+    extern std::string SectionName(const SectionType& section);
+}
+
+#endif

data/ext/snowcrash/src/SectionParser.h

@@ -0,0 +1,229 @@
+//
+//  SectionParser.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 5/4/13.
+//  Copyright (c) 2013 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_SECTIONPARSER_H
+#define SNOWCRASH_SECTIONPARSER_H
+
+#include <stdexcept>
+#include "SectionProcessor.h"
+
+#define ADAPTER_MISMATCH_ERR std::logic_error("mismatched adapter and node type")
+
+namespace snowcrash {
+
+    /**
+     *  Blueprint section parser
+     */
+    template<typename T, typename Adapter>
+    struct SectionParser {
+
+        
+        /**
+         *  \brief  Parse a section of blueprint
+         *  \param  node    Initial node to start parsing at
+         *  \param  siblings    Siblings of the initial node
+         *  \param  pd      Parser data
+         *  \param  T       Parsed output
+         *  \return Iterator to the first unparsed block
+         */
+        static MarkdownNodeIterator parse(const MarkdownNodeIterator& node,
+                                          const MarkdownNodes& siblings,
+                                          SectionParserData& pd,
+                                          Report& report,
+                                          T& out) {
+            
+            SectionLayout layout = DefaultSectionLayout;
+            MarkdownNodeIterator cur = Adapter::startingNode(node);
+            const MarkdownNodes& collection = Adapter::startingNodeSiblings(node, siblings);
+            
+            // Signature node
+            MarkdownNodeIterator lastCur = cur;
+            cur = SectionProcessor<T>::processSignature(cur, collection, pd, layout, report, out);
+
+            // Exclusive Nested Sections Layout
+            if (layout == ExclusiveNestedSectionLayout) {
+
+                cur = parseNestedSections(cur, collection, pd, report, out);
+                
+                SectionProcessor<T>::finalize(node, pd, report, out);
+                
+                return Adapter::nextStartingNode(node, siblings, cur);
+            }
+            
+            // Parser redirect layout
+            if (layout == RedirectSectionLayout) {
+                SectionProcessor<T>::finalize(node, pd, report, out);
+                
+                return Adapter::nextStartingNode(node, siblings, cur);
+            }
+
+            // Default layout
+            if (lastCur == cur)
+                return Adapter::nextStartingNode(node, siblings, cur);
+            
+            // Description nodes
+            while(cur != collection.end() &&
+                  SectionProcessor<T>::isDescriptionNode(cur, pd.sectionContext())) {
+                
+                lastCur = cur;
+                cur = SectionProcessor<T>::processDescription(cur, collection, pd, report, out);
+                if (lastCur == cur)
+                    return Adapter::nextStartingNode(node, siblings, cur);
+            }
+            
+            // Content nodes
+            while(cur != collection.end() &&
+                  SectionProcessor<T>::isContentNode(cur, pd.sectionContext())) {
+                
+                lastCur = cur;
+                cur = SectionProcessor<T>::processContent(cur, collection, pd, report, out);
+                if (lastCur == cur)
+                    return Adapter::nextStartingNode(node, siblings, cur);
+            }
+            
+            // Nested Sections
+            cur = parseNestedSections(cur, collection, pd, report, out);
+
+            SectionProcessor<T>::finalize(node, pd, report, out);
+
+            return Adapter::nextStartingNode(node, siblings, cur);
+        }
+        
+        
+        /** Parse nested sections */
+        static MarkdownNodeIterator parseNestedSections(const MarkdownNodeIterator& node,
+                                                        const MarkdownNodes& collection,
+                                                        SectionParserData& pd,
+                                                        Report& report,
+                                                        T& out) {
+
+            MarkdownNodeIterator cur = node;
+            MarkdownNodeIterator lastCur = cur;
+            
+            SectionType lastSectionType = UndefinedSectionType;
+            
+            // Nested sections
+            while(cur != collection.end()) {
+                
+                lastCur = cur;
+                SectionType nestedType = SectionProcessor<T>::nestedSectionType(cur);
+                
+                pd.sectionsContext.push_back(nestedType);
+                
+                if (nestedType != UndefinedSectionType) {
+                    cur = SectionProcessor<T>::processNestedSection(cur, collection, pd, report, out);
+                }
+                else if (Adapter::nextSkipsUnexpected ||
+                         SectionProcessor<T>::isUnexpectedNode(cur, pd.sectionContext())) {
+                    cur = SectionProcessor<T>::processUnexpectedNode(cur, collection, pd, lastSectionType, report, out);
+                }
+                
+                if (cur != collection.end() &&
+                    (pd.sectionContext() != UndefinedSectionType ||
+                     (cur->type != mdp::ParagraphMarkdownNodeType &&
+                      cur->type != mdp::CodeMarkdownNodeType))) {
+                         
+                    lastSectionType = pd.sectionContext();
+                }
+                
+                pd.sectionsContext.pop_back();
+                
+                if (lastCur == cur)
+                    break;
+            }
+            
+            return cur;
+        }
+    };
+    
+    /** Parser Adapter for parsing header-defined sections */
+    struct HeaderSectionAdapter {
+        
+        /** \return Node to start parsing with */
+        static const MarkdownNodeIterator startingNode(const MarkdownNodeIterator& seed) {
+            if (seed->type != mdp::HeaderMarkdownNodeType)
+                throw ADAPTER_MISMATCH_ERR;
+            
+            return seed;
+        }
+        
+        /** \return Collection of siblings to starting Node */
+        static const MarkdownNodes& startingNodeSiblings(const MarkdownNodeIterator& seed,
+                                                         const MarkdownNodes& siblings) {
+            return siblings;
+        }
+        
+        /** \return Starting node for next parsing */
+        static const MarkdownNodeIterator nextStartingNode(const MarkdownNodeIterator& seed,
+                                                           const MarkdownNodes& siblings,
+                                                           const MarkdownNodeIterator& cur) {
+            return cur;
+        }
+        
+        /** 
+         *  \brief Adapter Markdown node skipping behavior trait.
+         *
+         *  Adapter trait signalizing that the adapter can possibly skip some Markdown nodes on a nextStartingNode() call.
+         *  If set to true, a call to nextStartingNode() can skip some nodes causing some information loss. False otherwise.
+         */
+        static const bool nextSkipsUnexpected = false;
+    };
+    
+    /** Parser Adapter for parsing list-defined sections */
+    struct ListSectionAdapter {
+        
+        static const MarkdownNodeIterator startingNode(const MarkdownNodeIterator& seed) {
+            if (seed->type != mdp::ListItemMarkdownNodeType)
+                throw ADAPTER_MISMATCH_ERR;
+            
+            return seed->children().begin();
+        }
+        
+        static const MarkdownNodes& startingNodeSiblings(const MarkdownNodeIterator& seed,
+                                                         const MarkdownNodes& siblings) {
+            return seed->children();
+        }
+        
+        static const MarkdownNodeIterator nextStartingNode(const MarkdownNodeIterator& seed,
+                                                           const MarkdownNodes& siblings,
+                                                           const MarkdownNodeIterator& cur) {
+            if (seed == siblings.end())
+                return seed;
+            
+            return ++MarkdownNodeIterator(seed);
+        }
+        
+        static const bool nextSkipsUnexpected = true;
+    };
+
+    /** Parser Adapter for parsing blueprint sections */
+    struct BlueprintSectionAdapter {
+
+        /** \return Node to start parsing with */
+        static const MarkdownNodeIterator startingNode(const MarkdownNodeIterator& seed) {
+            return seed;
+        }
+
+        /** \return Collection of siblings to starting Node */
+        static const MarkdownNodes& startingNodeSiblings(const MarkdownNodeIterator& seed,
+                                                         const MarkdownNodes& siblings) {
+            return siblings;
+        }
+
+        /** \return Starting node for next parsing */
+        static const MarkdownNodeIterator nextStartingNode(const MarkdownNodeIterator& seed,
+                                                           const MarkdownNodes& siblings,
+                                                           const MarkdownNodeIterator& cur) {
+            return cur;
+        }
+        
+        static const bool nextSkipsUnexpected = false;
+    };
+}
+
+#endif

data/ext/snowcrash/src/SectionParserData.h

@@ -0,0 +1,81 @@
+//
+//  SectionParserData.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 5/21/14.
+//  Copyright (c) 2014 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_SECTIONPARSERDATA_H
+#define SNOWCRASH_SECTIONPARSERDATA_H
+
+#include "Blueprint.h"
+#include "Section.h"
+#include "SymbolTable.h"
+
+namespace snowcrash {
+
+    /**
+     *  \brief Blueprint Parser Options.
+     *
+     *  Controls blueprint parser behavior.
+     */
+    enum BlueprintParserOption {
+        RenderDescriptionsOption = (1 << 0),    /// < Render Markdown in description.
+        RequireBlueprintNameOption = (1 << 1)   /// < Treat missing blueprint name as error
+    };
+    
+    typedef unsigned int BlueprintParserOptions;
+    
+    /**
+     *  \brief Section Parser Data
+     *
+     *  State of the parser.
+     */
+    struct SectionParserData {
+        SectionParserData(BlueprintParserOptions opts,
+                          const mdp::ByteBuffer& src,
+                          const Blueprint& bp)
+        : options(opts), sourceData(src), blueprint(bp) {}
+        
+        /** Parser Options */
+        BlueprintParserOptions options;
+        
+        /** Symbol Table */
+        SymbolTable symbolTable;
+        
+        /** Source Data */
+        const mdp::ByteBuffer& sourceData;
+        
+        /** AST being parsed **/
+        const Blueprint& blueprint;
+        
+        /** Sections Context */
+        typedef std::vector<SectionType> SectionsStack;
+        SectionsStack sectionsContext;
+
+        /** \returns Actual Section Context */
+        SectionType sectionContext() const {
+            return (sectionsContext.empty()) ? UndefinedSectionType : sectionsContext.back();
+        }
+        
+        /** \returns Parent Section Context */
+        SectionType parentSectionContext() const {
+            if (sectionsContext.empty())
+                return UndefinedSectionType;
+            
+            size_t size = sectionsContext.size();
+            if (size == 1)
+                return sectionsContext.back();
+            else
+                return sectionsContext[size-2];
+        }
+        
+    private:
+        SectionParserData();
+        SectionParserData(const SectionParserData&);
+        SectionParserData& operator=(const SectionParserData&);
+    };
+}
+
+#endif

data/ext/snowcrash/src/SectionProcessor.h

@@ -0,0 +1,211 @@
+//
+//  Processor.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 5/14/14.
+//  Copyright (c) 2014 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_SECTIONPROCESSOR_H
+#define SNOWCRASH_SECTIONPROCESSOR_H
+
+#include "SectionParserData.h"
+#include "SourceAnnotation.h"
+#include "Signature.h"
+
+namespace snowcrash {
+    
+    using mdp::MarkdownNode;
+    using mdp::MarkdownNodes;
+    using mdp::MarkdownNodeIterator;
+    
+    typedef Collection<SectionType>::type SectionTypes;
+    
+    /**
+     *  Layout of the section being parsed
+     */
+    enum SectionLayout {
+        DefaultSectionLayout,          /// Default Section Layout: Signature > Description > Content > Nested
+        ExclusiveNestedSectionLayout,  /// Section is composed of nested sections only
+        RedirectSectionLayout          /// Section should be parsed by another parser as whole
+    };
+
+    /*
+     * Forward Declarations
+     */
+    template<typename T>
+    struct SectionProcessor;
+    
+    /**
+     *  \brief  Section Processor Base
+     *
+     *  Defines section processor interface alongised with its default
+     *  behavior.
+     */
+    template<typename T>
+    struct SectionProcessorBase {
+
+        /**
+         *  \brief Process section signature Markdown node
+         *  \param node     Node to process
+         *  \param siblings Siblings of the node being processed
+         *  \param pd       Section parser state
+         *  \param report   Process log report
+         *  \param out      Processed output
+         *  \return Result of the process operation
+         */
+        static MarkdownNodeIterator processSignature(const MarkdownNodeIterator& node,
+                                                     const MarkdownNodes& siblings,
+                                                     SectionParserData& pd,
+                                                     SectionLayout& layout,
+                                                     Report& report,
+                                                     T& out) {
+            return ++MarkdownNodeIterator(node);
+        }
+
+        /** Process section description Markdown node */
+        static MarkdownNodeIterator processDescription(const MarkdownNodeIterator& node,
+                                                       const MarkdownNodes& siblings,
+                                                       SectionParserData& pd,
+                                                       Report& report,
+                                                       T& out) {
+
+            if (!out.description.empty()) {
+                TwoNewLines(out.description);
+            }
+
+            out.description += mdp::MapBytesRangeSet(node->sourceMap, pd.sourceData);
+
+            return ++MarkdownNodeIterator(node);
+        }
+        
+        /** Process section-specific content Markdown node */
+        static MarkdownNodeIterator processContent(const MarkdownNodeIterator& node,
+                                                   const MarkdownNodes& siblings,
+                                                   SectionParserData& pd,
+                                                   Report& report,
+                                                   T& out) {
+            return ++MarkdownNodeIterator(node);
+        }
+        
+        /**
+         *  \brief Process nested sections Markdown node(s)
+         *  \param node     Node to process
+         *  \param siblings Siblings of the node being processed
+         *  \param pd       Section parser state
+         *  \param report   Process log report
+         *  \param out      Processed output
+         */
+        static MarkdownNodeIterator processNestedSection(const MarkdownNodeIterator& node,
+                                                         const MarkdownNodes& siblings,
+                                                         SectionParserData& pd,
+                                                         Report& report,
+                                                         T& out) {
+            return node;
+        }
+        
+        /** Process unexpected Markdown node */
+        static MarkdownNodeIterator processUnexpectedNode(const MarkdownNodeIterator& node,
+                                                          const MarkdownNodes& siblings,
+                                                          SectionParserData& pd,
+                                                          SectionType& lastSectionType,
+                                                          Report& report,
+                                                          T& out) {
+
+            // WARN: Ignoring unexpected node
+            std::stringstream ss;
+            mdp::CharactersRangeSet sourceMap = mdp::BytesRangeSetToCharactersRangeSet(node->sourceMap, pd.sourceData);
+
+            if (node->type == mdp::HeaderMarkdownNodeType) {
+                ss << "unexpected header block, expected a group, resource or an action definition";
+                ss << ", e.g. '# Group <name>', '# <resource name> [<URI>]' or '# <HTTP method> <URI>'";
+            } else {
+                ss << "ignoring unrecognized block";
+            }
+
+            report.warnings.push_back(Warning(ss.str(),
+                                              IgnoringWarning,
+                                              sourceMap));
+
+            return ++MarkdownNodeIterator(node);
+        }
+
+        /** Final validation after processing */
+        static void finalize(const MarkdownNodeIterator& node,
+                             SectionParserData& pd,
+                             Report& report,
+                             T& out) {
+        }
+        
+        /** \return True if the node is a section description node */
+        static bool isDescriptionNode(const MarkdownNodeIterator& node,
+                                      SectionType sectionType) {
+
+            if (SectionProcessor<T>::isContentNode(node, sectionType) ||
+                SectionProcessor<T>::nestedSectionType(node) != UndefinedSectionType) {
+
+                return false;
+            }
+
+            SectionType keywordSectionType = SectionKeywordSignature(node);
+
+            if (keywordSectionType == UndefinedSectionType) {
+                return true;
+            }
+
+            SectionTypes nestedTypes = SectionProcessor<T>::nestedSectionTypes();
+
+            if (std::find(nestedTypes.begin(), nestedTypes.end(), keywordSectionType) != nestedTypes.end()) {
+                // Node is a keyword defined section defined in one of the nested sections
+                // Treat it as a description
+                return true;
+            }
+
+            return false;
+        }
+
+        /** \return True if the node is a section-specific content node */
+        static bool isContentNode(const MarkdownNodeIterator& node,
+                                  SectionType sectionType) {
+            return false;
+        }
+
+        /** \return True if the node is unexpected in the current context */
+        static bool isUnexpectedNode(const MarkdownNodeIterator& node,
+                                     SectionType sectionType) {
+            
+            SectionType keywordSectionType = SectionKeywordSignature(node);
+            SectionTypes nestedTypes = SectionProcessor<T>::nestedSectionTypes();
+
+            if (std::find(nestedTypes.begin(), nestedTypes.end(), keywordSectionType) != nestedTypes.end()) {
+                return true;
+            }
+            
+            return (keywordSectionType == UndefinedSectionType);
+        }
+
+        /** \return Nested sections of the section */
+        static SectionTypes nestedSectionTypes() {
+            return SectionTypes();
+        }
+
+        /** \return %SectionType of the node */
+        static SectionType sectionType(const MarkdownNodeIterator& node) {
+            return UndefinedSectionType;
+        }
+        
+        /** \return Nested %SectionType of the node */
+        static SectionType nestedSectionType(const MarkdownNodeIterator& node) {
+            return UndefinedSectionType;
+        }
+    };
+    
+    /**
+     *  Default Section Processor
+     */
+    template<typename T>
+    struct SectionProcessor : public SectionProcessorBase<T> {
+    };
+}
+
+#endif