command_kit 0.1.0.pre1

data/lib/command_kit/help/man.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module CommandKit
+  module Help
+    #
+    # Allows displaying a man-page instead of the usual `--help` output.
+    #
+    # ## Environment Variables
+    #
+    # * `TERM` - Specifies the type of terminal. When set to `DUMB`, it will
+    #   disable man-page help output.
+    #
+    module Man
+      module ModuleMethods
+        #
+        # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+        # {Help::Man} is being included into a class or a module.
+        #
+        # @param [Class, Module] context
+        #   The class or module including {Man}.
+        #
+        def included(context)
+          super(context)
+
+          if context.class == Module
+            context.extend ModuleMethods
+          else
+            context.extend ClassMethods
+          end
+        end
+      end
+
+      extend ModuleMethods
+
+      #
+      # Defines class-level methods.
+      #
+      module ClassMethods
+        #
+        # Gets or sets the directory where man-pages are stored.
+        #
+        # @param [String, nil] new_man_dir
+        #   If a String is given, it will set The class'es man-page directory.
+        #
+        # @return [String, nil]
+        #   The class'es or superclass'es man-page directory.
+        #
+        # @example
+        #   man_dir File.expand_path('../../../man',__FILE__)
+        #
+        def man_dir(new_man_dir=nil)
+          if new_man_dir
+            @man_dir = File.expand_path(new_man_dir)
+          else
+            @man_dir || (superclass.man_dir if superclass.kind_of?(ClassMethods))
+          end
+        end
+      end
+
+      #
+      # Determines if displaying man pages is supported.
+      #
+      # @return [Boolean]
+      #   Indicates whether the `TERM` environment variable is not `dumb`
+      #   and `$stdout` is a TTY.
+      #
+      def self.supported?
+        ENV['TERM'] != 'dumb' && $stdout.tty?
+      end
+
+      #
+      # Returns the man-page file name for the given command name.
+      #
+      # @param [String] command
+      #   The given command name.
+      #
+      # @return [String]
+      #   The man-page file name.
+      #
+      def man_page(command=command_name)
+        "#{command}.1"
+      end
+
+      #
+      # Displays the given man page.
+      #
+      # @param [String] page
+      #   The man page file name.
+      #
+      # @return [Boolean, nil]
+      #   Specifies whether the `man` command was successful or not.
+      #   Returns `nil` when the `man` command is not installed.
+      #
+      def man(page=man_page)
+        system('man',page)
+      end
+
+      #
+      # Displays the {#man_page} instead of the usual `--help` output.
+      #
+      # @raise [NotImplementedError]
+      #   {ClassMethods#man_dir man_dir} does not have a value.
+      #
+      # @note
+      #   if `TERM` is `dumb` or `$stdout` is not a TTY, fallsback to printing
+      #   the usual `--help` output.
+      #
+      def help
+        if Man.supported?
+          unless self.class.man_dir
+            raise(NotImplementedError,"#{self.class}.man_dir not set")
+          end
+
+          man_path = File.join(self.class.man_dir,man_page)
+
+          if man(man_path).nil?
+            super
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/command_kit/inflector.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module CommandKit
+  #
+  # A very simple inflector.
+  #
+  # @note
+  #   If you need something more powerful, checkout
+  #   [dry-inflector](https://dry-rb.org/gems/dry-inflector/0.1/)
+  #
+  module Inflector
+    #
+    # Removes the namespace from a constant name.
+    #
+    # @param [#to_s] name
+    #   The constant name.
+    #
+    # @return [String]
+    #   The class or module's name, without the namespace.
+    #
+    def self.demodularize(name)
+      name.to_s.split('::').last
+    end
+
+    #
+    # Converts a CamelCased name to an under_scored name.
+    #
+    # @param [#to_s] name
+    #   The CamelCased name.
+    #
+    # @return [String]
+    #   The resulting under_scored name.
+    #
+    def self.underscore(name)
+      # sourced from: https://github.com/dry-rb/dry-inflector/blob/c918f967ff82611da374eb0847a77b7e012d3fa8/lib/dry/inflector.rb#L286-L287
+      name = name.to_s.dup
+
+      name.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+      name.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      name.tr!('-','_')
+      name.downcase!
+
+      name
+    end
+
+    #
+    # Replaces all underscores with dashes.
+    #
+    # @param [#to_s] name
+    #   The under_scored name.
+    #
+    # @return [String]
+    #   The dasherized name.
+    #
+    def self.dasherize(name)
+      name.to_s.tr('_','-')
+    end
+
+    #
+    # Converts an under_scored name to a CamelCased name.
+    #
+    # @param [String] name
+    #   The under_scored name.
+    #
+    # @return [String]
+    #   The CamelCased name.
+    #
+    def self.camelize(name)
+      name = name.to_s.dup
+
+      # sourced from: https://github.com/dry-rb/dry-inflector/blob/c918f967ff82611da374eb0847a77b7e012d3fa8/lib/dry/inflector.rb#L329-L334
+      name.sub!(/^[a-z\d]*/,&:capitalize)
+      name.gsub!(%r{(?:[_-]|(/))([a-z\d]*)}i) do |match|
+        slash = Regexp.last_match(1)
+        word  = Regexp.last_match(2)
+
+        "#{slash}#{word.capitalize}"
+      end
+
+      name.gsub!('/','::')
+      name
+    end
+  end
+end

data/lib/command_kit/main.rb

@@ -0,0 +1,103 @@
+module CommandKit
+  #
+  # Defines a `main` method.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Main
+  #     
+  #     def main(argv=[])
+  #       # ...
+  #       return 0
+  #     end
+  #
+  module Main
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Main}
+      # is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Main}.
+      #
+      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
+      #
+      # Starts the command and then exits.
+      #
+      # @param [Array<String>] argv
+      #   The Array of command-line arguments.
+      #
+      def start(argv=ARGV, **kwargs)
+        begin
+          exit main(argv, **kwargs)
+        rescue Interrupt
+          # https://tldp.org/LDP/abs/html/exitcodes.html
+          exit 130
+        rescue Errno::EPIPE
+          # STDOUT pipe broken
+          exit 0
+        end
+      end
+
+      #
+      # Initializes the command class with the given keyword arguments, then
+      # calls {Main#main main} with the given `argv`.
+      #
+      # @param [Array<String>] argv
+      #   The Array of command-line arguments.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments to initialize the command class with.
+      #
+      # @return [Integer]
+      #   The exit status of the command.
+      #
+      def main(argv=[], **kwargs)
+        new(**kwargs).main(argv)
+      end
+    end
+
+    #
+    # Place-holder `main` method, which parses options, before calling {#run}.
+    #
+    # @param [Array<String>] argv
+    #   The Array of command-line arguments.
+    #
+    # @return [Integer]
+    #   The exit status code.
+    #
+    def main(argv=[])
+      run(*argv)
+      return 0
+    rescue SystemExit => system_exit
+      return system_exit.status
+    end
+
+    #
+    # Place-holder method for command business logic.
+    #
+    # @param [Array<Object>] args
+    #   Additional arguments for the command.
+    #   
+    # @abstract
+    #
+    def run(*args)
+    end
+  end
+end

data/lib/command_kit/options.rb

@@ -0,0 +1,179 @@
+require 'command_kit/options/option'
+require 'command_kit/options/parser'
+
+module CommandKit
+  #
+  # Provides a thin DSL for defining options as attributes.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Options
+  #     
+  #     option :foo, type: String,
+  #                  short: '-f',
+  #                  desc: "Foo option"
+  #     
+  #     option :bar, type: String,
+  #                  short: '-b',
+  #                  usage: 'STR:STR:...',
+  #                  desc: "Bar option" do |arg|
+  #       @bar = arg.split(':')
+  #     end
+  #     
+  #     option :number, type: Integer,
+  #                     desc: 'Numbers' do |num|
+  #       @numbers << num
+  #     end
+  #     
+  #     def initialize
+  #       super
+  #     
+  #       @numbers = []
+  #     end
+  #
+  module Options
+    include Parser
+
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Options} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Options}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Defines class-level methods.
+    #
+    module ClassMethods
+      #
+      # All defined options for the command class.
+      #
+      # @return [Hash{Symbol => Option}]
+      #
+      def options
+        @options ||= if superclass.kind_of?(ClassMethods)
+                       superclass.options.dup
+                     else
+                       {}
+                     end
+      end
+
+      #
+      # Defines an {Option option} for the class.
+      #
+      # @param [Symbol] name
+      #   The option name.
+      #
+      # @yield [(value)]
+      #   If a block is given, it will be passed the parsed option value.
+      #
+      # @yieldparam [Object, nil] value
+      #   The parsed option value.
+      #
+      # @return [Option]
+      #
+      # @example Define an option:
+      #     option :foo, desc: "Foo option"
+      #
+      # @example With a custom short option:
+      #     option :foo, short: '-f',
+      #                  desc: "Foo option"
+      #
+      # @example With a custom long option:
+      #     option :foo, short: '--foo-opt',
+      #                  desc: "Foo option"
+      #
+      # @example With a custom usage string:
+      #     option :foo, value: {usage: 'FOO'},
+      #                  desc: "Foo option"
+      #
+      # @example With a custom block:
+      #     option :foo, desc: "Foo option" do |value|
+      #       @foo = Foo.new(value)
+      #     end
+      #
+      # @example With a custom type:
+      #     option :foo, value: {type: Integer},
+      #                  desc: "Foo option"
+      #
+      # @example With a default value:
+      #     option :foo, value: {type: Integer, default: 1},
+      #                  desc: "Foo option"
+      #
+      # @example With a required value:
+      #     option :foo, value: {type: String, required: true},
+      #                  desc: "Foo option"
+      #
+      # @example With a custom option value Hash map:
+      #     option :flag, value: {
+      #                     type: {
+      #                       'enabled'  => :enabled,
+      #                       'yes'      => :enabled,
+      #                       'disabled' => :disabled,
+      #                       'no'       => :disabled
+      #                     }
+      #                   },
+      #                   desc: "Flag option"
+      #
+      # @example With a custom option value Array enum:
+      #     option :enum, value: {type: %w[yes no]},
+      #                   desc: "Enum option"
+      #
+      # @example With a custom option value Regexp:
+      #     option :date, value: {type: /(\d+)-(\d+)-(\d{2,4})/},
+      #                   desc: "Regexp optin" do |date,d,m,y|
+      #       # ...
+      #     end
+      #
+      def option(name,**kwargs,&block)
+        options[name] = Option.new(name,**kwargs,&block)
+      end
+    end
+
+    # Hash of parsed option values.
+    #
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+
+    #
+    # Initializes {#options} and populates the
+    # {Parser#option_parser option parser}.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Optional pre-populated options hash.
+    #
+    def initialize(options: {}, **kwargs)
+      @options = options
+
+      super(**kwargs)
+
+      self.class.options.each_value do |option|
+        option_parser.on(*option.usage,option.type,option.desc) do |arg,*captures|
+          @options[option.name] = if arg.nil?
+                                    option.default_value
+                                  else
+                                    arg
+                                  end
+
+          if option.block
+            instance_exec(*arg,*captures,&option.block)
+          end
+        end
+      end
+    end
+  end
+end