Module: Cl::Cmd::Dsl

Includes:
Merge, Underscore
Included in:
Cl::Cmd
Defined in:
lib/cl/dsl.rb

Constant Summary

Constants included from Merge

Merge::MERGE

Instance Method Summary collapse

Methods included from Merge

#merge

Methods included from Underscore

#underscore

Instance Method Details

#abstract ⇒ Object 



8
9
10
 
# File 'lib/cl/dsl.rb', line 8

def abstract
  unregister
end

#arg(name, description, opts) ⇒ Object

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).

Parameters:

  • name (String) —

    the argument name

  • description (String) —

    description for the argument, shown in the help output

  • opts (Hash) —

    argument options

Options Hash (opts):

  • :type (Symbol) —

    the argument type (‘:array`, `:string`, `:integer`, `:float`, `:boolean`)

  • :required (Boolean) —

    whether the argument is required

  • :sep (String) —

    separator to split strings by, if the argument is an array

  • :splat (Boolean) —

    whether to splat the argument, if the argument is an array



45
46
47
 
# File 'lib/cl/dsl.rb', line 45

def arg(*args)
  self.args.define(self, *args)
end

#args(*args) ⇒ Object

Declare multiple arguments at once

See #arg for more details.



15
16
17
18
19
 
# File 'lib/cl/dsl.rb', line 15

def args(*args)
  return @args ||= Args.new unless args.any?
  opts = args.last.is_a?(Hash) ? args.pop : {}
  args.each { |arg| arg(arg, opts) }
end

#description(description = nil) ⇒ String

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
```

Returns:

  • (String) —

    the description if no argument was given



65
66
67
 
# File 'lib/cl/dsl.rb', line 65

def description(description = nil)
  description ? @description = description : @description
end

#examples(examples = nil) ⇒ String

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
```

Returns:

  • (String) —

    the description if no argument was given



87
88
89
 
# File 'lib/cl/dsl.rb', line 87

def examples(examples = nil)
  examples ? @examples = examples : @examples
end

#opt(name, description, opts) ⇒ Object

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.

Parameters:

  • name (String) —

    the option name

  • description (String) —

    description for the option, shown in the help output

  • opts (Hash) —

    option options

Options Hash (opts):

  • :alias (Symbol or Array<Symbol>) —

    alias name(s) for the option

  • :default (Object) —

    default value for the option

  • :deprecated (String or Symbol) —

    deprecation message for the option, or if given a Symbol, deprecated alias name

  • :downcase (Boolean) —

    whether to downcase the option value

  • :enum (Array<Object>) —

    list of acceptable option values

  • :example (String) —

    example(s) for the option, shown in help output

  • :format (Regexp) —

    acceptable option value format

  • :internal (Boolean) —

    whether to hide the option from help output

  • :min (Numeric) —

    minimum acceptable value

  • :max (Numeric) —

    maximum acceptable value

  • :see (String) —

    see also reference (e.g. documentation URL)

  • :type (Symbol) —

    the option value type (‘:array`, `:string`, `:integer`, `:float`, `:boolean`)

  • :required (Boolean) —

    whether the option is required

  • :requires (Array<Symbol> or Symbol) — default: an —

    other options required this option depends on



115
116
117
 
# File 'lib/cl/dsl.rb', line 115

def opt(*args, &block)
  self.opts.define(self, *args, &block)
end

#opts ⇒ Object

Collection of options supported by this command

This collection is being inherited from super classes.



122
123
124
 
# File 'lib/cl/dsl.rb', line 122

def opts
  @opts ||= self == Cmd ? Opts.new : superclass.opts.dup
end

#required(*required) ⇒ Object

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.



154
155
156
 
# File 'lib/cl/dsl.rb', line 154

def required(*required)
  required.any? ? self.required << required : @required ||= []
end

#required? ⇒ Boolean

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.

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/cl/dsl.rb', line 130

def required?
  !!@required
end

#summary(summary = nil) ⇒ String

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
```

Returns:

  • (String) —

    the summary if no argument was given



171
172
173
 
# File 'lib/cl/dsl.rb', line 171

def summary(summary = nil)
  summary ? @summary = summary : @summary
end