cli-kit 4.0.0 → 5.0.0

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

@@ -0,0 +1,344 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module Args
+      class Definition
+        extend T::Sig
+
+        Error = Class.new(Args::Error)
+        ConflictingFlag = Class.new(Error)
+        InvalidFlag = Class.new(Error)
+        InvalidLookup = Class.new(Error)
+        InvalidPosition = Class.new(Error)
+
+        sig { returns(T::Array[Flag]) }
+        attr_reader :flags
+
+        sig { returns(T::Array[Option]) }
+        attr_reader :options
+
+        sig { returns(T::Array[Position]) }
+        attr_reader :positions
+
+        sig { params(name: Symbol, short: T.nilable(String), long: T.nilable(String), desc: T.nilable(String)).void }
+        def add_flag(name, short: nil, long: nil, desc: nil)
+          short, long = strip_prefixes_and_validate(short, long)
+          flag = Flag.new(name: name, short: short, long: long, desc: desc)
+          add_resolution(flag)
+          @flags << flag
+        end
+
+        sig do
+          params(
+            name: Symbol, short: T.nilable(String), long: T.nilable(String),
+            desc: T.nilable(String),
+            default: T.any(
+              NilClass,
+              String, T.proc.returns(String),
+              T::Array[String], T.proc.returns(T::Array[String])
+            ),
+            required: T::Boolean, multi: T::Boolean
+          ).void
+        end
+        def add_option(name, short: nil, long: nil, desc: nil, default: nil, required: false, multi: false)
+          short, long = strip_prefixes_and_validate(short, long)
+          option = Option.new(
+            name: name, short: short, long: long, desc: desc, default: default,
+            required: required, multi: multi
+          )
+          add_resolution(option)
+          @options << option
+        end
+
+        sig do
+          params(
+            name: Symbol,
+            required: T::Boolean,
+            multi: T::Boolean,
+            desc: T.nilable(String),
+            default: T.any(NilClass, String, T.proc.returns(String)),
+            skip: T.any(
+              NilClass,
+              T.proc.returns(T::Boolean),
+              T.proc.params(arg0: String).returns(T::Boolean),
+            ),
+          ).void
+        end
+        def add_position(name, required:, multi:, desc: nil, default: nil, skip: nil)
+          position = Position.new(
+            name: name, desc: desc, required: required, multi: multi,
+            default: default, skip: skip
+          )
+          validate_order(position)
+          add_name_resolution(position)
+          @positions << position
+        end
+
+        sig { void }
+        def initialize
+          @flags = []
+          @options = []
+          @by_short = {}
+          @by_long = {}
+          @by_name = {}
+          @positions = []
+        end
+
+        module OptBase
+          extend T::Sig
+
+          sig { returns(Symbol) }
+          attr_reader :name
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :desc
+        end
+
+        module OptValue
+          extend T::Sig
+
+          sig { returns(T.any(NilClass, String, T::Array[String])) }
+          def default
+            if @default.is_a?(Proc)
+              @default.call
+            else
+              @default
+            end
+          end
+
+          sig { returns(T::Boolean) }
+          def dynamic_default?
+            @default.is_a?(Proc)
+          end
+
+          sig { returns(T::Boolean) }
+          def required?
+            @required
+          end
+
+          sig { returns(T::Boolean) }
+          def multi?
+            @multi
+          end
+
+          sig { returns(T::Boolean) }
+          def optional?
+            !required?
+          end
+        end
+
+        class Flag
+          extend T::Sig
+          include OptBase
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :short
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :long
+
+          sig { returns(String) }
+          def as_written_by_user
+            long ? "--#{long}" : "-#{short}"
+          end
+
+          sig { params(name: Symbol, short: T.nilable(String), long: T.nilable(String), desc: T.nilable(String)).void }
+          def initialize(name:, short: nil, long: nil, desc: nil)
+            if long&.start_with?('-') || short&.start_with?('-')
+              raise(ArgumentError, 'invalid - prefix')
+            end
+
+            @name = name
+            @short = short
+            @long = long
+            @desc = desc
+          end
+        end
+
+        class Position
+          extend T::Sig
+          include OptBase
+          include OptValue
+
+          sig do
+            params(
+              name: Symbol,
+              desc: T.nilable(String),
+              required: T::Boolean,
+              multi: T::Boolean,
+              default: T.any(NilClass, String, T.proc.returns(String)),
+              skip: T.any(
+                NilClass,
+                T.proc.returns(T::Boolean),
+                T.proc.params(arg0: String).returns(T::Boolean),
+              ),
+            ).void
+          end
+          def initialize(name:, desc:, required:, multi:, default: nil, skip: nil)
+            if multi && (default || required)
+              raise(ArgumentError, 'multi-valued positions cannot have a default or required value')
+            end
+
+            @name = name
+            @desc = desc
+            @required = required
+            @multi = multi
+            @default = default
+            @skip = skip
+          end
+
+          sig { params(arg: String).returns(T::Boolean) }
+          def skip?(arg)
+            if @skip.nil?
+              false
+            elsif T.must(@skip).arity == 0
+              T.cast(@skip, T.proc.returns(T::Boolean)).call
+            else
+              T.cast(@skip, T.proc.params(arg0: String).returns(T::Boolean)).call(arg)
+            end
+          end
+        end
+
+        class Option < Flag
+          extend T::Sig
+          include OptValue
+
+          sig do
+            params(
+              name: Symbol, short: T.nilable(String), long: T.nilable(String),
+              desc: T.nilable(String),
+              default: T.any(
+                NilClass,
+                String, T.proc.returns(String),
+                T::Array[String], T.proc.returns(T::Array[String])
+              ),
+              required: T::Boolean, multi: T::Boolean
+            ).void
+          end
+          def initialize(name:, short: nil, long: nil, desc: nil, default: nil, required: false, multi: false)
+            if multi && required
+              raise(ArgumentError, 'multi-valued options cannot have a required value')
+            end
+
+            super(name: name, short: short, long: long, desc: desc)
+            @default = default
+            @required = required
+            @multi = multi
+          end
+        end
+
+        sig { params(name: Symbol).returns(T.nilable(Flag)) }
+        def lookup_flag(name)
+          flagopt = @by_name[name]
+          if flagopt.class == Flag
+            flagopt
+          end
+        end
+
+        sig { params(name: Symbol).returns(T.nilable(Option)) }
+        def lookup_option(name)
+          flagopt = @by_name[name]
+          if flagopt.class == Option
+            flagopt
+          end
+        end
+
+        sig { params(name: String).returns(T.any(Flag, Option, NilClass)) }
+        def lookup_short(name)
+          raise(InvalidLookup, "invalid '-' prefix") if name.start_with?('-')
+
+          @by_short[name]
+        end
+
+        sig { params(name: String).returns(T.any(Flag, Option, NilClass)) }
+        def lookup_long(name)
+          raise(InvalidLookup, "invalid '-' prefix") if name.start_with?('-')
+
+          @by_long[name]
+        end
+
+        sig { params(name: Symbol).returns(T.nilable(Position)) }
+        def lookup_position(name)
+          position = @by_name[name]
+          if position.class == Position
+            position
+          end
+        end
+
+        private
+
+        sig { params(position: Position).void }
+        def validate_order(position)
+          raise(InvalidPosition, 'Cannot have any more positional arguments after multi') if @positions.last&.multi?
+        end
+
+        sig { params(short: String).returns(String) }
+        def strip_short_prefix(short)
+          unless short.match?(/^-[^-]/)
+            raise(InvalidFlag, "Short flag '#{short}' does not start with '-'")
+          end
+          if short.size != 2
+            raise(InvalidFlag, 'Short flag must be a single character')
+          end
+
+          short.sub(/^-/, '')
+        end
+
+        sig { params(long: String).returns(String) }
+        def strip_long_prefix(long)
+          unless long.match?(/^--[^-]/)
+            raise(InvalidFlag, "Long flag '#{long}' does not start with '--'")
+          end
+
+          long.sub(/^--/, '')
+        end
+
+        sig do
+          params(short: T.nilable(String), long: T.nilable(String))
+            .returns([T.nilable(String), T.nilable(String)])
+        end
+        def strip_prefixes_and_validate(short, long)
+          if short.nil? && long.nil?
+            raise(Error, 'One or more of short and long must be specified')
+          end
+
+          short = strip_short_prefix(short) if short
+          long = strip_long_prefix(long) if long
+
+          [short, long]
+        end
+
+        sig { params(flagopt: Flag).void }
+        def add_resolution(flagopt)
+          if flagopt.short
+            if (existing = @by_short[flagopt.short])
+              raise(ConflictingFlag, "Short flag '#{flagopt.short}' already defined by #{existing.name}")
+            end
+
+            @by_short[flagopt.short] = flagopt
+          end
+          if flagopt.long
+            if (existing = @by_long[flagopt.long])
+              raise(ConflictingFlag, "Long flag '#{flagopt.long}' already defined by #{existing.name}")
+            end
+
+            @by_long[flagopt.long] = flagopt
+          end
+          add_name_resolution(flagopt)
+        end
+
+        sig { params(arg: T.any(Flag, Position)).void }
+        def add_name_resolution(arg)
+          if (existing = @by_name[arg.name])
+            raise(ConflictingFlag, "Flag '#{arg.name}' already defined by #{existing.name}")
+          end
+
+          @by_name[arg.name] = arg
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,245 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module Args
+      class Evaluation
+        extend T::Sig
+
+        Error = Class.new(Args::Error)
+
+        class MissingRequiredOption < Error
+          extend T::Sig
+          sig { params(name: String).void }
+          def initialize(name)
+            super("missing required option `#{name}'")
+          end
+        end
+
+        class MissingRequiredPosition < Error
+          extend T::Sig
+          sig { void }
+          def initialize
+            super('more arguments required')
+          end
+        end
+
+        class TooManyPositions < Error
+          extend T::Sig
+          sig { void }
+          def initialize
+            super('too many arguments')
+          end
+        end
+
+        class FlagProxy
+          extend T::Sig
+
+          sig { params(sym: Symbol).returns(T::Boolean) }
+          def method_missing(sym)
+            flag = @evaluation.defn.lookup_flag(sym)
+            unless flag
+              raise NoMethodError, "undefined flag `#{sym}' for #{self}"
+            end
+
+            @evaluation.send(:lookup_flag, flag)
+          end
+
+          sig { params(sym: Symbol, include_private: T::Boolean).returns(T::Boolean) }
+          def respond_to_missing?(sym, include_private = false)
+            !!@evaluation.defn.lookup_flag(sym)
+          end
+
+          sig { params(evaluation: Evaluation).void }
+          def initialize(evaluation)
+            @evaluation = evaluation
+          end
+        end
+
+        class OptionProxy
+          extend T::Sig
+
+          sig { params(sym: Symbol).returns(T.any(NilClass, String, T::Array[String])) }
+          def method_missing(sym)
+            opt = @evaluation.defn.lookup_option(sym)
+            unless opt
+              raise NoMethodError, "undefined option `#{sym}' for #{self}"
+            end
+
+            @evaluation.send(:lookup_option, opt)
+          end
+
+          sig { params(sym: Symbol, include_private: T::Boolean).returns(T::Boolean) }
+          def respond_to_missing?(sym, include_private = false)
+            !!@evaluation.defn.lookup_option(sym)
+          end
+
+          sig { params(evaluation: Evaluation).void }
+          def initialize(evaluation)
+            @evaluation = evaluation
+          end
+        end
+
+        class PositionProxy
+          extend T::Sig
+
+          sig { params(sym: Symbol).returns(T.any(NilClass, String, T::Array[String])) }
+          def method_missing(sym)
+            position = @evaluation.defn.lookup_position(sym)
+            unless position
+              raise NoMethodError, "undefined position `#{sym}' for #{self}"
+            end
+
+            @evaluation.send(:lookup_position, position)
+          end
+
+          sig { params(sym: Symbol, include_private: T::Boolean).returns(T::Boolean) }
+          def respond_to_missing?(sym, include_private = false)
+            !!@evaluation.defn.lookup_position(sym)
+          end
+
+          sig { params(evaluation: Evaluation).void }
+          def initialize(evaluation)
+            @evaluation = evaluation
+          end
+        end
+
+        sig { returns(FlagProxy) }
+        def flag
+          @flag_proxy ||= FlagProxy.new(self)
+        end
+
+        sig { returns(OptionProxy) }
+        def opt
+          @option_proxy ||= OptionProxy.new(self)
+        end
+
+        sig { returns(PositionProxy) }
+        def position
+          @position_proxy ||= PositionProxy.new(self)
+        end
+
+        sig { returns(Definition) }
+        attr_reader :defn
+
+        sig { returns(T::Array[Parser::Node]) }
+        attr_reader :parse
+
+        sig { returns(T::Array[String]) }
+        def unparsed
+          @unparsed ||= begin
+            nodes = T.cast(
+              parse.select { |node| node.is_a?(Parser::Node::Unparsed) },
+              T::Array[Parser::Node::Unparsed],
+            )
+            nodes.flat_map(&:value)
+          end
+        end
+
+        sig { params(defn: Definition, parse: T::Array[Parser::Node]).void }
+        def initialize(defn, parse)
+          @defn = defn
+          @parse = parse
+          check_required_options!
+        end
+
+        sig { void }
+        def check_required_options!
+          @defn.options.each do |opt|
+            next unless opt.required?
+
+            node = @parse.detect do |node|
+              node.is_a?(Parser::Node::Option) && node.name == opt.name
+            end
+            if !node || T.cast(node, Parser::Node::Option).value.nil?
+              raise(MissingRequiredOption, opt.as_written_by_user)
+            end
+          end
+        end
+
+        sig { void }
+        def resolve_positions!
+          args_i = 0
+          @position_values = Hash.new
+          @defn.positions.each do |position|
+            raise(MissingRequiredPosition) if position.required? && args_i >= args.size
+            next if args_i >= args.size || position.skip?(T.must(args[args_i]))
+
+            if position.multi?
+              @position_values[position.name] = args[args_i..]
+              args_i = args.size
+            else
+              @position_values[position.name] = T.must(args[args_i])
+              args_i += 1
+            end
+          end
+          raise(TooManyPositions) if args_i < args.size
+        end
+
+        sig { params(flag: Definition::Flag).returns(T::Boolean) }
+        def lookup_flag(flag)
+          if flag.short
+            flags = T.cast(
+              parse.select { |node| node.is_a?(Parser::Node::ShortFlag) },
+              T::Array[Parser::Node::ShortFlag],
+            )
+            return true if flags.any? { |node| node.value == flag.short }
+          end
+          if flag.long
+            flags = T.cast(
+              parse.select { |node| node.is_a?(Parser::Node::LongFlag) },
+              T::Array[Parser::Node::LongFlag],
+            )
+            return true if flags.any? { |node| node.value == flag.long }
+          end
+          false
+        end
+
+        sig { params(opt: Definition::Option).returns(T.any(NilClass, String, T::Array[String])) }
+        def lookup_option(opt)
+          if opt.short
+            opts = T.cast(
+              parse.select { |node| node.is_a?(Parser::Node::ShortOption) },
+              T::Array[Parser::Node::ShortOption],
+            )
+            matches = opts.select { |node| node.name == opt.short }
+            if (last = matches.last)
+              return(opt.multi? ? matches.map(&:value) : last.value)
+            end
+          end
+          if opt.long
+            opts = T.cast(
+              parse.select { |node| node.is_a?(Parser::Node::LongOption) },
+              T::Array[Parser::Node::LongOption],
+            )
+            matches = opts.select { |node| node.name == opt.long }
+            if (last = matches.last)
+              return(opt.multi? ? matches.map(&:value) : last.value)
+            end
+          end
+          opt.default
+        end
+
+        sig { params(position: Definition::Position).returns(T.any(NilClass, String, T::Array[String])) }
+        def lookup_position(position)
+          @position_values.fetch(position.name) { position.multi? ? [] : position.default }
+        end
+
+        private
+
+        sig { returns(T::Array[String]) }
+        def args
+          @args ||= begin
+            nodes = T.cast(
+              parse.select { |node| node.is_a?(Parser::Node::Argument) },
+              T::Array[Parser::Node::Argument],
+            )
+            nodes.map(&:value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    module Args
+      class Parser
+        class Node
+          extend T::Sig
+
+          sig { void }
+          def initialize
+          end
+
+          sig { params(other: T.untyped).returns(T::Boolean) }
+          def ==(other)
+            self.class == other.class
+          end
+
+          class Option < Node
+            extend T::Sig
+
+            sig { returns(String) }
+            attr_reader :name
+
+            sig { returns(String) }
+            attr_reader :value
+
+            sig { params(name: String, value: String).void }
+            def initialize(name, value)
+              @name = name
+              @value = value
+              super()
+            end
+            private_class_method(:new) # don't instantiate this class directly
+
+            sig { returns(String) }
+            def inspect
+              "#<#{self.class.name} #{@name}=#{@value}>"
+            end
+
+            sig { params(other: T.untyped).returns(T::Boolean) }
+            def ==(other)
+              !!(super(other) && @value == other.value && @name == other.name)
+            end
+          end
+
+          class LongOption < Option
+            public_class_method(:new)
+          end
+
+          class ShortOption < Option
+            public_class_method(:new)
+          end
+
+          class Flag < Node
+            sig { returns(String) }
+            attr_reader :value
+
+            sig { params(value: String).void }
+            def initialize(value)
+              @value = value
+              super()
+            end
+            private_class_method(:new) # don't instantiate this class directly
+
+            sig { returns(String) }
+            def inspect
+              "#<#{self.class.name} #{@value}>"
+            end
+
+            sig { params(other: T.untyped).returns(T::Boolean) }
+            def ==(other)
+              !!(super(other) && @value == other.value)
+            end
+          end
+
+          class LongFlag < Flag
+            public_class_method(:new)
+          end
+
+          class ShortFlag < Flag
+            public_class_method(:new)
+          end
+
+          class Argument < Node
+            sig { returns(String) }
+            attr_reader :value
+
+            sig { params(value: String).void }
+            def initialize(value)
+              @value = value
+              super()
+            end
+
+            sig { returns(String) }
+            def inspect
+              "#<#{self.class.name} #{@value}>"
+            end
+
+            sig { params(other: T.untyped).returns(T::Boolean) }
+            def ==(other)
+              !!(super(other) && @value == other.value)
+            end
+          end
+
+          class Unparsed < Node
+            sig { returns(T::Array[String]) }
+            attr_reader :value
+
+            sig { params(value: T::Array[String]).void }
+            def initialize(value)
+              @value = value
+              super()
+            end
+
+            sig { returns(String) }
+            def inspect
+              "#<#{self.class.name} #{@value.join(" ")}>"
+            end
+
+            sig { params(other: T.untyped).returns(T::Boolean) }
+            def ==(other)
+              !!(super(other) && @value == other.value)
+            end
+          end
+        end
+      end
+    end
+  end
+end