cl 0.1.12 → 0.1.13

data/examples/readme/requires

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+class Add < Cl::Cmd
+  opt '--to GROUP'
+  opt '--retries INT', requires: :to
+
+  def run
+    p to, retries
+  end
+end
+
+Cl.new('owners').run(%w(add --to one --retries 1))
+
+# Output:
+#
+#   "one"
+#   1
+
+Cl.new('owners').run(%w(add --retries 1))
+
+# Missing option: to (required by retries)
+#
+# Usage: requires add [options]
+#
+# Options:
+#
+#   --to GROUP         type: string
+#   --retries INT      type: string, requires: to
+#   --help             Get help on this command

data/examples/readme/see

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+class Add < Cl::Cmd
+  opt '--to GROUP', see: 'https://docs.io/cli/owners/add'
+
+  def run
+    p retries
+  end
+end
+
+Cl.new('owners').run(%w(add --help))
+
+# Usage: see add [options]
+#
+# Options:
+#
+#   --to GROUP      type: string, see: https://docs.io/cli/owners/add
+#   --help          Get help on this command

data/examples/readme/type

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+class Add < Cl::Cmd
+  opt '--active BOOL', type: :boolean
+  opt '--retries INT', type: :integer
+  opt '--sleep FLOAT', type: :float
+
+  def run
+    p active.class, retries.class, sleep.class
+  end
+end
+
+Cl.new('owners').run(%w(add --active yes --retries 1 --sleep 0.1))
+
+# Output:
+#
+#   TrueClass
+#   Integer
+#   Float

data/lib/cl.rb

@@ -1,70 +1,17 @@
 require 'cl/cmd'
 require 'cl/help'
-require 'cl/runner/default'
-require 'cl/runner/multi'
+require 'cl/runner'
+require 'cl/errors'
 
 class Cl
-  class Error < StandardError
-    MSGS = {
-      missing_args:   'Missing arguments (given: %s, required: %s)',
-      too_many_args:  'Too many arguments (given: %s, allowed: %s)',
-      wrong_type:     'Wrong argument type (given: %s, expected: %s)',
-      exceeding_max:  'Exceeds max value: %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)
-  RequiredOpts = Class.new(OptionError)
-
-  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 ExceedingMax < OptionError
-    def initialize(opts)
-      opts = opts.map { |opt, max| "#{opt} (max: #{max})" }.join(', ')
-      super(:exceeding_max, 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 UnknownValues < OptionError
-    def initialize(opts)
-      opts = opts.map { |(key, value, known)| "#{key}=#{value} (known values: #{known.join(', ')})" }.join(', ')
-      super(:unknown_values, opts)
-    end
-  end
-
   attr_reader :ctx, :name, :opts
 
+  # @overload initialize(ctx, name, opts)
+  #   @param ctx  [Cl::Ctx] the current execution context (optional)
+  #   @param name [String] the program (executable) name (optional, defaults to $0)
+  #   @param opts [Hash] options (optional)
+  #   @option opts [Cl::Runner] :runner registry key for a runner (optional, defaults to :default)
+  #   @option opts [Cl::Ui] :ui the ui for handling user interaction
   def initialize(*args)
     ctx   = args.shift if args.first.is_a?(Ctx)
     @opts = args.last.is_a?(Hash) ? args.pop : {}
@@ -72,19 +19,32 @@ class Cl
     @ctx  = ctx || Ctx.new(name, opts)
   end
 
+  # Runs the command.
+  #
+  # Instantiates a runner with the given arguments, and runs it.
+  #
+  # If the command fails (raises a Cl::Error) then the exception is caught, and
+  # the process aborted with the error message and help output for the given
+  # command.
+  #
+  # @param args [Array<String>] arguments (usually ARGV)
   def run(args)
     runner(args.map(&:dup)).run
+  rescue UnknownCmd => e
+    ctx.abort e
   rescue Error => e
-    abort [e.message, runner(['help', args.first]).cmd.help].join("\n\n")
+    ctx.abort e, help(args.first)
   end
 
+  # Returns a runner instance for the given arguments.
   def runner(args)
     runner = :default if args.first.to_s == 'help'
     runner ||= opts[:runner] || :default
-    Runner.const_get(runner.to_s.capitalize).new(ctx, args)
+    Runner[runner].new(ctx, args)
   end
 
-  # def help(*args)
-  #   runner(:help, *args).run
-  # end
+  # Returns help output for the given command
+  def help(*args)
+    runner(['help', *args]).cmd.help
+  end
 end

data/lib/cl/arg.rb

@@ -20,20 +20,24 @@ class Cl
       opts[:description]
     end
 
-    def splat?
-      type == :array
-    end
-
     def required?
       !!opts[:required]
     end
 
+    def separator
+      opts[:sep]
+    end
+
+    def splat?
+      opts[:splat] && type == :array
+    end
+
     def to_s
       str = name
       case type
       when :array          then str = "#{str}.."
-      when :integer, :int  then str = "#{str}:int"
       when :boolean, :bool then str = "#{str}:bool"
+      when :integer, :int  then str = "#{str}:int"
       when :float          then str = "#{str}:float"
       end
       required? ? str : "[#{str}]"

data/lib/cl/cast.rb

@@ -8,7 +8,7 @@ class Cl
       when nil
         value
       when :array
-        Array(value).compact.flatten.map { |value| value.to_s.split(',') }.flatten
+        Array(value).compact.flatten.map { |value| split(value) }.flatten
       when :string, :str
         value.to_s unless value.to_s.empty?
       when :flag, :boolean, :bool
@@ -25,5 +25,9 @@ class Cl
     rescue ::ArgumentError => e
       raise ArgumentError.new(:wrong_type, value.inspect, type)
     end
+
+    def split(value)
+      separator ? value.to_s.split(separator) : value
+    end
   end
 end

data/lib/cl/cmd.rb

@@ -1,21 +1,28 @@
 require 'registry'
 require 'cl/args'
-require 'cl/helper'
+require 'cl/dsl'
 require 'cl/opts'
 require 'cl/parser'
 
 class Cl
+  # Base class for all command classes that can be run.
+  #
+  # Inherit your command classes from this class, use the {Cl::Cmd::Dsl} to
+  # declare arguments, options, summary, description, examples etc., and
+  # implement the method #run.
+  #
+  # See {Cl::Cmd::Dsl} for details on the DSL methods.
   class Cmd
     include Registry
+    extend Dsl
 
     class << self
-      include Merge
+      include Merge, Underscore
 
       inherited = ->(const) do
         const.register [registry_key, underscore(const.name.split('::').last)].compact.join(':') if const.name
         const.define_singleton_method(:inherited, &inherited)
       end
-
       define_method(:inherited, &inherited)
 
       def cmds
@@ -27,51 +34,6 @@ class Cl
         opts = merge(ctx.config[registry_key], opts) if ctx.config[registry_key]
         [args, opts || {}]
       end
-
-      def abstract
-        unregister
-      end
-
-      def args(*args)
-        return @args ||= Args.new unless args.any?
-        opts = args.last.is_a?(Hash) ? args.pop : {}
-        args.each { |arg| arg(arg, opts) }
-      end
-
-      def arg(*args)
-        self.args.define(self, *args)
-      end
-
-      def opt(*args, &block)
-        self.opts.define(self, *args, &block)
-      end
-
-      def opts
-        @opts ||= self == Cmd ? Opts.new : superclass.opts.dup
-      end
-
-      def description(description = nil)
-        description ? @description = description : @description
-      end
-
-      def required?
-        !!@required
-      end
-
-      def required(*required)
-        required.any? ? self.required << required : @required ||= []
-      end
-
-      def summary(summary = nil)
-        summary ? @summary = summary : @summary
-      end
-      alias purpose summary
-
-      def underscore(string)
-        string.gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-        gsub(/([a-z\d])([A-Z])/,'\1_\2').
-        downcase
-      end
     end
 
     opt '--help', 'Get help on this command'
@@ -92,7 +54,7 @@ class Cl
     def deprecated_opts
       opts = self.class.opts.select(&:deprecated?)
       opts = opts.select { |opt| self.opts.key?(opt.deprecated[0]) }
-      opts.map(&:deprecated)
+      opts.map(&:deprecated).to_h
     end
   end
 end

data/lib/cl/ctx.rb

@@ -13,13 +13,11 @@ class Cl
 
     def initialize(name, opts = {})
       @config = Config.new(name).to_h
-      @ui = Ui.new(self, opts)
+      @ui = opts[:ui] || Ui.new(self, opts)
     end
 
-    def abort(str)
-      fail(str) if test?
-      ui.error(str)
-      exit 1
+    def abort(error, *strs)
+      ui.abort(error, *strs)
     end
 
     def test?

data/lib/cl/dsl.rb

@@ -0,0 +1,176 @@
+require 'cl/helper'
+
+class Cl
+  class Cmd
+    module Dsl
+      include Merge, Underscore
+
+      def abstract
+        unregister
+      end
+
+      # Declare multiple arguments at once
+      #
+      # See {Cl::Cmd::Dsl#arg} for more details.
+      def args(*args)
+        return @args ||= 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 [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