Class: Pry::Command

Inherits:
Object show all
Extended by:
Pry::CodeObject::Helpers, Helpers::DocumentationHelpers
Includes:
Helpers::BaseHelpers, Helpers::CommandHelpers
Defined in:
lib/pry/command.rb

Overview

The super-class of all commands, new commands should be created by calling Pry::CommandSet#command which creates a BlockCommand or Pry::CommandSet#create_command which creates a ClassCommand. Please don't use this class directly.

Direct Known Subclasses

BlockCommand, ClassCommand

Defined Under Namespace

Classes: AmendLine, Bang, BangPry, Cat, Cd, ChangeInspector, ChangePrompt, CodeCollector, DisablePry, Edit, Exit, ExitAll, ExitProgram, FindMethod, FixIndent, GemCd, GemInstall, GemList, GemOpen, GemReadme, GemSearch, Gist, Help, Hist, ImportSet, InstallCommand, JumpTo, ListInspectors, ListPrompts, Ls, Nesting, Play, PryBacktrace, RaiseUp, ReloadCode, Reset, Ri, SaveFile, ShellCommand, ShellMode, ShowDoc, ShowInfo, ShowInput, ShowSource, SimplePrompt, Stat, SwitchTo, ToggleColor, Version, WatchExpression, Whereami, Wtf

Constant Summary

VOID_VALUE =

represents a void return value for a command

Object.new

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Pry::CodeObject::Helpers

c_method?, command?, module_with_yard_docs?, real_method_object?

Methods included from Helpers::DocumentationHelpers

get_comment_content, get_comment_content, process_comment_markup, process_comment_markup, process_rdoc, process_rdoc, process_yardoc, process_yardoc, process_yardoc_tag, process_yardoc_tag, strip_comments_from_c_code, strip_comments_from_c_code, strip_leading_whitespace, strip_leading_whitespace

Methods included from Helpers::CommandHelpers

#absolute_index_number, absolute_index_number, absolute_index_range, #absolute_index_range, command_error, #command_error, #get_method_or_raise, get_method_or_raise, internal_binding?, #internal_binding?, one_index_number, #one_index_number, one_index_range, #one_index_range, #one_index_range_or_number, one_index_range_or_number, #restrict_to_lines, restrict_to_lines, #set_file_and_dir_locals, set_file_and_dir_locals, #temp_file, temp_file, #unindent, unindent

Methods included from Helpers::OptionsHelpers

method_object, #method_object, method_options, #method_options

Methods included from Helpers::BaseHelpers

#colorize_code, colorize_code, command_dependencies_met?, #command_dependencies_met?, #find_command, find_command, #heading, heading, highlight, #highlight, jruby?, #jruby?, #jruby_19?, jruby_19?, mri?, #mri?, #mri_19?, mri_19?, #mri_20?, mri_20?, #mri_21?, mri_21?, mri_2?, #mri_2?, #not_a_real_file?, not_a_real_file?, #rbx?, rbx?, #safe_send, safe_send, silence_warnings, #silence_warnings, #stagger_output, stagger_output, use_ansi_codes?, #use_ansi_codes?, windows?, #windows?, windows_ansi?, #windows_ansi?

Constructor Details

#initialize(context = {}) ⇒ Command

Instantiate a command, in preparation for calling it.

Parameters:

  • context (Hash) (defaults to: {})

    The runtime context to use with this command.



268
269
270
271
272
273
274
275
# File 'lib/pry/command.rb', line 268

def initialize(context={})
  self.context      = context
  self.target       = context[:target]
  self.output       = context[:output]
  self.eval_string  = context[:eval_string]
  self.command_set  = context[:command_set]
  self._pry_        = context[:pry_instance]
end

Class Attribute Details

.blockObject



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

def block
  @block || instance_method(:process)
end

.command_options(arg = nil) ⇒ Object

Define or get the command's options



43
44
45
46
47
# File 'lib/pry/command.rb', line 43

def command_options(arg=nil)
  @command_options ||= default_options(match)
  @command_options.merge!(arg) if arg
  @command_options
end

.description(arg = nil) ⇒ Object

Define or get the command's description



37
38
39
40
# File 'lib/pry/command.rb', line 37

def description(arg=nil)
  @description = arg if arg
  @description ||= nil
end

.match(arg = nil) ⇒ Object



27
28
29
30
31
32
33
34
# File 'lib/pry/command.rb', line 27

def match(arg=nil)
  if arg
    @command_options ||= default_options(arg)
    @command_options[:listing] = arg.is_a?(String) ? arg : arg.inspect
    @match = arg
  end
  @match ||= nil
end

Instance Attribute Details

#_pry_Object

Returns the value of attribute pry



226
227
228
# File 'lib/pry/command.rb', line 226

def _pry_
  @_pry_
end

#arg_stringObject

Returns the value of attribute arg_string



223
224
225
# File 'lib/pry/command.rb', line 223

def arg_string
  @arg_string
end

#capturesObject

Returns the value of attribute captures



221
222
223
# File 'lib/pry/command.rb', line 221

def captures
  @captures
end

#command_blockObject

The block we pass into a command so long as :takes_block is not equal to false

Examples:

my-command | do
  puts "block content"
end


234
235
236
# File 'lib/pry/command.rb', line 234

def command_block
  @command_block
end

#command_setObject

Returns the value of attribute command_set



225
226
227
# File 'lib/pry/command.rb', line 225

def command_set
  @command_set
end

#contextObject

Returns the value of attribute context



224
225
226
# File 'lib/pry/command.rb', line 224

def context
  @context
end

#eval_stringObject

Returns the value of attribute eval_string



222
223
224
# File 'lib/pry/command.rb', line 222

def eval_string
  @eval_string
end

#outputObject

Properties of one execution of a command (passed by Pry#run_command as a hash of context and expanded in #initialize



219
220
221
# File 'lib/pry/command.rb', line 219

def output
  @output
end

#targetObject

Returns the value of attribute target



220
221
222
# File 'lib/pry/command.rb', line 220

def target
  @target
end

Class Method Details

Define or get the command's banner



53
54
55
56
# File 'lib/pry/command.rb', line 53

def banner(arg=nil)
  @banner = arg if arg
  @banner || description
end

.command_nameObject



118
119
120
# File 'lib/pry/command.rb', line 118

def command_name
  self.options[:listing]
end

.command_regexObject



177
178
179
180
181
182
183
# File 'lib/pry/command.rb', line 177

def command_regex
  pr = Pry.respond_to?(:config) ? Pry.config.command_prefix : ""
  prefix = convert_to_regex(pr)
  prefix = "(?:#{prefix})?" unless options[:use_prefix]

  /^#{prefix}#{convert_to_regex(match)}(?!\S)/
end

.convert_to_regex(obj) ⇒ Object



185
186
187
188
189
190
191
192
# File 'lib/pry/command.rb', line 185

def convert_to_regex(obj)
  case obj
  when String
    Regexp.escape(obj)
  else
    obj
  end
end

.default_options(match) ⇒ Object



85
86
87
88
89
90
91
92
93
94
95
96
# File 'lib/pry/command.rb', line 85

def default_options(match)
  {
    :requires_gem      => [],
    :keep_retval       => false,
    :argument_required => false,
    :interpolate       => true,
    :shellwords        => true,
    :listing           => (String === match ? match : match.inspect),
    :use_prefix        => true,
    :takes_block       => false
  }
end

.docObject



67
68
69
# File 'lib/pry/command.rb', line 67

def doc
  new.help
end

.group(name = nil) ⇒ Object

The group in which the command should be displayed in "help" output. This is usually auto-generated from directory naming, but it can be manually overridden if necessary. Group should not be changed once it is initialized.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
# File 'lib/pry/command.rb', line 198

def group(name=nil)
  @group ||= if name
               name
             else
               case Pry::Method(block).source_file
               when %r{/pry/.*_commands/(.*).rb}
                 $1.capitalize.gsub(/_/, " ")
               when %r{(pry-\w+)-([\d\.]+([\w\.]+)?)}
                 name, version = $1, $2
                 "#{name.to_s} (v#{version.to_s})"
               when /pryrc/
                 "~/.pryrc"
               else
                 "(other)"
               end
             end
end

.hooksObject

Store hooks to be run before or after the command body.

See Also:

  • {Pry{Pry::CommandSet{Pry::CommandSet#before_command}
  • {Pry{Pry::CommandSet{Pry::CommandSet#after_command}


173
174
175
# File 'lib/pry/command.rb', line 173

def hooks
  @hooks ||= {:before => [], :after => []}
end

.inspectObject



114
115
116
# File 'lib/pry/command.rb', line 114

def inspect
  name
end

.match_score(val) ⇒ Fixnum

How well does this command match the given line?

Higher scores are better because they imply that this command matches the line more closely.

The score is calculated by taking the number of characters at the start of the string that are used only to identify the command, not as part of the arguments.

Examples:

/\.(.*)/.match_score(".foo") #=> 1
/\.*(.*)/.match_score("...foo") #=> 3
'hi'.match_score("hi there") #=> 2

Parameters:

  • val (String)

    A line input at the REPL

Returns:

  • (Fixnum)


162
163
164
165
166
167
168
# File 'lib/pry/command.rb', line 162

def match_score(val)
  if command_regex =~ val
    Regexp.last_match.size > 1 ? Regexp.last_match.begin(1) : Regexp.last_match.end(0)
  else
    -1
  end
end

.matches?(val) ⇒ Boolean

Should this command be called for the given line?

Parameters:

  • val (String)

    A line input at the REPL

Returns:

  • (Boolean)


142
143
144
# File 'lib/pry/command.rb', line 142

def matches?(val)
  command_regex =~ val
end

.nameObject



110
111
112
# File 'lib/pry/command.rb', line 110

def name
  super.to_s == "" ? "#<class(Pry::Command #{match.inspect})>" : super
end

.optionsObject

Define or get the command's options backward compatibility



49
50
51
52
53
# File 'lib/pry/command.rb', line 49

def command_options(arg=nil)
  @command_options ||= default_options(match)
  @command_options.merge!(arg) if arg
  @command_options
end

.sourceObject



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

def source
  file, line = block.source_location
  strip_leading_whitespace(Pry::Code.from_file(file).expression_at(line))
end

.source_fileObject Also known as: file



75
76
77
# File 'lib/pry/command.rb', line 75

def source_file
  Array(block.source_location).first
end

.source_lineObject Also known as: line



80
81
82
# File 'lib/pry/command.rb', line 80

def source_line
  Array(block.source_location).last
end

.source_locationObject



71
72
73
# File 'lib/pry/command.rb', line 71

def source_location
  block.source_location
end

.subclass(match, description, options, helpers) { ... } ⇒ Class

Create a new command with the given properties.

Parameters:

  • match (String, Regex)

    The thing that triggers this command

  • description (String)

    The description to appear in help

  • options (Hash)

    Behavioral options (see Pry::CommandSet#command)

  • helpers (Module)

    A module of helper functions to be included.

Yields:

  • optional, used for BlockCommands

Returns:



129
130
131
132
133
134
135
136
137
# File 'lib/pry/command.rb', line 129

def subclass(match, description, options, helpers, &block)
  klass = Class.new(self)
  klass.send(:include, helpers)
  klass.match = match
  klass.description = description
  klass.command_options = options
  klass.block = block
  klass
end

Instance Method Details

#blockObject



103
# File 'lib/pry/command.rb', line 103

def block; self.class.block; end

#call_safely(*args) ⇒ Object

Run the command with the given args.

This is a public wrapper around #call which ensures all preconditions are met.

Parameters:

  • args (Array<String>)

    The arguments to pass to this command.

Returns:



413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
# File 'lib/pry/command.rb', line 413

def call_safely(*args)
  unless dependencies_met?
    gems_needed = Array(command_options[:requires_gem])
    gems_not_installed = gems_needed.select { |g| !Rubygem.installed?(g) }
    output.puts "\nThe command '#{command_name}' is #{text.bold("unavailable")} because it requires the following gems to be installed: #{(gems_not_installed.join(", "))}"
    output.puts "-"
    output.puts "Type `install-command #{command_name}` to install the required gems and activate this command."
    return void
  end

  if command_options[:argument_required] && args.empty?
    raise CommandError, "The command '#{command_name}' requires an argument."
  end

  ret = call_with_hooks(*args)
  command_options[:keep_retval] ? ret : void
end

#call_with_hooks(*args) ⇒ Object (private)

Run the #call method and all the registered hooks.

Parameters:

  • args (Array<String>)

    The arguments to #call

Returns:

  • (Object)

    The return value from #call



451
452
453
454
455
456
457
458
459
460
461
462
463
# File 'lib/pry/command.rb', line 451

def call_with_hooks(*args)
  self.class.hooks[:before].each do |block|
    instance_exec(*args, &block)
  end

  ret = call(*args)

  self.class.hooks[:after].each do |block|
    ret = instance_exec(*args, &block)
  end

  ret
end

#check_for_command_collision(command_match, arg_string) ⇒ Object

Display a warning if a command collides with a local/method in the current scope.



307
308
309
310
311
312
313
314
315
# File 'lib/pry/command.rb', line 307

def check_for_command_collision(command_match, arg_string)
  collision_type = target.eval("defined?(#{command_match})")
  collision_type ||= 'local-variable' if arg_string.match(%r{\A\s*[-+*/%&|^]*=})

  if collision_type
    output.puts "#{text.bold('WARNING:')} Calling Pry command '#{command_match}', which conflicts with a #{collision_type}.\n\n"
  end
rescue Pry::RescuableException
end

#command_nameObject



105
# File 'lib/pry/command.rb', line 105

def command_name; self.class.command_name; end

#command_optionsObject



104
# File 'lib/pry/command.rb', line 104

def command_options; self.class.options; end

#commandsObject



251
252
253
# File 'lib/pry/command.rb', line 251

def commands
  command_set.to_hash
end

#complete(search) ⇒ Array<String>

Generate completions for this command

Parameters:

  • search (String)

    The line typed so far

Returns:

  • (Array<String>)

    Completion words



442
443
444
# File 'lib/pry/command.rb', line 442

def complete(search)
  []
end

#correct_arg_arity(arity, args) ⇒ Array (private)

Fix the number of arguments we pass to a block to avoid arity warnings.

Parameters:

  • arity (Fixnum)

    The arity of the block

  • args (Array)

    The arguments to pass

Returns:

  • (Array)

    A (possibly shorter) array of the arguments to pass



469
470
471
472
473
474
475
476
477
478
# File 'lib/pry/command.rb', line 469

def correct_arg_arity(arity, args)
  case
  when arity < 0
    args
  when arity == 0
    []
  when arity > 0
    args.values_at(*(0..(arity - 1)).to_a)
  end
end

#dependencies_met?Boolean

Are all the gems required to use this command installed?

Returns:

  • (Boolean)

    Boolean



434
435
436
# File 'lib/pry/command.rb', line 434

def dependencies_met?
  @dependencies_met ||= command_dependencies_met?(command_options)
end

#descriptionObject



102
# File 'lib/pry/command.rb', line 102

def description; self.class.description; end

#interpolate_string(str) ⇒ String

Revaluate the string (str) and perform interpolation.

Parameters:

  • str (String)

    The string to reevaluate with interpolation.

Returns:

  • (String)

    The reevaluated string with interpolations applied (if any).



296
297
298
299
300
301
302
303
# File 'lib/pry/command.rb', line 296

def interpolate_string(str)
  dumped_str = str.dump
  if dumped_str.gsub!(/\\\#\{/, '#{')
    target.eval(dumped_str)
  else
    str
  end
end

#matchObject



101
# File 'lib/pry/command.rb', line 101

def match; self.class.match; end

#nameObject

Make those properties accessible to instances



100
# File 'lib/pry/command.rb', line 100

def name; self.class.name; end

#pass_block(arg_string) ⇒ Object (private)

Pass a block argument to a command.

Parameters:

  • arg_string (String)

    The arguments (as a string) passed to the command. We inspect these for a '| do' or a '| {' and if we find it we use it to start a block input sequence. Once we have a complete block, we save it to an accessor that can be retrieved from the command context. Note that if we find the '| do' or '| {' we delete this and the elements following it from arg_string.



379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
# File 'lib/pry/command.rb', line 379

def pass_block(arg_string)
  # Workaround for weird JRuby bug where rindex in this case can return nil
  # even when there's a match.
  arg_string.scan(/\| *(?:do|\{)/)
  block_index = $~ && $~.offset(0)[0]

  return if !block_index

  block_init_string = arg_string.slice!(block_index..-1)[1..-1]
  prime_string = "proc #{block_init_string}\n"

  if !Pry::Code.complete_expression?(prime_string)
    block_string = _pry_.r(target, prime_string)
  else
    block_string = prime_string
  end

  begin
    self.command_block = target.eval(block_string)
  rescue Pry::RescuableException
    raise CommandError, "Incomplete block definition."
  end
end

#process_line(line) ⇒ Object, Command::VOID_VALUE

Process a line that Command.matches? this command.

Parameters:

  • line (String)

    The line to process

Returns:



361
362
363
364
365
366
367
368
369
370
# File 'lib/pry/command.rb', line 361

def process_line(line)
  command_match, arg_string, captures, args = tokenize(line)

  check_for_command_collision(command_match, arg_string) if Pry.config.collision_warning

  self.arg_string = arg_string
  self.captures = captures

  call_safely(*(captures + args))
end

#run(command_string, *args) ⇒ Object

Run a command from another command.

Examples:

run "show-input"
run ".ls"
run "amend-line",  "5", 'puts "hello world"'

Parameters:

  • command_string (String)

    The string that invokes the command

  • args (Array)

    Further arguments to pass to the command



245
246
247
248
249
# File 'lib/pry/command.rb', line 245

def run(command_string, *args)
  command_string = _pry_.config.command_prefix.to_s + command_string
  complete_string = "#{command_string} #{args.join(" ")}".rstrip
  command_set.process_line(complete_string, context)
end

#sourceObject



106
# File 'lib/pry/command.rb', line 106

def source; self.class.source; end

#source_locationObject



107
# File 'lib/pry/command.rb', line 107

def source_location; self.class.source_location; end

#stateHash

Returns Pry commands can store arbitrary state here. This state persists between subsequent command invocations. All state saved here is unique to the command, it does not need to be namespaced.

Examples:

state.my_state = "my state"  # this will not conflict with any
                             # `state.my_state` used in another command.

Returns:

  • (Hash)

    Pry commands can store arbitrary state here. This state persists between subsequent command invocations. All state saved here is unique to the command, it does not need to be namespaced.



287
288
289
# File 'lib/pry/command.rb', line 287

def state
  _pry_.command_state[match] ||= Pry::Config.from_hash({})
end

#target_selfObject

Returns The value of self inside the target binding.

Returns:

  • (Object)

    The value of self inside the target binding.



278
# File 'lib/pry/command.rb', line 278

def target_self; target.eval('self'); end

#textObject



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

def text
  Pry::Helpers::Text
end

#tokenize(val) ⇒ Array

Extract necessary information from a line that Command.matches? this command.

Returns an array of four elements:

 [String] the portion of the line that matched with the Command match
 [String] a string of all the arguments (i.e. everything but the match)
 [Array]  the captures caught by the command_regex
 [Array]  the arguments obtained by splitting the arg_string

Parameters:

  • val (String)

    The line of input

Returns:

  • (Array)

Raises:



331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
# File 'lib/pry/command.rb', line 331

def tokenize(val)
  val.replace(interpolate_string(val)) if command_options[:interpolate]

  self.class.command_regex =~ val

  # please call Command.matches? before Command#call_safely
  raise CommandError, "fatal: called a command which didn't match?!" unless Regexp.last_match
  captures = Regexp.last_match.captures
  pos = Regexp.last_match.end(0)

  arg_string = val[pos..-1]

  # remove the one leading space if it exists
  arg_string.slice!(0) if arg_string.start_with?(" ")

  # process and pass a block if one is found
  pass_block(arg_string) if command_options[:takes_block]

  if arg_string
    args = command_options[:shellwords] ? Shellwords.shellwords(arg_string) : arg_string.split(" ")
  else
    args = []
  end

  [val[0..pos].rstrip, arg_string, captures, args]
end

#voidObject



259
260
261
# File 'lib/pry/command.rb', line 259

def void
  VOID_VALUE
end