rake-toolkit_program 0.1.1

data/lib/rake/toolkit_program/completion.rb

@@ -0,0 +1,158 @@
+# 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 the bash completion behavior of the rake-toolkit_program
+# library.
+
+module Rake
+  module ToolkitProgram
+    def self.each_completion_script_line(static_options: nil, static_flags: nil)
+      options = static_options || %Q{$("$1" --commands)}
+      flags = (static_flags.shellescape if static_flags) || \
+        ('' if static_options) || \
+        %Q{$("$1" --flag-completion "${COMP_WORDS[@]}")}
+      
+      <<-END_BASH.dedent.each_line {|l| yield("  " + l)}
+        COMPREPLY=()
+        MY_WORDNUM=1
+        if [ "${COMP_CWORD}" = 2 ] && [ "${COMP_WORDS[1]}" = help ]; then
+          MY_WORDNUM=2
+        elif [ "${COMP_CWORD}" != "1" ]; then
+          HELP_FLAG="--help"
+          if [ -n "${COMP_WORDS[$COMP_CWORD]}" ] && [ "${HELP_FLAG\#${COMP_WORDS[$COMP_CWORD]}}" = "$HELP_FLAG" ]; then
+            # Word being completed is NOT a prefix of --help: don't offer --help
+            :
+          elif ! { echo " ${COMP_WORDS[*]}" | egrep -q '\\s(--help|-h|--\\s)'; }; then
+            COMPREPLY=("--help")
+          fi
+          DO_COMPGEN=true
+          if ! { echo " ${COMP_WORDS[*]}" | egrep -q '\\s(--help|-h|--\\s)'; }; then
+            FLAGS_CANDIDATE=#{flags}
+            if [ "$(echo "$FLAGS_CANDIDATE" | head -n1)" == '!NOFSCOMP!' ]; then
+              DO_COMPGEN=false
+              COMPREPLY+=($(echo "$FLAGS_CANDIDATE" | tail -n+2))
+            else
+              COMPREPLY+=($FLAGS_CANDIDATE)
+            fi
+          fi
+          if $DO_COMPGEN && [ "${COMP_WORDS[$COMP_CWORD]}" != "--" ] && ! { echo " ${COMP_WORDS[*]}" | egrep -q '\\s(--help|-h)'; }; then
+            COMPREPLY+=($(compgen -f -d -- "${COMP_WORDS[$COMP_CWORD]}"))
+          fi
+          return
+        fi
+        COMPREPLY=($(compgen -W "#{options}" -- "${COMP_WORDS[$MY_WORDNUM]}"))
+      END_BASH
+    end
+  end
+end
+
+
+Rake::ToolkitProgram.command_tasks do # define task for shell completion
+  task '--commands' do
+    cmds = Rake::ToolkitProgram.available_commands(include: :listable)
+    puts(cmds.map do |t|
+      t.name[(Rake::ToolkitProgram::NAMESPACE.length + 1)..-1]
+    end.join(' '))
+  end
+  
+  task '--flag-completion' do
+    program = Rake::ToolkitProgram
+    begin
+      script_path, command_name, *args = program.args
+      command = program.find(command_name)
+      next unless program::ArgParsingTask === command
+      incomplete = args.pop
+      candidate = command.argument_parser.candidate(incomplete.empty? ? '-' : incomplete)
+      begin
+        command.argument_parser.parse(args)
+      rescue OptionParser::MissingArgument
+        # We can't help complete flags because there is a flag that requires an
+        # argument, but it's fine to build more
+      rescue program::WrongArgumentCount
+        # args doesn't have the right number of arguments, and adding flags
+        # won't help, but it's fine to build more arguments -- so far, but see below
+      rescue OptionParser::ParseError
+        puts '!NOFSCOMP!'
+      else
+        if incomplete.empty? && !command.argument_parser.positional_cardinality_ok?(args.length + 1)
+          puts '!NOFSCOMP!'
+        end
+        candidate.select! {|c| c.start_with?('--')}
+        candidate = candidate.collect_concat do |c|
+          if c =~ /^--\[(\w+-)\](.*)/
+            ["--#{$2}", "--#{$1}#{$2}"]
+          else
+            [c]
+          end
+        end
+        puts candidate
+      end
+    rescue StandardError
+    end
+  end
+  
+  task '--install-completions' do
+    script_path = Pathname(
+      Rake::ToolkitProgram.script_name(placeholder_ok: false)
+    )
+    
+    profile_path, completions_dir = case Process.euid
+    when 0
+      ["/etc/profile", "/usr/local/lib/"]
+    else
+      ["~/.bash_profile", "~/.bash-complete"]
+    end.map {|path_str| Pathname(path_str).expand_path}
+    name_parts = [script_path.basename.to_s, 'completions']
+    completions_fpath = completions_dir / name_parts.join('-')
+    
+    completions_fpath.dirname.mkpath
+    completions_fpath.open('w', 0644) do |out|
+      uniq_name = "_" + Random.new.bytes(20).unpack('H*').first
+      out.puts "#{uniq_name}() {"
+      Rake::ToolkitProgram.each_completion_script_line do |line|
+        out.puts line
+      end
+      out.puts "}"
+      out.puts "complete -F #{uniq_name} -o bashdefault #{script_path.basename}"
+    end
+    
+    load_completions = %Q{source #{completions_fpath}}
+    load_completions_split = Shellwords.split(load_completions)
+    
+    load_present = begin
+      profile_path.each_line.any? do |line|
+        begin
+          Shellwords.split(line, drop_comment: true)
+        rescue ArgumentError
+          []
+        end == load_completions_split
+      end
+    rescue Errno::ENOENT
+      false
+    end
+    
+    if load_present
+      puts "Completions already installed in #{profile_path}"
+    else
+      profile_path.open('a') do |out|
+        out.puts load_completions
+      end
+      puts "Completions installed in #{profile_path}"
+      puts "Source #{completions_fpath} for immediate availability."
+    end
+  end
+end

data/lib/rake/toolkit_program/errors.rb

@@ -0,0 +1,77 @@
+# 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 errors classes used by Rake::ToolkitProgram.
+
+module Rake
+  module ToolkitProgram
+    class UnknownName < StandardError
+      include ProgramExitFromError
+      exit_with_code 2
+      
+      def initialize(name)
+        super("The command '#{name}' is not known")
+        @name = name.to_s.dup.freeze
+      end
+      
+      attr_reader :name
+      
+      def print_error_message
+        s = ToolkitProgram.help_styling
+        $stderr.puts "#{s.error_marker '[ERROR]'} #{s.code name} is not a recognized command name."
+        $stderr.puts "Use #{s.code "#{ToolkitProgram.script_name} help"} for a list of available commands."
+      end
+    end
+    
+    class NoCommand < StandardError
+      include ProgramExitFromError
+      exit_with_code 2
+      
+      def print_error_message
+        s = ToolkitProgram.help_styling
+        $stderr.puts "#{s.error_marker '[ERROR]'} #{s.code name} A command is required."
+        $stderr.puts "Use #{s.code "#{ToolkitProgram.script_name} help"} for a list of available commands."
+      end
+    end
+    
+    class InvalidCommandLine < StandardError
+      include ProgramExitFromError
+      exit_with_code 2
+      
+      def print_error_message
+        s = ToolkitProgram.help_styling
+        $stderr.puts "#{s.error_marker 'ERROR'} #{self}"
+      end
+    end
+    
+    class WrongArgumentCount < InvalidCommandLine
+      include ProgramExitFromError
+      exit_with_code 2
+      
+      def initialize(cardinality_test, actual_count)
+        super(case cardinality_test
+        when Integer
+          "expected #{cardinality_test} arguments, got #{actual_count}"
+        when Range
+          "expected #{cardinality_test.to_inclusive} (inclusive) arguments, got #{actual_count}"
+        else
+          "#{actual_count} arguments given"
+        end)
+      end
+    end
+  end
+end

data/lib/rake/toolkit_program/help.rb

@@ -0,0 +1,105 @@
+# 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 implements the 'help' command of rake-toolkit_program.
+
+module Rake
+  module ToolkitProgram
+    command_tasks do # define 'help' command
+      task '-h' => :help
+      task '--help' => :help
+
+      help_styling {|s| desc <<-END_HELP.dedent
+        Show a list of commands or details of one command
+        
+        To get help on a specific command, put the command's name as the first
+        argument after #{s.code('help')} or use #{s.code('-h')} or #{s.code('--help')} after the command's name.
+        END_HELP
+      }
+      task :help do
+        style = help_styling
+        
+        puts
+        puts style.title(title)
+        puts
+        
+        options_usage = "[#{style.param('OPTION ...')}]"
+        unless (task = find(args[0]))
+          puts "Usage: #{style.code(script_name)} #{style.param('COMMAND')} #{options_usage}"
+          puts
+          puts "Avaliable options vary depending on the command given. For details"
+          puts "of a particular command, use:"
+          puts
+          puts "    #{style.code(script_name)} #{style.code('help')} #{style.param('COMMAND')}"
+          puts
+          puts "Commands:"
+          cmds = available_commands(include: :listable)
+          nsp_len = NAMESPACE.length + 1
+          name_field_length = cmds.map {|t| t.name.length - nsp_len}.max
+          cmds.each do |t|
+            puts "    #{style.code(t.name[nsp_len..-1].rjust(name_field_length))}   #{t.comment}"
+          end
+          puts
+          puts "Use #{style.code('help')} #{style.param('COMMAND')} to get more help on a specific command."
+        else
+          cmd_name = args[0]
+          arg_parser = (ArgParsingTask === task) ? task.argument_parser : nil
+          usage_parts = [
+            style.code(script_name),
+            style.code(cmd_name),
+          ]
+          option_count = arg_parser ? arg_parser.enum_for(:summarize).count : 0
+          usage_parts << options_usage if !arg_parser || option_count > 0
+          generic_arg_usage = "[#{style.param('ARG')} ...]"
+          if arg_parser
+            usage_parts.concat case arg_parser.positional_cardinality
+            when 0
+              []
+            when Integer
+              [style.param('ARG')] * arg_parser.positional_cardinality
+            when ->(card) {Range === card && card.to_inclusive == (0..1)}
+              ["[#{style.param('ARG')}]"]
+            when ->(card) {Range === card && card.begin > 0}
+              [generic_arg_usage[1..-2]]
+            else
+              [generic_arg_usage]
+            end
+          else
+            usage_parts << generic_arg_usage
+          end
+          puts "Usage: #{usage_parts.join(' ')}"
+          puts
+          puts task.full_comment
+          if arg_parser
+            if (pos_exp = arg_parser.positional_cardinality_explanation)
+              puts
+              puts pos_exp
+            end
+          end
+          if option_count > 0
+            puts
+            puts "Options:"
+            arg_parser.summarize do |optline|
+              puts optline
+            end
+          end
+        end
+        puts
+      end
+    end
+  end
+end

data/lib/rake/toolkit_program/help_styling.rb

@@ -0,0 +1,68 @@
+# 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 the HelpStyling class, used to style the help output
+# of a Rake::ToolkitProgram.
+
+module Rake
+  module ToolkitProgram
+    ##
+    # An object that captures styling rules for a CLI program
+    #
+    # This class defines several methods that either configure a styling
+    # transformation or apply the configured transformation, depending on the
+    # argument type.  These methods are defined with .define_style for
+    # consistency.
+    #
+    # Each "style" method (e.g. #title) "learns" how to apply its style if
+    # passed anything responding to #to_proc and applies its current style
+    # transformation if passed a string.
+    #
+    class HelpStyling
+      IDENTITY = -> (s) {s}
+      
+      def initialize
+        super
+        begin
+          require 'colorize'
+        rescue LoadError
+          title ->(s) {"*** #{s} ***"}
+        else
+          title ->(s) {"*** #{s} ***".light_white.bold.on_blue}
+          code  ->(s) {s.bold}
+          param ->(s) {s.italic}
+          error_marker ->(s) {s.bold.red.on_black}
+        end
+      end
+      
+      def self.define_style(*names)
+        names.each do |name|
+          vname = "@#{name}".to_sym
+          define_method(name) do |s|
+            case 
+            when String === s then (instance_variable_get(vname) || IDENTITY)[s]
+            when s.respond_to?(:to_proc) then instance_variable_set(vname, s.to_proc)
+            else raise ArgumentError, "\##{name} accepts a String or Proc"
+            end
+          end
+        end
+      end
+      
+      define_style :title, :code, :param, :error_marker
+    end
+  end
+end

data/lib/rake/toolkit_program/task_ext.rb

@@ -0,0 +1,83 @@
+# 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 the extensions to Rake::Task to support the
+# rake-toolkit_program library.
+
+module Rake
+  module ToolkitProgram
+    module TaskExt
+      ##
+      # Define argument parsing for a Rake::Task used as a command
+      #
+      # The block receives two arguments:
+      #
+      # 1.  a Rake::ToolkitProgram::CommandOptionParser (a subclass of
+      #     OptionParser)
+      # 2.  the argument accumulator object passed in as +into+
+      #
+      # When the subject task is invoked through Rake::ToolkitProgram.run,
+      # the parser configured in this block is run against the _remaining_
+      # arguments (after the command name).  The argument accumulator +into+
+      # will be available as Rake::ToolkitProgram.args instead of the default
+      # argument Array.
+      #
+      # Rake::ToolkitProgram::CommandOptionParser offers some useful extensions
+      # around positional parameters, since the Array containing the remaining
+      # arguments after parsing would be otherwise unavailable.
+      #
+      def parse_args(into: ToolkitProgram.new_default_parsed_args {Hash.new})
+        parser, new_args = CommandOptionParser.new(into), into
+        yield parser, new_args
+        @arg_parser = parser
+        extend ArgParsingTask
+        return self
+      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
+      
+      ##
+      # Prohibit any arguments when this command is invoked
+      #
+      # Help arguments are still allowed, as the special 'help' command is the
+      # one invoked when they are present.
+      #
+      def prohibit_args
+        parse_args(into: []) {|parser| parser.no_positional_args!}
+      end
+    end
+    Rake::Task.include TaskExt
+    
+    module ArgParsingTask
+      def argument_parser
+        @arg_parser
+      end
+      
+      def parsed_arguments
+        @arg_parser.argument_destination
+      end
+    end
+  end
+end