prmd 0.7.0 → 0.7.1

data/lib/prmd/multi_loader/yajl.rb

@@ -0,0 +1,19 @@
+require 'prmd/multi_loader/loader'
+require 'yajl'
+
+module Prmd #:nodoc:
+  module MultiLoader #:nodoc:
+    # JSON MultiLoader using Yajl
+    module Yajl
+      extend Prmd::MultiLoader::Loader
+
+      # @see (Prmd::MultiLoader::Loader#load_data)
+      def self.load_data(data)
+        ::Yajl::Parser.parse(data)
+      end
+
+      # register this loader for all .json files
+      extensions '.json'
+    end
+  end
+end

data/lib/prmd/multi_loader/yaml.rb

@@ -0,0 +1,19 @@
+require 'prmd/multi_loader/loader'
+require 'yaml'
+
+module Prmd #:nodoc:
+  module MultiLoader #:nodoc:
+    # YAML MultiLoader
+    module Yaml
+      extend Prmd::MultiLoader::Loader
+
+      # @see (Prmd::MultiLoader::Loader#load_data)
+      def self.load_data(data)
+        ::YAML.load(data)
+      end
+
+      # register this loader for all .yaml and .yml files
+      extensions '.yaml', '.yml'
+    end
+  end
+end

data/lib/prmd/multi_loader/yml.rb

@@ -0,0 +1,2 @@
+# alias for yaml
+require 'prmd/multi_loader/yaml'

data/lib/prmd/rake_tasks/base.rb

@@ -14,20 +14,48 @@ module Prmd
       attr_accessor :name
 
       # Options to pass to command
-      # @return [Hash<Symbol, Object>] the options passed to the command
+      # @return [Hash<Symbol, Object>] the options passed to the Prmd command
       attr_accessor :options
 
       # Creates a new task with name +name+.
       #
-      # @param [String, Symbol] name the name of the rake task
-      def initialize(name)
-        @name = name
-        @options = {}
+      # @param [Hash<Symbol, Object>] options
+      #   .option [String, Symbol] name  the name of the rake task
+      #   .option [String, Symbol] options  options to pass to the Prmd command
+      def initialize(options = {})
+        @name = options.fetch(:name, default_name)
+        @options = options.fetch(:options) { {} }
 
         yield self if block_given?
 
         define
       end
+
+      private
+
+      # This method will be removed in the future
+      # @api private
+      def legacy_parameters(*args)
+        if args.size == 0
+          return {}
+        else
+          arg, = *args
+          case arg
+          when String, Symbol
+            warn "#{self.class}.new(name) has been deprecated, use .new(name: name) instead"
+            return { name: arg }
+          else
+            return arg
+          end
+        end
+      end
+
+      # Default name of the rake task
+      #
+      # @return [Symbol]
+      def default_name
+        :base
+      end
     end
   end
 end

data/lib/prmd/rake_tasks/combine.rb

@@ -24,10 +24,26 @@ module Prmd
 
       # Creates a new task with name +name+.
       #
-      # @param [String, Symbol] name the name of the rake task
-      def initialize(name = :combine)
-        @paths = []
-        super
+      # @overload initialize(name)
+      #   @param [String]
+      # @overload initialize(options)
+      #   @param [Hash<Symbol, Object>] options
+      #     .option [String] output_file
+      #     .option [Array<String>] paths
+      def initialize(*args, &block)
+        options = legacy_parameters(*args)
+        @paths = options.fetch(:paths) { [] }
+        @output_file = options[:output_file]
+        super options, &block
+      end
+
+      private
+
+      # Default name of the rake task
+      #
+      # @return [Symbol]
+      def default_name
+        :combine
       end
 
       protected

data/lib/prmd/rake_tasks/doc.rb

@@ -15,21 +15,33 @@ module Prmd
     #     t.files = { 'schema/api.json' => 'schema/api.md' }
     #   end
     class Doc < Base
-      # Schema files that should be verified
+      # Schema files that should be rendered
       # @return [Array<String>, Hash<String, String>] list of files
       attr_accessor :files
 
       # Creates a new task with name +name+.
       #
-      # @param [String, Symbol] name the name of the rake task
-      def initialize(name = :doc, &block)
-        @files = []
-        super name, &block
+      # @overload initialize(name)
+      #   @param [String]
+      # @overload initialize(options)
+      #   @param [Hash<Symbol, Object>] options
+      #     .option [Array<String>, Hash<String, String>] files  schema files
+      def initialize(*args, &block)
+        options = legacy_parameters(*args)
+        @files = options.fetch(:files) { [] }
+        super options, &block
         @options[:template] ||= Prmd::Template.template_dirname
       end
 
       private
 
+      # Default name of the rake task
+      #
+      # @return [Symbol]
+      def default_name
+        :doc
+      end
+
       # Render file to markdown
       #
       # @param [String] filename
@@ -40,13 +52,17 @@ module Prmd
         Prmd.render(schema, options)
       end
 
+      # Render +infile+ to +outfile+
+      #
       # @param [String] infile
       # @param [String] outfile
       # @return [void]
       def render_to_file(infile, outfile)
         result = render_file(infile)
-        File.open(outfile, 'w') do |file|
-          file.write(result)
+        if outfile
+          File.open(outfile, 'w') do |file|
+            file.write(result)
+          end
         end
       end
 
@@ -55,7 +71,7 @@ module Prmd
       # Defines the rake task
       # @return [void]
       def define
-        desc 'Verifying schemas' unless Rake.application.last_comment
+        desc 'Generate documentation' unless Rake.application.last_comment
         task(name) do
           if files.is_a?(Hash)
             files.each do |infile, outfile|

data/lib/prmd/rake_tasks/verify.rb

@@ -19,14 +19,26 @@ module Prmd
 
       # Creates a new task with name +name+.
       #
-      # @param [String, Symbol] name the name of the rake task
-      def initialize(name = :verify)
-        @files = []
-        super
+      # @overload initialize(name)
+      #   @param [String]
+      # @overload initialize(options)
+      #   @param [Hash<Symbol, Object>] options
+      #     .option [Array<String>] files  schema files to verify
+      def initialize(*args, &block)
+        options = legacy_parameters(*args)
+        @files = options.fetch(:files) { [] }
+        super options, &block
       end
 
       private
 
+      # Default name of the rake task
+      #
+      # @return [Symbol]
+      def default_name
+        :verify
+      end
+
       # Defines the rake task
       #
       # @param [String] filename
@@ -46,7 +58,7 @@ module Prmd
       # Defines the rake task
       # @return [void]
       def define
-        desc 'Verifying schemas' unless Rake.application.last_comment
+        desc 'Verify schemas' unless Rake.application.last_comment
         task(name) do
           all_errors = []
           files.each do |filename|

data/lib/prmd/schema.rb

@@ -103,7 +103,11 @@ module Prmd
       elsif value.key?('items') # array of objects
         _, items = dereference(value['items'])
         if value['items'].key?('example')
-          [items['example']]
+          if items["example"].is_a?(Array)
+            items["example"]
+          else
+            [items['example']]
+          end
         else
           [schema_example(items)]
         end

data/lib/prmd/templates/combine_head.json

@@ -1,6 +1,6 @@
 {
-  "$schema": "http://json-schema.org/draft-04/hyper-schema",
+  "$schema": "http://interagent.github.io/interagent-hyper-schema",
+  "type": ["object"],
   "definitions": {},
-  "properties": {},
-  "type": ["object"]
+  "properties": {}
 }

data/lib/prmd/templates/init_default.json

@@ -1,9 +1,11 @@
  {
   "$schema": "http://json-schema.org/draft-04/hyper-schema",
   "title": "FIXME",
-  "definitions": {},
   "description": "FIXME",
+  "stability": "prototype",
+  "strictProperties": true,
+  "type": ["object"],
+  "definitions": {},
   "links": [],
-  "properties": {},
-  "type": ["object"]
+  "properties": {}
 }

data/lib/prmd/templates/init_resource.json.erb

@@ -5,11 +5,25 @@
     "id": {
       "description": "unique identifier of <%= resource %>",
       "example": "01234567-89ab-cdef-0123-456789abcdef",
+      "readOnly": true,
       "format": "uuid",
       "type": ["string"]
     },
+    "name": {
+      "description": "unique name of <%= resource %>",
+      "example": "name",
+      "readOnly": true,
+      "type": ["string"]
+    },
     "identity": {
-      "$ref": "/schemata/<%= resource %>#/definitions/id"
+      "anyOf": [
+        {
+          "$ref": "/schemata/<%= resource %>#/definitions/id"
+	},
+	{
+          "$ref": "/schemata/<%= resource %>#/definitions/name"
+	}
+      ]
     },
     "created_at": {
       "description": "when <%= resource %> was created",
@@ -31,6 +45,9 @@
     "id": {
       "$ref": "/schemata/<%= resource %>#/definitions/id"
     },
+    "name": {
+      "$ref": "/schemata/<%= resource %>#/definitions/name"
+    },
     "updated_at": {
       "$ref": "/schemata/<%= resource %>#/definitions/updated_at"
     }

data/lib/prmd/templates/schemata.md.erb

@@ -12,16 +12,19 @@
 -%>
 <%- unless options[:doc][:disable_title_and_description] %>
 ## <%= title %>
+
 <%= schemata['description'] %>
 <%- end -%>
 
 <%- if schemata['properties'] && !schemata['properties'].empty? %>
 ### Attributes
+
 | Name | Type | Description | Example |
 | ------- | ------- | ------- | ------- |
 <%- extract_attributes(schema, schemata['properties']).each do |(key, type, description, example)| %>
 | **<%= key %>** | *<%= type %>* | <%= description %> | <%= example %> |
 <%- end %>
+
 <%- end %>
 <%- schemata['links'].each do |link, datum| %>
 <%=

data/lib/prmd/templates/schemata/helper.erb

@@ -2,6 +2,8 @@
   def extract_attributes(schema, properties)
     attributes = []
 
+    _, properties = schema.dereference(properties)
+
     properties.each do |key, value|
       # found a reference to another element:
       _, value = schema.dereference(value)
@@ -85,6 +87,24 @@
       description += "<br/> **pattern:** <code>#{value['pattern'].gsub /\|/, '&#124;'}</code>"
     end
 
+    if value['minLength'] || value['maxLength']
+      description += "<br/> **Length:** `"
+      if value['minLength']
+        description += "#{value['minLength'].to_json}"
+      end
+      unless value['minLength'] == value['maxLength']
+        if value['maxLength']
+          unless value['minLength']
+            description += "0"
+          end
+          description += "..#{value['maxLength'].to_json}"
+        else
+          description += "..∞"
+        end
+      end
+      description += "`"
+    end
+
     if value.has_key?('example')
       example = if value['example'].is_a?(Hash) && value['example'].has_key?('oneOf')
         value['example']['oneOf'].map { |e| "`#{e.to_json}`" }.join(" or ")

data/lib/prmd/templates/schemata/link.md.erb

@@ -4,6 +4,7 @@
   link_schema_properties_template = Prmd::Template.load_template('link_schema_properties.md.erb', options[:template])
 -%>
 ### <%= title %> <%= link['title'] %>
+
 <%= link['description'] %>
 
 ```
@@ -18,16 +19,19 @@
   %>
   <%- unless required.empty? %>
 #### Required Parameters
+
 <%= link_schema_properties_template.result(params: required, schema: schema, options: options) %>
 
   <%- end %>
   <%- unless optional.empty? %>
 #### Optional Parameters
+
 <%= link_schema_properties_template.result(params: optional, schema: schema, options: options) %>
   <%- end %>
 <%- end %>
 
 #### Curl Example
+
 <%=
   curl_options = options.dup
   http_header = link['http_header'] || {}
@@ -43,6 +47,7 @@
 %>
 
 #### Response Example
+
 ```
 <%- if response_example %>
 <%=   response_example['head'] %>
@@ -58,13 +63,18 @@ HTTP/1.1 <%=
   end %>
 <%- end %>
 ```
+
 ```json
 <%- if response_example %>
 <%=   response_example['body'] %>
 <%- else %>
 <%-   if link['rel'] == 'empty' %>
 <%-   elsif link.has_key?('targetSchema') %>
-<%=     JSON.pretty_generate(schema.schema_example(link['targetSchema'])) %>
+<%-     if link['targetSchema']['type'] == 'array' -%>
+<%=       JSON.pretty_generate(schema.schema_example(link['targetSchema'])) %>
+<%-     else -%>
+<%=       JSON.pretty_generate([schema.schema_example(link['targetSchema'])]) %>
+<%-     end -%>
 <%-   elsif link['rel'] == 'instances' %>
 <%=     JSON.pretty_generate([schema.schemata_example(resource)]) %>
 <%-   else %>

data/lib/prmd/templates/schemata/link_curl_example.md.erb

@@ -1,13 +1,13 @@
 ```bash
   <%-
-    data = {}
+    data = nil
     path = path.gsub(/{([^}]*)}/) {|match| '$' + match.gsub(/[{}]/, '').upcase}
     get_params = []
 
     if link.has_key?('schema')
-      data.merge!(schema.schema_example(link['schema']))
+      data = schema.schema_example(link['schema'])
 
-      if link['method'].upcase == 'GET' && !data.empty?
+      if link['method'].upcase == 'GET' && !data.nil?
         get_params << Prmd::UrlGenerator.new({schema: schema, link: link, options: options}).url_params
       end
     end
@@ -16,14 +16,17 @@
       options[:http_header] = { 'Content-Type' => options[:content_type] }.merge(options[:http_header])
     end
   %>
+<%- if link['method'].upcase != 'GET' %>
 $ curl -n -X <%= link['method'] %> <%= schema.href %><%= path -%><%- unless options[:http_header].empty? %> \<%- end %>
+<%- else %>
+$ curl -n <%= schema.href %><%= path -%><%- unless options[:http_header].empty? %> \<%- end %>
+<%- end %>
   <%- options[:http_header].each do |key, value| %>
   -H "<%= key %>: <%= value %>" \
   <%- end %>
-<%- if !data.empty? && link['method'].upcase != 'GET' %> \
+<%- if !data.nil? && link['method'].upcase != 'GET' %> \
   -d '<%= JSON.pretty_generate(data) %>'
 <%- elsif !get_params.empty? && link['method'].upcase == 'GET' %> -G \
   -d <%= get_params.join(" \\\n  -d ") %>
 <%- end %>
-
 ```