command_kit 0.1.0.pre1

data/lib/command_kit/program_name.rb

@@ -0,0 +1,57 @@
+module CommandKit
+  #
+  # Retrieves the current program name (`$PROGRAM_NAME`).
+  #
+  module ProgramName
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {ProgramName} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {ProgramName}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Class-level methods.
+    #
+    module ClassMethods
+      # List of `$PROGRAM_NAME`s that should be ignored.
+      IGNORED_PROGRAM_NAMES = [
+        '-e',   # ruby -e "..."
+        'irb',  # running in irb
+        'rspec' # running in rspec
+      ]
+
+      #
+      # The current program name (`$PROGRAM_NAME`).
+      #
+      # @return [String, nil]
+      #   The `$PROGRAM_NAME` or `nil` if the `$PROGRAM_NAME` is `-e`, `irb`,
+      #   or `rspec`.
+      #
+      def program_name
+        $PROGRAM_NAME unless IGNORED_PROGRAM_NAMES.include?($PROGRAM_NAME)
+      end
+    end
+
+    #
+    # @see ClassMethods#program_name
+    #
+    def program_name
+      self.class.program_name
+    end
+  end
+end

data/lib/command_kit/stdio.rb

@@ -0,0 +1,138 @@
+module CommandKit
+  #
+  # Provides access to stdin, stdout, and stderr streams.
+  #
+  # ## Examples
+  #
+  #     class MyCmd
+  #       include CommandKit::Stdio
+  #
+  #       def main
+  #       end
+  #     end
+  #
+  # ## Testing
+  #
+  # Can be initialized with custom stdin, stdout, and stderr streams for testing
+  # purposes.
+  #
+  #     stdin  = StringIO.new
+  #     stdout = StringIO.new
+  #     stderr = StringIO.new
+  #     MyCmd.new(stdin: stdin, stdout: stdout, stderr: stderr)
+  #
+  module Stdio
+    #
+    # Initializes {#stdin}, {#stdout}, and {#stderr}.
+    #
+    # @param [IO] stdin
+    #   The stdin input stream. Defaults to `$stdin`.
+    #
+    # @param [IO] stdout
+    #   The stdout output stream. Defaults to `$stdout`.
+    #
+    # @param [IO] stderr
+    #   The stderr error output stream. Defaults to `$stderr`.
+    #
+    def initialize(stdin: nil, stdout: nil, stderr: nil, **kwargs)
+      @stdin  = stdin
+      @stdout = stdout
+      @stderr = stderr
+
+      super(**kwargs)
+    end
+
+    #
+    # Returns the stdin input stream.
+    #
+    # @return [$stdin, IO]
+    #   The initialized `@stdin` value or `$stdin`.
+    #
+    def stdin
+      @stdin || $stdin
+    end
+
+    #
+    # Returns the stdout output stream.
+    #
+    # @return [$stdout, IO]
+    #   The initialized `@stdout` value or `$stdout`.
+    #
+    def stdout
+      @stdout || $stdout
+    end
+
+    #
+    # Returns the stderr error output stream.
+    #
+    # @return [$stderr, IO]
+    #   The initialized `@stderr` value or `$stderr`.
+    #
+    def stderr
+      @stderr || $stderr
+    end
+
+    #
+    # Calls `stdin.gets`.
+    #
+    def gets(*arguments)
+      stdin.gets(*arguments)
+    end
+
+    #
+    # Calls `stdin.readline`.
+    #
+    def readline(*arguments)
+      stdin.readline(*arguments)
+    end
+
+    #
+    # Calls `stdin.readlines`.
+    #
+    def readlines(*arguments)
+      stdin.readlines(*arguments)
+    end
+
+    # NOTE: intentionally do not override `Kenrel#p` or `Kernel#pp` to not
+    # hijack echo-debugging.
+
+    #
+    # Calls `stdout.putc`.
+    #
+    def putc(*arguments)
+      stdout.putc(*arguments)
+    end
+
+    #
+    # Calls `stdout.puts`.
+    #
+    def puts(*arguments)
+      stdout.puts(*arguments)
+    end
+
+    #
+    # Calls `stdout.print`.
+    #
+    def print(*arguments)
+      stdout.print(*arguments)
+    end
+
+    #
+    # Calls `stdout.printf`.
+    #
+    def printf(*arguments)
+      stdout.printf(*arguments)
+    end
+
+    #
+    # Overrides `Kernel.abort` to print to {#stderr}.
+    #
+    # @param [String, nil] message
+    #   The optional abort message.
+    #
+    def abort(message=nil)
+      stderr.puts(message) if message
+      exit(1)
+    end
+  end
+end

data/lib/command_kit/usage.rb

@@ -0,0 +1,102 @@
+require 'command_kit/command_name'
+require 'command_kit/help'
+
+module CommandKit
+  #
+  # Defines the usage string for a command class.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Usage
+  #
+  #     usage "[options] ARG1 ARG2 [ARG3 ...]"
+  #
+  module Usage
+    include CommandName
+    include Help
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Usage}
+      # is being included into a class or module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Usage}.
+      #
+      def included(context)
+        super
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Class-level methods.
+    #
+    module ClassMethods
+      #
+      # Gets or sets the class'es usage string(s).
+      #
+      # @param [String, Array<String>, nil] new_usage
+      #   If a new_usage argument is given, it will set the class'es usage
+      #   string(s).
+      #
+      # @return [String, Array<String>]
+      #   The class'es or superclass'es usage string(s).
+      #
+      def usage(new_usage=nil)
+        if new_usage
+          @usage = new_usage
+        else
+          @usage || (superclass.usage if superclass.kind_of?(ClassMethods))
+        end
+      end
+    end
+
+    #
+    # Similar to {ClassMethods#usage .usage}, but prepends
+    # {CommandName#command_name command_name}.
+    #
+    # @return [Array<String>, String, nil]
+    #
+    def usage
+      case (usage = self.class.usage)
+      when Array
+        usage.map { |command| "#{command_name} #{command}" }
+      when String
+        "#{command_name} #{usage}"
+      end
+    end
+
+    #
+    # Prints the `usage: ...` output.
+    #
+    def help_usage
+      case (usage = self.usage)
+      when Array
+        puts "usage: #{usage[0]}"
+
+        usage[1..].each do |command|
+          puts "       #{command}"
+        end
+      when String
+        puts "usage: #{usage}"
+      end
+    end
+
+    #
+    # Prints the usage.
+    #
+    # @see #help_usage
+    #
+    def help
+      help_usage
+    end
+  end
+end

data/lib/command_kit/version.rb

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

data/lib/command_kit/xdg.rb

@@ -0,0 +1,138 @@
+require 'command_kit/command_name'
+require 'command_kit/env/home'
+
+module CommandKit
+  #
+  # Provides access to [XDG directories].
+  #
+  # * `~/.config`
+  # * `~/.local/share`
+  # * `~/.cache`
+  #
+  # ## Environment Variables
+  #
+  # * `XDG_CONFIG_HOME` - The directory that should contain user-specific
+  #   configuration. Defaults to `~/.config/`.
+  # * `XDG_DATA_HOME` - The directory that should contain user-specific data.
+  #   Defaults to `~/.local/share/`.
+  # * `XDG_CACHE_HOME` - The directory that should contain user-specific cache
+  #   data. Defaults to `~/.cache/`.
+  #
+  # [XDG directories]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+  #
+  module XDG
+    include CommandName
+    include Env::Home
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether {XDG} is
+      # being included into a class or a module..
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {XDG}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    module ClassMethods
+      #
+      # Gets or sets the XDG sub-directory name used by the command.
+      #
+      # @param [#to_s, nil] new_namespace
+      #   If a new_namespace argument is given, it will set the class'es
+      #   {#xdg_namespace} string.
+      #
+      # @return [String]
+      #   The class'es or superclass'es {#xdg_namespace}. Defaults to
+      #   {CommandName::ClassMethods#command_name} if no {#xdg_namespace} has
+      #   been defined.
+      #
+      def xdg_namespace(new_namespace=nil)
+        if new_namespace
+          @xdg_namespace = new_namespace.to_s
+        else
+          @xdg_namespace || (superclass.xdg_namespace if superclass.kind_of?(ClassMethods)) || command_name
+        end
+      end
+    end
+
+    # The `~/.config/<xdg_namespace>` directory.
+    #
+    # @return [String]
+    attr_reader :config_dir
+
+    # The `~/.local/share/<xdg_namespace>` directory.
+    #
+    # @return [String]
+    attr_reader :local_share_dir
+
+    # The `~/.cache/<xdg_namespace>` directory.
+    #
+    # @return [String]
+    attr_reader :cache_dir
+
+    #
+    # Initializes {#config_dir}, {#local_share_dir}, and {#cache_dir}.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @note
+    #   If the `$XDG_CONFIG_HOME` env variable is set, then {#config_dir} will
+    #   be initialized to effectively `$XDG_CONFIG_HOME/<xdg_namespace>`.
+    #   Otherwise {#config_dir} will be initialized to
+    #   `~/.config/<xdg_namespace>`.
+    #
+    # @note
+    #   If the `$XDG_DATA_HOME` env variable is set, then {#local_share_dir}
+    #   will be initialized to effectively `$XDG_DATA_HOME/<xdg_namespace>`.
+    #   Otherwise {#local_share_dir} will be initialized to
+    #   `~/.local/share/<xdg_namespace>`.
+    #
+    # @note
+    #   If the `$XDG_CACHE_HOME` env variable is set, then {#cache_dir} will
+    #   be initialized to effectively `$XDG_CACHE_HOME/<xdg_namespace>`.
+    #   Otherwise {#cache_dir} will be initialized to
+    #   `~/.cache/<xdg_namespace>`.
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      xdg_config_home = env.fetch('XDG_CONFIG_HOME') do
+        File.join(home_dir,'.config')
+      end
+
+      @config_dir = File.join(xdg_config_home,xdg_namespace)
+
+      xdg_data_home = env.fetch('XDG_DATA_HOME') do
+        File.join(home_dir,'.local','share')
+      end
+
+      @local_share_dir = File.join(xdg_data_home,xdg_namespace)
+
+      xdg_cache_home = env.fetch('XDG_CACHE_HOME') do
+        File.join(home_dir,'.cache')
+      end
+
+      @cache_dir = File.join(xdg_cache_home,xdg_namespace)
+    end
+
+    #
+    # @see ClassMethods#xdg_namespace
+    #
+    def xdg_namespace
+      self.class.xdg_namespace
+    end
+  end
+end

data/spec/arguments/argument_spec.rb

@@ -0,0 +1,169 @@
+require 'spec_helper'
+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,
+                              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) }
+
+      it "must include usage: in #usage" do
+        expect(subject.usage).to include(usage)
+      end
+    end
+
+    context "when the usage: keyword is not given" do
+      subject { described_class.new(name, desc: desc) }
+
+      it "should use uppercased argument name in #usage" do
+        expect(subject.usage).to include(name.to_s.upcase)
+      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) }
+
+      it "must set #required" do
+        expect(subject.required).to eq(required)
+      end
+    end
+
+    context "when the required: keyword is not given" do
+      subject { described_class.new(name, desc: desc) }
+
+      it "default #required to String" do
+        expect(subject.required).to eq(true)
+      end
+    end
+
+    context "when the repeats: keyword is given" do
+      subject { described_class.new(name, repeats: repeats, desc: desc) }
+
+      it "must set #repeats" do
+        expect(subject.repeats).to eq(repeats)
+      end
+    end
+
+    context "when the repeats: keyword is not given" do
+      subject { described_class.new(name, desc: desc) }
+
+      it "default #repeats to String" do
+        expect(subject.repeats).to eq(false)
+      end
+    end
+
+    context "when the desc: keyword is given" do
+      subject { described_class.new(name, desc: desc) }
+
+      it "must set #desc" do
+        expect(subject.desc).to eq(desc)
+      end
+    end
+
+    context "when the desc: keyword is not given" do
+      it do
+        expect {
+          described_class.new(name)
+        }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe "#repeats?" do
+    context "when initialized with repeats: true" do
+      let(:repeats) { true }
+
+      it { expect(subject.repeats?).to be(true) }
+    end
+
+    context "when initialized with repeats: false" do
+      let(:repeats) { false }
+
+      it { expect(subject.repeats?).to be(false) }
+    end
+  end
+
+  describe "#usage" do
+    let(:usage) { 'FOO' }
+
+    context "initialized with required: true" do
+      let(:required) { true }
+
+      it "must return the usage unchanged" do
+        expect(subject.usage).to eq(usage)
+      end
+    end
+
+    context "initialized with required: false" do
+      let(:required) { false }
+
+      it "must wrap the usage in [ ] brackets" do
+        expect(subject.usage).to eq("[#{usage}]")
+      end
+    end
+
+    context "initialized with repeats: true" do
+      let(:repeats) { true }
+
+      it "must append the ... ellipses" do
+        expect(subject.usage).to eq("#{usage} ...")
+      end
+    end
+
+    context "initialized with repeats: false" do
+      let(:repeats) { false }
+
+      it "must return the usage name unchanged" do
+        expect(subject.usage).to eq("#{usage}")
+      end
+    end
+  end
+end