redsnow 0.0.8

data/ext/snowcrash/src/AssetParser.h

@@ -0,0 +1,215 @@
+//
+//  AssetParser.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 5/17/13.
+//  Copyright (c) 2013 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_ASSETPARSER_H
+#define SNOWCRASH_ASSETPARSER_H
+
+#include <sstream>
+#include "BlueprintParserCore.h"
+#include "Blueprint.h"
+#include "RegexMatch.h"
+#include "StringUtility.h"
+#include "SectionUtility.h"
+
+namespace snowcrashconst {
+    
+    /** Body matching regex */
+    const char* const BodyRegex("^[[:blank:]]*[Bb]ody[[:blank:]]*$");
+
+    /** Schema matching regex */
+    const char* const SchemaRegex("^[[:blank:]]*[Ss]chema[[:blank:]]*$");
+}
+
+namespace snowcrash {
+    
+    /// Asset signature
+    enum AssetSignature {
+        UndefinedAssetSignature,
+        NoAssetSignature,
+        BodyAssetSignature,         /// < Explicit body asset
+        PayloadBodyAssetSignature,  /// < Body asset using abbreviated syntax
+        SchemaAssetSignature,       /// < Explicit Schema asset
+        GenericAssetSignature
+    };
+    
+    // Query asset signature a of given block
+    FORCEINLINE AssetSignature GetAssetSignature(const BlockIterator& begin,
+                                                 const BlockIterator& end) {
+        
+        if (begin->type == ListBlockBeginType || begin->type == ListItemBlockBeginType) {
+            
+            BlockIterator cur = ListItemNameBlock(begin, end);
+            if (cur == end)
+                return NoAssetSignature;
+            
+            if (cur->type != ParagraphBlockType &&
+                cur->type != ListItemBlockEndType)
+                return NoAssetSignature;
+            
+            std::string content = GetFirstLine(cur->content);
+            if (RegexMatch(content, snowcrashconst::BodyRegex))
+                return BodyAssetSignature;
+
+            if (RegexMatch(content, snowcrashconst::SchemaRegex))
+                return SchemaAssetSignature;
+            
+            if (HasPayloadAssetSignature(begin, end))
+                return PayloadBodyAssetSignature;
+        }
+        
+        return NoAssetSignature;
+    }
+    
+    FORCEINLINE bool HasAssetSignature(const BlockIterator& begin,
+                                       const BlockIterator& end) {
+        AssetSignature signature = GetAssetSignature(begin, end);
+        return (signature != NoAssetSignature);
+    }
+    
+    /**
+     *  Return true if given block might be a dangling asset block,
+     *  false otherwise.
+     */
+    FORCEINLINE bool IsDanglingBlock(const BlockIterator& begin, const BlockIterator& end) {
+        return (begin->type == ParagraphBlockType
+                || begin->type == CodeBlockType);
+    }
+    
+    /**
+     *  Block Classifier, asset context.
+     */
+    template <>
+    FORCEINLINE SectionType ClassifyBlock<Asset>(const BlockIterator& begin,
+                                                 const BlockIterator& end,
+                                                 const SectionType& context) {
+        
+        if (context == UndefinedSectionType) {
+            AssetSignature asset = GetAssetSignature(begin, end);
+            if (asset == BodyAssetSignature || asset == PayloadBodyAssetSignature)
+                return BodySectionType;
+            if (asset == SchemaAssetSignature)
+                return SchemaSectionType;
+        }
+        else if (context == BodySectionType ||
+                 context == SchemaSectionType) {
+            
+            // SectionType closure
+            if (begin->type == ListItemBlockEndType ||
+                begin->type == ListBlockEndType) {
+
+                // Look ahead for a dangling asset
+                BlockIterator cur = CloseNestedList(begin, end);
+                if (cur == end)
+                    return UndefinedSectionType;
+                
+                if (IsDanglingBlock(cur, end))
+                    return (context == BodySectionType) ? DanglingBodySectionType : DanglingSchemaSectionType;
+                else
+                    return UndefinedSectionType;
+            }
+            
+            // Adjacent list item
+            if (begin->type == ListItemBlockBeginType) {
+                    return UndefinedSectionType;
+            }
+        }
+        else if (context == DanglingBodySectionType ||
+                 context == DanglingSchemaSectionType) {
+            
+            if (begin->type == ListItemBlockEndType ||
+                begin->type == ListBlockEndType)
+                return UndefinedSectionType;
+            
+            if (!IsDanglingBlock(begin, end))
+                return UndefinedSectionType;
+        }
+        
+        return (context == BodySectionType ||
+                context == SchemaSectionType ||
+                context == DanglingBodySectionType ||
+                context == DanglingSchemaSectionType) ? context : UndefinedSectionType;
+    }
+    
+    //
+    // Asset SectionType Parser
+    //
+    template<>
+    struct SectionParser<Asset> {
+        
+        static ParseSectionResult ParseSection(const BlueprintSection& section,
+                                               const BlockIterator& cur,
+                                               BlueprintParserCore& parser,
+                                               Asset& asset) {
+            
+            ParseSectionResult result = std::make_pair(Result(), cur);
+            switch (section.type) {
+                case BodySectionType:
+                case SchemaSectionType: 
+                    result = HandleAssetSectionBlock(section, cur, parser, asset);
+                    break;
+                    
+                case DanglingBodySectionType:
+                case DanglingSchemaSectionType:
+                    result = HandleDanglingAssetSectionBlock(section, cur, parser, asset);
+                    break;
+                    
+                case UndefinedSectionType:
+                    result.second = CloseList(cur, section.bounds.second);
+                    break;
+                    
+                default:
+                    result.first.error = UnexpectedBlockError(section, cur, parser.sourceData);
+                    break;
+            }
+            
+            return result;
+        }
+        
+        static void Finalize(const SectionBounds& bounds,
+                             BlueprintParserCore& parser,
+                             Asset& asset,
+                             Result& result) {}
+        
+        static ParseSectionResult HandleAssetSectionBlock(const BlueprintSection& section,
+                                                          const BlockIterator& cur,
+                                                          BlueprintParserCore& parser,
+                                                          Asset& asset) {
+
+            SourceData data;
+            SourceDataBlock sourceMap;
+            // NOTE: Use `Payload` traits for parsing pre-formatted list block.
+            ParseSectionResult result = ParseListPreformattedBlock<Payload>(section,
+                                                                            cur,
+                                                                            parser,
+                                                                            data,
+                                                                            sourceMap);
+            if (result.first.error.code != Error::OK ||
+                parser.sourceData.empty())
+                return result;
+            
+            asset += data;
+            return result;
+        }
+        
+        static ParseSectionResult HandleDanglingAssetSectionBlock(const BlueprintSection& section,
+                                                                  const BlockIterator& cur,
+                                                                  BlueprintParserCore& parser,
+                                                                  Asset& asset) {
+            
+            // Skip any closing list blocks
+            BlockIterator sectionCur = CloseNestedList(cur, section.bounds.second);
+            return HandleAssetSectionBlock(section, sectionCur, parser, asset);
+        }
+
+    };
+    
+    typedef BlockParser<Asset, SectionParser<Asset> > AssetParser;
+
+}
+
+#endif

data/ext/snowcrash/src/BlockUtility.h

@@ -0,0 +1,186 @@
+//
+//  BlockUtility.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 11/11/13.
+//  Copyright (c) 2013 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_BLOCKUTILITY_H
+#define SNOWCRASH_BLOCKUTILITY_H
+
+#include "BlueprintSection.h"
+#include "StringUtility.h"
+
+namespace snowcrash {
+    
+    /**
+     *  \brief  Skip to the matching closing block.
+     *  \param  begin   Begin of the section inside a block buffer.
+     *  \param  end     End of the block buffer.
+     *  \param  sectionBegin    A %MarkdownBlockType of the beginning.
+     *  \param  sectionEnd      A %MarkdownBlockType of the end.
+     *  \return An iterator pointing to the end of the section.
+     *
+     *  Advances iterator from the begin of a section to the end
+     *  of a section at the same nesting level.
+     */
+    FORCEINLINE BlockIterator SkipToClosingBlock(const BlockIterator& begin,
+                                                 const BlockIterator& end,
+                                                 MarkdownBlockType sectionBegin,
+                                                 MarkdownBlockType sectionEnd) {
+        
+        BlockIterator currentBlock = begin;
+        if (currentBlock->type == sectionBegin) {
+            int level = 1;
+            ++currentBlock;
+            while (currentBlock != end && level) {
+                if (currentBlock->type == sectionBegin)
+                    ++level;
+                
+                if (currentBlock->type == sectionEnd)
+                    --level;
+                
+                if (level)
+                    ++currentBlock;
+            }
+        }
+        
+        return currentBlock;
+    }
+    
+    /**
+     *  \brief  Parse one line of raw `key:value` data.
+     *  \param  line    A line to parse.
+     *  \param  keyValuePair    The output buffer to place the parsed data into.
+     *  \return True on success, false otherwise.
+     */
+    FORCEINLINE bool KeyValueFromLine(const std::string& line,
+                                      KeyValuePair& keyValuePair) {
+        
+        std::vector<std::string> rawMetadata = SplitOnFirst(line, ':');
+        if (rawMetadata.size() != 2)
+            return false;
+        
+        keyValuePair = std::make_pair(rawMetadata[0], rawMetadata[1]);
+        TrimString(keyValuePair.first);
+        TrimString(keyValuePair.second);
+        
+        return (!keyValuePair.first.empty() && !keyValuePair.second.empty());
+    }
+    
+    /**
+     *  \brief  Construct unexpected block error message for given block.
+     *  \param  section A section being parsed.
+     *  \param  cue     Cursor to the unexpected markdown block.
+     *  \param  sourceData  Source data byte buffer.
+     *  \return An Error with description relevant to the type of the unexpected block.
+     *
+     *  This function 
+     */
+    FORCEINLINE Error UnexpectedBlockError(const BlueprintSection& section,
+                                           const BlockIterator& cur,
+                                           const SourceData& sourceData) {
+        
+        
+        std::stringstream ss;
+        ss << "unexpected " << BlockName(cur->type) << " block";
+        
+        if (section.hasParent()) {
+            
+            switch (section.parent().type) {
+
+                // Top-level section
+                case UndefinedSectionType:
+                    ss << ", expected a group, resource or an action definition, e.g. ";
+                    ss << "'# Group <name>', '# <resource name> [<URI>]' or '# <HTTP method> <URI>'";
+                    break;
+
+                // TODO: other sections
+                    
+                default:
+                    break;
+            }
+        }
+        
+        return Error(ss.str(),
+                     BusinessError,
+                     MapSourceDataBlock(cur->sourceMap, sourceData));
+    }
+    
+    
+    /**
+     *  \brief  Retrieves source code character map for a markdown block.
+     *  \param  cur         A block to retrieve the characters map for.
+     *  \param  fallback    Alternative block if %cur map source does not exists.
+     *  \param  bounds      Boundaries of the %cur and %fallback container.
+     *  \param  sourceData  Source data to map.
+     *  \returns            Character map for given markdown block or its alternative block,
+     *                      if exists. Empty source character map otherwise.
+     */
+    FORCEINLINE SourceCharactersBlock CharacterMapForBlock(const BlockIterator& cur,
+                                                           const BlockIterator& fallback,
+                                                           const SectionBounds& bounds,
+                                                           const SourceData& sourceData)
+    {
+        // Try to use cursor's source map
+        if (cur != bounds.second &&
+            !cur->sourceMap.empty()) {
+            return MapSourceDataBlock(cur->sourceMap, sourceData);
+        }
+        
+        // Fallback to alternative (previous) block
+        if (fallback != bounds.second &&
+            !fallback->sourceMap.empty()) {
+            return MapSourceDataBlock(fallback->sourceMap, sourceData);
+        }
+        
+        return SourceCharactersBlock();
+    }
+    
+    /**
+     *  \brief Checks cursor validity within its container.
+     *  \param section   A section to check against.
+     *  \param cur  An iterator to be checked.
+     *  \param sourceData   Source data byte buffer.
+     *  \param result   Error result output, an error object is added in case of failed check.
+     *  \returns True if cursor appears to be valid, false otherwise.
+     */
+    FORCEINLINE bool CheckCursor(const BlueprintSection& section,
+                                 const BlockIterator& cur,
+                                 const SourceData& sourceData,
+                                 Result& result) {
+        if (cur != section.bounds.second)
+            return true;
+        
+        if (!section.hasParent() ||
+            section.parent().bounds.first->sourceMap.empty())
+            return false;
+        
+        // ERR: Sanity check
+        SourceCharactersBlock sourceBlock = CharacterMapForBlock(section.parent().bounds.first,
+                                                                 section.parent().bounds.second,
+                                                                 section.parent().bounds,
+                                                                 sourceData);
+        result.error = Error("unexpected markdown closure",
+                             ApplicationError,
+                             sourceBlock);
+        return false;
+    }
+    
+    /**
+     *  \brief Check header block for an potential ambiguous signature
+     *  \return True if a header does not contain potential ambiguous signature, false otherwise.
+     */
+    template <class T>
+    FORCEINLINE bool CheckHeaderBlock(const BlueprintSection& section,
+                                      const BlockIterator& cur,
+                                      const SourceData& sourceData,
+                                      Result& result) {
+        
+        return false;
+    }
+}
+
+
+#endif

data/ext/snowcrash/src/Blueprint.h

@@ -0,0 +1,283 @@
+//
+//  Blueprint.h
+//  snowcrash
+//
+//  Created by Zdenek Nemec on 4/3/13.
+//  Copyright (c) 2013 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_BLUEPRINT_H
+#define SNOWCRASH_BLUEPRINT_H
+
+#include <vector>
+#include <string>
+#include <utility>
+#include "Platform.h"
+
+/**
+ *  API Blueprint Abstract Syntax Tree
+ *  -----------------------------------
+ *
+ *  Data types in this documents define the API Blueprint AST.
+ */
+
+namespace snowcrash {
+    
+    /** Name of a an API Blueprint entity. */
+    typedef std::string Name;
+
+    /** 
+     *  \brief An API Blueprint entity Description.
+     *
+     *  Depending on parser setting the description might be 
+     *  rendered HTML from Markdown or raw Markdown.
+     */
+    typedef std::string Description;
+    
+    /** URI */
+    typedef std::string URI;
+    
+    /** URI template */
+    typedef std::string URITemplate;
+    
+    /** HTTP Method */
+    typedef std::string HTTPMethod;
+
+    /** Parameter Type */
+    typedef std::string Type;
+    
+    /** Parameter Value */
+    typedef std::string Value;
+     
+    /** A generic key - value pair */
+    typedef std::pair<std::string, std::string> KeyValuePair;
+    
+    /**
+     * Default Container for collections.
+     *
+     *  FIXME: Use C++11 template aliases when migrating to C++11.
+     */
+    template<typename T>
+    struct Collection {
+        typedef std::vector<T> type;
+        typedef typename std::vector<T>::iterator iterator;
+        typedef typename std::vector<T>::const_iterator const_iterator;
+    };
+    
+    /** An asset data */
+    typedef std::string Asset;
+
+    /** 
+     *  \brief Metadata key-value pair,
+     *
+     *  E.g. "HOST: http://acme.com"
+     */
+    typedef KeyValuePair Metadata;
+
+    /** 
+     *  \brief  Header key-value pair.
+     *
+     *  E.g. "Content-Type: application/json"
+     */
+    typedef KeyValuePair Header;
+    
+    /** Parameter Use flag */
+    enum ParameterUse {
+        UndefinedParameterUse,
+        OptionalParameterUse,
+        RequiredParameterUse
+    };
+    
+    /** Parameter */
+    struct Parameter {
+        
+        /** Parameter Name */
+        Name name;
+        
+        /** Parameter Description */
+        Description description;
+        
+        /** Type */
+        Type type;
+        
+        /** Required flag */
+        ParameterUse use;
+        
+        /** Default Value, applicable only when `required == false` */
+        Value defaultValue;
+        
+        /** Example Value */
+        Value exampleValue;
+        
+        /** Enumeration of possible values */
+        Collection<Value>::type values;
+    };
+
+    
+    /**
+     *  Payload
+     */
+    struct Payload {
+        
+        /** A Payload Name */
+        Name name;
+        
+        /** Payload Description */
+        Description description;
+        
+        /** Payload-specific Parameters */
+        Collection<Parameter>::type parameters;
+        
+        /** Payload-specific Headers */
+        Collection<Header>::type headers;
+        
+        /** Body */
+        Asset body;
+        
+        /** Schema */
+        Asset schema;
+    };
+    
+    /** Resource Model */
+    typedef Payload ResourceModel;
+    
+    /** Request */
+    typedef Payload Request;
+    
+    /** 
+     *  \brief Response
+     *
+     *  A payload returned in a response to an action.
+     *  Payload's name represents the HTTP status code.
+     */
+    typedef Payload Response;
+    
+    /**
+     *  An HTTP transaction example.
+     */
+    struct TransactionExample {
+        
+        /** An example name */
+        Name name;
+        
+        /** Description */
+        Description description;
+        
+        /** Requests */
+        Collection<Request>::type requests;
+        
+        /** Responses */
+        Collection<Response>::type responses;
+    };
+    
+    /**
+     *  Action
+     */
+    struct Action {
+        
+        /** HTTP method */
+        HTTPMethod method;
+        
+        /** An Action name */
+        Name name;
+        
+        /** Description */
+        Description description;
+        
+        /** Action-specific Parameters */
+        Collection<Parameter>::type parameters;
+        
+        /** 
+         *  \brief Action-specific HTTP headers
+         *
+         *  DEPRECATION WARNING:
+         *  --------------------
+         *
+         *  This AST node is build for deprecated API Blueprint syntax
+         *  and as such it will be removed in a future version of 
+         *  Snow Crash. 
+         *  
+         *  Use respective payload's header collection instead.
+         */
+        DEPRECATED Collection<Header>::type headers;
+        
+        /** Transactions examples */
+        Collection<TransactionExample>::type examples;
+    };
+    
+    /**
+     *  API Resource
+     */
+    struct Resource {
+        
+        /** URI template */
+        URITemplate uriTemplate;
+        
+        /** A Resource Name */
+        Name name;
+        
+        /** Description of the resource */
+        Description description;
+        
+        /** Model representing this Resource */
+        ResourceModel model;
+        
+        /** Parameters */
+        Collection<Parameter>::type parameters;
+        
+        /**
+         *  \brief Resource-specific HTTP Headers
+         *
+         *  DEPRECATION WARNING:
+         *  --------------------
+         *
+         *  This AST node is build for deprecated API Blueprint syntax
+         *  and as such it will be removed in a future version of
+         *  Snow Crash.
+         *
+         *  Use respective payload's header collection instead.
+         */
+        DEPRECATED Collection<Header>::type headers;
+        
+        /** A set of Actions specified for this Resource */
+        Collection<Action>::type actions;
+    };
+    
+    /**
+     *  Group of API Resources
+     */
+    struct ResourceGroup {
+        
+        /** A Group Name */
+        Name name;
+        
+        /** Group description */
+        Description description;
+        
+        /** Resources */
+        Collection<Resource>::type resources;
+    };
+    
+    /** 
+     *  \brief API Blueprint AST
+     *
+     *  This is top-level (or root if you prefer) of API Blueprint abstract syntax tree.
+     *  Start reading a parsed API here.
+     */
+    struct Blueprint {
+        
+        /** Metadata */
+        Collection<Metadata>::type metadata;
+        
+        /** The API Name */
+        Name name;
+
+        /** An API Overview description */
+        Description description;
+        
+        /** The set of API Resource Groups */
+        Collection<ResourceGroup>::type resourceGroups;
+    };
+}
+
+#endif