prmd 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92c67299c0bc9e4bec5141b516ec7fa78d841f6d
-  data.tar.gz: dbcdf2ec6712b37f5980904e998d7085d3ca6dc9
+  metadata.gz: f2d8980d47308e01724a4038226dcb44581cd4ad
+  data.tar.gz: 528abc2bf4b32d96469d27453bf011944a43e0fe
 SHA512:
-  metadata.gz: bc6d901ec87dc0df4882265c7d5f95210f5bcf2777dda10870366547aabe9b42a90adc8007fa872b925f35ac1b192237a1c2eaebe8464f3b4083cad8405e90a5
-  data.tar.gz: 2b117de96b7c80c06db4e7173d3954265531ab3f70df26512118854ea6025068e3d0852cc615f1c79a5da84bd5609a4c9ba95824f5292fef9ca41cfd393db06d
+  metadata.gz: af62a75a4a3cba5bec58e76be3ce9243697abbfec32fded14745a1f89cc29b32a7344b4fbd1fd2a3559b97a9b2ebce2eeb097f448a836353a52b52388e556587
+  data.tar.gz: e67e0d992a1ac14686565ddb53c071b46055ee8e57bb61fc149afb5c32fd458969cd080f87c5db1b57eb90d7f84c1f466250214eba8a22f1a61cc64508d22732

data/.gitignore

@@ -17,3 +17,4 @@ tmp
 .yardoc
 _yardoc
 doc/
+Gemfile.lock

data/README.md

@@ -80,6 +80,21 @@ $ prmd verify schema.json
 $ prmd doc schema.json > schema.md
 ```
 
+### Using YAML instead of JSON as a resource and meta format
+
+`init` and `combine` supports YAML format:
+
+```bash
+# Generate resources in YAML format
+$ prmd init --yaml app  > schemata/app.yml
+$ prmd init --yaml user > schemata/user.yml
+
+# Combine into a single schema
+$ prmd combine --meta meta.json schemata/ > schema.json
+```
+
+`combine` can detect both `*.yml` and `*.json` and use them side by side. For example, if one have a lot of legacy JSON resources and wants to create new resources in YAML format - `combine` will be able to handle it properly.
+
 # Render from schema
 
 ```bash
@@ -110,7 +125,7 @@ $ prmd doc --settings config.json schema.json > schema.md
 ```
 
 Available options (and their defaults)
-```json
+```js
 {
   "doc": {
     "url_style": "default", // can also be "json"
@@ -131,7 +146,7 @@ require 'prmd/rake_tasks/doc'
 
 namespace :schema do
   Prmd::RakeTasks::Combine.new do |t|
-    t.options[:meta] = 'schema/meta.json'
+    t.options[:meta] = 'schema/meta.json'    # use meta.yml if you prefer YAML format
     t.paths << 'schema/schemata/api'
     t.output_file = 'schema/api.json'
   end
@@ -156,13 +171,15 @@ We suggest the following file layout for JSON schema related files:
 /docs (top-level directory for project documentation)
   /schema (API schema documentation)
     /schemata
-      /{resource.json} (individual resource schema)
-    /meta.json (overall API metadata)
+      /{resource.[json,yml]} (individual resource schema)
+    /meta.[json,yml] (overall API metadata)
     /overview.md (preamble for generated API docs)
     /schema.json (complete generated JSON schema file)
     /schema.md (complete generated API documentation file)
 ```
 
+where `[json,yml]` means that it could be either `json` or `yml`.
+
 ## Contributing
 
 1. Fork it

data/docs/schemata.md

@@ -84,6 +84,9 @@ Links that expect a json-encoded body as input MUST also include the following a
 The `schema` object MAY also include a `required` array to define all attributes for this link, which can not be omitted.
 If this field is not present, all attributes in this link are considered as optional.
 
+Links that expect a custom http header MUST include the following attributes:
+* `http_header` - an object which has the key as the header name, and value as an example header value.
+
 ```javascript
 {
   "links": [
@@ -92,6 +95,7 @@ If this field is not present, all attributes in this link are considered as opti
       "href":         "/resources",
       "method":       "POST",
       "rel":          "create",
+      "http_header": { "Custom-Header": "examplevalue" },
       "schema":       {
         "properties": {
           "owner":  { "$ref": "/schemata/user#/definitions/identity" },

data/lib/prmd/core/combiner.rb

@@ -1,5 +1,6 @@
 require 'prmd/schema'
 require 'prmd/core/schema_hash'
+require 'prmd/core/reference_localizer'
 
 # :nodoc:
 module Prmd
@@ -14,39 +15,10 @@ module Prmd
       @meta = properties.fetch(:meta, {})
     end
 
-    # @param [Array] array
-    # @return [Array]
-    def reference_localizer_array(array)
-      array.map { |element| reference_localizer(element) }
-    end
-
-    # @param [Hash] hash
-    # @return [Hash]
-    def reference_localizer_hash(hash)
-      if hash.key?('$ref')
-        hash['$ref'] = '#/definitions' + hash['$ref'].gsub('#', '')
-                                                     .gsub('/schemata', '')
-      end
-      if hash.key?('href') && hash['href'].is_a?(String)
-        hash['href'] = hash['href'].gsub('%23', '')
-                                   .gsub(/%2Fschemata(%2F[^%]*%2F)/,
-                                         '%23%2Fdefinitions\1')
-      end
-      hash.each_with_object({}) { |(k, v), r| r[k] = reference_localizer(v) }
-    end
-
-    #
     # @param [Object] datum
     # @return [Object]
     def reference_localizer(datum)
-      case datum
-      when Array
-        reference_localizer_array(datum)
-      when Hash
-        reference_localizer_hash(datum)
-      else
-        datum
-      end
+      ReferenceLocalizer.localize(datum)
     end
 
     #
@@ -65,8 +37,8 @@ module Prmd
         id_ary = id.split('/').last
 
         if s = schemata_map[id]
-          $stderr.puts "`#{id}` (from #{schema.filename}) was already defined" \
-                       "in `#{s.filename}` and will overwrite the first" \
+          $stderr.puts "`#{id}` (from #{schema.filename}) was already defined " \
+                       "in `#{s.filename}` and will overwrite the first " \
                        "definition"
         end
         # avoinding damaging the original schema
@@ -84,8 +56,6 @@ module Prmd
       Prmd::Schema.new(data)
     end
 
-    private :reference_localizer_array
-    private :reference_localizer_hash
     private :reference_localizer
   end
 end

data/lib/prmd/core/reference_localizer.rb

@@ -0,0 +1,93 @@
+# :nodoc:
+module Prmd
+  # @api private
+  # Schema references localizer
+  class ReferenceLocalizer
+    attr_reader :object
+
+    # @param [Object] object
+    def initialize(object)
+      @object = object
+    end
+
+    # @param [Object] object
+    # @return [ReferenceLocalizer]
+    def self.build(object)
+      case object
+      when Array
+        ForArray
+      when Hash
+        ForHash
+      else
+        self
+      end.new(object)
+    end
+
+    # @param [Object] object
+    # @return [Object]
+    def self.localize(object)
+      build(object).localize
+    end
+
+    # @return [Object]
+    def localize
+      object
+    end
+
+    private :object
+
+    # @api private
+    # Schema references localizer for arrays
+    class ForArray < self
+      alias_method :array, :object
+
+      # @return [Array]
+      def localize
+        array.map { |element| ReferenceLocalizer.localize(element) }
+      end
+    end
+
+    # @api private
+    # Schema references localizer for hashes
+    class ForHash < self
+      alias_method :hash, :object
+
+      # @return [Hash]
+      def localize
+        localize_ref
+        localize_href
+        localize_values
+      end
+
+      def localize_ref
+        return unless hash.key?('$ref')
+        hash['$ref'] = '#/definitions' + local_reference
+      end
+
+      def localize_href
+        return unless hash.key?('href') && hash['href'].is_a?(String)
+        hash['href'] = hash['href'].gsub('%23', '')
+                       .gsub(/%2Fschemata(%2F[^%]*%2F)/,
+                             '%23%2Fdefinitions\1')
+      end
+
+      # @return [Hash]
+      def localize_values
+        hash.each_with_object({}) { |(k, v), r| r[k] = ReferenceLocalizer.localize(v) }
+      end
+
+      # @return [String]
+      def local_reference
+        ref = hash['$ref']
+        # clean out leading #/definitions to not create a duplicate one
+        ref = ref.gsub(/^#\/definitions\//, '#/') while ref.match(/^#\/definitions\//)
+        ref.gsub('#', '').gsub('/schemata', '')
+      end
+
+      private :localize_ref
+      private :localize_href
+      private :localize_values
+      private :local_reference
+    end
+  end
+end

data/lib/prmd/load_schema_file.rb

@@ -1,25 +1,14 @@
 require 'yaml'
 require 'json'
+require 'prmd/multi_loader'
 
-# :nodoc:
-module Prmd
+module Prmd #:nodoc:
   # Attempts to load either a json or yaml file, the type is determined by
   # filename extension.
   #
   # @param [String] filename
   # @return [Object] data
   def self.load_schema_file(filename)
-    extname = File.extname(filename)
-    File.open(filename) do |file|
-      case extname.downcase
-      when '.yaml', '.yml'
-        YAML.load(file.read)
-      when '.json'
-        JSON.load(file.read)
-      else
-        abort "Cannot load schema file #{filename}" \
-              "(unsupported file extension #{extname})"
-      end
-    end
+    Prmd::MultiLoader.load_file(filename)
   end
 end

data/lib/prmd/multi_loader.rb

@@ -0,0 +1,2 @@
+require 'prmd/multi_loader/json'
+require 'prmd/multi_loader/yaml'

data/lib/prmd/multi_loader/json.rb

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

data/lib/prmd/multi_loader/loader.rb

@@ -0,0 +1,128 @@
+module Prmd #:nodoc:
+  module MultiLoader #:nodoc:
+    # Exception raised when a extension loader cannot be found.
+    class LoaderNotFound < StandardError
+    end
+
+    # @return [Hash<String, Prmd::MultiLoader::Loader>]
+    @file_extensions = {}
+
+    class << self
+      attr_accessor :file_extensions
+    end
+
+    # Attempts to autoload a Loader named +name+
+    #
+    # @param [String]
+    # @return [Boolean]  load success
+    def self.autoload_loader(name)
+      # extension names are preceeded with a .
+      # TODO. probably just remove the first .
+      loader_name = name.gsub('.', '')
+      require "prmd/multi_loader/#{loader_name}"
+      true
+    rescue
+      false
+    end
+
+    # Locates and returns a loader for the given +ext+
+    # If no extension is found the first time, MultiLoader will attempt
+    # to load one of the same name.
+    #
+    # @param [String] ext
+    # @return [Prmd::MultiLoader::Loader]
+    # @eg
+    #   # by default, Prmd does not load the TOML Loader
+    #   MultiLoader.loader('.toml')
+    #   # this will check the loaders the first time and find that
+    #   # there is no Loader for toml, it will then use the ::autoload_loader
+    #   # to locate a Loader named "prmd/multi_loader/toml"
+    def self.loader(name)
+      tried_autoload = false
+      begin
+        @file_extensions.fetch(name)
+      rescue KeyError
+        if tried_autoload
+          raise LoaderNotFound, "Loader for extension (#{name}) was not found."
+        else
+          autoload_loader(name)
+          tried_autoload = true
+          retry
+        end
+      end
+    end
+
+    # @param [String] ext
+    # @param [String] data
+    # @eg
+    #   Prmd::MultiLoader.load_data('.json', json_string)
+    def self.load_data(ext, data)
+      loader(ext).load_data(data)
+    end
+
+    # @param [String] ext  name of the loader also the extension of the stream
+    # @param [IO] stream
+    # @eg
+    #   Prmd::MultiLoader.load_stream('.json', io)
+    def self.load_stream(ext, stream)
+      loader(ext).load_stream(stream)
+    end
+
+    # Shortcut for loading any supported file
+    #
+    # @param [String] ext
+    # @param [String] filename
+    # @eg
+    #   Prmd::MultiLoader.load_file('my_file.json')
+    def self.load_file(filename)
+      ext = File.extname(filename)
+      loader(ext).load_file(filename)
+    end
+
+    # Base Loader module used to extend all other loaders
+    module Loader
+      # Using the loader, parse or do whatever magic the loader does to the
+      # string to get back data.
+      #
+      # @param [String] data
+      # @return [Object]
+      # @abstract
+      def load_data(data)
+        # overwrite in children
+      end
+
+      # Load a stream
+      #
+      # @param [IO] stream
+      # @return [Object]
+      # @eg
+      #   my_io = File.open('my_file.ext', 'r')
+      #   my_loader.load_stream(my_io)
+      def load_stream(stream)
+        load_data(stream.read)
+      end
+
+      # Load a file given a +filename+
+      #
+      # @param [String] filename
+      # @return [Object]
+      # @eg
+      #   my_loader.load_file('my_file.ext')
+      def load_file(filename)
+        File.open(filename, 'r') { |f| return load_stream(f) }
+      end
+
+      # Register the loader to the +args+ extensions
+      #
+      # @param [Array<String>] args
+      # @eg extensions '.json'
+      def extensions(*args)
+        args.each do |file|
+          Prmd::MultiLoader.file_extensions[file] = self
+        end
+      end
+
+      private :extensions
+    end
+  end
+end

data/lib/prmd/multi_loader/toml.rb

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