run_kit 0.1.0

data/lib/run_kit/options/flag.rb

@@ -0,0 +1,135 @@
+#
+# One configured flag, including all switches that invoke it.
+#
+
+module RunKit
+  module Options
+    class Flag
+      # --foo or -f
+      SWITCH_RE = /\A-(\w|-\w[\w-]*)\z/
+      # --foo=bar
+      INLINE_RE = /\A-(\w|-\w[\w-]*)=(.*)\z/m
+      # --no-foo
+      NEGATE_RE = /\A--no-(\w[\w-]*)\z/
+
+      KINDS = %i[bool float int path str sym]
+
+      attr_reader :choices, :default, :help, :kind, :meta, :required, :switches
+
+      # ctor
+      def initialize(kind, opts, default: nil, required: false, choices: nil)
+        @choices, @kind, @required = choices, kind, required
+
+        # extract @help from last string
+        @switches = opts.dup
+        @help = if switch && !switch.start_with?("-")
+          switches.pop
+        end
+
+        # Extract meta from the final switch, if written as `--port <int>`.
+        @meta = build_meta
+
+        # default, with some special handling for bool
+        @default = default
+        if bool? && default.nil? && !required?
+          @default = false
+        end
+
+        validate
+      end
+
+      #
+      # parsing
+      #
+
+      # Parse a single cli param
+      def parse(switch, param)
+        if bool?
+          raise Error, "option '#{switch}=#{param}' does not take a value" if param
+          return true
+        end
+
+        raise Error, "option '#{switch}' requires a value" if !param
+        parsed = begin
+          case kind
+          when :float then Float(param)
+          when :int then Integer(param, 10)
+          when :path then Pathname.new(param)
+          when :str then param
+          when :sym then param.to_sym
+          end
+        rescue ArgumentError
+          raise Error, "invalid value '#{param}' for option '#{switch}'"
+        end
+
+        if choices && !choices.include?(parsed)
+          raise Error, "invalid value '#{parsed}' for option '#{switch}', must be one of #{choices.join(", ")}"
+        end
+        parsed
+      end
+
+      # one-liners
+      def bool? = kind == :bool
+      def key = @key ||= switch.sub(/^-+/, "").tr("-", "_").to_sym
+      def switch = switches.last
+      def takes_param? = !bool?
+      alias_method :required?, :required
+
+      protected
+
+      #
+      # validation
+      #
+
+      def validate
+        # switches
+        raise ArgumentError, "at least one switch is required" if switches.empty?
+        switches.each do
+          raise ArgumentError, "invalid switch: #{_1}" unless _1.is_a?(String)
+          raise ArgumentError, "invalid switch: #{_1}" unless _1.match?(SWITCH_RE)
+        end
+        raise ArgumentError, "duplicate switch" unless switches.uniq.length == switches.length
+
+        # params
+        raise ArgumentError, "invalid flag kind: #{kind}" unless KINDS.include?(kind)
+        raise ArgumentError, "boolean flags do not accept meta" if bool? && meta
+        raise ArgumentError, "required must be true or false" unless required == true || required == false
+        raise ArgumentError, "required flags cannot have defaults" if required && default != nil
+        raise ArgumentError, "invalid default #{default.inspect} for #{kind}" if default != nil && !allowed?(default)
+
+        # choices
+        if choices
+          raise ArgumentError, "choices must be an array" unless choices.is_a?(Array)
+          raise ArgumentError, "choices cannot be empty" if choices.empty?
+          choices.each do
+            raise ArgumentError, "invalid choice #{_1.inspect} for #{kind}" unless allowed?(_1)
+          end
+        end
+      end
+
+      #
+      # helpers
+      #
+
+      def build_meta
+        # Only the final spelling may carry an inferred `<meta>`.
+        if (m = /\A(\S+) <([^>]+)>\z/.match(switch))
+          switches[switches.length - 1] = m[1]
+          return m[2]
+        end
+        kind.to_s unless bool?
+      end
+
+      def allowed?(candidate)
+        case kind
+        when :bool then candidate == true || candidate == false
+        when :float then candidate.is_a?(Float)
+        when :int then candidate.is_a?(Integer)
+        when :path then candidate.is_a?(Pathname)
+        when :str then candidate.is_a?(String)
+        when :sym then candidate.is_a?(Symbol)
+        end
+      end
+    end
+  end
+end

data/lib/run_kit/options/help.rb

@@ -0,0 +1,85 @@
+#
+# Renders the generated help text. Most of the fiddly work here is keeping
+# columns aligned while ANSI color is present.
+#
+
+module RunKit
+  module Options
+    class Help
+      INDENT = 2
+
+      attr_reader :config, :width
+
+      def initialize(config, width = nil)
+        @config = config
+        @width = (width || Term.winsize[1]).clamp(60, 100)
+      end
+
+      # Render generated help, unless the caller supplied complete help text.
+      def to_s
+        return config.help if config.help
+
+        # usage: xyz (banner)
+        buf = StringIO.new
+        buf << banner
+        buf << "\n"
+        buf << "\n" if config.separators.any? { _1.first.zero? }
+
+        # Render each flag with aligned switch labels and wrapped help text.
+        label_width = widest_label
+        config.flags.each.with_index do |flag, idx|
+          buf << separator_text(idx) # sep
+
+          # left
+          label = flag_label(flag)
+          buf << " " * INDENT
+          buf << label
+
+          # right
+          if flag.help
+            buf << " " * (label_width - Term.width(label) + 2)
+            indent = INDENT + label_width + 2
+            buf << Term.wrap(flag.help, width - indent).gsub("\n", "\n#{" " * indent}")
+          end
+          buf << "\n"
+        end
+        buf << separator_text(config.flags.length)
+
+        buf.string
+      end
+
+      # Build the usage line from the configured app name and positionals.
+      def banner
+        text = config.banner
+        text ||= [color.blue("Usage:"), color.green(config.app_name), "[options]"].tap do
+          _1.push(*config.positionals.map(&:meta))
+        end.join(" ")
+        Term.wrap(text, width)
+      end
+
+      # Render separator text at its recorded position between flags.
+      def separator_text(position)
+        StringIO.new.tap do |buf|
+          config.separators.each do |(pos, str)|
+            if pos == position
+              buf << color.blue(str)
+              buf << "\n"
+            end
+          end
+        end.string
+      end
+
+      # one-liners
+      def color = @color ||= Color.new(config.color)
+      def widest_label = config.flags.map { Term.width(flag_label(_1)) }.max
+
+      protected
+
+      def flag_label(flag)
+        label = flag.switches.map { color.green(_1) }.join(", ")
+        return label unless flag.takes_param?
+        "#{label} #{color.yellow("<#{flag.meta}>")}"
+      end
+    end
+  end
+end

data/lib/run_kit/options/main.rb

@@ -0,0 +1,82 @@
+#
+# Main entry point and parsing
+#
+#
+# Glossary
+#
+# | term       | meaning                            | example                   |
+# |------------|------------------------------------|---------------------------|
+# | flag       | configured cli flag                | o.int "-p", "--port"      |
+# | switch     | dashed string invoking a flag      | -p or --port              |
+# | key        | result field derived from a switch | --http-port => :http_port |
+# | param      | raw input consumed by a flag       | 8080 from --port=8080     |
+# | -          | -                                  | -                         |
+# | app_name   | program name used in output        | "curl"                    |
+# | banner     | usage text at top of help          | Usage: curl [options]     |
+# | meta       | placeholder shown for a param      | <xxx> from `--port <xxx>` |
+# | positional | configured required param slot     | o.positional "<url>"      |
+# | separator  | help section heading               | "Network:"                |
+#
+
+module RunKit
+  module Options
+    class Main
+      attr_reader :config
+
+      def initialize = @config = Config.new
+      def app_name = config.app_name
+
+      # Parse argv and turn internal parser outcomes into CLI behavior.
+      def parse(argv)
+        config.prepare!
+
+        begin
+          options = Parser.new(config).parse(argv)
+          klass = Data.define(*options.keys)
+          klass.new(**options)
+        rescue Error => ex
+          warn "#{app_name}: #{ex.message}"
+          warn "#{app_name}: try '#{app_name} --help' for more information"
+          exit_fn(1, error: ex.message)
+        rescue HelpRequested, NakedRequested, VersionRequested => ex
+          early_exit(ex)
+          exit_fn(0)
+        end
+      end
+
+      protected
+
+      def early_exit(ex)
+        case ex
+        when HelpRequested
+          puts Help.new(config)
+        when NakedRequested
+          puts "#{app_name}: try '#{app_name} --help' for more information"
+        when VersionRequested
+          puts "#{app_name} #{config.version}"
+        end
+      end
+
+      def exit_fn(status, error: nil)
+        args = [].tap do
+          _1 << status
+          _1 << error if config.exit.arity == 2
+        end
+        config.exit.call(*args)
+        nil
+      end
+    end
+
+    class Error < StandardError; end
+
+    # early exits
+    class HelpRequested < Exception; end # rubocop:disable Lint/InheritException
+    class NakedRequested < Exception; end # rubocop:disable Lint/InheritException
+    class VersionRequested < Exception; end # rubocop:disable Lint/InheritException
+
+    # main entry point
+    def self.parse(argv = ARGV)
+      Main.new.tap { yield _1.config if block_given? }.parse(argv)
+    end
+  end
+end

data/lib/run_kit/options/parser.rb

@@ -0,0 +1,142 @@
+#
+# Turns argv into a typed result. It knows the CLI grammar but stays away from
+# printing and exiting.
+#
+
+module RunKit
+  module Options
+    class Parser
+      attr_reader :config, :options, :queue
+
+      def initialize(config)
+        @config = config
+      end
+
+      # Reset transient state, parse argv, and assemble the result.
+      def parse(argv)
+        @options, @queue = config.defaults, argv.dup
+        parse_queue
+        validate!
+        options
+      end
+
+      protected
+
+      #
+      # main parser
+      #
+
+      def parse_queue
+        raise NakedRequested if config.naked? && queue.empty?
+
+        # any non-flags we find below
+        operands = []
+
+        # process argv as queue
+        while (item = queue.shift)
+          case item
+          when Flag::SWITCH_RE, Flag::INLINE_RE then parse_switch(item, Regexp.last_match)
+          when /\A-[^-]/ then parse_smashed(item)
+          when "", /\A[^-]/ then operands << item
+          when "--" then break operands.concat(queue)
+          else; raise Error, "unexpected argument '#{item}' found"
+          end
+        end
+
+        # add pred? for bools
+        config.flags.filter_map { _1.key if _1.bool? }.each do
+          options[:"#{_1}?"] = options[_1] if options.key?(_1)
+        end
+
+        # positionals
+        config.positionals.each do
+          options[_1.key] = operands.shift
+        end
+
+        # _args
+        options[:_args] = operands
+      end
+
+      #
+      # -x or -x=123 or --xyz or --xyz=123 or --no-xyz
+      #
+
+      def parse_switch(item, match)
+        switch = "-#{match[1]}"
+        param = match[2]
+        separator = param ? "=" : ""
+
+        # -x or --xyz?
+        if (flag = config.flag(switch))
+          builtin!(flag)
+          param = queue.shift if flag.takes_param? && separator.empty?
+          options[flag.key] = flag.parse(switch, param)
+          return
+        end
+
+        # --no-xyz?
+        if (neg = find_negated_flag(switch))
+          raise Error, "option '#{item}' does not take a value" if separator == "="
+          options[neg.key] = false
+          return
+        end
+
+        raise Error, "unexpected argument '#{item}' found"
+      end
+
+      #
+      # smashed flags
+      #
+
+      # Expand short-switch groups such as `-qv`. A parameter-taking switch ends
+      # the group and consumes either its attached suffix or the next queue item.
+      def parse_smashed(group)
+        (1...group.length).each do |idx|
+          switch = "-#{group[idx]}"
+          flag = config.flag(switch)
+          raise Error, "unexpected argument '#{group}' found" unless flag
+          builtin!(flag)
+
+          # For `-qnLee`, `Lee` belongs to `-n`; for `-qn Lee`, shift the queue.
+          if flag.takes_param?
+            param = if idx + 1 < group.length
+              group[idx + 1...group.length]
+            else
+              queue.shift
+            end
+            options[flag.key] = flag.parse(switch, param)
+            return
+          end
+
+          # bool
+          options[flag.key] = true
+        end
+      end
+
+      #
+      # helpers
+      #
+
+      def builtin!(flag)
+        raise HelpRequested if flag == config.help_flag
+        raise VersionRequested if flag == config.version_flag
+      end
+
+      def find_negated_flag(switch)
+        if (m = Flag::NEGATE_RE.match(switch))
+          flag = config.flag("--#{m[1]}")
+          flag if flag&.bool?
+        end
+      end
+
+      def validate!
+        config.required.each do
+          raise Error, "required option '#{_1.switch}' is missing" if !options.key?(_1.key)
+        end
+        config.positionals.each do
+          raise Error, "required argument '#{_1.meta}' is missing" if !options[_1.key]
+        end
+      end
+    end
+  end
+end

data/lib/run_kit/options/positional.rb

@@ -0,0 +1,23 @@
+#
+# A required positional param like `<url>`.
+#
+
+module RunKit
+  module Options
+    class Positional
+      POSITIONAL_RE = /\A<([A-Z]\w*)>\z/i
+
+      attr_reader :help, :meta
+
+      def initialize(meta:, help:)
+        @help, @meta = help, meta
+        raise ArgumentError, "positional help must be a string" unless help.is_a?(String)
+        raise ArgumentError, "positional meta must be a string" unless meta.is_a?(String)
+        raise ArgumentError, "positional must use <meta>" unless POSITIONAL_RE.match?(meta)
+      end
+
+      # one-liners
+      def key = @key ||= POSITIONAL_RE.match(meta)[1].to_sym
+    end
+  end
+end

data/lib/run_kit/options.rb

@@ -0,0 +1,7 @@
+require_relative "options/color"
+require_relative "options/config"
+require_relative "options/flag"
+require_relative "options/help"
+require_relative "options/main"
+require_relative "options/parser"
+require_relative "options/positional"