Class: GLI::Command

Inherits:
CommandLineToken show all
Includes:
CopyOptionsToAliases
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#command. You then use the methods described here to describe the command-specific command-line arguments, much as you use the methods in GLI to describe the global command-line interface

Direct Known Subclasses

DefaultHelpCommand, InitConfig, RDocCommand

Instance Attribute Summary

Attributes inherited from CommandLineToken

#aliases, #description, #long_description, #name

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CopyOptionsToAliases

#copy_options_to_aliases

Methods inherited from CommandLineToken

#<=>

Constructor Details

#initialize(names, description, arguments_name = nil, long_desc = nil, skips_pre = false, skips_post = false) ⇒ Command

Create a new command

names

A String, Symbol, or Array of String or Symbol that represents the name(s) of this command.

description

short description of this command as a Strign

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 and text formatting

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



20
21
22
23
24
25
26
 
# File 'lib/gli/command.rb', line 20

def initialize(names,description,arguments_name=nil,long_desc=nil,skips_pre=false,skips_post=false) # :nodoc:
  super(names,description,long_desc)
  @arguments_description = arguments_name || ''
  @skips_pre = skips_pre
  @skips_post = skips_post
  clear_nexts
end

Class Method Details

.name_as_string(name) ⇒ Object

:nodoc:



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

def self.name_as_string(name) #:nodoc:
  name.to_s
end

Instance Method Details

#action(&block) ⇒ Object

Define the action to take when the user executes this command

block

A block of code to execute. The block will be given 3 arguments:

global_options

A Hash (or Options, see GLI#use_openstruct) of the global options specified by the user, with defaults set and config file values used (if using a config file, see GLI#config_file)

options

A Hash (or Options, see GLI#use_openstruct) of the command-specific options specified by the user, with defaults set and config file values used (if using a config file, see GLI#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



104
105
106
 
# File 'lib/gli/command.rb', line 104

def action(&block)
  @action = block
end

#arg_name(name) ⇒ Object

describe the argument name of the next flag, just as GLI#arg_name does.



71
 
# File 'lib/gli/command.rb', line 71

def arg_name(name); @next_arg_name = name; end

#arguments_description ⇒ Object

Return the arguments description



29
30
31
 
# File 'lib/gli/command.rb', line 29

def arguments_description #:nodoc:
  @arguments_description
end

#clear_nexts ⇒ Object

:nodoc:



112
113
114
115
116
117
 
# File 'lib/gli/command.rb', line 112

def clear_nexts #:nodoc:
  @next_desc = nil
  @next_arg_name = nil
  @next_default_value = nil
  @next_long_desc = nil
end

#default_value(val) ⇒ Object

set the default value of the next flag, just as GLI#default_value does.



73
 
# File 'lib/gli/command.rb', line 73

def default_value(val); @next_default_value = val; end

#desc(description) ⇒ Object

describe the next switch or flag just as GLI#desc does.



67
 
# File 'lib/gli/command.rb', line 67

def desc(description); @next_desc = description; end

#execute(global_options, options, arguments) ⇒ Object

Executes the command



120
121
122
 
# File 'lib/gli/command.rb', line 120

def execute(global_options,options,arguments) #:nodoc:
  @action.call(global_options,options,arguments)
end

#flag(*names) ⇒ Object

Create a command-specific flag, similar to GLI#flag



76
77
78
79
80
81
82
 
# File 'lib/gli/command.rb', line 76

def flag(*names)
  names = [names].flatten
  GLI.verify_unused(names,flags,switches,"in command #{name}")
  flag = Flag.new(names,@next_desc,@next_arg_name,@next_default_value,@next_long_desc)
  flags[flag.name] = flag
  clear_nexts
end

#flags ⇒ Object

Return the flags as a Hash



58
59
60
 
# File 'lib/gli/command.rb', line 58

def flags #:nodoc:
  @flags ||= {}
end

#long_desc(long_desc) ⇒ Object

set the long description of this flag/switch, just as GLI#long_desc does.



69
 
# File 'lib/gli/command.rb', line 69

def long_desc(long_desc); @next_long_desc = long_desc; end

#names ⇒ Object

Return the Array of the command’s names



44
45
46
 
# File 'lib/gli/command.rb', line 44

def names #:nodoc:
  all_forms
end

#skips_post ⇒ Object

If true, this command doesn’t want the post block run before it executes



39
40
41
 
# File 'lib/gli/command.rb', line 39

def skips_post #:nodoc:
  @skips_post
end

#skips_pre ⇒ Object

If true, this command doesn’t want the pre block run before it executes



34
35
36
 
# File 'lib/gli/command.rb', line 34

def skips_pre #:nodoc:
  @skips_pre
end

#switch(*names) ⇒ Object

Create a command-specific switch, similar to GLI#switch



85
86
87
88
89
90
91
 
# File 'lib/gli/command.rb', line 85

def switch(*names)
  names = [names].flatten
  GLI.verify_unused(names,flags,switches,"in command #{name}")
  switch = Switch.new(names,@next_desc,@next_long_desc)
  switches[switch.name] = switch
  clear_nexts
end

#switches ⇒ Object

Return the switches as a Hash



62
63
64
 
# File 'lib/gli/command.rb', line 62

def switches #:nodoc:
  @switches ||= {}
end

#usage ⇒ Object

Get the usage string CR: This should probably not be here



50
51
52
53
54
55
 
# File 'lib/gli/command.rb', line 50

def usage #:nodoc:
  usage = name.to_s
  usage += ' [command options]' if !flags.empty? || !switches.empty?
  usage += ' ' + @arguments_description if @arguments_description
  usage
end