module Cl::Cmd::Dsl

Public Instance Methods

abstract() click to toggle source
# File lib/cl/dsl.rb, line 8
def abstract
  unregister
  @abstract = true
end
abstract?() click to toggle source
# File lib/cl/dsl.rb, line 13
def abstract?
  !!@abstract
end
arg(*args) click to toggle source

Declares an argument

Use this method to declare arguments the command accepts.

For example:

```ruby
class GitPush < Cl::Cmd
  arg remote, 'The Git remote to push to.', type: :string
end
```

Arguments do not need to be declared, in order to be passed to the Cmd instance, but it is useful to do so for more explicit help output, and in order to define extra properties on the arguments (e.g. their type).

@overload arg(name, description, opts)

@param name [String] the argument name
@param description [String] description for the argument, shown in the help output
@param opts [Hash] argument options
@option opts [Symbol] :type the argument type (`:array`, `:string`, `:integer`, `:float`, `:boolean`)
@option opts [Boolean] :required whether the argument is required
@option opts [String] :sep separator to split strings by, if the argument is an array
@option opts [Boolean] :splat whether to splat the argument, if the argument is an array
# File lib/cl/dsl.rb, line 50
def arg(*args)
  self.args.define(self, *args)
end
args(*args) click to toggle source

Declare multiple arguments at once

See {Cl::Cmd::Dsl#arg} for more details.

# File lib/cl/dsl.rb, line 20
def args(*args)
  return @args ||= superclass.respond_to?(:args) ? superclass.args.dup : Args.new unless args.any?
  opts = args.last.is_a?(Hash) ? args.pop : {}
  args.each { |arg| arg(arg, opts) }
end
description(description = nil) click to toggle source

Declare a description for this command

This is the description that will be shown in the command details help output.

For example:

```ruby
class Api::Login < Cl::Cmd
  description <<~str
    Use this command to login to our API.
    [...]
  str
end
```

@return [String] the description if no argument was given

# File lib/cl/dsl.rb, line 70
def description(description = nil)
  description ? @description = description : @description
end
examples(examples = nil) click to toggle source

Declare an example text for this command

This is the example text that will be shown in the command details help output.

For example:

```ruby
class Api::Login < Cl::Cmd
  example <<~str
    For example, in order to login to our API with your username and
    password, you can use:

      ./api --username [username] --password [password]
  str
end
```

@return [String] the description if no argument was given

# File lib/cl/dsl.rb, line 92
def examples(examples = nil)
  examples ? @examples = examples : @examples
end
opt(*args, &block) click to toggle source

Declares an option

Use this method to declare options a command accepts.

See [this section](/#Options) for a full explanation on each feature supported by command options.

@overload opt(name, description, opts)

@param name [String] the option name
@param description [String] description for the option, shown in the help output
@param opts [Hash] option options
@option opts [Symbol or Array<Symbol>] :alias alias name(s) for the option
@option opts [Object] :default default value for the option
@option opts [String or Symbol] :deprecated deprecation message for the option, or if given a Symbol, deprecated alias name
@option opts [Boolean] :downcase whether to downcase the option value
@option opts [Boolean] :upcase whether to upcase the option value
@option opts [Array<Object>] :enum list of acceptable option values
@option opts [String] :example example(s) for the option, shown in help output
@option opts [Regexp] :format acceptable option value format
@option opts [Boolean] :internal whether to hide the option from help output
@option opts [Numeric] :min minimum acceptable value
@option opts [Numeric] :max maximum acceptable value
@option opts [String] :see see also reference (e.g. documentation URL)
@option opts [Symbol] :type the option value type (`:array`, `:string`, `:integer`, `:float`, `:boolean`)
@option opts [Boolean] :required whether the option is required
@option opts [Array<Symbol> or Symbol] :requires (an)other options required this option depends on
# File lib/cl/dsl.rb, line 121
def opt(*args, &block)
  self.opts.define(self, *args, &block)
end
opts() click to toggle source

Collection of options supported by this command

This collection is being inherited from super classes.

# File lib/cl/dsl.rb, line 128
def opts
  @opts ||= self == Cmd ? Opts.new : superclass.opts.dup
end
required(*required) click to toggle source

Declare alternative option requirements.

Alternative (combinations of) options can be required. These need to be declared on the class body.

For example,

```ruby
class Api::Login < Cl::Cmd
  # DNF, read as: api_key OR username AND password
  required :api_key, [:username, :password]

  opt '--api_key KEY'
  opt '--username NAME'
  opt '--password PASS'
end
```

Will require either the option `api_key`, or both the options `username` and `password`.

See [this section](/#Required_Options) for a full explanation of how alternative option requirements can be used.

# File lib/cl/dsl.rb, line 160
def required(*required)
  required.any? ? self.required << required : @required ||= []
end
required?() click to toggle source

Whether any alternative option requirements have been declared.

See [this section](/#Required_Options) for a full explanation of how alternative option requirements can be used.

# File lib/cl/dsl.rb, line 136
def required?
  !!@required
end
summary(summary = nil) click to toggle source

Declare a summary for this command

This is the summary that will be shown in both the command list, and command details help output.

For example:

```ruby
class Api::Login < Cl::Cmd
  summary 'Login to the API'
end
```

@return [String] the summary if no argument was given

# File lib/cl/dsl.rb, line 177
def summary(summary = nil)
  summary ? @summary = summary : @summary
end