command_kit 0.1.0.pre2 → 0.2.1

data/lib/command_kit/terminal.rb

@@ -0,0 +1,159 @@
+require 'command_kit/stdio'
+require 'command_kit/env'
+
+begin
+  require 'io/console'
+rescue LoadError
+end
+
+module CommandKit
+  #
+  # Provides direct access to the terminal.
+  #
+  # ## Environment Variables
+  #
+  # * `LINES` - The explicit number of lines or rows the console should have.
+  # * `COLUMNS` - The explicit number of columns the console should have.
+  #
+  # @see https://rubydoc.info/gems/io-console/IO
+  #
+  module Terminal
+    include Stdio
+    include Env
+
+    # The default terminal height to fallback to.
+    DEFAULT_TERMINAL_HEIGHT = 25
+
+    # The default terminal width to fallback to.
+    DEFAULT_TERMINAL_WIDTH = 80
+
+    #
+    # Initializes any terminal settings.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @note
+    #   If the `$LINES` env variable is set, and is non-zero, it will be
+    #   returned by {#terminal_height}.
+    #
+    # @note
+    #   If the `$COLUMNS` env variable is set, and is non-zero, it will be
+    #   returned by {#terminal_width}.
+    #
+    # @api public
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @terminal_height = if (lines = env['LINES'])
+                           lines.to_i
+                         else
+                           DEFAULT_TERMINAL_HEIGHT
+                         end
+
+      @terminal_width  = if (columns = env['COLUMNS'])
+                           columns.to_i
+                         else
+                           DEFAULT_TERMINAL_WIDTH
+                         end
+    end
+
+    #
+    # Determines if program is running in a terminal.
+    #
+    # @return [Boolean]
+    #   Specifies whether {Stdio#stdout stdout} is connected to a terminal.
+    #
+    # @api public
+    #
+    def terminal?
+      IO.respond_to?(:console) && stdout.tty?
+    end
+
+    #
+    # @since 0.2.0
+    #
+    alias tty? terminal?
+
+    #
+    # Returns the terminal object, if {Stdio#stdout stdout} is connected to a
+    # terminal.
+    #
+    # @return [IO, nil]
+    #   The IO objects or `nil` if {Stdio#stdout stdout} is not connected to a
+    #   terminal.
+    #
+    # @example
+    #   terminal
+    #   # => #<File:/dev/tty>
+    #
+    # @see https://rubydoc.info/gems/io-console/IO
+    #
+    # @api semipublic
+    #
+    def terminal
+      IO.console if terminal?
+    end
+
+    #
+    # Returns the terminal's height in number of lines.
+    #
+    # @return [Integer]
+    #   The terminal's height in number of lines.
+    #
+    # @example
+    #   terminal_height
+    #   # => 22
+    #
+    # @api public
+    #
+    def terminal_height
+      if (terminal = self.terminal)
+        terminal.winsize[0]
+      else
+        @terminal_height
+      end
+    end
+
+    #
+    # Returns the terminal's width in number of lines.
+    #
+    # @return [Integer]
+    #   The terminal's width in number of columns.
+    #
+    # @example
+    #   terminal_width
+    #   # => 91
+    #
+    # @api public
+    #
+    def terminal_width
+      if (terminal = self.terminal)
+        terminal.winsize[1]
+      else
+        @terminal_width
+      end
+    end
+
+    #
+    # The terminal height (lines) and width (columns).
+    #
+    # @return [(Integer, Integer)]
+    #   Returns the height and width of the terminal.
+    #
+    # @example
+    #   terminal_size
+    #   # => [23, 91]
+    #
+    # @api public
+    #
+    def terminal_size
+      if (terminal = self.terminal)
+        terminal.winsize
+      else
+        [@terminal_height, @terminal_width]
+      end
+    end
+  end
+end

data/lib/command_kit/usage.rb

@@ -15,6 +15,9 @@ module CommandKit
     include CommandName
     include Help
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Usage}
@@ -50,6 +53,11 @@ module CommandKit
       # @return [String, Array<String>]
       #   The class'es or superclass'es usage string(s).
       #
+      # @example
+      #   usage "[options] ARG1 ARG2 [ARG3 ...]"
+      #
+      # @api public
+      #
       def usage(new_usage=nil)
         if new_usage
           @usage = new_usage
@@ -65,6 +73,8 @@ module CommandKit
     #
     # @return [Array<String>, String, nil]
     #
+    # @api public
+    #
     def usage
       case (usage = self.class.usage)
       when Array
@@ -77,6 +87,8 @@ module CommandKit
     #
     # Prints the `usage: ...` output.
     #
+    # @api semipublic
+    #
     def help_usage
       case (usage = self.usage)
       when Array
@@ -95,6 +107,8 @@ module CommandKit
     #
     # @see #help_usage
     #
+    # @api public
+    #
     def help
       help_usage
     end

data/lib/command_kit/version.rb

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

data/lib/command_kit/xdg.rb

@@ -24,6 +24,9 @@ module CommandKit
     include CommandName
     include Env::Home
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {XDG} is
@@ -61,6 +64,8 @@ module CommandKit
       #   {CommandName::ClassMethods#command_name} if no {#xdg_namespace} has
       #   been defined.
       #
+      # @api public
+      #
       def xdg_namespace(new_namespace=nil)
         if new_namespace
           @xdg_namespace = new_namespace.to_s
@@ -77,16 +82,22 @@ module CommandKit
     # The `~/.config/<xdg_namespace>` directory.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :config_dir
 
     # The `~/.local/share/<xdg_namespace>` directory.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :local_share_dir
 
     # The `~/.cache/<xdg_namespace>` directory.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :cache_dir
 
     #
@@ -138,6 +149,8 @@ module CommandKit
     #
     # @see ClassMethods#xdg_namespace
     #
+    # @api semipublic
+    #
     def xdg_namespace
       self.class.xdg_namespace
     end

data/lib/command_kit.rb

@@ -1 +1,2 @@
+require 'command_kit/command'
 require 'command_kit/version'

data/spec/arguments/argument_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 require 'command_kit/arguments/argument'
 
-describe Arguments::Argument do
+describe CommandKit::Arguments::Argument do
   let(:name)     { :foo }
   let(:usage)    { 'FOO' }
   let(:required) { true }
@@ -126,7 +126,7 @@ describe Arguments::Argument do
       let(:repeats) { false }
 
       it "must return the usage name unchanged" do
-        expect(subject.usage).to eq("#{usage}")
+        expect(subject.usage).to eq(usage)
       end
     end
   end

data/spec/arguments_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 require 'command_kit/arguments'
 
-describe Arguments do
+describe CommandKit::Arguments do
   module TestArguments
     class ImplicitCmd
       include CommandKit::Arguments
@@ -13,8 +13,8 @@ describe Arguments do
   describe ".included" do
     subject { command_class }
 
-    it { expect(subject).to include(Main) }
-    it { expect(subject).to include(Help) }
+    it { expect(subject).to include(CommandKit::Main) }
+    it { expect(subject).to include(CommandKit::Help) }
   end
 
   describe ".arguments" do
@@ -137,6 +137,56 @@ describe Arguments do
 
   subject { command_class.new }
 
+  describe "#main" do
+    module TestArguments
+      class TestCommand
+
+        include CommandKit::Arguments
+
+        argument :argument1, required: true,
+                             usage:    'ARG1',
+                             desc:     "Argument 1"
+
+        argument :argument2, required: false,
+                             usage:    'ARG2',
+                             desc:     "Argument 2"
+
+      end
+    end
+
+    let(:command_class) { TestArguments::TestCommand }
+
+    context "when given the correct number of arguments" do
+      let(:argv) { %w[arg1 arg2] }
+
+      it "must parse options before validating the number of arguments" do
+        expect {
+          expect(subject.main(argv)).to eq(0)
+        }.to_not output.to_stderr
+      end
+    end
+
+    context "when given fewer than the required number of arguments" do
+      let(:argv) { %w[] }
+
+      it "must print an error message and return 1" do
+        expect {
+          expect(subject.main(argv)).to eq(1)
+        }.to output("#{subject.command_name}: insufficient number of arguments.#{$/}").to_stderr
+      end
+    end
+
+    context "when given more than the total number of arguments" do
+      let(:argv) { %w[foo bar baz] }
+
+      it "must print an error message and return 1" do
+        expect {
+          expect(subject.main(argv)).to eq(1)
+        }.to output("#{subject.command_name}: too many arguments given.#{$/}").to_stderr
+      end
+    end
+  end
+
   describe "#help_arguments" do
     context "when #arguments returns {}" do
       module TestArguments
@@ -192,29 +242,5 @@ describe Arguments do
 
       subject.help
     end
-
-    context "when the superclass defines it's own #help method" do
-      module TestDescription
-        class SuperclassHelpMethod
-          def help
-            puts 'superclass'
-          end
-        end
-
-        class InheritedHelpMethod < SuperclassHelpMethod
-          include CommandKit::Arguments
-        end
-      end
-
-      let(:super_command_class) { TestDescription::SuperclassHelpMethod }
-      let(:command_class) { TestDescription::InheritedHelpMethod }
-
-      it "must call the superclass'es #help method first" do
-        expect_any_instance_of(super_command_class).to receive(:help)
-        expect(subject).to receive(:help_arguments)
-
-        subject.help
-      end
-    end
   end
 end