Multiple values¶

You may want your options or arguments to accept multiple values. Think for example of ls or curl:

$ curl --header "X-First-Name: Jean" --header "X-Last-Name: Martin" http://frenchexample.org/
$ ls file1 file2 file3

Here we gave 2 --headers options to curl, and 3 FILE argument to ls.

Clip also supports that. We just declare our option or argument's type as an array.

Options with multiple value¶

require "clip"

module Myapplication
  VERSION = "0.1.0"

  struct Command
    include Clip::Mapper

    getter name = ["World"]
  end

  def self.run
    begin
      command = Command.parse
    rescue ex : Clip::Error
      puts ex
      return
    end

    if command.is_a?(Clip::Mapper::Help)
      puts command.help
    else
      hello(command.name)
    end
  end

  def self.hello(name)
    puts "Hello #{name.join(", ")}"
  end
end

Myapplication.run

$ shards build
Dependencies are satisfied
Building: myapplication
$ ./bin/myapplication --help
Usage: ./bin/myapplication [OPTIONS]

Options:
  --name TEXT  [default: [World]]
  --help       Show this message and exit.
$ ./bin/myapplication
Hello World
$ ./bin/myapplication --name Alice --name Barbara --name Chloé
Hello Alice, Barbara, Chloé

Arguments with multiple values¶

require "clip"

module Myapplication
  VERSION = "0.1.0"

  struct Command
    include Clip::Mapper

    getter name : Array(String)
  end

  def self.run
    begin
      command = Command.parse
    rescue ex : Clip::Error
      puts ex
      return
    end

    if command.is_a?(Clip::Mapper::Help)
      puts command.help
    else
      hello(command.name)
    end
  end

  def self.hello(name)
    puts "Hello #{name.join(", ")}"
  end
end

Myapplication.run

$ shards build
Dependencies are satisfied
Building: myapplication
$ ./bin/myapplication --help
Usage: ./bin/myapplication [OPTIONS] NAME...

Arguments:
  NAME  [required]

Options:
  --help  Show this message and exit.
$ ./bin/myapplication Alice Barbara Chloé
Hello Alice, Barbara, Chloé

Supported types¶

All the types supported for one value are supported for multiple values. The only exception is the type Bool, because it makes no sens to have a flag option repeated multiple times.

The supported types are:

array of all subtypes of Int
array of all subtypes of Float
Array(String)
and all those types combined with Nil

Default value¶

Like with options and arguments with only one value, a multiple values options or arguments can have a default value. If so, it will not be required.

If you want it to not have the message [default: [value]] in the help, just set the default value to nil.

Warning

If the default value is Array(String).new or [] of String, it will be shown as is in the help message.

A better way is to make the type nilable and to set its default value to nil.