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 collapse

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 Helpers::DocumentationHelpers

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

Methods included from Pry::CodeObject::Helpers

c_method?, c_module?, command?, module_with_yard_docs?, real_method_object?

Methods included from Helpers::CommandHelpers

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

Methods included from Helpers::OptionsHelpers

method_object, method_options

Methods included from Helpers::BaseHelpers

colorize_code, command_dependencies_met?, find_command, heading, highlight, jruby?, jruby_19?, mri?, mri_19?, mri_2?, not_a_real_file?, rbx?, #safe_send, safe_send, silence_warnings, stagger_output, use_ansi_codes?, windows?, 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.



270
271
272
273
274
275
276
277
278
 
# File 'lib/pry/command.rb', line 270

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.hooks        = context[:hooks]
  self._pry_        = context[:pry_instance]
end

Class Attribute Details

.block ⇒ Object 



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.



228
229
230
 
# File 'lib/pry/command.rb', line 228

def _pry_
  @_pry_
end

#arg_string ⇒ Object

Returns the value of attribute arg_string.



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

def arg_string
  @arg_string
end

#captures ⇒ Object

Returns the value of attribute captures.



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

def captures
  @captures
end

#command_block ⇒ Object

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


236
237
238
 
# File 'lib/pry/command.rb', line 236

def command_block
  @command_block
end

#command_set ⇒ Object

Returns the value of attribute command_set.



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

def command_set
  @command_set
end

#context ⇒ Object

Returns the value of attribute context.



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

def context
  @context
end

#eval_string ⇒ Object

Returns the value of attribute eval_string.



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

def eval_string
  @eval_string
end

#hooks ⇒ Object

Returns the value of attribute hooks.



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

def hooks
  @hooks
end

#output ⇒ Object

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



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

def output
  @output
end

#target ⇒ Object

Returns the value of attribute target.



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

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_name ⇒ Object 



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

def command_name
  self.options[:listing]
end

.command_regex ⇒ Object 



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

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 



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

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

.doc ⇒ Object 



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.



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

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

.hooks ⇒ Object

Deprecated.

Replaced with Hooks#add_hook. Left for compatibility.

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}


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

def hooks
  Pry.hooks
end

.inspect ⇒ Object 



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

.name ⇒ Object 



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

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

.options ⇒ Object

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

.source ⇒ Object 



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_file ⇒ Object Also known as: file 



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

def source_file
  Array(block.source_location).first
end

.source_line ⇒ Object Also known as: line 



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

def source_line
  Array(block.source_location).last
end

.source_location ⇒ Object 



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

#block ⇒ Object 



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:



416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/pry/command.rb', line 416

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 = use_unpatched_symbol do
    call_with_hooks(*args)
  end
  command_options[:keep_retval] ? ret : void
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.



310
311
312
313
314
315
316
317
318
 
# File 'lib/pry/command.rb', line 310

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_name ⇒ Object 



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

def command_name; self.class.command_name; end

#command_options ⇒ Object 



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

def command_options; self.class.options; end

#commands ⇒ Object 



253
254
255
 
# File 'lib/pry/command.rb', line 253

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



455
456
457
 
# File 'lib/pry/command.rb', line 455

def complete(search)
  []
end

#dependencies_met? ⇒ Boolean

Are all the gems required to use this command installed?

Returns:

  • (Boolean) —

    Boolean



447
448
449
 
# File 'lib/pry/command.rb', line 447

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

#description ⇒ Object 



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).



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

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

#match ⇒ Object 



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

def match; self.class.match; end

#name ⇒ Object

Make those properties accessible to instances



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

def name; self.class.name; end

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

Process a line that Command.matches? this command.

Parameters:

  • line (String) —

    The line to process

Returns:



364
365
366
367
368
369
370
371
372
373
 
# File 'lib/pry/command.rb', line 364

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



247
248
249
250
251
 
# File 'lib/pry/command.rb', line 247

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

#source ⇒ Object 



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

def source; self.class.source; end

#source_location ⇒ Object 



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

def source_location; self.class.source_location; end

#state ⇒ Hash

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.



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

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

#target_self ⇒ Object

Returns The value of ‘self` inside the `target` binding.

Returns:

  • (Object) —

    The value of ‘self` inside the `target` binding.



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

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

#text ⇒ Object 



257
258
259
 
# File 'lib/pry/command.rb', line 257

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:



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

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

#use_unpatched_symbol ⇒ Object 



436
437
438
439
440
441
442
 
# File 'lib/pry/command.rb', line 436

def use_unpatched_symbol
  call_method = Symbol.method_defined?(:call) && Symbol.instance_method(:call)
  Symbol.class_eval { undef :call } if call_method
  yield
ensure
  Symbol.instance_eval { define_method(:call, call_method) } if call_method
end

#void ⇒ Object 



261
262
263
 
# File 'lib/pry/command.rb', line 261

def void
  VOID_VALUE
end