A command to be run, in context of global flags and switches. You are given an instance of this class to the block you use for GLI::DSL#command. This class mixes in GLI::DSL so all of those methods are available to describe the command, in addition to the methods documented here, most importantly action.
Example:
command :list do |c| # <- c is an instance of GLI::Command c.desc 'use long form' c.switch :l c.action do |global,options,args| # list things here end c.command :tasks do |t| # <- t is an instance of GLI::Command # this is a "subcommand" of list t.action do |global,options,args| # do whatever list tasks should do end end end
Key in an options hash to find the parent’s parsed options
Define the action to take when the user executes this command. Every command should either define this action block, or have subcommands (or both).
block
A block of code to execute. The block will be given 3 arguments:
global_options
A Hash of the global options specified by the user, with defaults set and config file values used (if using a config file, see GLI::App#config_file)
options
A Hash of the command-specific options specified by the user, with defaults set and config file values used (if using a config file, see GLI::App#config_file).
arguments
An Array of Strings representing the unparsed command line arguments
The block’s result value is not used; raise an exception or use GLI::App#exit_now! if you need an early exit based on an error condition
# File lib/gli/command.rb, line 100 def action(&block) @action = block end
Set the default command if this command has subcommands and the user doesn’t provide a subcommand when invoking THIS command. When nil, this will show an error and the help for this command; when set, the command with this name will be executed.
command_name
The primary name of the subcommand of this command that should be run by default as a String or Symbol.
# File lib/gli/command.rb, line 82 def default_command(command_name) @default_command = command_name end
Describes this commands action block when it also has subcommands. In this case, the GLI::DSL#desc value is the general description of the commands that this command groups, and the value for this method documents what will happen if you omit a subcommand.
Note that if you omit the action block and specify a subcommand, that subcommand’s description will be used to describe what happens by default.
the description of what this command’s action block does.
Example
desc 'list things' command :list do |c| c.desc 'list tasks' c.command :tasks do |t| t.action do |global,options,args| end end c.desc 'list contexts' c.command :contexts do |t| t.action do |global,options,args| end end c.default_desc 'list both tasks and contexts' c.action do |global,options,args| # list everything end end > todo help list NAME list - List things SYNOPSIS todo [global options] list [command options] todo [global options] list [command options] tasks todo [global options] list [command options] contexts COMMANDS <default> - list both tasks and contexts tasks - list tasks contexts - list contexts
# File lib/gli/command.rb, line 152 def default_desc(desc) @default_desc = desc end
Specify an example invocation.
test of a complete command-line invocation you want to show
refine the example:
:desc
A description of the example to be shown with it (optional)
# File lib/gli/command.rb, line 71 def example(example_invocation,options = {}) @examples << { example: example_invocation }.merge(options) end
Returns full name for help command including parents
Example
command :remote do |t| t.command :add do |global,options,args| end end @add_command.name_for_help # => ["remote", "add"]
# File lib/gli/command.rb, line 174 def name_for_help name_array = [name.to_s] command_parent = parent while(command_parent.is_a?(GLI::Command)) do name_array.unshift(command_parent.name.to_s) command_parent = command_parent.parent end name_array end
Create a new command.
Keys should be:
names
A String, Symbol, or Array of String or Symbol that represents the name(s) of this command (required).
description
short description of this command as a String
arguments_name
description of the arguments as a String, or nil if this command doesn’t take arguments
long_desc
a longer description of the command, possibly with multiple lines. A double line-break is treated as a paragraph break. No other formatting is respected, though inner whitespace is maintained.
skips_pre
if true, this command advertises that it doesn’t want the pre block called first
skips_post
if true, this command advertises that it doesn’t want the post block called after it
skips_around
if true, this command advertises that it doesn’t want the around block called
hide_commands_without_desc
if true and there isn’t a description the command is not going to be shown in the help
examples
An array of Hashes, where each hash must have the key :example
mapping to a string, and may optionally have the key :desc
that documents that example.
# File lib/gli/command.rb, line 50 def initialize(options) super(options[:names],options[:description],options[:long_desc]) @arguments_description = options[:arguments_name] || '' @arguments_options = Array(options[:arguments_options]).flatten @arguments = options[:arguments] || [] @skips_pre = options[:skips_pre] @skips_post = options[:skips_post] @skips_around = options[:skips_around] @hide_commands_without_desc = options[:hide_commands_without_desc] @commands_declaration_order = [] @flags_declaration_order = [] @switches_declaration_order = [] @examples = options[:examples] || [] clear_nexts end