rake-toolkit_program 0.1.1

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+task :default => :test
+
+task :test do
+  sh *%w[rspec -fd spec]
+end

data/bin/console

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+require "bundler"
+Bundler.setup(:default, :development)
+require "rake/toolkit_program"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# Pry (if it's in the Gemfile)
+begin
+  require "pry"
+rescue LoadError
+  require "irb"
+  IRB.start
+else
+  Pry.start
+end

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/program_exit_from_error.rb

@@ -0,0 +1,56 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# Copyright 2019 PayTrace, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file defines a way to handle errors when running a CLI.
+
+##
+# Idiomatic support for dealing with errors during CLI use
+#
+# Rather than allowing an error to propagate to the top level of the
+# interpreter, this module provides the #exit_program! method, which
+# prints a message to STDERR and exits with an exit code of 1 (unless
+# otherwise specified with .exit_with_code).
+#
+# For debugging support, this module also exposes the #exit_code it
+# would use to exit the program were #exit_program! called.
+#
+module ProgramExitFromError
+  def self.included(klass)
+    klass.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    def exit_with_code(n)
+      @exit_code = n
+    end
+    
+    attr_reader :exit_code
+  end
+  
+  def exit_code
+    self.class.instance_variable_get(:@exit_code) || 1
+  end
+  
+  def exit_program!
+    print_error_message
+    Kernel.exit(exit_code)
+  end
+  
+  def print_error_message
+    $stderr.puts("! ERROR: #{self}".bold.red)
+  end
+end

data/lib/rake/toolkit_program.rb

@@ -0,0 +1,231 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# Copyright 2019 PayTrace, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This is the main file of the rake-toolkit_program library.
+
+require "rake/toolkit_program/version"
+require 'dedent'
+require 'optparse'
+require 'pathname'
+require 'rake'
+require 'shellwords'
+require 'program_exit_from_error'
+
+%w[
+  command_option_parser
+  errors
+  help_styling
+  task_ext
+  utils
+].each do |support_file|
+  require "rake/toolkit_program/#{support_file}"
+end
+
+# From https://stackoverflow.com/a/8781522/160072
+Rake::TaskManager.record_task_metadata = true
+
+module Rake
+  ##
+  # Tools to easily build CLI programs for UNIX-like systems
+  #
+  # In addition to any commands defined, this module provides:
+  #
+  # * a <tt>--install-completions</tt> command
+  # * a <tt>help</tt> command
+  # * <tt>-h</tt> and <tt>--help</tt> flags (until <tt>--</tt> is encountered)
+  #
+  # Use .command_tasks to define commands and .run to execute the CLI.
+  #
+  module ToolkitProgram
+    extend Rake::DSL
+    NAMESPACE="cli_cmd"
+    
+    def self.title=(s)
+      @title = s
+    end
+    
+    def self.title
+      @title || "#{script_name.capitalize} Toolkit Program"
+    end
+    
+    @help_styling = HelpStyling.new
+    ##
+    # Access the HelpStyling object used for styling generated help
+    #
+    def self.help_styling
+      if block_given?
+        yield @help_styling
+      end
+      @help_styling
+    end
+    
+    def self.task_name(name)
+      "#{NAMESPACE}:#{name}"
+    end
+    
+    def self.is_task_name?(name)
+      name.to_s.start_with?(NAMESPACE + ':')
+    end
+    
+    def self.known_command?(name)
+      !name.nil? && Rake::Task.task_defined?(task_name(name))
+    end
+    
+    def self.available_commands(include: :all)
+      Rake::Task.tasks.select {|t| is_task_name?(t.name)}.reject do |t|
+        case include
+        when :all then false
+        when :listable then t.comment.to_s.empty?
+        else raise ArgumentError, "#{include.inspect} not valid as include:"
+        end
+      end
+    end
+    
+    def self.find(name, raise_if_missing: false)
+      case 
+      when known_command?(name)
+        Rake::Task[task_name(name)]
+      when raise_if_missing
+        raise UnknownName.new(name)
+      end
+    end
+    
+    ##
+    # Run a CLI
+    #
+    # Idiomatically, this is usually invoked as:
+    #
+    #   if __FILE__ == $0
+    #     Rake::ToolkitProgram.run(on_error: :exit_program!)
+    #   end
+    #
+    # The first element of +args+ (which defaults to ARGV) names the command to
+    # execute.  Additional arguments are available via .args.
+    #
+    # +on_error+ may be anything supporting #to_proc (including a Proc or
+    # lambda) and accepts one parameter, which is an error object that is
+    # guaranteed to have an #exit_program! method.  Since Symbol#to_proc
+    # creates a Proc that sends the target Symbol to the single argument of the
+    # created Proc, passing <tt>:exit_program!</tt> (as in the idiomatic
+    # invocation) results in program exit according to the error being handled.
+    #
+    # If the error to be handled by +on_error+ does not #respond_to?
+    # <tt>:exit_program!</tt>, it will be extended with ProgramExitFromError,
+    # giving it default #exit_program! behavior of printing the error message
+    # on STDERR and exiting with code 1.
+    #
+    # When +on_error+ is nil, any errors are allowed to propagate out of #run.
+    #
+    def self.run(argv=ARGV, on_error: nil)
+      name, *@args = argv
+      raise NoCommand if name.nil?
+      if_help_request {name, args[0] = 'help', name}
+      specified_task = find(name, raise_if_missing: true)
+      if specified_task.kind_of?(ArgParsingTask)
+        new_args = specified_task.parsed_arguments
+        specified_task.argument_parser.parse(
+          *case new_args
+          when Hash then [args, {into: new_args}]
+          else [args]
+          end
+        )
+        @args = new_args
+      end
+      specified_task.invoke
+    rescue StandardError => error
+      error.extend(ProgramExitFromError) unless error.respond_to?(:exit_program!)
+      
+      case
+      when on_error then on_error.to_proc
+      else method(:raise)
+      end.call(error)
+    end
+    
+    def self.if_help_request
+      if args[0] == 'help'
+        yield
+      else
+        args.each do |a|
+          case a
+          when '--'
+            break
+          when '-h', '--help'
+            yield
+            break
+          end
+        end
+      end
+    end
+    
+    def self.args
+      @args
+    end
+    
+    ##
+    # Specify a standard type for parsed argument accumulation
+    #
+    # If this is called, the block is used to construct the argument
+    # accumulator if no accumulator object is explicitly specified when calling
+    # Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args.  This helps
+    # Rake::ToolkitProgram.args be more consistent throughout the client
+    # program.
+    #
+    def self.default_parsed_args(&blk)
+      @default_parsed_args_creator = blk
+    end
+    
+    ##
+    # Construct a parsed argument accumulator
+    #
+    # The constructor can be defined via the block of .default_parsed_args
+    #
+    def self.new_default_parsed_args(&blk)
+      (@default_parsed_args_creator || blk).call
+    end
+    
+    def self.script_name(placeholder_ok: true)
+      case 
+      when $0 != '-' then $0
+      when ENV['THIS_SCRIPT'] then ENV['THIS_SCRIPT']
+      when placeholder_ok then '<script-name>'
+      else raise "Script name unknown"
+      end
+    end
+    
+    ##
+    # Access the Rake namespace for CLI tasks/commands
+    #
+    # Defining Rake tasks inside the block of this method (with #task) defines
+    # the tasks such that they are recognized as invocable from the command
+    # line (via the first command line argument, or the first element of +args+
+    # passed to .run).
+    #
+    # To make commands/tasks defined in this block visible in the help and
+    # shell completion, use #desc to describe the task.
+    #
+    def self.command_tasks
+      namespace(NAMESPACE) {yield}
+    end
+  end
+end
+
+# Require this at the end because it defines tasks, using some methods defined
+# above
+%w[
+  completion
+  help
+].each {|task_file| require "rake/toolkit_program/#{task_file}"}

data/lib/rake/toolkit_program/command_option_parser.rb

@@ -0,0 +1,256 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+# Copyright 2019 PayTrace, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file creates the Rake::ToolkitProgram::CommandOptionParser subclass
+# of the standard library's OptionParser with supporting operations for a
+# toolkit program, particularly around dealing with positional arguments.
+
+require 'optparse'
+
+module Rake
+  module ToolkitProgram
+    class CommandOptionParser < OptionParser
+      IDENTITY = ->(v) {v}
+      RUBY_GTE_2_4 = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.4')
+      
+      def initialize(arg_dest)
+        super()
+        @argument_destination = arg_dest
+        @positional_mapper = IDENTITY
+      end
+      
+      attr_reader :argument_destination
+      
+      # Method override, see OptionParser#order!
+      if RUBY_GTE_2_4
+        def order!(argv = default_argv, into: nil, &nonopt)
+          super(argv, into: into) do |arg|
+            nonopt.call(@positional_mapper.call(arg))
+          end
+        end
+      else
+        def order!(argv = default_args, into: nil, &nonopt)
+          raise ArgumentError, "Ruby #{RUBY_VERSION} cannot accept 'into' for OptionParser#order!" unless into.nil?
+          super(argv) do |arg|
+            nonopt.call(@positional_mapper.call(arg))
+          end
+        end
+      end
+      
+      # Method override, see OptionParser#parse! -- though we don't do POSIXLY_COMPLIANT
+      def parse!(argv = default_argv, into: nil)
+        positionals = []
+        do_positional_capture(positionals) if @precapture_positionals_array
+        order!(argv, into: into, &positionals.method(:<<)).tap do
+          argv[0, 0] = positionals
+          do_positional_capture(argv) if !@precapture_positionals_array
+          
+          unless positional_cardinality_ok?(positionals.length)
+            raise WrongArgumentCount.new(
+              @positional_cardinality_test,
+              positionals.length
+            )
+          end
+        end
+        return argv
+      end
+      
+      ##
+      # Query whether a given number of positional arguments is acceptable
+      #
+      # The result is based on the test established by
+      # #expect_positional_cardinality, and returns true if no such test
+      # has been established.
+      #
+      def positional_cardinality_ok?(n)
+        pc_test = @positional_cardinality_test
+        !pc_test || pc_test === n
+      end
+      
+      ##
+      # True unless positional arguments have been prohibited
+      #
+      # Technically, this test can only check that the established cardinality
+      # test is for 0, given as an Integer.  If the test established by
+      # #expect_positional_cardinality is a Proc that only returns true for
+      # 0 or the Range <tt>0..0</tt>, this method will report incorrect
+      # results.
+      #
+      def positional_arguments_allowed?
+        @positional_cardinality_test != 0
+      end
+      
+      ##
+      # Return the established test for positional cardinality (or nil)
+      #
+      # If a test has been established by #expect_positional_cardinality,
+      # this method returns that test.  Otherwise, it returns nil.
+      #
+      def positional_cardinality
+        @positional_cardinality_test
+      end
+      
+      ##
+      # String explanation of the positional cardinality, for help
+      #
+      def positional_cardinality_explanation
+        @positional_cardinality_explanation.tap do |explicit|
+          return explicit if explicit
+        end
+        obscure_answer = "A rule exists about the number of positional arguments."
+        
+        case (pc_test = @positional_cardinality_test)
+        when nil, 0 then nil
+        when 1 then "Requires 1 positional argument."
+        when Integer then "Requires #{pc_test} positional arguments."
+        when Range then "Requires #{pc_test.to_inclusive} (inclusive) positional arguments."
+        when Proc then begin
+          [pc_test.call(:explain)].map do |exp|
+            case exp
+            when String then exp
+            else obscure_answer
+            end
+          end[0]
+        rescue StandardError
+          obscure_answer
+        end
+        else obscure_answer
+        end
+      end
+      
+      ##
+      # Explicitly define capture of positional (non-option) arguments
+      #
+      # When parsing into a Hash, the default is to store the Array of
+      # remaining positional arguments in the +nil+ key.  This method
+      # overrides that behavior by either specifying a specific key to
+      # use or by specifying a block to call with the positional arguments,
+      # which is much more useful when accumulating arguments to a non-Hash
+      # object.  Passing +key+ or a block are mutually exclusive.
+      #
+      # +precapture_dest_array+ can be set to +true+ to cause the capture
+      # to take place before the positional arguments are accumulated.  In this
+      # case, the Array object yielded to the block (if this method is called
+      # with a block) _must_ be stored, as it will be the recipient of all
+      # positional arguments.  In any case, when this option is passed to this
+      # method, capture behavior for the (empty) Array into which the
+      # positional arguments will be stored is carried out _before_ option
+      # parsing, and values are (after any transformation dictated by
+      # #map_positional_args) stored in the positional arguments Array; there
+      # is no option to store positionals for consumption by the command task
+      # code in anything other than an Array.  Note that the Array into which
+      # arguments are captured <i>is not</i> the same array either passed to
+      # or returned from the #parse! (or #parse, for that matter) method.
+      #
+      # If multiple calls to this method are made, the last one is the one
+      # that defines the behavior.
+      #
+      # +key+:: Key under which positionals shall be accumulated in a Hash
+      # +precapture_dest_array+:: Capture before argument accumulation
+      #
+      def capture_positionals(key=nil, precapture_dest_array: false, &blk)
+        if blk && !key.nil?
+          raise ArgumentError, "either specify key or block"
+        end
+        @positionals_key = key
+        @positionals_capture = blk
+        @precapture_positionals_array = precapture_dest_array
+      end
+      
+      ##
+      # Constrain the number of positional arguments
+      #
+      # This is a declarative way of expressing how many positional (i.e.
+      # non-option) arguments should be accepted by the command.  The
+      # #=== (i.e. "case match") method of +cardinality_test+ is used to test
+      # the length of the positional argument Array, raising
+      # Rake::ToolkitProgram::WrongArgumentCount if #=== returns false.
+      #
+      # A special case exists when +cardinality_test+ is a Symbol: because
+      # a Symbol could never match an Integer, Symbol#to_proc is called to
+      # create a useful test.
+      #
+      # *NOTE* It is worth attention that Proc#=== is an alias for Proc#call,
+      # so the operator argument is passed to the Proc.  This enables arbitrary
+      # computation for the validity of the positional argument count,
+      # syntactically aided by the "stabby-lambda" notation.
+      #
+      # While this gem will do its best to explain the argument cardinality,
+      # +explanation+ provides an opportunity to explicitly provide a 
+      # sentence to be included in the help about the allowed cardinality
+      # (i.e. count) of positional arguments.
+      #
+      def expect_positional_cardinality(cardinality_test, explanation=nil)
+        @positional_cardinality_explanation = explanation
+        if cardinality_test.kind_of?(Symbol)
+          cardinality_test.to_s.tap do |test_name|
+            if explanation.nil? && test_name.end_with?('?')
+              @positional_cardinality_explanation = (
+                "Positional argument count must be #{test_name[0..-2].gsub('_', ' ')}."
+              )
+            end
+          end
+          cardinality_test = cardinality_test.to_proc
+        end
+        @positional_cardinality_test = cardinality_test
+      end
+      
+      ##
+      # Disallow positional arguments
+      #
+      # The command will raise Rake::ToolkitProgram::WrongArgumentCount if
+      # any positional arguments are given.
+      #
+      def no_positional_args!
+        expect_positional_cardinality(0)
+      end
+      
+      ##
+      # Convenience method for raising Rake::ToolkitProgram::InvalidCommandLine
+      #
+      # The error raised is the standard error for an invalid command line
+      # when using Rake::ToolkitProgram.
+      #
+      def invalid_args!(message)
+        raise InvalidCommandLine, message
+      end
+      
+      ##
+      # Define a mapping function for positional arguments during accumulation
+      #
+      # The block given to this method will be called with each positional
+      # argument in turn; the return value of the block will be acculumated
+      # as the positional argument.  The block's computation may be purely
+      # functional or it may refer to outside factors in its binding such as
+      # accumulated values for options or preceding positional arguments.
+      #
+      def map_positional_args(&blk)
+        raise ArgumentError, "block required" if blk.nil?
+        @positional_mapper = blk
+      end
+      
+      private
+      def do_positional_capture(positionals)
+        if @positionals_capture
+          @positionals_capture.call(positionals)
+        elsif argument_destination.kind_of?(Hash)
+          argument_destination[@positionals_key] = positionals
+        end
+      end
+    end
+  end
+end