travis-cl 1.2.4

data/lib/cl/dsl.rb

@@ -0,0 +1,182 @@
+require 'cl/helper'
+
+class Cl
+  class Cmd
+    module Dsl
+      include Merge, Underscore
+
+      def abstract
+        unregister
+        @abstract = true
+      end
+
+      def abstract?
+        !!@abstract
+      end
+
+      # Declare multiple arguments at once
+      #
+      # See {Cl::Cmd::Dsl#arg} for more details.
+      def args(*args)
+        return @args ||= superclass.respond_to?(:args) ? superclass.args.dup : Args.new unless args.any?
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        args.each { |arg| arg(arg, opts) }
+      end
+
+      # Declares an argument
+      #
+      # Use this method to declare arguments the command accepts.
+      #
+      # For example:
+      #
+      #   ```ruby
+      #   class GitPush < Cl::Cmd
+      #     arg remote, 'The Git remote to push to.', type: :string
+      #   end
+      #   ```
+      #
+      # Arguments do not need to be declared, in order to be passed to the Cmd
+      # instance, but it is useful to do so for more explicit help output, and
+      # in order to define extra properties on the arguments (e.g. their type).
+      #
+      # @overload arg(name, description, opts)
+      #   @param name [String] the argument name
+      #   @param description [String] description for the argument, shown in the help output
+      #   @param opts [Hash] argument options
+      #   @option opts [Symbol] :type the argument type (`:array`, `:string`, `:integer`, `:float`, `:boolean`)
+      #   @option opts [Boolean] :required whether the argument is required
+      #   @option opts [String] :sep separator to split strings by, if the argument is an array
+      #   @option opts [Boolean] :splat whether to splat the argument, if the argument is an array
+      def arg(*args)
+        self.args.define(self, *args)
+      end
+
+      # Declare a description for this command
+      #
+      # This is the description that will be shown in the command details help output.
+      #
+      # For example:
+      #
+      #   ```ruby
+      #   class Api::Login < Cl::Cmd
+      #     description <<~str
+      #       Use this command to login to our API.
+      #       [...]
+      #     str
+      #   end
+      #   ```
+      #
+      # @return [String] the description if no argument was given
+      def description(description = nil)
+        description ? @description = description : @description
+      end
+
+      # Declare an example text for this command
+      #
+      # This is the example text that will be shown in the command details help output.
+      #
+      # For example:
+      #
+      #   ```ruby
+      #   class Api::Login < Cl::Cmd
+      #     example <<~str
+      #       For example, in order to login to our API with your username and
+      #       password, you can use:
+      #
+      #         ./api --username [username] --password [password]
+      #     str
+      #   end
+      #   ```
+      #
+      # @return [String] the description if no argument was given
+      def examples(examples = nil)
+        examples ? @examples = examples : @examples
+      end
+
+      # Declares an option
+      #
+      # Use this method to declare options a command accepts.
+      #
+      # See [this section](/#Options) for a full explanation on each feature supported by command options.
+      #
+      # @overload opt(name, description, opts)
+      #   @param name [String] the option name
+      #   @param description [String] description for the option, shown in the help output
+      #   @param opts [Hash] option options
+      #   @option opts [Symbol or Array<Symbol>] :alias alias name(s) for the option
+      #   @option opts [Object] :default default value for the option
+      #   @option opts [String or Symbol] :deprecated deprecation message for the option, or if given a Symbol, deprecated alias name
+      #   @option opts [Boolean] :downcase whether to downcase the option value
+      #   @option opts [Boolean] :upcase whether to upcase the option value
+      #   @option opts [Array<Object>] :enum list of acceptable option values
+      #   @option opts [String] :example example(s) for the option, shown in help output
+      #   @option opts [Regexp] :format acceptable option value format
+      #   @option opts [Boolean] :internal whether to hide the option from help output
+      #   @option opts [Numeric] :min minimum acceptable value
+      #   @option opts [Numeric] :max maximum acceptable value
+      #   @option opts [String] :see see also reference (e.g. documentation URL)
+      #   @option opts [Symbol] :type the option value type (`:array`, `:string`, `:integer`, `:float`, `:boolean`)
+      #   @option opts [Boolean] :required whether the option is required
+      #   @option opts [Array<Symbol> or Symbol] :requires (an)other options required this option depends on
+      def opt(*args, &block)
+        self.opts.define(self, *args, &block)
+      end
+
+      # Collection of options supported by this command
+      #
+      # This collection is being inherited from super classes.
+      def opts
+        @opts ||= self == Cmd ? Opts.new : superclass.opts.dup
+      end
+
+      # Whether any alternative option requirements have been declared.
+      #
+      # See [this section](/#Required_Options) for a full explanation of how
+      # alternative option requirements can be used.
+      def required?
+        !!@required
+      end
+
+      # Declare alternative option requirements.
+      #
+      # Alternative (combinations of) options can be required. These need to be declared on the class body.
+      #
+      # For example,
+      #
+      #   ```ruby
+      #   class Api::Login < Cl::Cmd
+      #     # DNF, read as: api_key OR username AND password
+      #     required :api_key, [:username, :password]
+      #
+      #     opt '--api_key KEY'
+      #     opt '--username NAME'
+      #     opt '--password PASS'
+      #   end
+      #   ```
+      # Will require either the option `api_key`, or both the options `username` and `password`.
+      #
+      # See [this section](/#Required_Options) for a full explanation of how
+      # alternative option requirements can be used.
+      def required(*required)
+        required.any? ? self.required << required : @required ||= []
+      end
+
+      # Declare a summary for this command
+      #
+      # This is the summary that will be shown in both the command list, and command details help output.
+      #
+      # For example:
+      #
+      #   ```ruby
+      #   class Api::Login < Cl::Cmd
+      #     summary 'Login to the API'
+      #   end
+      #   ```
+      #
+      # @return [String] the summary if no argument was given
+      def summary(summary = nil)
+        summary ? @summary = summary : @summary
+      end
+    end
+  end
+end

data/lib/cl/errors.rb

@@ -0,0 +1,119 @@
+require 'cl/helper/suggest'
+
+class Cl
+  class Error < StandardError
+    MSGS = {
+      unknown_cmd:    'Unknown command: %s',
+      unknown_option: 'Unknown option: %s',
+      unknown_arg:    'Unknown argument value: %s (known: %s)',
+      missing_args:   'Missing arguments (given: %s, required: %s)',
+      too_many_args:  'Too many arguments: %s (given: %s, allowed: %s)',
+      wrong_type:     'Wrong argument type (given: %s, expected: %s)',
+      out_of_range:   'Out of range: %s',
+      invalid_format: 'Invalid format: %s',
+      unknown_values: 'Unknown value: %s',
+      required_opt:   'Missing required option: %s',
+      required_opts:  'Missing required options: %s',
+      requires_opt:   'Missing option: %s',
+      requires_opts:  'Missing options: %s',
+    }
+
+    def initialize(msg, *args)
+      super(MSGS[msg] ? MSGS[msg] % args : msg)
+    end
+  end
+
+  ArgumentError = Class.new(Error)
+  OptionError = Class.new(Error)
+
+  class UnknownCmd < Error
+    attr_reader :runner, :args
+
+    def initialize(runner, args)
+      @runner = runner
+      @args = args
+      super(:unknown_cmd, args.join(' '))
+    end
+
+    def suggestions
+      runner.suggestions(args)
+    end
+  end
+
+  class UnknownOption < Error
+    attr_reader :cmd, :opt
+
+    VALUE = /=[^ ]*/
+
+    def initialize(cmd, str)
+      @cmd = cmd
+      @opt = str.sub('invalid option: ', '').sub(VALUE, '')
+      super(:unknown_option, opt)
+    end
+
+    def suggestions
+      cmd.suggestions(opt)
+    end
+  end
+
+  class RequiredOpts < OptionError
+    def initialize(opts)
+      msg = opts.size == 1 ? :required_opt : :required_opts
+      super(msg, opts.join(', '))
+    end
+  end
+
+  class RequiredsOpts < OptionError
+    def initialize(opts)
+      opts = opts.map { |alts| alts.map { |alt| Array(alt).join(' and ') }.join(', or ' ) }
+      super(:requires_opts, opts.join('; '))
+    end
+  end
+
+  class RequiresOpts < OptionError
+    def initialize(opts)
+      msg = opts.size == 1 ? :requires_opt : :requires_opts
+      opts = opts.map { |one, other| "#{one} (required by #{other})" }.join(', ')
+      super(msg, opts)
+    end
+  end
+
+  class OutOfRange < OptionError
+    def initialize(opts)
+      opts = opts.map { |opt, opts| "#{opt} (#{opts.map { |pair| pair.join(': ') }.join(', ')})" }.join(', ')
+      super(:out_of_range, opts)
+    end
+  end
+
+  class InvalidFormat < OptionError
+    def initialize(opts)
+      opts = opts.map { |opt, format| "#{opt} (format: #{format})" }.join(', ')
+      super(:invalid_format, opts)
+    end
+  end
+
+  class UnknownArgumentValue < OptionError
+    def initialize(value, known)
+      super(:unknown_arg, value, known)
+    end
+  end
+
+  class UnknownValues < OptionError
+    include Suggest
+
+    attr_reader :opts
+
+    def initialize(opts)
+      @opts = opts
+      opts = opts.map do |(opt, values, known)|
+        pairs = values.map { |value| [opt, value].join('=') }.join(' ')
+        "#{pairs} (known values: #{known.join(', ')})"
+      end
+      super(:unknown_values, opts.join(', '))
+    end
+
+    def suggestions
+      opts.map { |_, value, known| suggest(known, value) }.flatten
+    end
+  end
+end

data/lib/cl/help/cmd.rb

@@ -0,0 +1,118 @@
+require 'cl/help/format'
+require 'cl/help/table'
+require 'cl/help/usage'
+
+class Cl
+  class Help
+    class Cmd < Struct.new(:ctx, :cmd)
+      include Format
+
+      def format
+        [usage, summary, description, arguments, options, common, examples].compact.join("\n\n")
+      end
+
+      def usage
+        "Usage: #{Usage.new(ctx, cmd).format.join("\n   or: ")}"
+      end
+
+      def summary
+        ['Summary:', indent(cmd.summary)] if cmd.summary
+      end
+
+      def description
+        ['Description:', indent(cmd.description)] if cmd.description
+      end
+
+      def arguments
+        ['Arguments:', table(:args)] if args.any?
+      end
+
+      def options
+        ['Options:', requireds, table(:opts)].compact if opts.any?
+      end
+
+      def common
+        ['Common Options:', table(:cmmn)] if common?
+      end
+
+      def examples
+        ['Examples:', indent(cmd.examples)] if cmd.examples
+      end
+
+      def table(name)
+        table = send(name)
+        indent(table.to_s(width - table.width + 5))
+      end
+
+      def args
+        @args ||= begin
+          Table.new(cmd.args.map { |arg| [arg.name, format_obj(arg)] })
+        end
+      end
+
+      def opts
+        @opts ||= begin
+          opts = cmd.opts.to_a
+          opts = opts.reject(&:internal?)
+          opts = opts - cmd.superclass.opts.to_a if common?
+          strs = Table.new(rjust(opts.map { |opt| opt_strs(opt) }))
+          opts = opts.map { |opt| format_obj(opt) }
+          Table.new(strs.rows.zip(opts))
+        end
+      end
+
+      def cmmn
+        @cmmn ||= begin
+          opts = cmd.superclass.opts
+          opts = opts.reject(&:internal?)
+          strs = Table.new(rjust(opts.map(&:strs)))
+          opts = opts.map { |opt| format_obj(opt) }
+          Table.new(strs.rows.zip(opts))
+        end
+      end
+
+      def opt_strs(opt)
+        return opt.strs if !opt.flag? || opt.help?
+        opts = [opt.short]
+        opts.push(negate?(opt) ? negate(opt) : opt.long)
+        opts.compact
+      end
+
+      def negate?(opt)
+        negations = opt.negate.map { |str| "#{str}-" }.join('|')
+        opt.long && opt.negate? && opt.long !~ /\[#{negations}\]/
+      end
+
+      def negate(opt)
+        negations = opt.negate.map { |str| "#{str}-" }.join('|')
+        opt.long.dup.insert(2, "[#{negations}]")
+      end
+
+      def requireds
+        return unless cmd.required?
+        opts = cmd.required
+        strs = opts.map { |alts| alts.map { |alt| Array(alt).join(' and ') }.join(', or ' ) }
+        strs = strs.map { |str| "Either #{str} are required." }.join("\n")
+        indent(strs) unless strs.empty?
+      end
+
+      def common?
+        cmd.superclass < Cl::Cmd
+      end
+
+      def width
+        [args.width, opts.width, cmmn.width].max
+      end
+
+      def rjust(objs)
+        return objs unless objs.any?
+        width = objs.max_by(&:size).size
+        objs.map { |objs| [*Array.new(width - objs.size) { '' }, *objs] }
+      end
+
+      def indent(str)
+        str.lines.map { |line| "  #{line}".rstrip }.join("\n")
+      end
+    end
+  end
+end

data/lib/cl/help/cmds.rb

@@ -0,0 +1,26 @@
+require 'cl/help/table'
+require 'cl/help/usage'
+
+class Cl
+  class Help
+    class Cmds < Struct.new(:ctx, :cmds)
+      HEAD = %(Type "%s help COMMAND [SUBCOMMAND]" for more details:\n)
+
+      def format
+        [head, Table.new(list).format].join("\n")
+      end
+
+      def head
+        HEAD % ctx.name
+      end
+
+      def list
+        cmds.any? ? cmds.map { |cmd| format_cmd(cmd) } : [['[no commands]']]
+      end
+
+      def format_cmd(cmd)
+        ["#{Usage.new(ctx, cmd).format.first}", cmd.summary]
+      end
+    end
+  end
+end

data/lib/cl/help/format.rb

@@ -0,0 +1,69 @@
+class Cl
+  class Help
+    module Format
+      def format_obj(obj)
+        Obj.new(obj).format
+      end
+
+      class Obj < Struct.new(:obj)
+        def format
+          opts = []
+          opts << "type: #{type(obj)}" unless obj.type == :flag
+          opts << 'required' if obj.required?
+          opts += Opt.new(obj).format if obj.is_a?(Cl::Opt)
+          opts = opts.join(', ')
+          opts = "(#{opts})" if obj.description && !opts.empty?
+          opts = [obj.description, opts]
+          opts.compact.map(&:strip).join(' ')
+        end
+
+        def type(obj)
+          return obj.type unless obj.is_a?(Cl::Opt) && obj.type == :array
+          "array (string, can be given multiple times)"
+        end
+      end
+
+      class Opt < Struct.new(:opt)
+        include Regex
+
+        def format
+          opts = []
+          opts << "alias: #{format_aliases(opt)}" if opt.aliases?
+          opts << "requires: #{opt.requires.join(', ')}" if opt.requires?
+          opts << "default: #{format_default(opt)}" if opt.default?
+          opts << "known values: #{format_enum(opt)}" if opt.enum?
+          opts << "format: #{opt.format}" if opt.format?
+          opts << "downcases" if opt.downcase?
+          opts << "upcases" if opt.upcase?
+          opts << "min: #{opt.min}" if opt.min?
+          opts << "max: #{opt.max}" if opt.max?
+          opts << "e.g.: #{opt.example}" if opt.example?
+          opts << "note: #{opt.note}" if opt.note?
+          opts << "see: #{opt.see}" if opt.see?
+          opts << format_deprecated(opt) if opt.deprecated?
+          opts.compact
+        end
+
+        def format_aliases(opt)
+          opt.aliases.map do |name|
+            strs = [name]
+            strs << "(deprecated, please use #{opt.name})" if opt.deprecated[0] == name
+            strs.join(' ')
+          end.join(', ')
+        end
+
+        def format_enum(opt)
+          opt.enum.map { |value| format_regex(value) }.join(', ')
+        end
+
+        def format_default(opt)
+          opt.default.is_a?(Symbol) ? opt.default.to_s.sub('_', ' ') : opt.default
+        end
+
+        def format_deprecated(opt)
+          return "deprecated (#{opt.deprecated[1]})" if opt.deprecated[0] == opt.name
+        end
+      end
+    end
+  end
+end

data/lib/cl/help/table.rb

@@ -0,0 +1,58 @@
+class Cl
+  class Help
+    class Table
+      include Wrap
+
+      attr_reader :data, :padding
+
+      def initialize(data)
+        @data = data
+      end
+
+      def any?
+        data.any?
+      end
+
+      def format(padding = 8)
+        @padding = padding
+        rows.join("\n")
+      end
+      alias to_s format
+
+      def rows
+        data.map { |row| cells(row).join(' ').rstrip }
+      end
+
+      def cells(row)
+        row.map.with_index do |cell, ix|
+          indent(wrap(cell.to_s), widths[ix - 1]).ljust(widths[ix])
+        end
+      end
+
+      def indent(str, width)
+        return str if str.empty? || !width
+        [str.lines[0], *str.lines[1..-1].map { |str| ' ' * (width + 1) + str }].join.rstrip
+      end
+
+      def width
+        widths = cols[0..-2].map { |col| col.max_by(&:size).size }.inject(&:+).to_i
+        widths + cols.size - 1
+      end
+
+      def widths
+        cols.map.with_index do |col, ix|
+          max = col.compact.max_by(&:size)
+          pad(max ? max.size : 0, ix)
+        end
+      end
+
+      def pad(width, ix)
+        ix < cols.size - 2 ? width : width + padding.to_i
+      end
+
+      def cols
+        @cols ||= data.transpose
+      end
+    end
+  end
+end

data/lib/cl/help/usage.rb

@@ -0,0 +1,26 @@
+class Cl
+  class Help
+    class Usage < Struct.new(:ctx, :cmd)
+      def format
+        cmd.registry_keys.map do |key|
+          line(key)
+        end
+      end
+
+      def line(key)
+        usage = [executable, key.to_s.gsub(':', ' ')]
+        usage += cmd.args.map(&:to_s) # { |arg| "[#{arg}]" }
+        usage << '[options]' if opts?
+        usage.join(' ')
+      end
+
+      def executable
+        ctx.name
+      end
+
+      def opts?
+        cmd.opts.any?
+      end
+    end
+  end
+end

data/lib/cl/help.rb

@@ -0,0 +1,37 @@
+class Cl
+  class Help < Cl::Cmd
+    register :help
+
+    arg :args, splat: true
+
+    def run
+      ctx.puts help
+    end
+
+    def help
+      Array(args).any? ? Cmd.new(ctx, cmd).format : Cmds.new(ctx, cmds).format
+    end
+
+    def help?
+      true
+    end
+
+    private
+
+      def cmds
+        cmds = Cl::Cmd.cmds.reject { |cmd| cmd.registry_key == :help }
+        key  = args.join(':') if args
+        cmds = cmds.select { |cmd| cmd.registry_key.to_s.start_with?(key) } if key
+        cmds
+      end
+
+      def cmd
+        key = args.join(':')
+        return Cl::Cmd[key] if Cl::Cmd.registered?(key)
+        ctx.abort("Unknown command: #{key}")
+      end
+  end
+end
+
+require 'cl/help/cmd'
+require 'cl/help/cmds'

data/lib/cl/helper/suggest.rb

@@ -0,0 +1,10 @@
+class Cl
+  module Suggest
+    def suggest(dict, value)
+      return [] unless defined?(DidYouMean::SpellChecker)
+      Array(value).map do |value|
+        DidYouMean::SpellChecker.new(dictionary: dict.map(&:to_s)).correct(value.to_s)
+      end.flatten
+    end
+  end
+end

data/lib/cl/helper.rb

@@ -0,0 +1,47 @@
+require 'cl/helper/suggest'
+
+class Cl
+  module Merge
+    MERGE = ->(key, lft, rgt) do
+      lft.is_a?(Hash) && rgt.is_a?(Hash) ? lft.merge(rgt, &MERGE) : rgt
+    end
+
+    def merge(*objs)
+      objs.inject({}) { |lft, rgt| lft.merge(rgt, &MERGE) }
+    end
+  end
+
+  module Regex
+    def format_regex(str)
+      return str unless str.is_a?(Regexp)
+      "/#{str.to_s.sub('(?-mix:', '').sub(/\)$/, '')}/"
+    end
+  end
+
+  module Wrap
+    def wrap(str, opts = {})
+      width = opts[:width] || 80
+      str.lines.map do |line|
+        line.size > width ? line.gsub(/(.{1,#{width}})(\s+|$)/, "\\1\n").strip : line
+      end.join("\n")
+    end
+  end
+
+  module Underscore
+    def underscore(string)
+      string.gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      downcase
+    end
+  end
+
+  extend Merge, Regex, Wrap
+end
+
+if RUBY_VERSION == '2.0.0'
+  Array.class_eval do
+    def to_h
+      Hash[self]
+    end
+  end
+end