Search results

std.optparse.Options

class pub Options

A type that describes the options to parse.

Fields

stop_at_first_non_option

let pub @stop_at_first_non_option: Bool

If parsing of arguments and options should stop when encountering the first non-option argument.

When set and a non-option is encountered, any remaining options and arguments are stored as-is in Matches.remaining.

Static methods

new

Show source code

fn pub static new -> Options {
  Options(mapping: Map.new, options: [], stop_at_first_non_option: false)
}

fn pub static new -> Options

Returns a new empty Options.

Instance methods

flag

Show source code

fn pub mut flag(short: String, long: String, description: String) {
  add(
    Opt(
      kind: Kind.Flag,
      short: short,
      long: long,
      description: description,
      hint: '',
    ),
  )
}

fn pub mut flag(short: String, long: String, description: String)

Adds a boolean option that can be specified once.

The short argument is the short name of the option, such as "h" or "v". This value must be a single character long.

The long argument is the long name of the option, such as "help" or "version".

The description argument is the description of the option, displayed when formatting the list of options as a String.

Panics

This method panics if:

Both short and long are empty.
An option is already defined for the short or long option name.
short contains more than one character.

Examples

import optparse.Options

let opts = Options.new

opts.flag('h', 'help', 'Show this help message')

multiple

Show source code

fn pub mut multiple(
  short: String,
  long: String,
  hint: String,
  description: String,
) {
  add(
    Opt(
      kind: Kind.Multiple,
      short: short,
      long: long,
      description: description,
      hint: hint,
    ),
  )
}

fn pub mut multiple(short: String, long: String, hint: String, description: String)

Adds an option that can be specified multiple times, and requires a value.

The short argument is the short name of the option, such as "h" or "v". This value must be a single character long.

The long argument is the long name of the option, such as "help" or "version".

The hint argument is an arbitrary String that describes the type of value that is expected, such as "CONFIG" for a configuration file option.

The description argument is the description of the option, displayed when formatting the list of options as a String.

Panics

This method panics if:

Both short and long are empty.
An option is already defined for the short or long option name.
short contains more than one character.

Examples

import optparse.Options

let opts = Options.new

opts.multiple('i', 'include', 'PATH', 'Include the given directory')

parse

Show source code

fn pub parse(arguments: ref Array[String]) -> Result[Matches, Error] {
  let lexer = Lexer.new(arguments)
  let matches = Matches(remaining: [], options: Map.new)

  loop {
    match lexer.next {
      case Some(Short(name) or Long(name)) -> {
        match @mapping.opt(name) {
          case Some(opt) -> {
            match opt.kind {
              case Flag if matches.contains?(name) -> {
                throw Error.DuplicateOption(name)
              }
              case Single if matches.contains?(name) -> {
                throw Error.DuplicateOption(name)
              }
              case Flag -> matches.add(opt, Value.Flag)
              case Single or Multiple -> {
                match lexer.next {
                  case Some(Value(val)) -> matches.add(opt, Value.String(val))
                  case _ -> throw Error.MissingValue(name)
                }
              }
            }
          }
          case _ -> throw Error.InvalidOption(name)
        }
      }
      case Some(LongPair(name, val)) -> {
        match @mapping.opt(name) {
          case Some(opt) -> {
            match opt.kind {
              case Flag -> throw Error.UnexpectedValue(name)
              case Single if matches.contains?(name) -> {
                throw Error.DuplicateOption(name)
              }
              case Single or Multiple -> matches.add(opt, Value.String(val))
            }
          }
          case _ -> throw Error.InvalidOption(name)
        }
      }
      case Some(Value(val)) -> {
        matches.remaining.push(val)

        if @stop_at_first_non_option {
          consume_remaining(lexer, matches.remaining)
          break
        }
      }
      case Some(Separator) -> {
        consume_remaining(lexer, matches.remaining)
        break
      }
      case _ -> break
    }
  }

  Result.Ok(matches)
}

fn pub parse(arguments: ref Array[String]) -> Result[Matches, Error]

Parses the given command-line arguments according to the options defined thus far.

Examples

import optparse.Options

let opts = Options.new

opts.flag('h', 'help', 'Show this help message')
opts.multiple('i', 'include', 'PATH', 'Include the given directory')

let matches = opts.parse(['-i', 'test', '-i', 'src']).unwrap

single

Show source code

fn pub mut single(
  short: String,
  long: String,
  hint: String,
  description: String,
) {
  add(
    Opt(
      kind: Kind.Single,
      short: short,
      long: long,
      description: description,
      hint: hint,
    ),
  )
}

fn pub mut single(short: String, long: String, hint: String, description: String)

Adds an option that can be specified at most once, and requires a value.

The short argument is the short name of the option, such as "h" or "v". This value must be a single character long.

The long argument is the long name of the option, such as "help" or "version".

The hint argument is an arbitrary String that describes the type of value that is expected, such as "CONFIG" for a configuration file option.

The description argument is the description of the option, displayed when formatting the list of options as a String.

Panics

This method panics if:

Both short and long are empty.
An option is already defined for the short or long option name.
short contains more than one character.

Examples

import optparse.Options

let opts = Options.new

opts.single('c', 'config', 'PATH', 'Use a custom configuration file')

to_string

Show source code

fn pub to_string -> String {
  let opts = []
  let descs = []

  @options.iter.each(fn (opt) {
    let short = if opt.short.size > 0 { '-${opt.short}' } else { '' }
    let long = if opt.long.size > 0 and opt.hint.size > 0 {
      '--${opt.long}=${opt.hint}'
    } else if opt.long.size > 0 {
      '--${opt.long}'
    } else {
      ''
    }

    if short.size > 0 and long.size > 0 {
      opts.push('${short}, ${long}')
    } else if long.size > 0 {
      opts.push('    ${long}')
    } else {
      opts.push(short)
    }

    descs.push(opt.description)
  })

  let max_size = opts.iter.reduce(0, fn (max, line) {
    let chars = character_count(line)

    if chars > max { chars } else { max }
  })

  let buf = StringBuffer.new

  opts.into_iter.each_with_index(fn (idx, opt) {
    let desc = descs.get(idx)
    let has_desc = desc.size > 0

    if idx > 0 { buf.push('\n') }

    buf.push(INDENT)

    if has_desc {
      buf.push(opt.pad_end(with: ' ', chars: max_size + 4))
      desc.split('\n').each_with_index(fn (index, line) {
        if index > 0 {
          buf.push('\n')
          buf.push(' '.repeat(max_size + 6))
        }

        buf.push(line)
      })
    } else {
      buf.push(opt)
    }
  })

  buf.into_string
}

fn pub to_string -> String

Returns a String describing all the options defined thus far.

Implemented traits

std.string.

ToString

impl ToString for Options