cl 1.0.0 → 1.0.1

data/examples/readme/basic

@@ -0,0 +1,65 @@
+require 'cl'
+
+# e.g. lib/owners/add.rb
+module Owners
+  class Add < Cl::Cmd
+    summary 'Add one or more owners to an existing owner group'
+
+    description <<~str
+      Use this command to add one or more owners to an existing
+      owner group.
+
+      [...]
+    str
+
+    args :owner
+
+    opt '-t', '--to TO', 'An existing owner group'
+
+    def run
+      # implement adding the owner as given in `owner` (as well as `args`)
+      # to the group given in `to` (as well as `opts[:to]`).
+      p owner: owner, to: to, to?: to?, args: args, opts: opts
+    end
+  end
+end
+
+# Running this, e.g. using `bin/owners add one,two --to group` will instantiate the
+# class `Owners::Add`, and call the method `run` on it.
+
+# e.g. bin/owners
+#
+# args normally would be ARGV
+args = %w(add one --to group)
+
+Cl.new('owners').run(args)
+
+# Output:
+#
+#   {:owner=>"one", :to=>"group", :to?=>true, :args=>["one"], :opts=>{:to=>"group"}}
+
+Cl.new('owners').run(%w(add --help))
+
+# Output:
+#
+#   Usage: owners add [owner] [options]
+#
+#   Summary:
+#
+#     Add one or more owners to an existing owner group
+#
+#   Description:
+#
+#     Use this command to add one or more owners to an existing
+#     owner group.
+#
+#     [...]
+#
+#   Arguments:
+#
+#     owner           type: string
+#
+#   Options:
+#
+#     -t --to TO      An existing owner group (type: string)
+#        --help       Get help on this command

data/examples/readme/description

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+module Owners
+  class Add < Cl::Cmd
+    summary 'Add one or more owners to an existing owner group'
+
+    description <<~str
+      Use this command to add one or more owners to an existing
+      owner group.
+    str
+
+    examples <<~str
+      Adding a single user to the group admins:
+
+        owners add user --to admins
+
+      Adding a several users at once:
+
+        owners add one two three --to admins
+    str
+  end
+end
+
+Cl.new('owners').run(%w(add --help))
+
+# Output:
+#
+#   Usage: owners add [options]
+#
+#   Summary:
+#
+#     Add one or more owners to an existing owner group
+#
+#   Description:
+#
+#     Use this command to add one or more owners to an existing
+#     owner group.
+#
+#   Options:
+#
+#     --help      Get help on this command
+#
+#   Examples:
+#
+#     Adding a single user to the group admins:
+#
+#       owners add user --to admins
+#
+#     Adding a several users at once:
+#
+#       owners add one two three --to admins

data/examples/readme/note

@@ -9,9 +9,11 @@ end
 
 Cl.new('owners').run(%w(add --help))
 
-# Usage: owners add [options]
+# Output:
 #
-# Options:
+#   Usage: owners add [options]
 #
-#   --to GROUP      type: string, note: needs to be a group
-#   --help          Get help on this command
+#   Options:
+#
+#     --to GROUP      type: string, note: needs to be a group
+#     --help          Get help on this command

data/examples/readme/registry

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+module Cmd
+  class One < Cl::Cmd
+  end
+
+  class Two < Cl::Cmd
+  end
+end
+
+p Cl::Cmd[:one] # => Cmd::One
+p Cl::Cmd[:two] # => Cmd::Two

data/examples/readme/runner

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+module Git
+  class Pull < Cl::Cmd
+    register :'git:pull'
+
+    def run
+      p cmd: registry_key, args: args
+    end
+  end
+end
+
+# With this class registered (and assuming the executable that calls `Cl` is
+# `bin/run`) the default runner would recognize and run it:
+#
+# $ bin/run git:pull master # instantiates Git::Pull, and passes ["master"] as args
+# $ bin/run git pull master # does the same
+
+Cl.new('run').run(%w(git:pull master))
+# Output:
+#
+#   {:cmd=>:"git:pull", :args=>["master"]}
+
+Cl.new('run').run(%w(git pull master))
+# Output:
+#
+#   {:cmd=>:"git:pull", :args=>["master"]}

data/examples/readme/runner_custom

@@ -0,0 +1,22 @@
+# anywhere in your library
+
+require 'cl'
+
+class Runner
+  Cl::Runner.register :custom, self
+
+  def initialize(ctx, args)
+    # ...
+  end
+
+  def run
+    const = identify_cmd_class_from_args
+    const.new(ctx, args).run
+  end
+end
+
+# in bin/run
+Cl.new('run', runner: :custom).run(ARGV)
+
+
+

data/lib/cl/args.rb

@@ -13,11 +13,11 @@ class Cl
       self.args << arg
     end
 
-    def apply(cmd, args, opts)
-      return args if self.args.empty? || opts[:help]
-      args = grouped(args)
-      validate(args)
-      args.map { |(arg, value)| arg.set(cmd, value) }.flatten(1)
+    def apply(cmd, values, opts)
+      return values if args.empty? || opts[:help]
+      values = splat(values) if splat?
+      validate(values)
+      args.zip(values).map { |(arg, value)| arg.set(cmd, value) }.flatten(1).compact
     end
 
     def each(&block)
@@ -51,19 +51,11 @@ class Cl
         select(&:required?).size
       end
 
-      def grouped(values)
-        values.inject([0, {}]) do |(ix, group), value|
-          arg = args[ix]
-          if arg && arg.splat?
-            group[arg] ||= []
-            group[arg] << value
-            ix += 1 if args.size + group[arg].size > values.size
-          else
-            group[arg] = value
-            ix += 1
-          end
-          [ix, group]
-        end.last
+      def splat(values)
+        args.each.with_index.inject([]) do |group, (arg, ix)|
+          count = arg && arg.splat? ? [values.size - args.size + ix + 1] : []
+          group << values.shift(*count)
+        end
       end
   end
 end

data/lib/cl/cast.rb

@@ -1,33 +1,55 @@
 class Cl
   module Cast
-    TRUE  = /^(true|yes|on)$/
-    FALSE = /^(false|no|off)$/
+    class Cast < Struct.new(:type, :value, :opts)
+      TRUE  = /^(true|yes|on)$/
+      FALSE = /^(false|no|off)$/
 
-    def cast(value)
-      case type
-      when nil
-        value
-      when :array
-        Array(value).compact.flatten.map { |value| split(value) }.flatten
-      when :string, :str
-        value.to_s unless value.to_s.empty?
-      when :flag, :boolean, :bool
-        return true  if value.to_s =~ TRUE
-        return false if value.to_s =~ FALSE
-        !!value
-      when :integer, :int
-        Integer(value)
-      when :float
-        Float(value)
-      else
-        raise ArgumentError, "Unknown type: #{type}" if value
+      def apply
+        return send(type) if respond_to?(type, true)
+        raise ArgumentError, "Unknown type: #{type}"
+      rescue ::ArgumentError => e
+        raise ArgumentError.new(:wrong_type, value.inspect, type)
       end
-    rescue ::ArgumentError => e
-      raise ArgumentError.new(:wrong_type, value.inspect, type)
+
+      private
+
+        def array
+          Array(value).compact.flatten.map { |value| split(value) }.flatten.compact
+        end
+
+        def string
+          value.to_s unless value.to_s.empty?
+        end
+        alias str string
+
+        def boolean
+          return true  if value.to_s =~ TRUE
+          return false if value.to_s =~ FALSE
+          !!value
+        end
+        alias bool boolean
+        alias flag boolean
+
+        def int
+          Integer(value)
+        end
+        alias integer int
+
+        def float
+          Float(value)
+        end
+
+        def split(value)
+          separator ? value.to_s.split(separator) : value
+        end
+
+        def separator
+          opts[:separator]
+        end
     end
 
-    def split(value)
-      separator ? value.to_s.split(separator) : value
+    def cast(value)
+      type ? Cast.new(type, value, separator: separator).apply : value
     end
   end
 end

data/lib/cl/help/cmd.rb

@@ -1,10 +1,11 @@
+require 'cl/help/format'
 require 'cl/help/table'
 require 'cl/help/usage'
 
 class Cl
   class Help
     class Cmd < Struct.new(:ctx, :cmd)
-      include Regex
+      include Format
 
       def format
         [usage, summary, description, arguments, options, common, examples].compact.join("\n\n")
@@ -86,59 +87,6 @@ class Cl
         [args.width, opts.width, cmmn.width].max
       end
 
-      def format_obj(obj)
-        opts = []
-        opts << "type: #{format_type(obj)}" unless obj.type == :flag
-        opts << 'required: true' if obj.required?
-        opts += format_opt(obj) if obj.is_a?(Opt)
-        opts = opts.join(', ')
-        opts = "(#{opts})" if obj.description && !opts.empty?
-        opts = [obj.description, opts]
-        opts.compact.map(&:strip).join(' ')
-      end
-
-      def format_opt(opt)
-        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 << "downcase: true" if opt.downcase?
-        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_type(obj)
-        return obj.type unless obj.is_a?(Opt) && obj.type == :array
-        "array (string, can be given multiple times)"
-      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
-
       def rjust(objs)
         return objs unless objs.any?
         width = objs.max_by(&:size).size
@@ -146,7 +94,7 @@ class Cl
       end
 
       def indent(str)
-        str.lines.map { |line| "  #{line}" }.join
+        str.lines.map { |line| "  #{line}".rstrip }.join("\n")
       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: true' 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 << "downcase: true" if opt.downcase?
+          opts << "upcase: true" 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

@@ -42,11 +42,14 @@ class Cl
       def widths
         cols.map.with_index do |col, ix|
           max = col.compact.max_by(&:size)
-          width = max ? max.size : 0
-          ix < cols.size - 2 ? width : width + padding.to_i
+          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

data/lib/cl/opt.rb

@@ -179,6 +179,10 @@ class Cl
       opts[:sep]
     end
 
+    def upcase?
+      !!opts[:upcase]
+    end
+
     def block
       # raise if no block was given, and the option's name cannot be inferred
       super || method(:assign)

data/lib/cl/opts/validate.rb

@@ -0,0 +1,117 @@
+require 'cl/helper'
+
+class Cl
+  class Opts
+    module Validate
+      def validate(cmd, opts, values)
+        Validate.constants.each do |name|
+          next if name == :Validator
+          const = Validate.const_get(name)
+          const.new(cmd, opts, values).apply
+        end
+      end
+
+      class Validator < Struct.new(:cmd, :opts, :values)
+        include Regex
+        def compact(hash, *keys)
+          hash.reject { |_, value| value.nil? }.to_h
+        end
+
+        def invert(hash)
+          hash.map { |key, obj| Array(obj).map { |obj| [obj, key] } }.flatten(1).to_h
+        end
+
+        def only(hash, *keys)
+          hash.select { |key, _| keys.include?(key) }.to_h
+        end
+      end
+
+      class Required < Validator
+        def apply
+          # make sure we do not accept unnamed required options
+          raise RequiredOpts.new(missing.map(&:name)) if missing.any?
+        end
+
+        def missing
+          @missing ||= opts.select(&:required?).select { |opt| !values.key?(opt.name) }
+        end
+      end
+
+      class Requireds < Validator
+        def apply
+          raise RequiredsOpts.new(missing) if missing.any?
+        end
+
+        def missing
+          @missing ||= cmd.class.required.map do |alts|
+            alts if alts.none? { |alt| Array(alt).all? { |key| values.key?(key) } }
+          end.compact
+        end
+      end
+
+      class Requires < Validator
+        def apply
+          raise RequiresOpts.new(invert(missing)) if missing.any?
+        end
+
+        def missing
+          @missing ||= requires.map do |opt|
+            missing = opt.requires.select { |key| !values.key?(key) }
+            [opt.name, missing] if missing.any?
+          end.compact
+        end
+
+        def requires
+          opts.select(&:requires?).select { |opt| values.key?(opt.name) }
+        end
+      end
+
+      class Format < Validator
+        def apply
+          raise InvalidFormat.new(invalid) if invalid.any?
+        end
+
+        def invalid
+          @invalid ||= opts.select(&:format?).map do |opt|
+            value = values[opt.name]
+            [opt.name, opt.format] if value && !opt.formatted?(value)
+          end.compact
+        end
+      end
+
+      class Enum < Validator
+        def apply
+          raise UnknownValues.new(unknown) if unknown.any?
+        end
+
+        def unknown
+          @unknown ||= opts.select(&:enum?).map do |opt|
+            value = values[opt.name]
+            next unless value && !opt.known?(value)
+            known = opt.enum.map { |str| format_regex(str) }
+            [opt.name, value, known]
+          end.compact
+        end
+      end
+
+      class Range < Validator
+        def apply
+          raise OutOfRange.new(invalid) if invalid.any?
+        end
+
+        def invalid
+          @invalid ||= opts.map do |opt|
+            next unless value = values[opt.name]
+            range = only(opt.opts, :min, :max)
+            [opt.name, compact(range)] if invalid?(range, value)
+          end.compact
+        end
+
+        def invalid?(range, value)
+          min, max = range.values_at(:min, :max)
+          min && value < min || max && value > max
+        end
+      end
+    end
+  end
+end