redsnow 0.2.0 → 0.2.1

data/ext/snowcrash/src/AssetParser.h

@@ -40,32 +40,40 @@ namespace snowcrash {
                                                      const MarkdownNodes& siblings,
                                                      SectionParserData& pd,
                                                      SectionLayout& layout,
-                                                     Report& report,
-                                                     Asset& out) {
+                                                     ParseResult<Asset>& out) {
             
-            out = "";
-            CodeBlockUtility::signatureContentAsCodeBlock(node, pd, report, out);
+            out.node = "";
+            CodeBlockUtility::signatureContentAsCodeBlock(node, pd, out.report, out.node);
+
+            if (pd.exportSourceMap() && !out.node.empty()) {
+                out.sourceMap.sourceMap.append(node->sourceMap);
+            }
+
             return ++MarkdownNodeIterator(node);
         }
         
         static MarkdownNodeIterator processDescription(const MarkdownNodeIterator& node,
                                                        const MarkdownNodes& siblings,
                                                        SectionParserData& pd,
-                                                       Report& report,
-                                                       Asset& out) {
+                                                       ParseResult<Asset>& out) {
+
             return node;
         }
 
         static MarkdownNodeIterator processContent(const MarkdownNodeIterator& node,
                                                    const MarkdownNodes& siblings,
                                                    SectionParserData& pd,
-                                                   Report& report,
-                                                   Asset& out) {
-            
+                                                   ParseResult<Asset>& out) {
             
             mdp::ByteBuffer content;
-            CodeBlockUtility::contentAsCodeBlock(node, pd, report, content);
-            out += content;
+            CodeBlockUtility::contentAsCodeBlock(node, pd, out.report, content);
+
+            out.node += content;
+
+            if (pd.exportSourceMap() && !content.empty()) {
+                out.sourceMap.sourceMap.append(node->sourceMap);
+            }
+
             return ++MarkdownNodeIterator(node);
         }
         

data/ext/snowcrash/src/Blueprint.h

@@ -80,7 +80,16 @@ namespace snowcrash {
      *  E.g. "Content-Type: application/json"
      */
     typedef KeyValuePair Header;
+
+    /** Metadata Collection */
+    typedef Collection<Metadata>::type MetadataCollection;
+
+    /** Headers */
+    typedef Collection<Header>::type Headers;
     
+    /** Collection of Parameter Values */
+    typedef Collection<Value>::type Values;
+
     /** Parameter Use flag */
     enum ParameterUse {
         UndefinedParameterUse,
@@ -110,9 +119,12 @@ namespace snowcrash {
         Value exampleValue;
         
         /** Enumeration of possible values */
-        Collection<Value>::type values;
+        Values values;
     };
 
+    /** Source Map of Collection of Parameters */
+    typedef Collection<Parameter>::type Parameters;
+
     /** Name of a symbol */
     typedef std::string SymbolName;
     
@@ -128,10 +140,10 @@ namespace snowcrash {
         Description description;
         
         /** Payload-specific Parameters */
-        Collection<Parameter>::type parameters;
+        Parameters parameters;
         
         /** Payload-specific Headers */
-        Collection<Header>::type headers;
+        Headers headers;
         
         /** Body */
         Asset body;
@@ -157,6 +169,12 @@ namespace snowcrash {
      */
     typedef Payload Response;
     
+    /** Collection of Requests */
+    typedef Collection<Request>::type Requests;
+
+    /** Collection of Responses */
+    typedef Collection<Response>::type Responses;
+
     /**
      *  An HTTP transaction example.
      */
@@ -169,12 +187,15 @@ namespace snowcrash {
         Description description;
         
         /** Requests */
-        Collection<Request>::type requests;
+        Requests requests;
         
         /** Responses */
-        Collection<Response>::type responses;
+        Responses responses;
     };
     
+    /** Collection of Transaction examples */
+    typedef Collection<TransactionExample>::type TransactionExamples;
+
     /**
      *  Action
      */
@@ -190,7 +211,7 @@ namespace snowcrash {
         Description description;
         
         /** Action-specific Parameters */
-        Collection<Parameter>::type parameters;
+        Parameters parameters;
         
         /** 
          *  \brief Action-specific HTTP headers
@@ -204,12 +225,15 @@ namespace snowcrash {
          *  
          *  Use respective payload's header collection instead.
          */
-        DEPRECATED Collection<Header>::type headers;
+        DEPRECATED Headers headers;
         
         /** Transactions examples */
-        Collection<TransactionExample>::type examples;
+        TransactionExamples examples;
     };
     
+    /** Collection of Actions */
+    typedef Collection<Action>::type Actions;
+
     /**
      *  API Resource
      */
@@ -228,7 +252,7 @@ namespace snowcrash {
         ResourceModel model;
         
         /** Parameters */
-        Collection<Parameter>::type parameters;
+        Parameters parameters;
         
         /**
          *  \brief Resource-specific HTTP Headers
@@ -242,12 +266,15 @@ namespace snowcrash {
          *
          *  Use respective payload's header collection instead.
          */
-        DEPRECATED Collection<Header>::type headers;
+        DEPRECATED Headers headers;
         
         /** A set of Actions specified for this Resource */
-        Collection<Action>::type actions;
+        Actions actions;
     };
     
+    /** Collection of Resources */
+    typedef Collection<Resource>::type Resources;
+
     /**
      *  Group of API Resources
      */
@@ -260,9 +287,12 @@ namespace snowcrash {
         Description description;
         
         /** Resources */
-        Collection<Resource>::type resources;
+        Resources resources;
     };
 
+    /** Collection of Resource groups */
+    typedef Collection<ResourceGroup>::type ResourceGroups;
+
     /** 
      *  \brief API Blueprint AST
      *
@@ -272,7 +302,7 @@ namespace snowcrash {
     struct Blueprint {
         
         /** Metadata */
-        Collection<Metadata>::type metadata;
+        MetadataCollection metadata;
         
         /** The API Name */
         Name name;
@@ -281,7 +311,7 @@ namespace snowcrash {
         Description description;
         
         /** The set of API Resource Groups */
-        Collection<ResourceGroup>::type resourceGroups;
+        ResourceGroups resourceGroups;
     };
 }
 

data/ext/snowcrash/src/BlueprintParser.h

@@ -19,9 +19,7 @@ namespace snowcrash {
 
     const char* const ExpectedAPINameMessage = "expected API name, e.g. '# <API Name>'";
 
-    /** Internal type alias for Collection of Metadata */
-    typedef Collection<Metadata>::type MetadataCollection;
-
+    /** Internal type alias for Collection iterator of Metadata */
     typedef Collection<Metadata>::iterator MetadataCollectionIterator;
 
     /**
@@ -34,22 +32,27 @@ namespace snowcrash {
                                                      const MarkdownNodes& siblings,
                                                      SectionParserData& pd,
                                                      SectionLayout& layout,
-                                                     Report& report,
-                                                     Blueprint& out) {
+                                                     ParseResult<Blueprint>& out) {
 
             MarkdownNodeIterator cur = node;
 
             while (cur != siblings.end() &&
                    cur->type == mdp::ParagraphMarkdownNodeType) {
 
-                MetadataCollection metadata;
-                parseMetadata(cur, pd, report, metadata);
+                ParseResult<MetadataCollection> metadata(out.report);
+                parseMetadata(cur, pd, metadata);
 
                 // First block is paragraph and is not metadata (no API name)
-                if (metadata.empty()) {
-                    return processDescription(cur, siblings, pd, report, out);
+                if (metadata.node.empty()) {
+                    return processDescription(cur, siblings, pd, out);
                 } else {
-                    out.metadata.insert(out.metadata.end(), metadata.begin(), metadata.end());
+                    out.node.metadata.insert(out.node.metadata.end(), metadata.node.begin(), metadata.node.end());
+
+                    if (pd.exportSourceMap()) {
+                        out.sourceMap.metadata.collection.insert(out.sourceMap.metadata.collection.end(),
+                                                                 metadata.sourceMap.collection.begin(),
+                                                                 metadata.sourceMap.collection.end());
+                    }
                 }
 
                 cur++;
@@ -70,12 +73,16 @@ namespace snowcrash {
                     return cur;
                 }
 
-                out.name = cur->text;
-                TrimString(out.name);
+                out.node.name = cur->text;
+                TrimString(out.node.name);
+
+                if (pd.exportSourceMap() && !out.node.name.empty()) {
+                    out.sourceMap.name.sourceMap = cur->sourceMap;
+                }
             } else {
 
                 // Any other type of block, add to description
-                return processDescription(cur, siblings, pd, report, out);
+                return processDescription(cur, siblings, pd, out);
             }
 
             return ++MarkdownNodeIterator(cur);
@@ -84,37 +91,40 @@ namespace snowcrash {
         static MarkdownNodeIterator processNestedSection(const MarkdownNodeIterator& node,
                                                          const MarkdownNodes& siblings,
                                                          SectionParserData& pd,
-                                                         Report& report,
-                                                         Blueprint& out) {
+                                                         ParseResult<Blueprint>& out) {
 
             if (pd.sectionContext() == ResourceGroupSectionType ||
                 pd.sectionContext() == ResourceSectionType) {
 
-                ResourceGroup resourceGroup;
-                MarkdownNodeIterator cur = ResourceGroupParser::parse(node, siblings, pd, report, resourceGroup);
+                ParseResult<ResourceGroup> resourceGroup(out.report);
+                MarkdownNodeIterator cur = ResourceGroupParser::parse(node, siblings, pd, resourceGroup);
 
-                ResourceGroupIterator duplicate = findResourceGroup(out.resourceGroups, resourceGroup);
+                ResourceGroupIterator duplicate = findResourceGroup(out.node.resourceGroups, resourceGroup.node);
 
-                if (duplicate != out.resourceGroups.end()) {
+                if (duplicate != out.node.resourceGroups.end()) {
 
                     // WARN: duplicate resource group
                     std::stringstream ss;
 
-                    if (resourceGroup.name.empty()) {
+                    if (resourceGroup.node.name.empty()) {
                         ss << "anonymous group";
                     } else {
-                        ss << "group '" << resourceGroup.name << "'";
+                        ss << "group '" << resourceGroup.node.name << "'";
                     }
 
                     ss << " is already defined";
 
                     mdp::CharactersRangeSet sourceMap = mdp::BytesRangeSetToCharactersRangeSet(node->sourceMap, pd.sourceData);
-                    report.warnings.push_back(Warning(ss.str(),
-                                                      DuplicateWarning,
-                                                      sourceMap));
+                    out.report.warnings.push_back(Warning(ss.str(),
+                                                          DuplicateWarning,
+                                                          sourceMap));
                 }
 
-                out.resourceGroups.push_back(resourceGroup);
+                out.node.resourceGroups.push_back(resourceGroup.node);
+
+                if (pd.exportSourceMap()) {
+                    out.sourceMap.resourceGroups.collection.push_back(resourceGroup.sourceMap);
+                }
 
                 return cur;
             }
@@ -161,26 +171,25 @@ namespace snowcrash {
 
         static void finalize(const MarkdownNodeIterator& node,
                              SectionParserData& pd,
-                             Report& report,
-                             Blueprint& out) {
+                             ParseResult<Blueprint>& out) {
             
-            if (!out.name.empty())
+            if (!out.node.name.empty())
                 return;
 
             if (pd.options & RequireBlueprintNameOption) {
 
                 // ERR: No API name specified
                 mdp::CharactersRangeSet sourceMap = mdp::BytesRangeSetToCharactersRangeSet(node->sourceMap, pd.sourceData);
-                report.error = Error(ExpectedAPINameMessage,
-                                     BusinessError,
-                                     sourceMap);
+                out.report.error = Error(ExpectedAPINameMessage,
+                                         BusinessError,
+                                         sourceMap);
                 
             }
-            else if (!out.description.empty()) {
+            else if (!out.node.description.empty()) {
                 mdp::CharactersRangeSet sourceMap = mdp::BytesRangeSetToCharactersRangeSet(node->sourceMap, pd.sourceData);
-                report.warnings.push_back(Warning(ExpectedAPINameMessage,
-                                                  APINameWarning,
-                                                  sourceMap));
+                out.report.warnings.push_back(Warning(ExpectedAPINameMessage,
+                                                      APINameWarning,
+                                                      sourceMap));
             }
         }
 
@@ -194,8 +203,7 @@ namespace snowcrash {
 
         static void parseMetadata(const MarkdownNodeIterator& node,
                                   SectionParserData& pd,
-                                  Report& report,
-                                  MetadataCollection& out) {
+                                  ParseResult<MetadataCollection>& out) {
 
             mdp::ByteBuffer content = node->text;
             TrimStringEnd(content);
@@ -209,28 +217,34 @@ namespace snowcrash {
                 Metadata metadata;
 
                 if (CodeBlockUtility::keyValueFromLine(*it, metadata)) {
-                    out.push_back(metadata);
+                    out.node.push_back(metadata);
+
+                    if (pd.exportSourceMap()) {
+                        SourceMap<Metadata> metadataSM;
+                        metadataSM.sourceMap = node->sourceMap;
+                        out.sourceMap.collection.push_back(metadataSM);
+                    }
                 }
             }
 
-            if (lines.size() == out.size()) {
+            if (lines.size() == out.node.size()) {
 
                 // Check duplicates
                 std::vector<mdp::ByteBuffer> duplicateKeys;
 
-                for (MetadataCollectionIterator it = out.begin();
-                     it != out.end();
+                for (MetadataCollectionIterator it = out.node.begin();
+                     it != out.node.end();
                      ++it) {
 
                     MetadataCollectionIterator from = it;
-                    if (++from == out.end())
+                    if (++from == out.node.end())
                         break;
 
                     MetadataCollectionIterator duplicate = std::find_if(from,
-                                                                        out.end(),
+                                                                        out.node.end(),
                                                                         std::bind2nd(MatchFirsts<Metadata>(), *it));
 
-                    if (duplicate != out.end() &&
+                    if (duplicate != out.node.end() &&
                         std::find(duplicateKeys.begin(), duplicateKeys.end(), it->first) == duplicateKeys.end()) {
 
                         duplicateKeys.push_back(it->first);
@@ -240,19 +254,19 @@ namespace snowcrash {
                         ss << "duplicate definition of '" << it->first << "'";
 
                         mdp::CharactersRangeSet sourceMap = mdp::BytesRangeSetToCharactersRangeSet(node->sourceMap, pd.sourceData);
-                        report.warnings.push_back(Warning(ss.str(),
-                                                          DuplicateWarning,
-                                                          sourceMap));
+                        out.report.warnings.push_back(Warning(ss.str(),
+                                                              DuplicateWarning,
+                                                              sourceMap));
                     }
                 }
             }
-            else if (!out.empty()) {
+            else if (!out.node.empty()) {
 
                 // WARN: malformed metadata block
                 mdp::CharactersRangeSet sourceMap = mdp::BytesRangeSetToCharactersRangeSet(node->sourceMap, pd.sourceData);
-                report.warnings.push_back(Warning("ignoring possible metadata, expected '<key> : <value>', one one per line",
-                                                  FormattingWarning,
-                                                  sourceMap));
+                out.report.warnings.push_back(Warning("ignoring possible metadata, expected '<key> : <value>', one one per line",
+                                                      FormattingWarning,
+                                                      sourceMap));
             }
         }
 

data/ext/snowcrash/src/BlueprintSourcemap.h

@@ -0,0 +1,254 @@
+//
+//  BlueprintSourcemap.h
+//  snowcrash
+//
+//  Created by Pavan Kumar Sunkara on 26/8/14.
+//  Copyright (c) 2014 Apiary Inc. All rights reserved.
+//
+
+#ifndef SNOWCRASH_BLUEPRINT_SOURCEMAP_H
+#define SNOWCRASH_BLUEPRINT_SOURCEMAP_H
+
+#include "Blueprint.h"
+#include "MarkdownParser.h"
+
+/**
+ *  API Blueprint Sourcemap Abstract Syntax Tree
+ *  ---------------------------------------------
+ *
+ *  Data types in this documents define the API Blueprint Sourcemap AST.
+ */
+
+#define SOURCE_MAP_COLLECTION(T, TC) template<>\
+struct SourceMap<TC> {\
+    Collection<SourceMap<T> >::type collection;\
+};\
+
+namespace snowcrash {
+
+    struct SourceMapBase {
+        mdp::BytesRangeSet sourceMap;
+    };
+
+    template<typename T>
+    struct SourceMap : public SourceMapBase {
+    };
+
+    /** Source Map of Metadata Collection */
+    SOURCE_MAP_COLLECTION(Metadata, MetadataCollection)
+
+    /** Source Map of Headers */
+    // 'Metadata' type is same as 'Header'
+
+    /** Source Map of Collection of Parameter values */
+    SOURCE_MAP_COLLECTION(Value, Values)
+
+    /** Source Map Structure for Parameter */
+    template<>
+    struct SourceMap<Parameter> : public SourceMapBase {
+
+        /** Source Map of Parameter Name */
+        SourceMap<Name> name;
+
+        /** Source Map of Parameter Description */
+        SourceMap<Description> description;
+
+        /** Source Map of Parameter Type */
+        SourceMap<Type> type;
+
+        /** Source Map of Required flag */
+        SourceMap<ParameterUse> use;
+
+        /** Source Map of Default Value, applicable only when `required == false` */
+        SourceMap<Value> defaultValue;
+
+        /** Source Map of Example Value */
+        SourceMap<Value> exampleValue;
+
+        /** Enumeration of possible values */
+        SourceMap<Values> values;
+    };
+
+    /** Source Map of Collection of Parameters */
+    SOURCE_MAP_COLLECTION(Parameter, Parameters)
+
+    /**
+     * Source Map Structure for Payload
+     */
+    template<>
+    struct SourceMap<Payload> : public SourceMapBase {
+
+        /** Source Map of a Payload Name */
+        SourceMap<Name> name;
+
+        /** Source Map of Payload Description */
+        SourceMap<Description> description;
+
+        /** Payload-specific Parameters */
+        SourceMap<Parameters> parameters;
+
+        /** Payload-specific Headers */
+        SourceMap<Headers> headers;
+
+        /** Source Map of Body */
+        SourceMap<Asset> body;
+
+        /** Source Map of Schema */
+        SourceMap<Asset> schema;
+
+        /** Source Map of Symbol */
+        SourceMap<SymbolName> symbol;
+    };
+
+    /** Source Map of Collection of Requests */
+    SOURCE_MAP_COLLECTION(Request, Requests)
+
+    /** Source Map of Collection of Responses */
+    // 'Response' type is same as 'Request'
+
+    /**
+     *  Source Map Structure for an HTTP transaction example.
+     */
+    template<>
+    struct SourceMap<TransactionExample> : public SourceMapBase {
+
+        /** Source Map of an example name */
+        SourceMap<Name> name;
+
+        /** Source Map of Description */
+        SourceMap<Description> description;
+
+        /** Requests */
+        SourceMap<Requests> requests;
+
+        /** Responses */
+        SourceMap<Responses> responses;
+    };
+
+    /** Source Map of Collection of Transaction examples */
+    SOURCE_MAP_COLLECTION(TransactionExample, TransactionExamples)
+
+    /**
+     *  Source Map Structure for Action
+     */
+    template<>
+    struct SourceMap<Action> : public SourceMapBase {
+
+        /** Source Map of HTTP method */
+        SourceMap<HTTPMethod> method;
+
+        /** Source Map of an Action name */
+        SourceMap<Name> name;
+
+        /** Source Map of Description */
+        SourceMap<Description> description;
+
+        /** Action-specific Parameters */
+        SourceMap<Parameters> 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 SourceMap<Headers> headers;
+
+        /** Transactions examples */
+        SourceMap<TransactionExamples> examples;
+    };
+
+    /** Source Map of Collection of Actions */
+    SOURCE_MAP_COLLECTION(Action, Actions)
+
+    /**
+     *  Source Map Structure for API Resource
+     */
+    template<>
+    struct SourceMap<Resource> : public SourceMapBase {
+
+        /** Source Map of URI template */
+        SourceMap<URITemplate> uriTemplate;
+
+        /** Source Map of a Resource Name */
+        SourceMap<Name> name;
+
+        /** Source Map of Description of the resource */
+        SourceMap<Description> description;
+
+        /** Model representing this Resource */
+        SourceMap<ResourceModel> model;
+
+        /** Parameters */
+        SourceMap<Parameters> 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 SourceMap<Headers> headers;
+
+        /** A set of Actions specified for this Resource */
+        SourceMap<Actions> actions;
+    };
+
+    /** Source Map of Collection of Resources */
+    SOURCE_MAP_COLLECTION(Resource, Resources)
+
+    /**
+     *  Source Map Structure for Group of API Resources
+     */
+    template<>
+    struct SourceMap<ResourceGroup> : public SourceMapBase {
+
+        /** Source Map of a Group Name */
+        SourceMap<Name> name;
+
+        /** Source Map of Group description */
+        SourceMap<Description> description;
+
+        /** Resources */
+        SourceMap<Resources> resources;
+    };
+
+    /** Source Map of Collection of Resource groups */
+    SOURCE_MAP_COLLECTION(ResourceGroup, ResourceGroups)
+
+    /**
+     *  \brief API Blueprint Sourcemap AST
+     *
+     *  This is top-level (or root if you prefer) of API Blueprint Sourcemap abstract syntax tree.
+     *  Start reading a parsed API here.
+     */
+    template<>
+    struct SourceMap<Blueprint> : public SourceMapBase {
+
+        /** Source Map of API Blueprint metadata */
+        SourceMap<MetadataCollection> metadata;
+
+        /** Source Map of the API Name */
+        SourceMap<Name> name;
+
+        /** Source Map of an API Overview description */
+        SourceMap<Description> description;
+
+        /** The set of API Resource Groups */
+        SourceMap<ResourceGroups> resourceGroups;
+    };
+}
+
+#endif