Class: Bashly::Script::Command

Inherits:
Base
  • Object
show all
Includes:
Completions::Command
Defined in:
lib/bashly/script/command.rb

Instance Attribute Summary collapse

Attributes inherited from Base

#options

Attributes included from Renderable

#render_options

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Completions::Command

#completion_data, #completion_function, #completion_script

Methods inherited from Base

#help, #initialize, #method_missing, #optional, #respond_to_missing?, #summary

Methods included from Renderable

#load_user_file, #render, #strings, #user_file_exist?, #user_file_path, #view_marker

Constructor Details

This class inherits a constructor from Bashly::Script::Base

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Bashly::Script::Base

Instance Attribute Details

#parent_command ⇒ Object

Returns the value of attribute parent_command.



18
19
20
 
# File 'lib/bashly/script/command.rb', line 18

def parent_command
  @parent_command
end

#parents ⇒ Object

Returns an array of all parents. For example, the command “docker container run” will have [docker, container] as its parents



245
246
247
 
# File 'lib/bashly/script/command.rb', line 245

def parents
  @parents ||= []
end

Class Method Details

.option_keys ⇒ Object 



7
8
9
10
11
12
13
14
15
 
# File 'lib/bashly/script/command.rb', line 7

def option_keys
  @option_keys ||= %i[
    alias args catch_all commands completions
    default dependencies environment_variables examples
    extensible expose filename filters flags
    footer function group help name
    private version
  ]
end

Instance Method Details

#action_name ⇒ Object

Returns the name to be used as an action.

  • If it is the root command, the action is “root”

  • Else, it is all the parents, except the first one (root) joined by space. For example, for a command like “docker container run” the action name is “container run”.



26
27
28
 
# File 'lib/bashly/script/command.rb', line 26

def action_name
  parents.any? ? (parents[1..] + [name]).join(' ') : 'root'
end

#aliases ⇒ Object

Returns all the possible aliases for this command



31
32
33
 
# File 'lib/bashly/script/command.rb', line 31

def aliases
  [name] + alt
end

#alt ⇒ Object

Returns an array of alternative aliases if any



36
37
38
39
40
 
# File 'lib/bashly/script/command.rb', line 36

def alt
  return [] unless options['alias']

  options['alias'].is_a?(String) ? [options['alias']] : options['alias']
end

#args ⇒ Object

Returns an array of Arguments



43
44
45
46
47
48
49
 
# File 'lib/bashly/script/command.rb', line 43

def args
  return [] unless options['args']

  options['args'].map do |options|
    Argument.new options
  end
end

#base_usage_pattern ⇒ Object 



330
331
332
333
 
# File 'lib/bashly/script/command.rb', line 330

def base_usage_pattern
  usage_pattern = default ? "[#{name}]" : name
  parents.any? ? (parents + [usage_pattern]).join(' ') : usage_pattern
end

#caption_string ⇒ Object

Returns a string suitable to be a headline



52
53
54
 
# File 'lib/bashly/script/command.rb', line 52

def caption_string
  help.empty? ? full_name : "#{full_name} - #{summary}"
end

#catch_all ⇒ Object

Returns an object representing the catch_all configuration



57
58
59
 
# File 'lib/bashly/script/command.rb', line 57

def catch_all
  @catch_all ||= CatchAll.from_config options['catch_all']
end

#command_aliases ⇒ Object

Returns a full list of the Command names and aliases combined



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

def command_aliases
  commands.map(&:aliases).flatten
end

#command_help_data ⇒ Object

Returns a data structure for displaying subcommands help



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/bashly/script/command.rb', line 67

def command_help_data
  result = {}

  public_commands.each do |command|
    result[command.group_string] ||= {}
    result[command.group_string][command.name] = { summary: command.summary_string }
    next unless command.expose

    command.public_commands.each do |subcommand|
      result[command.group_string]["#{command.name} #{subcommand.name}"] = {
        summary:   subcommand.summary_string,
        help_only: command.expose != 'always',
      }
    end
  end

  result
end

#command_names ⇒ Object

Returns only the names of the Commands



87
88
89
 
# File 'lib/bashly/script/command.rb', line 87

def command_names
  commands.map(&:name)
end

#commands ⇒ Object

Returns an array of the Commands



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/bashly/script/command.rb', line 92

def commands
  return [] unless options['commands']

  options['commands'].map do |options|
    result = Command.new options
    result.parents = parents + [name]
    result.parent_command = self
    result
  end
end

#deep_commands(include_self: false) ⇒ Object

Returns a flat array containing all the commands in this tree. This includes children + grandchildren (recursive), and may include self



105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/bashly/script/command.rb', line 105

def deep_commands(include_self: false)
  result = []
  result << self if include_self
  commands.each do |command|
    result << command
    if command.commands.any?
      result += command.deep_commands
    end
  end
  result
end

#default_args ⇒ Object

Returns an array of all the default Args



124
125
126
 
# File 'lib/bashly/script/command.rb', line 124

def default_args
  args.select(&:default)
end

#default_command ⇒ Object

If any of this command’s subcommands has the default option set to true, this default command will be returned, nil otherwise.



119
120
121
 
# File 'lib/bashly/script/command.rb', line 119

def default_command
  commands.find(&:default)
end

#default_environment_variables ⇒ Object

Returns an array of all the default Environment Variables



129
130
131
 
# File 'lib/bashly/script/command.rb', line 129

def default_environment_variables
  environment_variables.select(&:default)
end

#default_flags ⇒ Object

Returns an array of all the default Flags



134
135
136
 
# File 'lib/bashly/script/command.rb', line 134

def default_flags
  flags.select(&:default)
end

#dependencies ⇒ Object

Returns an array of Dependency objects



139
140
141
142
143
144
145
 
# File 'lib/bashly/script/command.rb', line 139

def dependencies
  return [] unless options['dependencies']

  @dependencies ||= options['dependencies'].map do |key, value|
    Dependency.from_config key, value
  end
end

#environment_variables ⇒ Object

Returns an array of EnvironmentVariable objects



148
149
150
151
152
153
154
 
# File 'lib/bashly/script/command.rb', line 148

def environment_variables
  return [] unless options['environment_variables']

  options['environment_variables'].map do |options|
    EnvironmentVariable.new options
  end
end

#examples ⇒ Object

Returns an array of examples



157
158
159
160
161
 
# File 'lib/bashly/script/command.rb', line 157

def examples
  return nil unless options['examples']

  options['examples'].is_a?(Array) ? options['examples'] : [options['examples']]
end

#filename ⇒ Object

Returns the filename that is expected to hold the user code for this command



165
166
167
 
# File 'lib/bashly/script/command.rb', line 165

def filename
  options['filename'] || implicit_filename
end

#flags ⇒ Object

Returns an array of Flags



170
171
172
173
174
175
176
 
# File 'lib/bashly/script/command.rb', line 170

def flags
  return [] unless options['flags']

  options['flags'].map do |options|
    Flag.new options
  end
end

#full_name ⇒ Object

Returns the name of the command, including its parent name (in case this is a subcommand)



185
186
187
 
# File 'lib/bashly/script/command.rb', line 185

def full_name
  parents.any? ? (parents + [name]).join(' ') : name
end

#function_name ⇒ Object

Returns a unique name, suitable to be used in a bash function



179
180
181
 
# File 'lib/bashly/script/command.rb', line 179

def function_name
  options['function'] || full_name.to_underscore
end

#global_flags? ⇒ Boolean

Returns true if this command’s flags should be considered as gloal flags, and cascade to subcommands

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/bashly/script/command.rb', line 191

def global_flags?
  flags.any? and commands.any?
end

#group_string ⇒ Object

Returns the string for the group caption



196
197
198
199
200
201
202
 
# File 'lib/bashly/script/command.rb', line 196

def group_string
  if group
    strings[:group] % { group: group }
  else
    strings[:commands]
  end
end

#grouped_commands ⇒ Object

Returns subcommands by group



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/bashly/script/command.rb', line 205

def grouped_commands
  result = {}

  public_commands.each do |command|
    result[command.group_string] ||= []
    result[command.group_string] << command
    next unless command.expose

    command.public_commands.each do |subcommand|
      result[command.group_string] << subcommand
    end
  end

  result
end

#has_unique_args_or_flags? ⇒ Boolean

Returns true if this command, or any subcommand (deep) as any arg or flag with arg that is defined as unique

Returns:

  • (Boolean) 


223
224
225
226
227
228
229
 
# File 'lib/bashly/script/command.rb', line 223

def has_unique_args_or_flags?
  deep_commands(include_self: true).each do |command|
    return true if command.args.count(&:unique).positive? ||
      command.flags.count(&:unique).positive?
  end
  false
end

#mode ⇒ Object

Returns a mode identifier



232
233
234
235
236
237
238
239
240
241
 
# File 'lib/bashly/script/command.rb', line 232

def mode
  @mode ||= if global_flags?    then :global_flags
  elsif commands.any?           then :commands
  elsif args.any? && flags.any? then :args_and_flags
  elsif args.any?               then :args
  elsif flags.any?              then :flags
  else
    :empty
  end
end

#public_command_aliases ⇒ Object

Returns a full list of the public Command names and aliases combined



255
256
257
 
# File 'lib/bashly/script/command.rb', line 255

def public_command_aliases
  public_commands.map(&:aliases).flatten
end

#public_commands ⇒ Object

Returns only commands that are not private



250
251
252
 
# File 'lib/bashly/script/command.rb', line 250

def public_commands
  commands.reject(&:private)
end

#public_environment_variables ⇒ Object

Returns only environment variables that are not private



260
261
262
 
# File 'lib/bashly/script/command.rb', line 260

def public_environment_variables
  environment_variables.reject(&:private)
end

#public_flags ⇒ Object

Returns only flags that are not private



265
266
267
 
# File 'lib/bashly/script/command.rb', line 265

def public_flags
  flags.reject(&:private)
end

#repeatable_arg_exist? ⇒ Boolean

Returns true if one of the args is repeatable

Returns:

  • (Boolean) 


270
271
272
 
# File 'lib/bashly/script/command.rb', line 270

def repeatable_arg_exist?
  args.any?(&:repeatable)
end

#required_args ⇒ Object

Returns an array of all the required Arguments



275
276
277
 
# File 'lib/bashly/script/command.rb', line 275

def required_args
  args.select(&:required)
end

#required_environment_variables ⇒ Object

Returns an array of all the required EnvironmentVariables



280
281
282
 
# File 'lib/bashly/script/command.rb', line 280

def required_environment_variables
  environment_variables.select(&:required)
end

#required_flags ⇒ Object

Returns an array of all the required Flags



285
286
287
 
# File 'lib/bashly/script/command.rb', line 285

def required_flags
  flags.select(&:required)
end

#root_command? ⇒ Boolean

Returns true if this is the root command (no parents)

Returns:

  • (Boolean) 


290
291
292
 
# File 'lib/bashly/script/command.rb', line 290

def root_command?
  parents.empty?
end

#short_flag_exist?(flag) ⇒ Boolean

Returns true if one of the flags matches the provided short code

Returns:

  • (Boolean) 


295
296
297
 
# File 'lib/bashly/script/command.rb', line 295

def short_flag_exist?(flag)
  flags.any? { |f| f.short == flag }
end

#summary_string ⇒ Object

Returns the summary string



300
301
302
303
304
305
306
 
# File 'lib/bashly/script/command.rb', line 300

def summary_string
  if default
    strings[:default_command_summary] % { summary: summary }
  else
    summary
  end
end

#usage_string ⇒ Object

Returns a constructed string suitable for Usage pattern



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/bashly/script/command.rb', line 309

def usage_string
  result = [base_usage_pattern]
  command_string = default_command&.default == 'force' ? '[COMMAND]' : 'COMMAND'

  result.push case mode
  when :global_flags    then ['[OPTIONS]', command_string]
  when :commands        then [command_string]
  when :args_and_flags  then usage_string_args + ['[OPTIONS]']
  when :args            then usage_string_args
  when :flags           then ['[OPTIONS]']
  end

  result.push catch_all.usage_string if catch_all.enabled? && commands.empty?
  result.compact.join ' '
end

#usage_string_args ⇒ Object

Returns an array of args usage_string for the command’s usage_string



326
327
328
 
# File 'lib/bashly/script/command.rb', line 326

def usage_string_args
  args.map(&:usage_string)
end

#user_lib ⇒ Object

Returns an array of files to include as is inside the script This is meant to provide the user with the ability to add custom functions



338
339
340
 
# File 'lib/bashly/script/command.rb', line 338

def user_lib
  @user_lib ||= Dir["#{Settings.full_lib_dir}/**/*.#{Settings.partials_extension}"]
end

#validatables ⇒ Object

Returns a mixed array of Argument and Flag objects that have validations



343
344
345
 
# File 'lib/bashly/script/command.rb', line 343

def validatables
  @validatables ||= args.select(&:validate) + flags.select(&:validate)
end

#whitelisted_args ⇒ Object

Returns an array of all the args with a whitelist



348
349
350
 
# File 'lib/bashly/script/command.rb', line 348

def whitelisted_args
  args.select(&:allowed)
end

#whitelisted_environment_variables ⇒ Object

Returns an array of all the environment_variables with a whitelist arg



353
354
355
 
# File 'lib/bashly/script/command.rb', line 353

def whitelisted_environment_variables
  environment_variables.select(&:allowed)
end

#whitelisted_flags ⇒ Object

Returns an array of all the flags with a whitelist arg



358
359
360
 
# File 'lib/bashly/script/command.rb', line 358

def whitelisted_flags
  flags.select(&:allowed)
end