Class: GLI::Command

Inherits:
CommandLineToken show all
Includes:
CommandSupport, DSL
Defined in:
lib/gli/command.rb

Overview

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

Defined Under Namespace

Classes: ParentKey

Constant Summary collapse

PARENT =

Key in an options hash to find the parent's parsed options. Note that if you are using openstruct, e.g. via use_openstruct true in your app setup, you will need to use the method __parent__ to access parent parsed options.

ParentKey.new

Instance Attribute Summary

Attributes included from CommandSupport

#parent

Attributes inherited from CommandLineToken

#aliases, #description, #long_description, #name

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CommandSupport

#arg_name, #arguments, #arguments_description, #arguments_options, #commands, #commands_declaration_order, #context_description, #default_description, #default_value, #desc, #examples, #execute, #flag, #flags, #get_default_command, #has_action?, #long_desc, #names, #nodoc, #skips_around, #skips_post, #skips_pre, #switch, #switches, #topmost_ancestor

Methods included from DSL

#arg, #arg_name, #clear_nexts, #command, #command_missing, #default_value, #desc, #flag, #flags_declaration_order, #long_desc, #switch, #switches_declaration_order

Methods inherited from CommandLineToken

#<=>, #names_and_aliases

Constructor Details

#initialize(options) ⇒ Command

Create a new command.

options

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.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/gli/command.rb', line 58

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

Class Method Details

.name_as_string(name, negatable = false) ⇒ Object

:nodoc:



192
193
194
 
# File 'lib/gli/command.rb', line 192

def self.name_as_string(name,negatable=false) #:nodoc:
  name.to_s
end

Instance Method Details

#action(&block) ⇒ Object

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#exit_now! if you need an early exit based on an error condition



108
109
110
 
# File 'lib/gli/command.rb', line 108

def action(&block)
  @action = block
end

#default_command(command_name) ⇒ Object

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.



90
91
92
 
# File 'lib/gli/command.rb', line 90

def default_command(command_name)
  @default_command = command_name
end

#default_desc(desc) ⇒ Object

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.

desc

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



160
161
162
 
# File 'lib/gli/command.rb', line 160

def default_desc(desc)
  @default_desc = desc
end

#example(example_invocation, options = {}) ⇒ Object

Specify an example invocation.

example_invocation

test of a complete command-line invocation you want to show

options

refine the example: :desc:: A description of the example to be shown with it (optional)



79
80
81
82
83
 
# File 'lib/gli/command.rb', line 79

def example(example_invocation,options = {})
  @examples << {
    example: example_invocation
  }.merge(options)
end

#has_option?(option) ⇒ Boolean

Returns true if this command has the given option defined

Returns:



165
166
167
168
169
 
# File 'lib/gli/command.rb', line 165

def has_option?(option) #:nodoc:
  option = option.gsub(/^\-+/,'')
  ((flags.values.map { |_| [_.name,_.aliases] }) + 
   (switches.values.map { |_| [_.name,_.aliases] })).flatten.map(&:to_s).include?(option)
end

#name_for_help ⇒ Object

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"]



182
183
184
185
186
187
188
189
190
 
# File 'lib/gli/command.rb', line 182

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