strop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7e4c1b959f079ed2beb07575918ae878b23051fa8fabd983e346aef8b340223
+  data.tar.gz: 88366bb7a1b7bf57328fd9a149e2b21c61b052508155a84d48e286e87d323550
+SHA512:
+  metadata.gz: ea8491685f9edebf4364c96886c1ab18cca85d628306ed2fbd76827cc7b1db06b8021851db33e2b337d765805700c12e6bf80e4e4d5479886818654d35f6c566
+  data.tar.gz: c14c0ac725fd9530adc4eaf474c142218c1f8eb88001de14907b34d79ee29db15564f535eb6d41dadffc5a7cd3b3cfe42fbaa8a73d7d46d8fcdf7a3c5ab94bd0

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Caio Chassot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,150 @@
+# Strop: Command-line Option Parser
+
+## Distinctive features
+
+- Build options from parsing help text, instead of the other way around
+- Pattern matching for result processing (with `case`/`in …`)
+
+## Core workflow
+
+```ruby
+opts = Optlist.from_help(help_text)  # extract from help
+result = Strop.parse(opts, ARGV)     # parse argv -> Result
+result = Strop.parse!(opts, ARGV)    # same but on error prints message and exits
+result = Strop.parse!(help_text)     # Automatically parse help text, ARGV default
+```
+
+## Processing parsed results
+
+```ruby
+Strop.parse!(help).each do |item|
+  case item
+  in Strop::Opt[label: "help"]               then show_help
+  in Strop::Opt[label: "verbose", value:]    then set_verbose(value)
+  in Strop::Opt[label: "output", value: nil] then output = :stdout
+  in Strop::Opt[label: "color"]              then item.no? ? disable_color : enable_color
+  in Strop::Arg[value:]                      then files << value
+  in Strop::Sep                              then break
+  end
+end
+```
+
+Or, more succinctly:
+
+```ruby
+Strop.parse!(help).each do |item|
+  case item
+  in label: "help" then show_help     # only Opt has .label
+  in arg:          then files << arg  # `value:` might match an Opt, so Arg offters alias .arg
+  end
+end
+```
+
+You can generate the case expression above with:
+
+```ruby
+puts Strop::Optlist.from_help(help_text).to_s(:case)
+```
+
+
+## Result members (Array of Opt, Arg, Sep)
+
+```ruby
+res.opts                             # all Opt objects
+res.args                             # all Arg objects
+res.rest                             # args after -- separator
+res["flag"]                          # find opt by name
+
+opt = res.opts.first
+arg = res.args.first
+opt.decl                             # Optdecl matched for this Opt instance
+opt.name                             # name used in invocation (could differ from label)
+opt.value                            # argument passed to this option
+opt.label                            # primary name (first long name or first name), used for pattern matching
+opt.no?                              # true if --no-foo variant used
+opt.yes?                             # opposite of `no?`
+arg.value                            # positional argument
+arg.arg                              # same as .value, useful for pattern matching
+Sep                                  # -- end of options marker; Const, not instantiated
+```
+
+Notice that parsing `--[no-]flag` from help results in a single `Optdecl[:flag, :"no-flag"]`, and you can use `yes?`/`no?` to check which was passed.
+
+
+## Help text format for parsing
+
+Auto-extracts indented option lines from help:
+
+```
+Options:
+  -f, --flag              Flag
+  -v, --verbose LEVEL     Required arg
+  -o, --output [FILE]     Optional arg
+  --color=MODE            Optional with =
+  --debug[=LEVEL]         Required/optional with =
+  --[no-]quiet            --quiet/--no-quiet pair
+  --[no]force             --force/--noforce pair
+```
+
+By default `parse_help` expects options to be indented by 2 or 4 spaces. Override with:
+
+```ruby
+Strop.parse_help(text, pad: / {6}/)  # 6 spaces exactly
+Strop.parse_help(text, pad: /\t/)    # tabs ????
+```
+
+Use at least two spaces before description, and only a single space before args.
+
+```
+  --file  PATH                       # !! PATH seen as description and ignored, --file considered a flag (no arg)
+  --quiet Supresses output           # !! interpreted as --quiet=Supresses
+```
+
+The latter case is detected and a warning is printed, but best to avoid this situation altogether.
+
+## Command-line parsing features
+
+```bash
+cmd -abc                              # short option clumping (-a -b -c)
+cmd -fVAL, --foo=VAL                  # attached values
+cmd -f VAL, --foo VAL                 # separate values
+cmd --foo val -- --bar                # --bar becomes positional after --
+cmd --intermixed args and --options   # flexible ordering
+```
+
+## Manual option declaration building
+
+```ruby
+Optdecl[:f]                           # flag only: -f
+Optdecl[:f?]                          # optional arg: -f [X]
+Optdecl[:f!]                          # required arg: -f x
+Optdecl[:f, :foo]                     # multiple names: -f or --foo
+Optdecl[:f?, :foo]                    # multiple + arg modifier: use ?/! only on first
+Optdecl[:f?, :foo?]                   # so this will result in -f, --foo?
+Optdecl[:f, :foo, arg: :may]          # explicit arg form: --foo [ARG]
+Optdecl[:?, arg: :shant]              # explicit form allows using ?/! in option name: -?
+Optdecl[:foo_bar]                     # --foo-bar: Underscores in symbol names get replaced with `-`
+Optdecl["foo_bar"]                    # --foo_bar: but not in strings.
+```
+
+### Option lists:
+
+```ruby
+optlist = Optlist[optdecl1, optdecl2] # combine decls into optlist
+optlist["f"]                          # lookup by name
+```
+
+## Argument requirements
+
+- `:shant` - no argument allowed
+- `:may`   - optional argument (takes next token if not option-like)
+- `:must`  - required argument (error if missing)
+
+## Adding hidden options
+
+If you want to use `parse_help` mainly, but need secret options:
+
+```ruby
+optlist = Strop.parse_help HELP
+optlist << Optdecl[:D, :debug]
+```

data/lib/strop/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Strop
+  VERSION = "0.1.0"
+end

data/lib/strop.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+# require "debug"; DEBUGGER__.add_catch_breakpoint "Exception"
+require_relative "strop/version"
+
+module Strop
+
+  Optdecl = Data.define(:names, :arg, :label) do
+    def self.[](*names, arg: nil) = new(names:, arg:)
+    def initialize(names:, arg: nil)
+      names = [*names].map{ Symbol === it ? it.to_s.gsub(?_, ?-) : it } # :foo_bar to "foo-bar" for symbols
+      names[0] = names[0].sub(/[!?]$/, "") unless arg                   # opt? / opt! to opt, and... (unless arg given)
+      arg ||= { ?? => :may, ?! => :must }[$&] || :shant                 # use ?/! to determine arg (unless arg given)
+      label = names.find{ it.size > 1 } || names.first                  # the canonical name used to search for it
+      %i[must may shant].member? arg or raise "invalid arg"             # validate arg
+      super names:, arg:, label:
+    end
+
+    def no?  = names.each_cons(2).any?{|a,b| b =~ /\Ano-?#{Regexp.escape a}\z/ } # is a flag like --[no-]foo, --[no]bar
+    def arg? = self.arg != :shant # accepts arg
+    def arg! = self.arg == :must  # requires arg
+    def to_s = names.map{ (it[1] ? "--" : "-")+it }.join(", ") + { must: " X", may: " [X]", shant: "" }[arg]
+  end
+
+  class Optlist < Array # a list of Optdecls
+    def self.from_help(doc) = Strop.parse_help(doc)
+    def [](k, ...) = [String, Symbol].any?{ it === k } ? self.find{ it.names.member? k.to_s } : super(k, ...)
+    def to_s(as=:plain)
+      case as
+      when :plain then join("\n")
+      when :case
+        caseins = map{|os| "in label: #{os.label.inspect}".tap{ it << ", value:" if os.arg? }}
+        len = caseins.map(&:size).max
+        caseins = caseins.zip(self).map{ |s,o| s.ljust(len) + " then#{' opt.no?' if o.no?} # #{o}" }
+        <<~RUBY
+          for item in Strop.parse!(optlist)
+            case item
+            #{caseins.map{ "  #{it}" }.join("\n").lstrip}
+            case Strop::Arg[value:] then
+            case Strop::Sep then break # if you want to handle result.rest separately
+            else raise "Unhandled result \#{item}"
+            end
+          end
+        RUBY
+      end
+    end
+  end
+
+
+  Arg = Data.define :value, :arg do
+    def initialize(value:) = super(value:, arg: value)
+    alias to_s value
+  end
+
+  Opt = Data.define :decl, :name, :value, :label, :no do
+    def initialize(decl:, name:, value: nil)
+      label = decl.label                              # repeated here so can be pattern-matched against in case/in
+      no = name =~ /\Ano-?/ && decl.names.member?($') # flag given in negated version: (given --no-foo and also accepts --foo)
+      super(decl:, name:, value:, label:, no: !!no)
+    end
+    alias no? no
+    def yes? = !no?
+  end
+
+  Sep = :end_marker
+
+  # for debugging only, TODO remove later probably
+  class Arg
+    def encode_with(coder) = (coder.scalar = self.value; coder.tag = nil)
+  end
+  class Opt
+    def encode_with(coder) = (coder.map = { self.name => self.value }; coder.tag = nil)
+  end
+
+
+  module Exports
+    Optlist = Strop::Optlist
+    Optdecl = Strop::Optdecl
+    Opt     = Strop::Opt
+    Arg     = Strop::Arg
+    Sep     = Strop::Sep
+  end
+
+  class Result < Array # of Opt, Arg, Sep
+    def rest = drop_while{ it != Sep }.drop(1) # args after sep
+    def args = Result.new(select { Arg === it })
+    def opts = Result.new(select { Opt === it })
+    def [](k, ...)
+      case k
+      when String, Symbol then find{ Opt === it && it.decl.names.member?(k.to_s) }
+      else super(k, ...)
+      end
+    end
+  end
+
+  class Unreachable < RuntimeError; end
+  class OptionError < ArgumentError; end
+
+  def self.parse(optlist, argv=ARGV)
+    Array === argv && argv.all?{ String === it } or raise "argv must be an array of strings (given #{argv.class})"
+    optlist = case optlist
+    when IO      then parse_help(optlist.read)
+    when String  then parse_help(optlist)
+    when Optlist then optlist
+    else raise "optlist must be an Optlist or help text (given #{optlist.class})"
+    end
+    tokens = argv.dup
+    res = Result.new
+    ctx = :top
+    name, token, opt = nil
+    rx_value = /\A[^-]|\A\z/
+    loop do
+      case ctx
+      when :end then return res.concat tokens.map{ Arg[it] } # opt parsing ended, rest is positional args
+      when :value then ctx = :top; res << Arg[token]         # interspersed positional arg amidst opts
+
+      when :top
+        token = tokens.shift or next ctx = :end                                   # next token or done
+        case token
+        when "--"          then ctx = :end; res << Sep                            # end of options
+        when /\A--(.+)\z/m then token, ctx = $1, :long                            # long (--foo, --foo xxx), long with attached value (--foo=xxx)
+        when /\A-(.+)\z/m  then token, ctx = $1, :short                           # short or clump (-a, -abc)
+        when rx_value      then ctx = :value                                      # value
+        else raise Unreachable
+        end
+
+      when :long
+        name, value = token =~ /\A(.*?)=/m ? [$1, $'] : [token, nil]
+        opt = optlist[name] or raise OptionError, "Unknown option: --#{name}"
+        case
+        when  opt.arg? &&  value then ctx = :top; res << Opt[opt, name, value]    # --foo=XXX
+        when !opt.arg? && !value then ctx = :top; res << Opt[opt, name]           # --foo
+        when  opt.arg? && !value then ctx = :arg                                  # --foo XXX
+        when !opt.arg? &&  value then raise OptionError, "Option --#{name} takes no argument"
+        else raise Unreachable
+        end
+
+      when :short
+        name, token = token[0], token[1..].then{ it != "" ? it : nil }            # -abc -> a, bc
+        opt = optlist[name] or raise OptionError, "Unknown option: -#{name}"
+        case
+        when  opt.arg? &&  token then ctx = :top; res << Opt[opt, name, token]    # -aXXX
+        when !opt.arg? && !token then ctx = :top; res << Opt[opt, name]           # end of -abc
+        when  opt.arg? && !token then ctx = :arg                                  # -a XXX
+        when !opt.arg? &&  token then res << Opt[opt, name]                       # -abc -> took -a, will parse -bc
+        else raise Unreachable
+        end
+
+      when :arg
+        token = tokens[0]&.=~(rx_value) ? tokens.shift : nil
+        case
+        when opt.arg! && !token then raise OptionError, "Expected argument for option -#{?- if name[1]}#{name}" # --req missing value
+        when opt.arg! &&  token then ctx = :top; res << Opt[opt, name, token]     # --req val
+        when opt.arg? &&  token then ctx = :top; res << Opt[opt, name, token]     # --opt val
+        when opt.arg? && !token then ctx = :top; res << Opt[opt, name]            # --opt followed by --foo, --opt as last token
+        else raise Unreachable
+        end
+
+      else raise Unreachable
+      end
+    end
+  end
+
+  def self.parse!(...) # same but catches errors, print msg, exit
+    parse(...)
+  rescue OptionError => e
+    $stderr.puts e.message
+    exit 1
+  end
+
+
+  RX_SOARG = /\[\S+?\]/                        # short opt optional arg
+  RX_SARG  = /[^\s,]+/                         # short opt required arg
+  RX_LOARG = /\[=\S+?\]| #{RX_SOARG}/          # long opt optional arg: --foo[=bar] or --foo [bar]
+  RX_LARG  = /[ =]#{RX_SARG}/                  # long opt required arg: --foo=bar or --foo bar
+  RX_NO    = /\[no-?\]/                        # prefix for --[no-]flags
+  RX_SOPT  = /-[^-\s,](?: (?:#{RX_SOARG}|#{RX_SARG}))?/                      # full short opt
+  RX_LOPT  = /--(?=[^-=,\s])#{RX_NO}?[^\s=,\[]+(?:#{RX_LOARG}|#{RX_LARG})?/  # full long opt
+  RX_OPT   = /#{RX_SOPT}|#{RX_LOPT}/           # either opt
+  RX_OPTS  = /#{RX_OPT}(?:, {0,2}#{RX_OPT})*/  # list of opts, comma separated
+
+  def self.parse_help(help, pad: /(?:  ){1,2}/)
+    help.scan(/^#{pad}(#{RX_OPTS})(.*)/).map do |line, rest| # get all opts lines
+      # Ambiguous: --opt Desc with only one space before will interpret "Desc" as arg.
+      if rest =~ /^ \S/ && line =~ / (#{RX_SARG})$/ # desc preceeded by sringle space && last arg is " "+word. Capture arg name
+        $stderr.puts "#{$1.inspect} was interpreted as argument, In #{(line+rest).inspect}. Use at least two spaces before description to avoid this warning."
+      end
+      line.scan(RX_OPT).map do |opt|    # take options from each line
+        opt.split(/(?=\[=)|=| +/, 2)    # separate name from arg
+      end.map do |name, arg|            # remove opt markers -/--, transform arg str into requirement
+        [name.sub(/^--?/, ''), arg.nil? ? :shant : arg[0] == "[" ? :may : :must]
+      end.transpose           # [[name,arg], ...] -> [names, args]
+      .then do |names, args|  # handle -f,--foo=x style (without arg on short opt); expand --[no]flag into --flag and --noflag (also --[no-])
+        args = args.uniq.tap{ it.delete :shant if it.size > 1 }                                  # delete excess :shant (from -f in -f,--foo=x)
+        raise "Option #{names} has conflicting arg requirements: #{args}" if args.size > 1       # raise if still conflict, like -f X, --ff [X]
+        [(names.flat_map{|f| f.start_with?(RX_NO) ? [$', $&[1...-1] + $'] : f }).uniq, args[0]]  # [flags and noflags, resolved single arg]
+      end
+    end.uniq.tap do |list| # [[[name, name, ...], arg, more opts ...]
+      dupes = list.flat_map(&:first).tally.reject{|k,v|v==1}
+      raise "Options #{dupes.keys.inspect} seen more than once in distinct definitions" if dupes.any?
+    end.map{ |names, arg| Optdecl[*names, arg:] }.then{ Optlist[*it] }
+  end
+
+
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: strop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Caio Chassot
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Build options from parsing help text, with pattern matching for result
+  processing
+email: dev@caiochassot.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/strop.rb
+- lib/strop/version.rb
+homepage: http://github.com/kch/strop
+licenses:
+- MIT
+metadata:
+  homepage_uri: http://github.com/kch/strop
+  source_code_uri: http://github.com/kch/strop
+  bug_tracker_uri: http://github.com/kch/strop/issues
+  documentation_uri: https://rubydoc.info/gems/strop
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Command-line option parser
+test_files: []