command_kit 0.1.0.pre1 → 0.1.0.pre2

data/lib/command_kit/main.rb

@@ -82,6 +82,8 @@ module CommandKit
     # @return [Integer]
     #   The exit status code.
     #
+    # @note `argv` is splatted into {#run}.
+    #
     def main(argv=[])
       run(*argv)
       return 0

data/lib/command_kit/options.rb

@@ -9,24 +9,28 @@ module CommandKit
   #
   #     include CommandKit::Options
   #     
-  #     option :foo, type: String,
-  #                  short: '-f',
-  #                  desc: "Foo option"
+  #     option :foo, short: '-f',
+  #                  value: {type: String},
+  #                  desc:  "Foo option"
   #     
-  #     option :bar, type: String,
-  #                  short: '-b',
-  #                  usage: 'STR:STR:...',
+  #     option :bar, short: '-b',
+  #                  value: {
+  #                    type:  String,
+  #                    usage: 'STR:STR:...'
+  #                  },
   #                  desc: "Bar option" do |arg|
   #       @bar = arg.split(':')
   #     end
+  #
+  # ### initialize and using ivars
   #     
-  #     option :number, type: Integer,
+  #     option :number, value: {type: Integer},
   #                     desc: 'Numbers' do |num|
   #       @numbers << num
   #     end
   #     
-  #     def initialize
-  #       super
+  #     def initialize(**kwargs)
+  #       super(**kwargs)
   #     
   #       @numbers = []
   #     end
@@ -78,6 +82,31 @@ module CommandKit
       # @param [Symbol] name
       #   The option name.
       #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Keyword arguments.
+      #
+      # @option kwargs [String, nil] short
+      #   Optional short-flag for the option.
+      #
+      # @option kwargs [String, nil] long
+      #   Optional explicit long-flag for the option.
+      #
+      # @option kwargs [Boolean] equals
+      #   Specifies whether the option is of the form (`--opt=value`).
+      #
+      # @option kwargs [Hash{Symbol => Object}, true, false, nil] value
+      #   Keyword arguments for {OptionValue#initialize}, or `nil` if the option
+      #   has no additional value.
+      #
+      # @option value [Class, Hash, Array, Regexp] type
+      #   The type of the option's value.
+      #
+      # @option value [String, nil] usage
+      #   The usage string for the option's value.
+      #
+      # @option kwargs [String] desc
+      #   The description for the option.
+      #
       # @yield [(value)]
       #   If a block is given, it will be passed the parsed option value.
       #
@@ -86,6 +115,10 @@ module CommandKit
       #
       # @return [Option]
       #
+      # @raise [TypeError]
+      #   The `value` keyword argument was not a `Hash`, `true`, `false`, or
+      #   `nil`.
+      #
       # @example Define an option:
       #     option :foo, desc: "Foo option"
       #
@@ -156,6 +189,10 @@ module CommandKit
     # @param [Hash{Symbol => Object}] options
     #   Optional pre-populated options hash.
     #
+    # @note
+    #   The {#option_parser} will populate {#options} and also call any
+    #   {ClassMethods#option option} blocks with the parsed option values.
+    #
     def initialize(options: {}, **kwargs)
       @options = options
 

data/lib/command_kit/options/option.rb

@@ -13,24 +13,33 @@ module CommandKit
     #
     class Option
 
+      # The option's name.
+      #
       # @return [Symbol]
       attr_reader :name
 
+      # The option's optional short-flag.
+      #
       # @return [String, nil]
       attr_reader :short
 
+      # The option's long-flag.
+      #
       # @return [String]
       attr_reader :long
 
-      # @return [Boolean]
-      attr_reader :equals
-
+      # The option value's type.
+      #
       # @return [OptionValue, nil]
       attr_reader :value
 
+      # The option's description.
+      #
       # @return [String]
       attr_reader :desc
 
+      # The optional block that will receive the parsed option value.
+      #
       # @return [Proc, nil]
       attr_reader :block
 
@@ -38,26 +47,39 @@ module CommandKit
       # Initializes the option.
       #
       # @param [Symbol] name
+      #   The name of the option.
       #
       # @param [String, nil] short
+      #   Optional short-flag for the option.
       #
       # @param [String, nil] long
+      #   Optional explicit long-flag for the option.
       #
       # @param [Boolean] equals
+      #   Specifies whether the option is of the form (`--opt=value`).
       #
-      # @param [Hash{Symbol => Object}, nil] value
+      # @param [Hash{Symbol => Object}, true, false, nil] value
       #   Keyword arguments for {OptionValue#initialize}, or `nil` if the option
       #   has no additional value.
       #
       # @option value [Class, Hash, Array, Regexp] type
+      #   The type of the option's value.
       #
       # @option value [String, nil] usage
+      #   The usage string for the option's value.
       #
       # @param [String] desc
+      #   The description for the option.
       #
       # @yield [(value)]
+      #   If a block is given, it will be called when the option is parsed.
       #
       # @yieldparam [Object, nil] value
+      #   The given block will be passed the parsed option's value.
+      #
+      # @raise [TypeError]
+      #   The `value` keyword argument was not a `Hash`, `true`, `false`, or
+      #   `nil`.
       #
       def initialize(name, short:   nil,
                            long:    self.class.default_long_opt(name),
@@ -69,7 +91,13 @@ module CommandKit
         @short   = short
         @long    = long
         @equals  = equals
-        @value   = OptionValue.new(**value) if value
+        @value   = case value
+                   when Hash       then OptionValue.new(**value)
+                   when true       then OptionValue.new()
+                   when false, nil then nil
+                   else
+                     raise(TypeError,"value: keyword must be Hash, true, false, or nil")
+                   end
         @desc    = desc
         @block   = block
       end
@@ -79,8 +107,10 @@ module CommandKit
       # (ex: `:long_opt`).
       #
       # @param [Symbol] name
+      #   The option name.
       #
       # @return [String]
+      #   The long-flag for the option.
       #
       def self.default_long_opt(name)
         "--#{Inflector.dasherize(name)}"

data/lib/command_kit/options/option_value.rb

@@ -16,6 +16,7 @@ module CommandKit
     #
     class OptionValue < Arguments::ArgumentValue
 
+      # Maps OptionParser types to USAGE strings.
       USAGES = {
         # NOTE: NilClass and Object are intentionally omitted
         Date       => 'DATE',
@@ -36,27 +37,52 @@ module CommandKit
         Regexp     => '/REGEXP/'
       }
 
+      # The desired type of the argument value.
+      #
+      # @return [Class, Hash, Array, Regexp, nil]
+      attr_reader :type
+
+      # The default parsed value for the argument value.
+      #
+      # @return [Object, Proc, nil]
+      attr_reader :default
+
       #
       # Initializes the option value.
       #
       # @param [Class, Hash, Array, Regexp] type
+      #   The type of the option value.
+      #
+      # @param [Object, Proc, nil] default
+      #   The default parsed value for the option value.
       #
       # @param [String, nil] usage
+      #   The optional usage string for the option value.
       #
       # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      # @option kwargs [Boolean] required
+      #   Specifies whether the option value is required or optional.
       #
-      def initialize(type: String,
-                     usage: self.class.default_usage(type),
+      def initialize(type:    String,
+                     default: nil,
+                     usage:   self.class.default_usage(type),
                      **kwargs)
-        super(type: type, usage: usage, **kwargs)
+        super(usage: usage, **kwargs)
+
+        @type    = type
+        @default = default
       end
 
       #
       # Returns the default option value usage for the given type.
       #
       # @param [Class, Hash, Array, Regexp] type
+      #   The option value type.
       #
       # @return [String, nil]
+      #   A default usage string based on the option value type.
       #
       # @raise [TypeError]
       #   The given type was not a Class, Hash, Array, or Regexp.
@@ -85,6 +111,17 @@ module CommandKit
         string
       end
 
+      #
+      # Returns a new default value.
+      #
+      # @return [Object]
+      #
+      def default_value
+        if @default.respond_to?(:call) then @default.call
+        else                                @default.dup
+        end
+      end
+
     end
   end
 end

data/lib/command_kit/pager.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'command_kit/stdio'
+require 'command_kit/console'
 require 'command_kit/env'
 require 'command_kit/env/path'
 
@@ -16,6 +17,7 @@ module CommandKit
   #
   #       def run
   #         pager do |io|
+  #           io.puts "This goes into the pager screen"
   #         end
   #       end
   #
@@ -34,6 +36,7 @@ module CommandKit
   #
   module Pager
     include Stdio
+    include Console
     include Env
     include Env::Path
 
@@ -43,6 +46,9 @@ module CommandKit
     #
     # Initializes the pager.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Keyword arguments.
+    #
     # @note
     #   Respects the `PAGER` env variable, or attemps to find `less` or
     #   `more` by searching the `PATH` env variable.

data/lib/command_kit/version.rb

@@ -1,4 +1,4 @@
 module CommandKit
   # command_kit version
-  VERSION = "0.1.0.pre1"
+  VERSION = "0.1.0.pre2"
 end

data/lib/command_kit/xdg.rb

@@ -45,6 +45,9 @@ module CommandKit
 
     extend ModuleMethods
 
+    #
+    # Class-level methods.
+    #
     module ClassMethods
       #
       # Gets or sets the XDG sub-directory name used by the command.
@@ -62,7 +65,11 @@ module CommandKit
         if new_namespace
           @xdg_namespace = new_namespace.to_s
         else
-          @xdg_namespace || (superclass.xdg_namespace if superclass.kind_of?(ClassMethods)) || command_name
+          @xdg_namespace || if superclass.kind_of?(ClassMethods)
+                              superclass.xdg_namespace
+                            else
+                              command_name
+                            end
         end
       end
     end

data/spec/arguments/argument_spec.rb

@@ -3,39 +3,19 @@ require 'command_kit/arguments/argument'
 
 describe Arguments::Argument do
   let(:name)     { :foo }
-  let(:type)     { String }
   let(:usage)    { 'FOO' }
-  let(:default)  { 'foo' }
   let(:required) { true }
   let(:repeats)  { false }
   let(:desc)     { 'Foo argument' }
 
   subject do
-    described_class.new name, type:     type,
-                              usage:    usage,
-                              default:  default,
+    described_class.new name, usage:    usage,
                               required: required,
                               repeats:  repeats,
                               desc:     desc
   end
 
   describe "#initialize" do
-    context "when the type: keyword is given" do
-      subject { described_class.new(name, type: type, desc: desc) }
-
-      it "must set #type" do
-        expect(subject.type).to eq(type)
-      end
-    end
-
-    context "when the type: keyword is not given" do
-      subject { described_class.new(name, desc: desc) }
-
-      it "default #type to String" do
-        expect(subject.type).to eq(String)
-      end
-    end
-
     context "when the usage: keyword is given" do
       subject { described_class.new(name, usage: usage, desc: desc) }
 
@@ -52,22 +32,6 @@ describe Arguments::Argument do
       end
     end
 
-    context "when the default: keyword is given" do
-      subject { described_class.new(name, default: default, desc: desc) }
-
-      it "must set #default" do
-        expect(subject.default).to eq(default)
-      end
-    end
-
-    context "when the default: keyword is not given" do
-      subject { described_class.new(name, desc: desc) }
-
-      it "default #default to String" do
-        expect(subject.default).to eq(nil)
-      end
-    end
-
     context "when the required: keyword is given" do
       subject { described_class.new(name, required: required, desc: desc) }
 
@@ -88,7 +52,7 @@ describe Arguments::Argument do
       subject { described_class.new(name, repeats: repeats, desc: desc) }
 
       it "must set #repeats" do
-        expect(subject.repeats).to eq(repeats)
+        expect(subject.repeats?).to eq(repeats)
       end
     end
 
@@ -96,7 +60,7 @@ describe Arguments::Argument do
       subject { described_class.new(name, desc: desc) }
 
       it "default #repeats to String" do
-        expect(subject.repeats).to eq(false)
+        expect(subject.repeats?).to eq(false)
       end
     end
 

data/spec/arguments/argument_value_spec.rb

@@ -2,16 +2,12 @@ require 'spec_helper'
 require 'command_kit/arguments/argument_value'
 
 describe CommandKit::Arguments::ArgumentValue do
-  let(:type)     { String }
   let(:required) { false  }
-  let(:default)  { "foo"  }
   let(:usage)    { 'FOO'  }
 
   subject do
     described_class.new(
-      type:     type,
       required: required,
-      default:  default,
       usage:    usage
     )
   end
@@ -19,26 +15,10 @@ describe CommandKit::Arguments::ArgumentValue do
   describe "#initialize" do
     it "must require a usage: keyword"do
       expect {
-        described_class.new(type: type, required: required, default: default)
+        described_class.new(required: required)
       }.to raise_error(ArgumentError)
     end
 
-    context "when type: is given" do
-      subject { described_class.new(type: type, usage: usage) }
-
-      it "must set #type" do
-        expect(subject.type).to eq(type)
-      end
-    end
-
-    context "when type: is not given" do
-      subject { described_class.new(usage: usage) }
-
-      it "must default to nil" do
-        expect(subject.type).to be_nil
-      end
-    end
-
     context "when required: is given" do
       subject { described_class.new(required: required, usage: usage) }
 
@@ -54,22 +34,6 @@ describe CommandKit::Arguments::ArgumentValue do
         expect(subject.required).to be(true)
       end
     end
-
-    context "when default: is given" do
-      subject { described_class.new(default: default, usage: usage) }
-
-      it "must set #default" do
-        expect(subject.default).to eq(default)
-      end
-    end
-
-    context "when default: is not given" do
-      subject { described_class.new(usage: usage) }
-
-      it "must default to nil" do
-        expect(subject.default).to be_nil
-      end
-    end
   end
 
   describe "#required?" do
@@ -99,28 +63,4 @@ describe CommandKit::Arguments::ArgumentValue do
       it { expect(subject.optional?).to be(true) }
     end
   end
-
-  describe "#default_value" do
-    context "when initialized with a default: that responded to #call" do
-      let(:default) do
-        ->{ [] }
-      end
-
-      it "must call the default #call method" do
-        expect(subject.default_value).to eq(default.call)
-      end
-    end
-
-    context "when initialized with a default: that it's an Object" do
-      let(:default) { "" }
-
-      it "must return the default: object" do
-        expect(subject.default_value).to eq(default)
-      end
-
-      it "must duplicate the default: object each time" do
-        expect(subject.default_value).to_not be(subject.default_value)
-      end
-    end
-  end
 end