cli-kit 4.0.0 → 5.0.0

data/lib/cli/kit/args/parser.rb

@@ -0,0 +1,129 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module Args
+      class Parser
+        extend T::Sig
+
+        autoload :Node, 'cli/kit/args/parser/node'
+
+        Error = Class.new(Args::Error)
+
+        class InvalidOptionError < Error
+          extend T::Sig
+          sig { params(option: String).void }
+          def initialize(option)
+            super("invalid option -- '#{option}'")
+          end
+        end
+
+        class OptionRequiresAnArgumentError < Error
+          extend T::Sig
+          sig { params(option: String).void }
+          def initialize(option)
+            super("option requires an argument -- '#{option}'")
+          end
+        end
+
+        sig { params(tokens: T::Array[Tokenizer::Token]).returns(T::Array[Node]) }
+        def parse(tokens)
+          nodes = T.let([], T::Array[Node])
+          args = T.let(tokens, T::Array[T.nilable(Tokenizer::Token)])
+          args << nil # to make each_cons pass (args.last, nil) on the final round.
+          state = :init
+          # TODO: test that "--height -- 3" is parsed correctly.
+          args.each_cons(2) do |(arg, next_arg)|
+            case state
+            when :skip
+              state = :init
+            when :init
+              state, val = parse_token(T.must(arg), next_arg)
+              nodes << val
+            when :unparsed
+              unless arg.is_a?(Tokenizer::Token::UnparsedArgument)
+                raise(Error, 'bug: non-unparsed argument after unparsed argument')
+              end
+
+              unparsed = nodes.last
+              unless unparsed.is_a?(Node::Unparsed)
+                # :nocov: not actually possible, in theory
+                raise(Error, 'bug: parser failed to recognize first unparsed argument')
+                # :nocov:
+              end
+
+              unparsed.value << arg.value
+            end
+          end
+          nodes
+        end
+
+        sig { params(definition: Definition).void }
+        def initialize(definition)
+          @defn = definition
+        end
+
+        private
+
+        sig do
+          params(token: Tokenizer::Token, next_token: T.nilable(Tokenizer::Token))
+            .returns([Symbol, Parser::Node])
+        end
+        def parse_token(token, next_token)
+          case token
+          when Tokenizer::Token::LongOptionName
+            case @defn.lookup_long(token.value)
+            when Definition::Option
+              [:skip, parse_option(token, next_token)]
+            when Definition::Flag
+              [:init, Node::LongFlag.new(token.value)]
+            else
+              raise(InvalidOptionError, token.value)
+            end
+          when Tokenizer::Token::ShortOptionName
+            case @defn.lookup_short(token.value)
+            when Definition::Option
+              [:skip, parse_option(token, next_token)]
+            when Definition::Flag
+              [:init, Node::ShortFlag.new(token.value)]
+            else
+              raise(InvalidOptionError, token.value)
+            end
+          when Tokenizer::Token::OptionValue
+            raise(Error, "bug: unexpected option value in argument parse sequence: #{token.value}")
+          when Tokenizer::Token::PositionalArgument
+            [:init, Node::Argument.new(token.value)]
+          when Tokenizer::Token::OptionValueOrPositionalArgument
+            [:init, Node::Argument.new(token.value)]
+          when Tokenizer::Token::UnparsedArgument
+            [:unparsed, Node::Unparsed.new([token.value])]
+          else
+            raise(Error, "bug: unexpected token type: #{token.class}")
+          end
+        end
+
+        sig { params(arg: Tokenizer::Token::OptionName, next_arg: T.nilable(Tokenizer::Token)).returns(Node) }
+        def parse_option(arg, next_arg)
+          case next_arg
+          when nil, Tokenizer::Token::LongOptionName,
+            Tokenizer::Token::ShortOptionName, Tokenizer::Token::PositionalArgument
+            raise(OptionRequiresAnArgumentError, arg.value)
+          when Tokenizer::Token::OptionValue, Tokenizer::Token::OptionValueOrPositionalArgument
+            case arg
+            when Tokenizer::Token::LongOptionName
+              Node::LongOption.new(arg.value, next_arg.value)
+            when Tokenizer::Token::ShortOptionName
+              Node::ShortOption.new(arg.value, next_arg.value)
+            else
+              raise(Error, "bug: unexpected token type: #{arg.class}")
+            end
+          else
+            raise(Error, "bug: unexpected argument type: #{next_arg.class}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cli/kit/args/tokenizer.rb

@@ -0,0 +1,133 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module Args
+      module Tokenizer
+        extend T::Sig
+
+        Error = Class.new(Args::Error)
+
+        class InvalidShortOption < Error
+          extend T::Sig
+          sig { params(short_option: String).void }
+          def initialize(short_option)
+            super("invalid short option: '-#{short_option}'")
+          end
+        end
+
+        class InvalidCharInShortOption < Error
+          extend T::Sig
+          sig { params(short_option: String, char: String).void }
+          def initialize(short_option, char)
+            super("invalid character '#{char}' in short option: '-#{short_option}'")
+          end
+        end
+
+        class Token
+          extend T::Sig
+
+          sig { returns(String) }
+          attr_reader :value
+
+          sig { params(value: String).void }
+          def initialize(value)
+            @value = value
+          end
+
+          sig { returns(String) }
+          def inspect
+            "#<#{self.class.name} #{@value}>"
+          end
+
+          sig { params(other: T.untyped).returns(T::Boolean) }
+          def ==(other)
+            self.class == other.class && @value == other.value
+          end
+
+          OptionName = Class.new(Token)
+          LongOptionName = Class.new(OptionName)
+          ShortOptionName = Class.new(OptionName)
+
+          OptionValue = Class.new(Token)
+          PositionalArgument = Class.new(Token)
+          OptionValueOrPositionalArgument = Class.new(Token)
+          UnparsedArgument = Class.new(Token)
+        end
+
+        class << self
+          extend T::Sig
+
+          sig { params(raw_args: T::Array[String]).returns(T::Array[Token]) }
+          def tokenize(raw_args)
+            args = []
+
+            mode = :init
+
+            raw_args.each do |arg|
+              case mode
+              when :unparsed
+                args << Token::UnparsedArgument.new(arg)
+              when :init
+                case arg
+                when '--'
+                  mode = :unparsed
+                when /\A--./
+                  name, value = arg.split('=', 2)
+                  args << Token::LongOptionName.new(T.must(T.must(name)[2..-1]))
+                  if value
+                    args << Token::OptionValue.new(value)
+                  end
+                when /\A-./
+                  args.concat(tokenize_short_option(T.must(arg[1..-1])))
+                else
+                  args << if args.last.is_a?(Token::OptionName)
+                    Token::OptionValueOrPositionalArgument.new(arg)
+                  else
+                    Token::PositionalArgument.new(arg)
+                  end
+                end
+              end
+            end
+
+            args
+          end
+
+          sig { params(arg: String).returns(T::Array[Token]) }
+          def tokenize_short_option(arg)
+            args = []
+            mode = :init
+            number = +''
+            arg.each_char do |char|
+              case mode
+              when :numeric
+                case char
+                when /[0-9]/
+                  number << char
+                else
+                  raise(InvalidShortOption, arg)
+                end
+              when :init
+                case char
+                when /[a-zA-Z]/
+                  args << Token::ShortOptionName.new(char)
+                when /[0-9]/
+                  mode = :numeric
+                  number << char
+                else
+                  raise(InvalidCharInShortOption.new(arg, char))
+                end
+              end
+            end
+            if number != ''
+              args << Token::OptionValue.new(number)
+            end
+            args
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cli/kit/args.rb

@@ -0,0 +1,16 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module Args
+      Error = Class.new(StandardError)
+
+      autoload :Definition, 'cli/kit/args/definition'
+      autoload :Parser, 'cli/kit/args/parser'
+      autoload :Evaluation, 'cli/kit/args/evaluation'
+      autoload :Tokenizer, 'cli/kit/args/tokenizer'
+    end
+  end
+end

data/lib/cli/kit/base_command.rb

@@ -1,46 +1,31 @@
+# typed: true
+
 require 'cli/kit'
 
 module CLI
   module Kit
     class BaseCommand
-      def self.defined?
-        true
-      end
+      extend T::Sig
+      extend T::Helpers
+      include CLI::Kit::CommandHelp
+      extend CLI::Kit::CommandHelp::ClassMethods
+      abstract!
 
-      def self.statsd_increment(_metric, **_kwargs)
-        nil
-      end
-
-      def self.statsd_time(_metric, **_kwargs)
-        yield
-      end
+      class << self
+        extend T::Sig
 
-      def self.call(args, command_name)
-        cmd = new
-        stats_tags = cmd.stats_tags(args, command_name)
-        begin
-          statsd_increment('cli.command.invoked', tags: stats_tags)
-          statsd_time('cli.command.time', tags: stats_tags) do
-            cmd.call(args, command_name)
-          end
-          statsd_increment('cli.command.success', tags: stats_tags)
-        rescue Exception => e # rubocop:disable Lint/RescueException
-          statsd_increment('cli.command.exception', tags: stats_tags + ["exception:#{e.class}"])
-          raise e
+        sig { returns(T::Boolean) }
+        def defined?
+          true
         end
-      end
-
-      def stats_tags(args, command_name)
-        tags = ["task:#{self.class}"]
-        tags << "command:#{command_name}" if command_name
-        tags << "subcommand:#{args.first}" if args&.first && has_subcommands?
-        tags
-      end
 
-      def call(_args, _command_name)
-        raise NotImplementedError, "#{self.class.name} must implement #{__method__}"
+        sig { params(args: T::Array[String], command_name: String).void }
+        def call(args, command_name)
+          new.call(args, command_name)
+        end
       end
 
+      sig { returns(T::Boolean) }
       def has_subcommands?
         false
       end

data/lib/cli/kit/command_help.rb

@@ -0,0 +1,271 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module CommandHelp
+      extend T::Sig
+      include Kernel # for sorbet
+
+      sig { params(args: T::Array[String], name: String).void }
+      def call(args, name)
+        begin
+          opts = self.class.opts_class
+          opts_inst = opts.new
+          defn = Args::Definition.new
+          opts_inst.define!(defn)
+          tokens = Args::Tokenizer.tokenize(args)
+          parse = Args::Parser.new(defn).parse(tokens)
+          evl = Args::Evaluation.new(defn, parse)
+          opts_inst.evaluate!(evl)
+        rescue Args::Evaluation::TooManyPositions, Args::Evaluation::MissingRequiredPosition => e
+          STDERR.puts CLI::UI.fmt("{{red:{{bold:Error: #{e.message}}}}}")
+          STDERR.puts
+          STDERR.puts self.class.build_help
+          raise(AbortSilent)
+        rescue Args::Error => e
+          raise(Abort, e)
+        end
+
+        if opts_inst.helpflag
+          puts self.class.build_help
+        else
+          invoke_wrapper(opts_inst, name)
+        end
+      end
+
+      # use to implement error handling
+      sig { params(op: T.untyped, name: String).void }
+      def invoke_wrapper(op, name)
+        invoke(op, name)
+      end
+
+      sig { params(op: T.untyped, name: String).void }
+      def invoke(op, name)
+        raise(NotImplementedError, '#invoke must be implemented, or #call overridden')
+      end
+
+      class << self
+        extend T::Sig
+
+        sig { params(tool_name: String).void }
+        attr_writer :tool_name
+
+        sig { params(max_desc_length: Integer).void }
+        attr_writer :max_desc_length
+
+        sig { returns(String) }
+        def _tool_name
+          unless @tool_name
+            raise 'You must set CLI::Kit::CommandHelp.tool_name='
+          end
+
+          @tool_name
+        end
+
+        sig { returns(Integer) }
+        def _max_desc_length
+          @max_desc_length || 80
+        end
+      end
+
+      module ClassMethods
+        extend T::Sig
+        include Kernel # for sorbet
+
+        DEFAULT_HELP_SECTIONS = [
+          :desc,
+          :long_desc,
+          :usage,
+          :examples,
+          :options,
+        ]
+
+        sig { returns(String) }
+        def build_help
+          h = (@help_sections || DEFAULT_HELP_SECTIONS).map do |section|
+            case section
+            when :desc
+              build_desc
+            when :long_desc
+              @long_desc
+            when :usage
+              @usage_section ||= build_usage
+            when :examples
+              @examples_section ||= build_examples
+            when :options
+              @options_section ||= build_options
+            else
+              raise "Unknown help section: #{section}"
+            end
+          end.compact.map(&:chomp).join("\n\n") + "\n"
+          CLI::UI.fmt(h)
+        end
+
+        sig { returns(String) }
+        def _command_name
+          return @command_name if @command_name
+
+          last_camel = send(:name).split('::').last
+          last_camel.gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+        end
+
+        sig { returns(String) }
+        def _desc
+          @desc
+        end
+
+        sig { returns(String) }
+        def build_desc
+          out = +"{{command:#{CommandHelp._tool_name} #{_command_name}}}"
+          if @desc
+            out << ": #{@desc}"
+          end
+          "{{bold:#{out}}}"
+        end
+
+        sig { returns(T.untyped) }
+        def opts_class
+          T.unsafe(self).const_get(:Opts) # rubocop:disable Sorbet/ConstantsFromStrings
+        rescue NameError
+          Class.new(CLI::Kit::Opts)
+        end
+
+        sig { returns(T.nilable(String)) }
+        def build_options
+          opts = opts_class
+          return(nil) unless opts
+
+          methods = []
+          loop do
+            methods.concat(opts.public_instance_methods(false))
+            break if opts.superclass == CLI::Kit::Opts
+
+            opts = opts.superclass
+          end
+
+          @defn = Args::Definition.new
+          o = opts.new
+          o.define!(@defn)
+
+          return nil if @defn.options.empty? && @defn.flags.empty?
+
+          merged = T.let(@defn.options, T::Array[T.any(Args::Definition::Option, Args::Definition::Flag)])
+          merged += @defn.flags
+          merged.sort_by!(&:name)
+          "{{bold:Options:}}\n" + merged.map do |o|
+            if o.is_a?(Args::Definition::Option)
+              z = '  ' + [o.short&.prepend('-'), o.long&.prepend('--')].compact.join(', ') + ' VALUE'
+              default = if o.dynamic_default?
+                '(generated default)'
+              elsif o.default.nil?
+                '(no default)'
+              else
+                "(default: #{o.default.inspect})"
+              end
+              z << if o.desc
+                "  {{italic:{{gray:# #{o.desc} #{default}}}}}"
+              else
+                "  {{italic:{{gray:# #{default}}}}}"
+              end
+            else
+              z = '  ' + [o.short&.prepend('-'), o.long&.prepend('--')].compact.join(', ')
+              if o.desc
+                z << "  {{italic:{{gray:# #{o.desc}}}}}"
+              end
+            end
+            z
+          end.join("\n")
+        end
+
+        sig { params(sections: T::Array[Symbol]).void }
+        def help_sections(sections)
+          @help_sections = sections
+        end
+
+        sig { params(command_name: String).void }
+        def command_name(command_name)
+          if @command_name
+            raise(ArgumentError, "Command name already set to #{@command_name}")
+          end
+
+          @command_name = command_name
+        end
+
+        sig { params(desc: String).void }
+        def desc(desc)
+          # A limit of 80 characters has been chosen to fit on standard terminal configurations. `long_desc` is
+          # available when descriptions don't fit nicely in that space. If you're using CLI::Kit for an application
+          # where you control the runtime environments and know that terminals will have more than 80 columns
+          # available, you can use
+          #
+          #   CLI::Kit::CommandHelp.max_desc_length =
+          #
+          # to increase this limit.
+          if desc.size > CommandHelp._max_desc_length
+            raise(ArgumentError, "description must be #{CommandHelp._max_desc_length} characters or less")
+          end
+          if @desc
+            raise(ArgumentError, 'description already set')
+          end
+
+          @desc = desc
+        end
+
+        sig { params(long_desc: String).void }
+        def long_desc(long_desc)
+          if @long_desc
+            raise(ArgumentError, 'long description already set')
+          end
+
+          @long_desc = long_desc
+        end
+
+        sig { returns(String) }
+        def build_usage
+          '{{bold:Usage:}}' + case (@usage || []).size
+          when 0
+            " {{command:#{CommandHelp._tool_name} #{_command_name}}} [options]\n"
+          when 1
+            " {{command:#{CommandHelp._tool_name} #{_command_name}}} #{@usage.first}\n"
+          else
+            "\n" + @usage.map do |usage|
+              "  {{command:#{CommandHelp._tool_name} #{_command_name}}} #{usage}\n"
+            end.join
+          end
+        end
+
+        sig { returns(T.nilable(String)) }
+        def build_examples
+          return nil unless @examples
+
+          cmd_prefix = "  {{command:#{CommandHelp._tool_name} #{_command_name}}}"
+          "{{bold:Examples:}}\n" + @examples.map do |command, explanation|
+            cmd = "#{cmd_prefix} #{command}"
+            exp = "{{italic:{{gray:# #{explanation}}}}}"
+
+            width = CLI::UI::ANSI.printing_width(CLI::UI.fmt("#{cmd} #{exp}"))
+            if width > CLI::UI::Terminal.width
+              "  #{exp}\n#{cmd}"
+            else
+              "#{cmd}  #{exp}"
+            end
+          end.join("\n\n")
+        end
+
+        sig { params(usage: String).void }
+        def usage(usage)
+          @usage ||= []
+          @usage << usage
+        end
+
+        sig { params(command: String, explanation: T.nilable(String)).void }
+        def example(command, explanation)
+          @examples ||= []
+          @examples << [command, explanation]
+        end
+      end
+    end
+  end
+end