Pry::Command

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.

Constants

VOID_VALUE: represents a void return value for a command

Attributes

block[RW]

command_options[W]

description[W]

name[RW]

options=[W]

_pry_[RW]

arg_string[RW]

captures[RW]

command_block[RW]

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

my-command | do
  puts "block content"
end

command_set[RW]

context[RW]

eval_string[RW]

output[RW]

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

target[RW]

Public Class Methods

command_options(arg=nil) click to toggle source

Define or get the command's options

# File lib/pry/command.rb, line 29
def command_options(arg=nil)
  @command_options ||= {}
  @command_options.merge!(arg) if arg
  @command_options
end

Also aliased as: options

command_regex() click to toggle source

# File lib/pry/command.rb, line 117
def command_regex
  prefix = convert_to_regex(Pry.config.command_prefix)
  prefix = "(?:#{prefix})?" unless options[:use_prefix]

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

convert_to_regex(obj) click to toggle source

# File lib/pry/command.rb, line 124
def convert_to_regex(obj)
  case obj
  when String
    Regexp.escape(obj)
  else
    obj
  end
end

description(arg=nil) click to toggle source

Define or get the command's description

# File lib/pry/command.rb, line 23
def description(arg=nil)
  @description = arg if arg
  @description
end

group(name=nil) click to toggle source

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.

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

hooks() click to toggle source

Store hooks to be run before or after the command body. @see {Pry::CommandSet#before_command} @see {Pry::CommandSet#after_command}

# File lib/pry/command.rb, line 113
def hooks
  @hooks ||= {:before => [], :after => []}
end

inspect() click to toggle source

# File lib/pry/command.rb, line 54
def inspect
  "#<class(Pry::Command #{name.inspect})>"
end

match_score(val) click to toggle source

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.

@example

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

@param String a line input at the REPL @return Fixnum

# File lib/pry/command.rb, line 102
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) click to toggle source

Should this command be called for the given line?

@param String a line input at the REPL @return Boolean

# File lib/pry/command.rb, line 82
def matches?(val)
  command_regex =~ val
end

new(context={}) click to toggle source

Instantiate a command, in preparation for calling it.

@param Hash context The runtime context to use with this command.

# File lib/pry/command.rb, line 206
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

options(arg=nil) click to toggle source

backward compatibility

Alias for: command_options

subclass(name, description, options, helpers, &block) click to toggle source

Create a new command with the given properties.

@param String name the name of the command @param String description the description to appear in {help} @param Hash options behavioural options (@see {Pry::CommandSet#command}) @param Module helpers a module of helper functions to be included. @param Proc &block (optional, a block, used for BlockCommands)

@return Class (a subclass of Pry::Command)

# File lib/pry/command.rb, line 68
def subclass(name, description, options, helpers, &block)
  klass = Class.new(self)
  klass.send(:include, helpers)
  klass.name = name
  klass.description = description
  klass.command_options = options
  klass.block = block
  klass
end

Public Instance Methods

block() click to toggle source

# File lib/pry/command.rb, line 49
def block; self.class.block; end

call_safely(*args) click to toggle source

Run the command with the given {args}.

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

@param *[String] the arguments to pass to this command. @return Object the return value of the {call} method, or Command::VOID_VALUE

# File lib/pry/command.rb, line 334
def call_safely(*args)
  unless dependencies_met?
    gems_needed = Array(command_options[:requires_gem])
    gems_not_installed = gems_needed.select { |g| !gem_installed?(g) }
    output.puts "\nThe command '#{name}' is #{Helpers::Text.bold("unavailable")} because it requires the following gems to be installed: #{(gems_not_installed.join(", "))}"
    output.puts "-"
    output.puts "Type `install-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 '#{name}' requires an argument."
  end

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

check_for_command_name_collision(command_name_match, arg_string) click to toggle source

Display a warning if a command collides with a local/method in the current scope. @param [String] command_name_match The name of the colliding command. @param [Binding] target The current binding context.

# File lib/pry/command.rb, line 236
def check_for_command_name_collision(command_name_match, arg_string)
  collision_type = target.eval("defined?(#{command_name_match})")
  collision_type ||= 'local-variable' if arg_string.match(%{\A\s*[-+*/%&|^]*=})

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

command_name() click to toggle source

# File lib/pry/command.rb, line 51
def command_name; command_options[:listing]; end

command_options() click to toggle source

# File lib/pry/command.rb, line 50
def command_options; self.class.options; end

commands() click to toggle source

# File lib/pry/command.rb, line 187
def commands
  command_set.commands
end

dependencies_met?() click to toggle source

Are all the gems required to use this command installed?

@return Boolean

# File lib/pry/command.rb, line 355
def dependencies_met?
  @dependencies_met ||= command_dependencies_met?(command_options)
end

description() click to toggle source

# File lib/pry/command.rb, line 48
def description; self.class.description; end

interpolate_string(str) click to toggle source

Revaluate the string (str) and perform interpolation. @param [String] str The string to reevaluate with interpolation.

@return [String] The reevaluated string with interpolations

applied (if any).

# File lib/pry/command.rb, line 223
def interpolate_string(str)
  dumped_str = str.dump
  if dumped_str.gsub!(/\\\#\{/, '#{')
    target.eval(dumped_str)
  else
    str
  end
end

name() click to toggle source

Make those properties accessible to instances

# File lib/pry/command.rb, line 47
def name; self.class.name; end

process_line(line) click to toggle source

Process a line that Command.matches? this command.

@param String the line to process @return Object or Command::VOID_VALUE

# File lib/pry/command.rb, line 287
def process_line(line)
  command_name, arg_string, captures, args = tokenize(line)

  check_for_command_name_collision(command_name, arg_string) if Pry.config.collision_warning

  self.arg_string = arg_string
  self.captures = captures

  call_safely(*(captures + args))
end

run(command_string, *args) click to toggle source

Run a command from another command. @param [String] command_string The string that invokes the command @param [Array] args Further arguments to pass to the command @example

run "show-input"

@example

run ".ls"

@example

run "amend-line",  "5", 'puts "hello world"'

# File lib/pry/command.rb, line 182
def run(command_string, *args)
  complete_string = "#{command_string} #{args.join(" ")}"
  command_set.process_line(complete_string, context)
end

target_self() click to toggle source

The value of {self} inside the {target} binding.

# File lib/pry/command.rb, line 216
def target_self; target.eval('self'); end

text() click to toggle source

# File lib/pry/command.rb, line 191
def text
  Pry::Helpers::Text
end

tokenize(val) click to toggle source

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

@param String the line of input @return [

String   the command name used, or portion of line that matched the command_regex
String   a string of all the arguments (i.e. everything but the name)
Array    the captures caught by the command_regex
Array    args the arguments got by splitting the arg_string

]

# File lib/pry/command.rb, line 256
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() click to toggle source

# File lib/pry/command.rb, line 195
def void
  VOID_VALUE
end

Home Classes Methods

In Files

Parent

Namespace

Methods

Included Modules

Class/Module Index

Pry::Command

Constants

Attributes

Public Class Methods

Public Instance Methods