Skip to main content

​
Overview

The Opts utility provides a generic CLI argument parser for any command-line parsing task. It separates concerns between parsing, validation, and execution, returning an immutable OpenStruct with typed values. Location: lib/util/opts.rb

​
Class Methods

​
parse

Parse an argument array (typically ARGV) into an immutable OpenStruct based on a schema definition. 
Opts.parse(argv, schema = {}) → OpenStruct
​
argv
Array<String>
required
Argument list to parse (usually ARGV)
​
schema
Hash
default:"{}"
Option definitions with metadata. Each key represents an option name, and the value is a hash with:
  • :type (Symbol) - Type coercion: :string, :boolean, :integer, or :array
  • :default (Object) - Default value if not provided
  • :parser (Proc) - Custom parser function for complex transformations
  • :short (String) - Short form flag (e.g., “v” for “-v”)
​
return
OpenStruct
Frozen OpenStruct with all specified keys from the schema

​
Examples

​
Basic Usage

opts = Lich::Util::Opts.parse(ARGV, {
  gui: { type: :boolean, default: true },
  account: { type: :string },
  password: { type: :string }
})

puts opts.gui      # true
puts opts.account  # "myaccount"

​
Boolean Flags

opts = Lich::Util::Opts.parse(['--verbose'], {
  verbose: { type: :boolean, default: false }
})

puts opts.verbose  # true

​
Custom Parser

opts = Lich::Util::Opts.parse(['--host=localhost:4000'], {
  host: { 
    type: :string, 
    parser: ->(v) { 
      h, p = v.split(':')
      { host: h, port: p.to_i } 
    } 
  }
})

puts opts.host  # { host: "localhost", port: 4000 }

​
Integer Type

opts = Lich::Util::Opts.parse(['--port', '8080'], {
  port: { type: :integer, default: 3000 }
})

puts opts.port  # 8080 (Integer)

​
Array Type

opts = Lich::Util::Opts.parse(['--files', 'a.txt', 'b.txt', 'c.txt'], {
  files: { type: :array }
})

puts opts.files  # ["a.txt", "b.txt", "c.txt"]

​
Short Flags

opts = Lich::Util::Opts.parse(['-v'], {
  verbose: { type: :boolean, short: 'v' }
})

puts opts.verbose  # true

​
Argument Formats

The parser supports multiple argument formats:
  • Boolean flags: --verbose or -v
  • Separate value: --port 8080
  • Equals syntax: --port=8080
  • Multiple values (array): --files a.txt b.txt c.txt
Option names with underscores in the schema are automatically converted to dashes in the CLI (e.g., max_connections → --max-connections).

​
Type Coercion

TypeBehavior
:booleanPresence of flag sets to true. With = syntax: matches true/on/yes/1 (case-insensitive)
:stringTakes next argument or value after =
:integerConverts to integer using .to_i
:arrayCollects all following arguments until next flag
Custom :parserCalls provided Proc with the value string

​
Immutability

The returned OpenStruct is frozen, making the parsed options immutable. This prevents accidental modification and makes the options safe to pass around. 
opts = Lich::Util::Opts.parse(ARGV, { verbose: { type: :boolean } })
opts.verbose = false  # raises FrozenError

Build docs developers (and LLMs) love

Get started for freeTalk to us