command_kit 0.1.0.pre1

data/lib/command_kit/options/quiet.rb

@@ -0,0 +1,53 @@
+require 'command_kit/options'
+
+module CommandKit
+  module Options
+    #
+    # Defines a `-q`,`--quiet` option.
+    #
+    # ## Examples
+    #
+    #     include CommandKit::Options::Quiet
+    #     
+    #     def main(*argv)
+    #       # ...
+    #       puts "verbose output" unless quiet?
+    #       # ...
+    #     end
+    #
+    module Quiet
+      include Options
+
+      module ModuleMethods
+        #
+        # Defines a `-q, --quiet` option.
+        #
+        # @param [Class, Module] context
+        #   The class or module including {Quiet}.
+        #
+        def included(context)
+          super(context)
+
+          if context.class == Module
+            context.extend ModuleMethods
+          else
+            context.option :quiet, short: '-q', desc: 'Enables quiet output' do
+              @quiet = true
+            end
+          end
+        end
+      end
+
+      extend ModuleMethods
+
+      #
+      # Determines if quiet mode is enabled.
+      #
+      # @return [Boolean]
+      #
+      def quiet?
+        @quiet
+      end
+    end
+  end
+end

data/lib/command_kit/options/usage.rb

@@ -0,0 +1,6 @@
+module CommandKit
+  module Options
+    module Usage
+    end
+  end
+end

data/lib/command_kit/options/verbose.rb

@@ -0,0 +1,55 @@
+require 'command_kit/options'
+
+module CommandKit
+  module Options
+    #
+    # Defines a `-v`,`--verbose` option.
+    #
+    # ## Examples
+    #
+    #     include Options::Verbose
+    #
+    #     def main(*argv)
+    #       # ...
+    #       puts "verbose output" if verbose?
+    #       # ...
+    #     end
+    #
+    module Verbose
+      include Options
+
+      module ModuleMethods
+        #
+        # Defines a `-v, --verbose` option or extends {ModuleMethods}, depending
+        # on whether {Options::Verbose} is being included into a class or a
+        # module.
+        #
+        # @param [Class, Module] context
+        #   The class or module including {Verbose}.
+        #
+        def included(context)
+          super(context)
+
+          if context.class == Module
+            context.extend ModuleMethods
+          else
+            context.option :verbose, short: '-v', desc: 'Enables verbose output' do
+              @verbose = true
+            end
+          end
+        end
+      end
+
+      extend ModuleMethods
+
+      #
+      # Determines if verbose mode is enabled.
+      #
+      # @return [Boolean]
+      #
+      def verbose?
+        @verbose
+      end
+    end
+  end
+end

data/lib/command_kit/options/version.rb

@@ -0,0 +1,62 @@
+require 'command_kit/options'
+
+module CommandKit
+  module Options
+    #
+    # Defines a version option.
+    #
+    module Version
+      #
+      # Includes {Options}, extends {Version::ClassMethods}, and defines a
+      # `-V, --version` option.
+      #
+      def self.included(command)
+        command.include Options
+        command.extend ClassMethods
+
+        command.option :version, short: '-V',
+                                 desc: 'Prints the version and exits' do
+          print_version
+          exit(0)
+        end
+      end
+
+      #
+      # Defines class-level methods.
+      #
+      module ClassMethods
+        #
+        # Gets or sets the version string.
+        #
+        # @param [String, nil] new_version
+        #   If given a new version String, it will set the class'es version
+        #   string.
+        #
+        # @return [String, nil]
+        #   The classes version string.
+        #
+        def version(new_version=nil)
+          if new_version
+            @version = new_version
+          else
+            @version || (superclass.version if superclass.kind_of?(ClassMethods))
+          end
+        end
+      end
+
+      #
+      # @see ClassMethods#version
+      #
+      def version
+        self.class.version
+      end
+
+      #
+      # Prints the version.
+      #
+      def print_version
+        puts "#{command_name} #{version}"
+      end
+    end
+  end
+end

data/lib/command_kit/os.rb

@@ -0,0 +1,47 @@
+module CommandKit
+  #
+  # Provides methods for determining the current OS.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::OS
+  #     
+  #     def main(*argv)
+  #       if linux?
+  #         # ...
+  #       elsif macos?
+  #         # ...
+  #       elsif windows?
+  #         # ...
+  #       end
+  #     end
+  #
+  module OS
+    #
+    # Determines if the current OS is Linux.
+    #
+    # @return [Boolean]
+    #
+    def linux?
+      RUBY_PLATFORM.include?('linux')
+    end
+
+    #
+    # Determines if the current OS is macOS.
+    #
+    # @return [Boolean]
+    #
+    def macos?
+      RUBY_PLATFORM.include?('darwin')
+    end
+
+    #
+    # Determines if the current OS is Windows.
+    #
+    # @return [Boolean]
+    #
+    def windows?
+      Gem.win_platform?
+    end
+  end
+end

data/lib/command_kit/pager.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'command_kit/stdio'
+require 'command_kit/env'
+require 'command_kit/env/path'
+
+module CommandKit
+  #
+  # Allows opening a pager, such as `less` or `more`.
+  #
+  # ## Examples
+  #
+  #     class CLI < CommandKit::Command
+  #
+  #       include CommandKit::Pager
+  #
+  #       def run
+  #         pager do |io|
+  #         end
+  #       end
+  #
+  #     end
+  #
+  # ## Environment Variables
+  #
+  # * `PAGER` - The optional command to override the default pager (usually
+  #   `less -r` or `more -r`).
+  # * `PATH` - The list of directories to search for the default pager program
+  #   (either `less` or `more`).
+  #
+  # ## Alternatives
+  #
+  # * [tty-pager](https://github.com/piotrmurach/tty-pager#readme)
+  #
+  module Pager
+    include Stdio
+    include Env
+    include Env::Path
+
+    # Common pager commands.
+    PAGERS = ['less -r', 'more -r']
+
+    #
+    # Initializes the pager.
+    #
+    # @note
+    #   Respects the `PAGER` env variable, or attemps to find `less` or
+    #   `more` by searching the `PATH` env variable.
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @pager = env.fetch('PAGER') do
+        PAGERS.find do |command|
+          bin = command.split(' ',2).first
+
+          command_installed?(bin)
+        end
+      end
+    end
+
+    #
+    # Opens a pager pipe.
+    #
+    # @yield [io]
+    #   The given block will be passed the IO pipe to the pager.
+    #
+    # @yieldparam [IO]
+    #   The IO pipe to the pager.
+    #
+    def pager
+      if !stdout.tty? || @pager.nil?
+        # fallback to stdout if the process does not have a console or we could
+        # not find a suitable pager command.
+        yield stdout
+        return
+      end
+
+      io  = IO.popen(@pager,'w')
+      pid = io.pid
+
+      begin
+        yield io
+      rescue Errno::EPIPE
+      ensure
+        io.close
+
+        begin
+          Process.waitpid(pid)
+        rescue Errno::EPIPE, Errno::ECHILD
+        end
+      end
+    end
+
+    #
+    # Pages the data if it's longer the console's height, otherwise prints the
+    # data to {Stdio#stdout stdout}.
+    #
+    # @param [Array<String>, #to_s] data
+    #   The data to print.
+    #
+    def print_or_page(data)
+      line_count = case data
+                   when Array  then data.length
+                   else             data.to_s.each_line.count
+                   end
+
+      if line_count > console_height
+        pager { |io| io.puts(data) }
+      else
+        stdout.puts(data)
+      end
+    end
+  end
+end

data/lib/command_kit/printing.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'command_kit/stdio'
+
+module CommandKit
+  #
+  # Provides printing methods.
+  #
+  module Printing
+    include Stdio
+
+    #
+    # Prints the error message to {Stdio#stderr stderr}.
+    #
+    # @param [String] message
+    #   The error message.
+    #
+    def print_error(message)
+      stderr.puts message
+    end
+
+    #
+    # Prints an exception to {Stdio#stderr stderr}.
+    #
+    # @param [Exception] error
+    #   The error to print.
+    #
+    def print_exception(error)
+      print_error error.full_message(highlight: stderr.tty?)
+    end
+  end
+end

data/lib/command_kit/printing/indent.rb

@@ -0,0 +1,78 @@
+module CommandKit
+  module Printing
+    #
+    # Adds the ability to automatically indent all calls to `puts`.
+    #
+    # ## Examples
+    #
+    #     include Printing::Indent
+    #     
+    #     def main
+    #       puts "regular output:"
+    #     
+    #       indent(4) do
+    #         puts "indented output"
+    #         puts "..."
+    #       end
+    #     
+    #       puts "back to regular output"
+    #     end
+    #
+    module Indent
+      #
+      # Initializes the indententation level to zero.
+      #
+      def initialize(**kwargs)
+        @indent = 0
+
+        super(**kwargs)
+      end
+
+      #
+      # Increases the indentation level by two, yields, then restores the
+      # indentation level.
+      #
+      # @param [Integer] n
+      #   How much to increase the indentation level by.
+      #
+      # @yield []
+      #   The given block will be called after the indentation level has been
+      #   increased.
+      #
+      # @return [Integer]
+      #   If no block is given, the indententation level will be returned.
+      #
+      def indent(n=2)
+        if block_given?
+          begin
+            original_indent = @indent
+            @indent += n
+
+            yield
+          ensure
+            @indent = original_indent
+          end
+        else
+          @indent
+        end
+      end
+
+      #
+      # Indents and prints the lines to stdout.
+      #
+      # @param [Array<String>] lines
+      #   The lines to indent and print.
+      #
+      def puts(*lines)
+        if (@indent > 0 && !lines.empty?)
+          padding = " " * @indent
+
+          super(*lines.map { |line| "#{padding}#{line}" })
+        else
+          super(*lines)
+        end
+      end
+
+    end
+  end
+end