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
11
 
# File 'lib/cl/dsl.rb', line 8

def abstract
  unregister
  @abstract = true
end

#abstract? ⇒ Boolean

Returns:

  • (Boolean) 


13
14
15
 
# File 'lib/cl/dsl.rb', line 13

def abstract?
  !!@abstract
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



50
51
52
 
# File 'lib/cl/dsl.rb', line 50

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

#args(*args) ⇒ Object

Declare multiple arguments at once

See #arg for more details.



20
21
22
23
24
 
# 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) ⇒ 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



70
71
72
 
# File 'lib/cl/dsl.rb', line 70

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



92
93
94
 
# File 'lib/cl/dsl.rb', line 92

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

  • :upcase (Boolean) —

    whether to upcase 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



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

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.



128
129
130
 
# File 'lib/cl/dsl.rb', line 128

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.



160
161
162
 
# File 'lib/cl/dsl.rb', line 160

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) 


136
137
138
 
# File 'lib/cl/dsl.rb', line 136

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



177
178
179
 
# File 'lib/cl/dsl.rb', line 177

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