module Cl::Cmd::Dsl
Public Instance Methods
# File lib/cl/dsl.rb, line 8 def abstract unregister @abstract = true end
# File lib/cl/dsl.rb, line 13 def abstract? !!@abstract end
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
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
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
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
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
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
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
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
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