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, 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?, 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_20?, mri_21?, 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.



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

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



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

def _pry_
  @_pry_
end

#arg_string ⇒ Object

Returns the value of attribute arg_string.



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

def arg_string
  @arg_string
end

#captures ⇒ Object

Returns the value of attribute captures.



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

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


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

def command_block
  @command_block
end

#command_set ⇒ Object

Returns the value of attribute command_set.



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

def command_set
  @command_set
end

#context ⇒ Object

Returns the value of attribute context.



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

def context
  @context
end

#eval_string ⇒ Object

Returns the value of attribute eval_string.



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

def eval_string
  @eval_string
end

#output ⇒ Object

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

#target ⇒ Object

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



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

def command_name
  self.options[:listing]
end

.command_regex ⇒ Object 



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

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



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

.hooks ⇒ Object

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

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



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

#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_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 



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

#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

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



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

#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:



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

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



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

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.



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

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

#text ⇒ Object 



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

#void ⇒ Object 



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

def void
  VOID_VALUE
end