prmd 0.6.2 → 0.7.0

data/lib/prmd/cli/base.rb

@@ -0,0 +1,151 @@
+require 'json'
+require 'prmd/core_ext/optparse'
+require 'prmd/load_schema_file'
+
+module Prmd
+  module CLI
+    # Base module for CLI commands.
+    # @api
+    module Base
+      # Create a parser specific for this command.
+      # The parsers produced by this method should yield their options.
+      #
+      # @example Overwriting
+      #   def make_parser(options = {})
+      #     OptionParser.new do |opts|
+      #       opts.on("-v", "--verbose", "set verbose debugging") do |v|
+      #         yield :verbose, v
+      #       end
+      #     end
+      #   end
+      #
+      # @param [Hash<Symbol, Object>] options
+      # @return [OptionParser] newly created parser
+      # @abstract
+      def make_parser(options = {})
+        #
+      end
+
+      # Runs the provided parser with the provided argv.
+      # This method can be overwritten to use a different parser method.
+      #
+      # @param [OptionParser] parser
+      # @param [Array<String>] argv
+      # @return [Array<String>] remaining arguments
+      # @private
+      def execute_parser(parser, argv)
+        parser.parse(argv)
+      end
+
+      # Set the given key and value in the given options Hash.
+      # This method can ben overwritten to support special keys or values
+      #
+      # @example Handling special keys
+      #   def self.set_option(options, key, value)
+      #     if key == :settings
+      #       options.replace(value.merge(options))
+      #     else
+      #       super
+      #     end
+      #   end
+      #
+      # @param [Hash<Symbol, Object>] options
+      # @param [Symbol] key
+      # @param [Object] value
+      # @return [void]
+      def set_option(options, key, value)
+        options[key] = value
+      end
+
+      # Parse the given argv and produce a options Hash specific to the command.
+      # The returned options Hash will include an :argv key which contains
+      # the remaining args from the parse operation.
+      #
+      # @param [Array<String>] argv
+      # @param [Hash<Symbol, Object>] options
+      # @return [Hash<Symbol, Object>] parsed options
+      def parse_options(argv, options = {})
+        opts = {}
+        parser = make_parser(options) do |key, value|
+          set_option(opts, key, value)
+        end
+        argv = execute_parser(parser, argv)
+        opts[:argv] = argv
+        opts
+      end
+
+      # Helper method for writing command results to a file or STD* IO.
+      #
+      # @param [String] data  to be written
+      # @param [Hash<Symbol, Object>] options
+      # @return [void]
+      def write_result(data, options = {})
+        output_file = options[:output_file]
+        if output_file
+          File.open(output_file, 'w') do |f|
+            f.write(data)
+          end
+        else
+          $stdout.puts data
+        end
+      end
+
+      # Helper method for reading schema data from a file or STD* IO.
+      #
+      # @param [String] filename  file to read
+      # @return [Array[Symbol, String]] source, data
+      def try_read(filename = nil)
+        if filename && !filename.empty?
+          return :file, Prmd.load_schema_file(filename)
+        elsif !$stdin.tty?
+          return :io, JSON.load($stdin.read)
+        else
+          abort 'Nothing to read'
+        end
+      end
+
+      # Method called to actually execute the command provided with an
+      # options Hash from the commands #parse_options.
+      #
+      # @param [Hash<Symbol, Object>] options
+      # @return [void]
+      # @abstract
+      def execute(options = {})
+        #
+      end
+
+      # Method called when the command is ran with the :noop option enabled.
+      # As the option implies, this should do absolutely nothing.
+      #
+      # @param [Hash<Symbol, Object>] options
+      # @return [void]
+      def noop_execute(options = {})
+        $stderr.puts options
+      end
+
+      # Run this command given a argv and optional options Hash.
+      # If all you have is the options from the #parse_options method, use
+      # #execute instead.
+      #
+      # @see #execute
+      # @see #parse_options
+      #
+      # @param [Array<String>] argv
+      # @param [Hash<Symbol, Object>] options
+      # @return [void]
+      def run(argv, options = {})
+        options = options.merge(parse_options(argv, options))
+        if options[:noop]
+          noop_execute(options)
+        else
+          execute(options)
+        end
+      end
+
+      private :execute_parser
+      private :set_option
+      private :write_result
+      private :try_read
+    end
+  end
+end

data/lib/prmd/cli/combine.rb

@@ -0,0 +1,42 @@
+require 'prmd/cli/base'
+require 'prmd/commands/combine'
+
+module Prmd
+  module CLI
+    # 'combine' command module.
+    module Combine
+      extend CLI::Base
+
+      # Returns a OptionParser for parsing 'combine' command options.
+      #
+      # @param (see Prmd::CLI::Base#make_parser)
+      # @return (see Prmd::CLI::Base#make_parser)
+      def self.make_parser(options = {})
+        binname = options.fetch(:bin, 'prmd')
+
+        OptionParser.new do |opts|
+          opts.banner = "#{binname} combine [options] <file or directory>"
+          opts.on('-m', '--meta FILENAME', String, 'Set defaults for schemata') do |m|
+            yield :meta, m
+          end
+          opts.on('-o', '--output-file FILENAME', String, 'File to write result to') do |n|
+            yield :output_file, n
+          end
+        end
+      end
+
+      # Executes the 'combine' command.
+      #
+      # @example Usage
+      #   Prmd::CLI::Combine.execute(argv: ['schema/schemata/api'],
+      #                              meta: 'schema/meta.json',
+      #                              output_file: 'schema/api.json')
+      #
+      # @param (see Prmd::CLI::Base#execute)
+      # @return (see Prmd::CLI::Base#execute)
+      def self.execute(options = {})
+        write_result Prmd.combine(options[:argv], options).to_s, options
+      end
+    end
+  end
+end

data/lib/prmd/cli/doc.rb

@@ -0,0 +1,69 @@
+require 'prmd/cli/base'
+require 'prmd/commands/render'
+require 'prmd/hash_helpers'
+
+module Prmd
+  module CLI
+    # 'doc' command module.
+    module Doc
+      extend CLI::Base
+
+      # Returns a OptionParser for parsing 'doc' command options.
+      #
+      # @param (see Prmd::CLI::Base#make_parser)
+      # @return (see Prmd::CLI::Base#make_parser)
+      def self.make_parser(options = {})
+        binname = options.fetch(:bin, 'prmd')
+
+        OptionParser.new do |opts|
+          opts.banner = "#{binname} doc [options] <combined schema>"
+          opts.on('-s', '--settings FILENAME', String, 'Config file to use') do |s|
+            settings = Prmd.load_schema_file(s) || {}
+            options = HashHelpers.deep_symbolize_keys(settings)
+            yield :settings, options
+          end
+          opts.on('-p', '--prepend header,overview', Array, 'Prepend files to output') do |p|
+            yield :prepend, p
+          end
+          opts.on('-c', '--content-type application/json', String, 'Content-Type header') do |c|
+            yield :content_type, c
+          end
+          opts.on('-o', '--output-file FILENAME', String, 'File to write result to') do |n|
+            yield :output_file, n
+          end
+        end
+      end
+
+      # Overwritten to support :settings merging.
+      #
+      # @see Prmd::CLI::Base#set_option
+      #
+      # @param (see Prmd::CLI::Base#set_option)
+      # @return (see Prmd::CLI::Base#set_option)
+      def self.set_option(options, key, value)
+        if key == :settings
+          options.replace(value.merge(options))
+        else
+          super
+        end
+      end
+
+      # Executes the 'doc' command.
+      #
+      # @example Usage
+      #   Prmd::CLI::Doc.execute(argv: ['schema/api.json'],
+      #                          output_file: 'schema/api.md')
+      #
+      # @param (see Prmd::CLI::Base#execute)
+      # @return (see Prmd::CLI::Base#execute)
+      def self.execute(options = {})
+        filename = options.fetch(:argv).first
+        template = File.expand_path('templates', File.dirname(__FILE__))
+        _, data = try_read(filename)
+        schema = Prmd::Schema.new(data)
+        opts = options.merge(template: template)
+        write_result Prmd.render(schema, opts), options
+      end
+    end
+  end
+end

data/lib/prmd/cli/generate.rb

@@ -0,0 +1,44 @@
+require 'prmd/cli/base'
+require 'prmd/commands/init'
+
+module Prmd
+  module CLI
+    # 'init' command module.
+    # Though this is called, Generate, it is used by the init method for
+    # creating new Schema files
+    module Generate
+      extend CLI::Base
+
+      # Returns a OptionParser for parsing 'init' command options.
+      #
+      # @param (see Prmd::CLI::Base#make_parser)
+      # @return (see Prmd::CLI::Base#make_parser)
+      def self.make_parser(options = {})
+        binname = options.fetch(:bin, 'prmd')
+
+        OptionParser.new do |opts|
+          opts.banner = "#{binname} init [options] <resource name>"
+          opts.on('-y', '--yaml', 'Generate YAML') do |y|
+            yield :yaml, y
+          end
+          opts.on('-o', '--output-file FILENAME', String, 'File to write result to') do |n|
+            yield :output_file, n
+          end
+        end
+      end
+
+      # Executes the 'init' command.
+      #
+      # @example Usage
+      #   Prmd::CLI::Generate.execute(argv: ['bread'],
+      #                               output_file: 'schema/schemata/bread.json')
+      #
+      # @param (see Prmd::CLI::Base#execute)
+      # @return (see Prmd::CLI::Base#execute)
+      def self.execute(options = {})
+        name = options.fetch(:argv).first
+        write_result Prmd.init(name, options), options
+      end
+    end
+  end
+end

data/lib/prmd/cli/render.rb

@@ -0,0 +1,48 @@
+require 'prmd/cli/base'
+require 'prmd/commands/render'
+
+module Prmd
+  module CLI
+    # 'render' command module.
+    module Render
+      extend CLI::Base
+
+      # Returns a OptionParser for parsing 'render' command options.
+      #
+      # @param (see Prmd::CLI::Base#make_parser)
+      # @return (see Prmd::CLI::Base#make_parser)
+      def self.make_parser(options = {})
+        binname = options.fetch(:bin, 'prmd')
+
+        OptionParser.new do |opts|
+          opts.banner = "#{binname} render [options] <combined schema>"
+          opts.on('-p', '--prepend header,overview', Array, 'Prepend files to output') do |p|
+            yield :prepend, p
+          end
+          opts.on('-t', '--template templates', String, 'Use alternate template') do |t|
+            yield :template, t
+          end
+          opts.on('-o', '--output-file FILENAME', String, 'File to write result to') do |n|
+            yield :output_file, n
+          end
+        end
+      end
+
+      # Executes the 'render' command.
+      #
+      # @example Usage
+      #   Prmd::CLI::Render.execute(argv: ['schema/api.json'],
+      #                             template: 'my_template.md.erb',
+      #                             output_file: 'schema/api.md')
+      #
+      # @param (see Prmd::CLI::Base#execute)
+      # @return (see Prmd::CLI::Base#execute)
+      def self.execute(options = {})
+        filename = options.fetch(:argv).first
+        _, data = try_read(filename)
+        schema = Prmd::Schema.new(data)
+        write_result Prmd.render(schema, options), options
+      end
+    end
+  end
+end

data/lib/prmd/cli/verify.rb

@@ -0,0 +1,49 @@
+require 'prmd/cli/base'
+require 'prmd/commands/verify'
+
+module Prmd
+  module CLI
+    # 'verify' command module.
+    module Verify
+      extend CLI::Base
+
+      # Returns a OptionParser for parsing 'verify' command options.
+      #
+      # @param (see Prmd::CLI::Base#make_parser)
+      # @return (see Prmd::CLI::Base#make_parser)
+      def self.make_parser(options = {})
+        binname = options.fetch(:bin, 'prmd')
+
+        OptionParser.new do |opts|
+          opts.banner = "#{binname} verify [options] <combined schema>"
+          opts.on('-y', '--yaml', 'Generate YAML') do |y|
+            yield :yaml, y
+          end
+          opts.on('-o', '--output-file FILENAME', String, 'File to write result to') do |n|
+            yield :output_file, n
+          end
+        end
+      end
+
+      # Executes the 'verify' command.
+      #
+      # @example Usage
+      #   Prmd::CLI::Verify.execute(argv: ['schema/api.json'])
+      #
+      # @param (see Prmd::CLI::Base#execute)
+      # @return (see Prmd::CLI::Base#execute)
+      def self.execute(options = {})
+        filename = options.fetch(:argv).first
+        _, data = try_read(filename)
+        errors = Prmd.verify(data)
+        unless errors.empty?
+          errors.map! { |error| "#{filename}: #{error}" } if filename
+          errors.each { |error| $stderr.puts(error) }
+          exit(1)
+        end
+        result = options[:yaml] ? data.to_yaml : JSON.pretty_generate(data)
+        write_result result, options
+      end
+    end
+  end
+end

data/lib/prmd/commands.rb

@@ -0,0 +1,4 @@
+require 'prmd/commands/combine'
+require 'prmd/commands/init'
+require 'prmd/commands/render'
+require 'prmd/commands/verify'

data/lib/prmd/commands/combine.rb

@@ -1,73 +1,100 @@
+require 'prmd/load_schema_file'
+require 'prmd/core/schema_hash'
+require 'prmd/core/combiner'
+
+# :nodoc:
 module Prmd
-  def self.combine(path, options={})
-    files = if File.directory?(path)
-      Dir.glob(File.join(path, '**', '*.json')) +
-        Dir.glob(File.join(path, '**', '*.yaml')) -
-        [options[:meta]]
-    else
-      [path]
-    end
-    # sort for stable loading on any platform
-    schemata = []
-    files.sort.each do |file|
-      begin
-        schemata << [file, YAML.load(File.read(file))]
-      rescue
-        $stderr.puts "unable to parse #{file}"
+  # Schema combine
+  module Combine
+    # @api private
+    # @param [#size] given
+    # @param [#size] expected
+    # @return [void]
+    def self.handle_faulty_load(given, expected)
+      unless given.size == expected.size
+        abort 'Somes files have failed to parse. ' \
+              'If you wish to continue without them,' \
+              'please enable faulty_load using --faulty-load'
       end
     end
-    unless schemata.length == files.length
-      exit(1) # one or more files failed to parse
-    end
-
-    data = {
-      '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
-      'definitions' => {},
-      'properties'  => {},
-      'type'        => ['object']
-    }
-
-    # tracks which entities where defined in which file
-    schemata_map = {}
 
-    if options[:meta] && File.exists?(options[:meta])
-      data.merge!(YAML.load(File.read(options[:meta])))
+    # @api private
+    # @param [Array<String>] paths
+    # @param [Hash<Symbol, Object>] options
+    # @return [Array<String>] list of filenames from paths
+    def self.crawl_map(paths, options = {})
+      files = [*paths].map do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, '**', '*.{json,yml,yaml}'))
+        else
+          path
+        end
+      end
+      files.flatten!
+      files.delete(options[:meta])
+      files
     end
 
-    schemata.each do |schema_file, schema_data|
-      id = schema_data['id'].split('/').last
+    # @api private
+    # @param [String] filename
+    # @return [SchemaHash]
+    def self.load_schema_hash(filename)
+      data = Prmd.load_schema_file(filename)
+      SchemaHash.new(data, filename: filename)
+    end
 
-      if file = schemata_map[schema_data['id']]
-        $stderr.puts "`#{schema_data['id']}` (from #{schema_file}) was already defined in `#{file}` and will overwrite the first definition"
+    # @api private
+    # @param [Array<String>] files
+    # @param [Hash<Symbol, Object>] options
+    # @return [Array<SchemaHash>] schema hashes
+    def self.load_files(files, options = {})
+      files.each_with_object([]) do |filename, result|
+        begin
+          result << load_schema_hash(filename)
+        rescue JSON::ParserError, Psych::SyntaxError => ex
+          $stderr.puts "unable to parse #{filename} (#{ex.inspect})"
+        end
       end
-      schemata_map[schema_data['id']] = schema_file
+    end
 
-      # schemas are now in a single scope by combine
-      schema_data.delete('id')
+    # @api private
+    # @param [Array<String>] paths
+    # @param [Hash<Symbol, Object>] options
+    # @return (see .load_files)
+    def self.load_schemas(paths, options = {})
+      files = crawl_map(paths, options)
+      # sort for stable loading on any platform
+      schemata = load_files(files.sort, options)
+      handle_faulty_load(schemata, files) unless options[:faulty_load]
+      schemata
+    end
 
-      data['definitions']
-      data['definitions'][id] = schema_data
-      reference_localizer = lambda do |datum|
-        case datum
-        when Array
-          datum.map {|element| reference_localizer.call(element)}
-        when Hash
-          if datum.has_key?('$ref')
-            datum['$ref'] = '#/definitions' + datum['$ref'].gsub('#', '').gsub('/schemata', '')
-          end
-          if datum.has_key?('href') && datum['href'].is_a?(String)
-            datum['href'] = datum['href'].gsub('%23', '').gsub(%r{%2Fschemata(%2F[^%]*%2F)}, '%23%2Fdefinitions\1')
-          end
-          datum.each { |k,v| datum[k] = reference_localizer.call(v) }
-        else
-          datum
-        end
-      end
-      reference_localizer.call(data['definitions'][id])
+    # Merges all found schema files in the given paths into a single Schema
+    #
+    # @param [Array<String>] paths
+    # @param [Hash<Symbol, Object>] options
+    # @return (see Prmd::Combiner#combine)
+    def self.combine(paths, options = {})
+      schemata = load_schemas(paths)
+      base = Prmd::Template.load_json('combine_head.json')
+      schema = base['$schema']
+      meta = {}
+      meta = Prmd.load_schema_file(options[:meta]) if options[:meta]
+      combiner = Prmd::Combiner.new(meta: meta, base: base, schema: schema)
+      combiner.combine(*schemata)
+    end
 
-      data['properties'][id] = { '$ref' => "#/definitions/#{id}" }
+    class << self
+      private :handle_faulty_load
+      private :crawl_map
+      private :load_schema_hash
+      private :load_files
+      private :load_schemas
     end
+  end
 
-    Prmd::Schema.new(data)
+  # (see Prmd::Combine.combine)
+  def self.combine(paths, options = {})
+    Combine.combine(paths, { faulty_load: false }.merge(options))
   end
 end