prmd 0.6.2 → 0.7.0

data/lib/prmd/core/schema_hash.rb

@@ -0,0 +1,47 @@
+require 'forwardable'
+
+# :nodoc:
+module Prmd
+  # Specialized Hash for handling loaded Schema data
+  class SchemaHash
+    extend Forwardable
+
+    # @return [Hash]
+    attr_reader :data
+    # @return [String]
+    attr_reader :filename
+
+    def_delegator :@data, :[]
+    def_delegator :@data, :[]=
+    def_delegator :@data, :delete
+    def_delegator :@data, :each
+
+    # @param [Hash] data
+    # @param [Hash<Symbol, Object>] options
+    def initialize(data, options = {})
+      @data = data
+      @filename = options.fetch(:filename, '')
+    end
+
+    # @param [Prmd::SchemaHash] other
+    # @return [self]
+    def initialize_copy(other)
+      super
+      @data = other.data.dup
+      @filename = other.filename.dup
+    end
+
+    # @param [String] key
+    # @return [self]
+    def fetch(key)
+      @data.fetch(key) { abort "Missing key #{key} in #{filename}" }
+    end
+
+    # @return [Hash]
+    def to_h
+      @data.dup
+    end
+
+    protected :data
+  end
+end

data/lib/prmd/core_ext/optparse.rb

@@ -0,0 +1,6 @@
+require 'optparse'
+
+# Extension of the standard library OptionParser
+class OptionParser
+  alias :to_str :to_s
+end

data/lib/prmd/hash_helpers.rb

@@ -0,0 +1,38 @@
+# :nodoc:
+module Prmd
+  # Hash helper methods
+  #
+  # @api private
+  module HashHelpers
+    # Attempts to convert all keys in the hash to a Symbol.
+    # This operation is recursive with subhashes
+    #
+    # @param [Hash] hash
+    # @return [Hash]
+    def self.deep_symbolize_keys(hash)
+      deep_transform_keys(hash) do |key|
+        if key.respond_to?(:to_sym)
+          key.to_sym
+        else
+          key
+        end
+      end
+    end
+
+    # Think of this as hash.keys.map! { |key| }, that actually maps recursively.
+    #
+    # @param [Hash] hash
+    # @return [Hash]
+    # @yield [Object] key
+    def self.deep_transform_keys(hash, &block)
+      result = {}
+      hash.each do |key, value|
+        new_key = yield(key)
+        new_value = value
+        new_value = deep_transform_keys(value, &block) if value.is_a?(Hash)
+        result[new_key] = new_value
+      end
+      result
+    end
+  end
+end

data/lib/prmd/load_schema_file.rb

@@ -0,0 +1,25 @@
+require 'yaml'
+require 'json'
+
+# :nodoc:
+module Prmd
+  # 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
+  end
+end

data/lib/prmd/rake_tasks/base.rb

@@ -0,0 +1,33 @@
+require 'rake'
+require 'rake/tasklib'
+
+# :nodoc:
+module Prmd
+  # :nodoc:
+  module RakeTasks
+    # Common class for Prmd rake tasks
+    #
+    # @api private
+    class Base < Rake::TaskLib
+      # The name of the task
+      # @return [String] the task name
+      attr_accessor :name
+
+      # Options to pass to command
+      # @return [Hash<Symbol, Object>] the options passed to the 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 = {}
+
+        yield self if block_given?
+
+        define
+      end
+    end
+  end
+end

data/lib/prmd/rake_tasks/combine.rb

@@ -0,0 +1,50 @@
+require 'prmd/commands/combine'
+require 'prmd/rake_tasks/base'
+
+# :nodoc:
+module Prmd
+  # :nodoc:
+  module RakeTasks
+    # Schema combine rake task
+    #
+    # @example
+    #   Prmd::RakeTasks::Combine.new do |t|
+    #     t.options[:meta] = 'schema/meta.json'
+    #     t.paths << 'schema/schemata/api'
+    #     t.output_file = 'schema/api.json'
+    #   end
+    class Combine < Base
+      #
+      # @return [Array<String>] list of paths
+      attr_accessor :paths
+
+      # target file the combined result should be written
+      # @return [String>] target filename
+      attr_accessor :output_file
+
+      # Creates a new task with name +name+.
+      #
+      # @param [String, Symbol] name the name of the rake task
+      def initialize(name = :combine)
+        @paths = []
+        super
+      end
+
+      protected
+
+      # Defines the rake task
+      # @return [void]
+      def define
+        desc 'Combine schemas' unless Rake.application.last_comment
+        task(name) do
+          result = Prmd.combine(paths, options)
+          if output_file
+            File.open(output_file, 'w') do |file|
+              file.write(result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prmd/rake_tasks/doc.rb

@@ -0,0 +1,73 @@
+require 'prmd/commands/render'
+require 'prmd/rake_tasks/base'
+require 'prmd/load_schema_file'
+require 'prmd/template'
+require 'prmd/schema'
+
+# :nodoc:
+module Prmd
+  # :nodoc:
+  module RakeTasks
+    # Documentation rake task
+    #
+    # @example
+    #   Prmd::RakeTasks::Doc.new do |t|
+    #     t.files = { 'schema/api.json' => 'schema/api.md' }
+    #   end
+    class Doc < Base
+      # Schema files that should be verified
+      # @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
+        @options[:template] ||= Prmd::Template.template_dirname
+      end
+
+      private
+
+      # Render file to markdown
+      #
+      # @param [String] filename
+      # @return (see Prmd.render)
+      def render_file(filename)
+        data = Prmd.load_schema_file(filename)
+        schema = Prmd::Schema.new(data)
+        Prmd.render(schema, options)
+      end
+
+      # @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)
+        end
+      end
+
+      protected
+
+      # Defines the rake task
+      # @return [void]
+      def define
+        desc 'Verifying schemas' unless Rake.application.last_comment
+        task(name) do
+          if files.is_a?(Hash)
+            files.each do |infile, outfile|
+              render_to_file(infile, outfile)
+            end
+          else
+            files.each do |infile|
+              render_to_file(infile, infile.ext('md'))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prmd/rake_tasks/verify.rb

@@ -0,0 +1,60 @@
+require 'prmd/commands/verify'
+require 'prmd/rake_tasks/base'
+require 'prmd/load_schema_file'
+
+# :nodoc:
+module Prmd
+  # :nodoc:
+  module RakeTasks
+    # Schema Verify rake task
+    #
+    # @example
+    #   Prmd::RakeTasks::Verify.new do |t|
+    #     t.files << 'schema/api.json'
+    #   end
+    class Verify < Base
+      # Schema files that should be verified
+      # @return [Array<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 = :verify)
+        @files = []
+        super
+      end
+
+      private
+
+      # Defines the rake task
+      #
+      # @param [String] filename
+      # @return [Array<String>] list of errors produced
+      def verify_file(filename)
+        data = Prmd.load_schema_file(filename)
+        errors = Prmd.verify(data)
+        unless errors.empty?
+          errors.map! { |error| "#{filename}: #{error}" } if filename
+          errors.each { |error| $stderr.puts(error) }
+        end
+        errors
+      end
+
+      protected
+
+      # Defines the rake task
+      # @return [void]
+      def define
+        desc 'Verifying schemas' unless Rake.application.last_comment
+        task(name) do
+          all_errors = []
+          files.each do |filename|
+            all_errors.concat(verify_file(filename))
+          end
+          fail unless all_errors.empty?
+        end
+      end
+    end
+  end
+end

data/lib/prmd/schema.rb

@@ -1,35 +1,67 @@
+require 'json'
+require 'yaml'
+
+# :nodoc:
 module Prmd
+  # Schema object
   class Schema
+    # @return [Hash] data
+    attr_reader :data
+
+    # @param [Hash<String, Object>] new_data
+    def initialize(new_data = {})
+      @data = convert_type_to_array(new_data)
+      @schemata_examples = {}
+    end
 
+    #
+    # @param [Object] datum
+    # @return [Object] same type as the input object
+    def convert_type_to_array(datum)
+      case datum
+      when Array
+        datum.map { |element| convert_type_to_array(element) }
+      when Hash
+        if datum.key?('type') && datum['type'].is_a?(String)
+          datum['type'] = [*datum['type']]
+        end
+        datum.each_with_object({}) do |(k, v), hash|
+          hash[k] = convert_type_to_array(v)
+        end
+      else
+        datum
+      end
+    end
+
+    # @param [String] key
+    # @return [Object]
     def [](key)
       @data[key]
     end
 
+    # @param [String] key
+    # @param [Object] value
     def []=(key, value)
       @data[key] = value
     end
 
-    def initialize(new_data = {})
-      convert_type_to_array = lambda do |datum|
-        case datum
-        when Array
-          datum.map { |element| convert_type_to_array.call(element) }
-        when Hash
-          if datum.has_key?('type') && datum['type'].is_a?(String)
-            datum['type'] = [*datum['type']]
-          end
-          datum.each { |k,v| datum[k] = convert_type_to_array.call(v) }
-        else
-          datum
-        end
+    # Merge schema data with provided schema
+    #
+    # @param [Hash, Prmd::Schema] schema
+    # @return [void]
+    def merge!(schema)
+      if schema.is_a?(Schema)
+        @data.merge!(schema.data)
+      else
+        @data.merge!(schema)
       end
-      @data = convert_type_to_array.call(new_data)
-      @schemata_examples = {}
     end
 
+    #
+    # @param [Hash, String] reference
     def dereference(reference)
       if reference.is_a?(Hash)
-        if reference.has_key?('$ref')
+        if reference.key?('$ref')
           value = reference.dup
           key = value.delete('$ref')
         else
@@ -40,7 +72,7 @@ module Prmd
       end
       begin
         datum = @data
-        key.gsub(%r{[^#]*#/}, '').split('/').each do |fragment|
+        key.gsub(/[^#]*#\//, '').split('/').each do |fragment|
           datum = datum[fragment]
         end
         # last dereference will have nil key, so compact it out
@@ -48,25 +80,29 @@ module Prmd
         dereferenced_key, dereferenced_value = dereference(datum)
         [
           [key, dereferenced_key].compact.last,
-          [dereferenced_value, value].inject({}) { |composite, element| composite.merge(element) }
+          [dereferenced_value, value].inject({}, &:merge)
         ]
       rescue => error
         $stderr.puts("Failed to dereference `#{key}`")
-        raise(error)
+        raise error
       end
     end
 
+    # @param [Hash] value
     def schema_value_example(value)
-      if value.has_key?('example')
+      if value.key?('example')
         value['example']
-      elsif value.has_key?('anyOf')
-        ref = value['anyOf'].detect {|ref| ref['$ref'].split('/').last == 'id'} || value['anyOf'].first
+      elsif value.key?('anyOf')
+        id_ref = value['anyOf'].find do |ref|
+          ref['$ref'] && ref['$ref'].split('/').last == 'id'
+        end
+        ref = id_ref || value['anyOf'].first
         schema_example(ref)
-      elsif value.has_key?('properties') # nested properties
+      elsif value.key?('properties') # nested properties
         schema_example(value)
-      elsif value.has_key?('items') # array of objects
+      elsif value.key?('items') # array of objects
         _, items = dereference(value['items'])
-        if value['items'].has_key?('example')
+        if value['items'].key?('example')
           [items['example']]
         else
           [schema_example(items)]
@@ -74,23 +110,25 @@ module Prmd
       end
     end
 
+    # @param [Hash, String] schema
     def schema_example(schema)
-      _, _schema = dereference(schema)
+      _, dff_schema = dereference(schema)
 
-      if _schema.has_key?('example')
-        _schema['example']
-      elsif _schema.has_key?('properties')
+      if dff_schema.key?('example')
+        dff_schema['example']
+      elsif dff_schema.key?('properties')
         example = {}
-        _schema['properties'].each do |key, value|
+        dff_schema['properties'].each do |key, value|
           _, value = dereference(value)
           example[key] = schema_value_example(value)
         end
         example
-      elsif _schema.has_key?('items')
-        schema_value_example(_schema)
+      elsif dff_schema.key?('items')
+        schema_value_example(dff_schema)
       end
     end
 
+    # @param [String] schemata_id
     def schemata_example(schemata_id)
       _, schema = dereference("#/definitions/#{schemata_id}")
       @schemata_examples[schemata_id] ||= begin
@@ -98,24 +136,38 @@ module Prmd
       end
     end
 
+    # Retrieve this schema's href
+    #
+    # @return [String, nil]
     def href
-      (@data['links'].detect { |link| link['rel'] == 'self' } || {})['href']
+      (@data['links'] && @data['links'].find { |link| link['rel'] == 'self' } || {})['href']
     end
 
+    # Convert Schema to JSON
+    #
+    # @return [String]
     def to_json
       new_json = JSON.pretty_generate(@data)
       # nuke empty lines
-      new_json = new_json.split("\n").delete_if {|line| line.empty?}.join("\n") + "\n"
+      new_json = new_json.split("\n").reject(&:empty?).join("\n") + "\n"
       new_json
     end
 
+    # Convert Schema to YAML
+    #
+    # @return [String]
     def to_yaml
       YAML.dump(@data)
     end
 
+    # Convert Schema to String
+    #
+    # @return [String]
     def to_s
       to_json
     end
 
+    private :convert_type_to_array
+    protected :data
   end
 end