options_by_example 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d803c63947acbb818c4fbf749cdb18084e6b0750678f9e600369ce543b78536
+  data.tar.gz: 21d6c8a4866627102f82d12a2805eb60850e6a24eb04d0ec064ea5af55dd87a2
+SHA512:
+  metadata.gz: a6e16dbd993f098415710aacd89e859ff9ac9403256a648a51fd4ab7754d91aa473e8c5b53f055ab0378d4acf1977e6b30f8826d1a626f6bcdeef4e0eb15e233
+  data.tar.gz: b9dcfa2249f316554b416f788109486caecefdc68c8d48890cc3e0033a3270509bea96fbe994931413bae7160c035e8968f63f855e59f522d67149d20e7fc15b

data/README.md

@@ -0,0 +1,48 @@
+# Options by Example
+
+No-code options parser that automatically detects command-line options from the usage text of your application. This intuitive parser identifies optional and required argument names as well as option names without requiring any additional code, making it easy to manage user input for your command-line applications.
+
+Features
+
+- Automatically detects optional and required argument names from usage text
+- Automatically detects option names and associated arguments (if any) from usage text
+- Parses those arguments and options from the command line (ARGV)
+- Raises errors for unknown options or missing required arguments
+
+
+Example
+
+```ruby
+require 'options_by_example'
+
+Options = OptionsByExample.read(DATA).parse(ARGV)
+
+puts Options.include_secure?
+puts Options.include_verbose?
+puts Options.include_retries?
+puts Options.include_timeout?
+puts Options.argument_retries
+puts Options.argument_timeout
+puts Options.argument_mode
+puts Options.argument_host
+puts Options.argument_port
+
+
+__END__
+Establishes a network connection to a designated host and port, enabling
+users to assess network connectivity and diagnose potential problems.
+
+Usage: connect [options] [mode] host port
+
+Options:
+  -s, --secure        Establish a secure connection (SSL/TSL)
+  -v, --verbose       Enable verbose output for detailed information
+  -r, --retries NUM   Specify the number of connection retries (default 3)
+  -t, --timeout NUM   Set the connection timeout in seconds (default 10)
+
+Arguments:
+  [mode]              Optional connection mode (active or passive)
+  host                The target host to connect to (e.g., example.com)
+  port                The target port to connect to (e.g., 80)
+```
+

data/lib/options_by_example/version.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class OptionsByExample
+  VERSION = '1.1.0'
+end
+
+
+__END__
+
+# Major version bump when breaking changes or new features
+# Minor version bump when backward-compatible changes or enhancements
+# Patch version bump when backward-compatible bug fixes, security updates etc
+
+1.0.1
+
+  - Update readme file with features and an example
+  - Update the gemspec to include readme and ruby files only
+
+1.0.0
+
+  - Extract optional and required argument names from a usage text
+  - Extract option names and associated argument names (if any) from a usage text
+  - Include help option by default
+  - Parse options and arguments from command-line arguments aka ARGV
+  - Exit gracefully or raise exceptions, depending on the exit_on_error parameter
+  - Implement dynamic methods for checking options and getting arguments
+  - Ensure correct git tag and all changes committed when building gem
+
+0.0.0
+
+  - Prehistory starts here...

data/lib/options_by_example.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "options_by_example/version"
+
+
+class OptionsByExample
+
+  attr_reader :argument_names_optional
+  attr_reader :argument_names_required
+  attr_reader :option_names
+
+  attr_reader :arguments
+  attr_reader :options
+
+
+  def self.read(data)
+    return new data.read
+  end
+
+  def initialize(text)
+    @usage = text.gsub('$0', File.basename($0)).gsub(/\n+\Z/, "\n\n")
+
+    # ---- 1) Parse argument names ------------------------------------
+    #
+    # Parse the usage string and extract both optional argument names
+    # and required argument names, for example:
+    #
+    # Usage: connect [options] [mode] host port
+
+    text =~ /Usage: (\w+|\$0) \[options\](( \[\w+\])*)(( \w+)*)/
+    raise RuntimeError, "Expected usage string, got none" unless $1
+    @argument_names_optional = $2.to_s.split.map { |match| match.tr('[]', '').downcase }
+    @argument_names_required = $4.to_s.split.map(&:downcase)
+
+    # ---- 2) Parse option names --------------------------------------
+    #
+    # Parse the usage message and extract option names, their short and
+    # long forms, and the associated argument name (if any), eg:
+    #
+    # Options:
+    #   -s, --secure        Use secure connection
+    #   -v, --verbose       Enable verbose output
+    #   -r, --retries NUM   Number of connection retries (default 3)
+    #   -t, --timeout NUM   Connection timeout in seconds (default 10)
+
+    @option_names = {}
+    text.scan(/((--?\w+)(, --?\w+)*) ?(\w+)?/) do
+      opts = $1.split(", ")
+      opts.each { |each| @option_names[each] = [opts.last.tr('-', ''), $4&.downcase] }
+    end
+
+    # ---- 3) Include help option by default --------------------------
+
+    @option_names.update("-h" => :help, "--help" => :help)
+  end
+
+  def parse(argv, exit_on_error: true)
+    array = argv.dup
+    @arguments = {}
+    @options = {}
+
+    # --- 1) Parse options --------------------------------------------
+
+    most_recent_option = nil
+    until array.empty? do
+      break unless array.first.start_with?(?-)
+      most_recent_option = option = array.shift
+      option_name, argument_name = @option_names[option]
+      raise "Got unknown option #{option}" if option_name.nil?
+      raise if option_name == :help # Show usage without error message
+      @options[option_name] = true
+
+      # Consume argument, if expected by most recent option
+      if argument_name
+        argument = array.shift
+        raise "Expected argument for option #{option}" unless /^[^-]/ === argument
+        @arguments[option_name] = argument
+        most_recent_option = nil
+      end
+    end
+
+    # --- 2) Parse optional arguments ---------------------------------
+
+    # Check any start with --, ie excess options
+    # Check min_length - max_length here
+
+    stash = array.pop(@argument_names_required.length)
+    @argument_names_optional.each do |argument_name|
+      break if array.empty?
+      argument = array.shift
+      raise "Expected more arguments, got option #{option}" unless /^[^-]/ === argument
+      @arguments[argument_name] = argument
+    end
+
+    # --- 3) Parse required arguments ---------------------------------
+
+    @argument_names_required.each do |argument_name|
+      raise "Expected required argument #{argument_name.upcase}, got none" if stash.empty?
+      argument = stash.shift
+      raise "Expected more arguments, got option #{option}" unless /^[^-]/ === argument
+      @arguments[argument_name] = argument
+    end
+
+    # --- 4) Expect to be done ----------------------------------------
+
+    if not array.empty?
+      # Custom error message if most recent option did not require argument
+      raise "Got unexpected argument for option #{most_recent_option}" if most_recent_option
+      raise "Expected #{min_length}#{"-#{max_length}" if max_length > min_length} arguments, got more"
+    end
+
+    return self
+
+  rescue RuntimeError => err
+    if exit_on_error
+      puts "ERROR: #{err.message}\n\n" unless err.message.empty?
+      puts @usage
+      exit
+    else
+      raise # Reraise the same exception
+    end
+  end
+
+  def method_missing(sym, *args, &block)
+    case sym
+    when /^argument_(\w+)$/
+      val = @arguments[$1]
+      block && val ? block.call(val) : val
+    when /^include_(\w+)\?$/
+      @options[$1]
+    else
+      super
+    end
+  end
+end
+

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: options_by_example
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Adrian Kuhn
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-04-28 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- akuhn@iam.unibe.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/options_by_example.rb
+- lib/options_by_example/version.rb
+homepage: https://github.com/akuhn/options_by_example
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/akuhn/options_by_example
+  source_code_uri: https://github.com/akuhn/options_by_example
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: No-code options parser that extracts arguments directly from usage text.
+test_files: []