class Pry::CommandSet

This class is used to create sets of commands. Commands can be imported from different sets, aliased, removed, etc.

Attributes

helper_module[R]

Public Class Methods

new(*imported_sets, &block) click to toggle source

@param [Array<Commandset>] imported_sets

Sets which will be imported automatically

@yield Optional block run to define commands

# File lib/pry/command_set.rb, line 20
def initialize(*imported_sets, &block)
  @commands      = {}
  @helper_module = Module.new
  import(*imported_sets)
  instance_eval(&block) if block
end

Public Instance Methods

[](pattern) click to toggle source

Find a command that matches the given line @param [String] pattern The line that might be a command invocation @return [Pry::Command, nil]

# File lib/pry/command_set.rb, line 275
def [](pattern)
  commands = @commands.values.select do |command|
    command.matches?(pattern)
  end
  commands.max_by { |command| command.match_score(pattern) }
end
Also aliased as: find_command
[]=(pattern, command) click to toggle source

Re-assign the command found at pattern with command.

@param [Regexp, String] pattern

The command to add or replace(found at _pattern_).

@param [Pry::Command] command

The command to add.

@return [Pry::Command]

Returns the new command (matched with "pattern".)

@example

Pry.config.commands["help"] = MyHelpCommand
# File lib/pry/command_set.rb, line 298
def []=(pattern, command)
  if command.equal?(nil)
    @commands.delete(pattern)
    return
  end

  unless command.is_a?(Class) && command < Pry::Command
    raise TypeError, "command is not a subclass of Pry::Command"
  end

  bind_command_to_pattern = pattern != command.match
  if bind_command_to_pattern
    command_copy = command.dup
    command_copy.match = pattern
    @commands[pattern] = command_copy
  else
    @commands[pattern] = command
  end
end
add_command(command) click to toggle source

Add a command to set.

@param [Command] command

a subclass of Pry::Command.
# File lib/pry/command_set.rb, line 324
def add_command(command)
  self[command.match] = command
end
alias_command(match, action, options = {}) click to toggle source

Aliases a command @param [String, Regex] match The match of the alias (can be a regex). @param [String] action The action to be performed (typically

another command).

@param [Hash] options The optional configuration parameters,

accepts the same as the `command` method, but also allows the
command description to be passed this way too as `:desc`

@example Creating an alias for `ls -M`

Pry.config.commands.alias_command "lM", "ls -M"

@example Pass explicit description (overriding default).

Pry.config.commands.alias_command "lM", "ls -M", :desc => "cutiepie"
# File lib/pry/command_set.rb, line 190
def alias_command(match, action, options = {})
  (cmd = find_command(action)) || raise("command: '#{action}' not found")
  original_options = cmd.options.dup

  options = original_options.merge!(
    desc: "Alias for `#{action}`",
    listing: match.is_a?(String) ? match : match.inspect
  ).merge!(options)

  # ensure default description is used if desc is nil
  desc = options.delete(:desc).to_s

  c = block_command match, desc, options do |*args|
    run action, *args
  end

  # TODO: untested. What's this about?
  c.class_eval do
    define_method(:complete) do |input|
      cmd.new(context).complete(input)
    end
  end

  c.group "Aliases"

  c
end
block_command(match, description = "No description.", options = {}, &block) click to toggle source

Defines a new Pry command. @param [String, Regexp] match The start of invocations of this command. @param [String] description A description of the command. @param [Hash] options The optional configuration parameters. @option options [Boolean] :keep_retval Whether or not to use return value

of the block for return of `command` or just to return `nil`
(the default).

@option options [Boolean] :interpolate Whether string #{} based

interpolation is applied to the command arguments before
executing the command. Defaults to true.

@option options [String] :listing The listing name of the

command. That is the name by which the command is looked up by
help and by show-source. Necessary for commands with regex matches.

@option options [Boolean] :use_prefix Whether the command uses

`Pry.config.command_prefix` prefix (if one is defined). Defaults
to true.

@option options [Boolean] :shellwords Whether the command's arguments

should be split using Shellwords instead of just split on spaces.
Defaults to true.

@yield The action to perform. The parameters in the block

determines the parameters the command will receive. All
parameters passed into the block will be strings. Successive
command parameters are separated by whitespace at the Pry prompt.

@example

MyCommands = Pry::CommandSet.new do
  command "greet", "Greet somebody" do |name|
    puts "Good afternoon #{name.capitalize}!"
  end
end

# From pry:
# pry(main)> pry_instance.commands = MyCommands
# pry(main)> greet john
# Good afternoon John!
# pry(main)> help greet
# Greet somebody

@example Regexp command

MyCommands = Pry::CommandSet.new do
  command(
    /number-(\d+)/, "number-N regex command", :listing => "number"
  ) do |num, name|
    puts "hello #{name}, nice number: #{num}"
  end
end

# From pry:
# pry(main)> pry_instance.commands = MyCommands
# pry(main)> number-10 john
# hello john, nice number: 10
# pry(main)> help number
# number-N regex command
# File lib/pry/command_set.rb, line 78
def block_command(match, description = "No description.", options = {}, &block)
  if description.is_a?(Hash)
    options = description
    description = "No description."
  end
  options = Pry::Command.default_options(match).merge!(options)

  @commands[match] = Pry::BlockCommand.subclass(
    match, description, options, helper_module, &block
  )
end
Also aliased as: command
command(match, description = "No description.", options = {}, &block)
Alias for: block_command
complete(search, context = {}) click to toggle source

Generate completions for the user's search. @param [String] search The line to search for @param [Hash] context The context to create the command with @return [Array<String>]

# File lib/pry/command_set.rb, line 365
def complete(search, context = {})
  if (command = find_command(search))
    command.new(context).complete(search)
  else
    keys = @commands.keys.select do |key|
      key.is_a?(String) && key.start_with?(search)
    end
    keys.map { |key| key + " " }
  end
end
create_command(match, description = "No description.", options = {}, &block) click to toggle source

Defines a new Pry command class.

@param [String, Regexp] match The start of invocations of this command. @param [String] description A description of the command. @param [Hash] options The optional configuration parameters, see {#command} @yield The class body's definition.

@example

Pry::Commands.create_command "echo", "echo's the input", :shellwords => false do
  def options(opt)
    opt.banner "Usage: echo [-u | -d] <string to echo>"
    opt.on :u, :upcase, "ensure the output is all upper-case"
    opt.on :d, :downcase, "ensure the output is all lower-case"
  end

  def process
    if opts.present?(:u) && opts.present?(:d)
      raise Pry::CommandError, "-u and -d makes no sense"
    end
    result = args.join(" ")
    result.downcase! if opts.present?(:downcase)
    result.upcase! if opts.present?(:upcase)
    output.puts result
  end
end
# File lib/pry/command_set.rb, line 117
def create_command(match, description = "No description.", options = {}, &block)
  if description.is_a?(Hash)
    options = description
    description = "No description."
  end
  options = Pry::Command.default_options(match).merge!(options)

  @commands[match] = Pry::ClassCommand.subclass(
    match, description, options, helper_module, &block
  )
  @commands[match].class_eval(&block)
  @commands[match]
end
delete(*searches) click to toggle source

Removes some commands from the set @param [Array<String>] searches the matches or listings of the commands

to remove
# File lib/pry/command_set.rb, line 138
def delete(*searches)
  searches.each do |search|
    cmd = find_command_by_match_or_listing(search)
    @commands.delete cmd.match
  end
end
desc(search, description = nil) click to toggle source

Sets or gets the description for a command (replacing the old description). Returns current description if no description parameter provided. @param [String, Regexp] search The command match. @param [String?] description (nil) The command description. @example Setting

MyCommands = Pry::CommandSet.new do
  desc "help", "help description"
end

@example Getting

Pry.config.commands.desc "amend-line"
# File lib/pry/command_set.rb, line 253
def desc(search, description = nil)
  cmd = find_command_by_match_or_listing(search)
  return cmd.description unless description

  cmd.description = description
end
each(&block) click to toggle source
# File lib/pry/command_set.rb, line 131
def each(&block)
  @commands.each(&block)
end
find_command(pattern)
Alias for: []
find_command_by_match_or_listing(match_or_listing) click to toggle source

@param [String, Regexp] match_or_listing The match or listing of a command.

of the command to retrieve.

@return [Command] The command object matched.

# File lib/pry/command_set.rb, line 173
def find_command_by_match_or_listing(match_or_listing)
  cmd = (@commands[match_or_listing] ||
    Pry::Helpers::BaseHelpers.find_command(match_or_listing, @commands))
  cmd || raise(ArgumentError, "cannot find a command: '#{match_or_listing}'")
end
find_command_for_help(search) click to toggle source

Find the command that the user might be trying to refer to. @param [String] search The user's search. @return [Pry::Command?]

# File lib/pry/command_set.rb, line 331
def find_command_for_help(search)
  find_command(search) ||
    (begin
       find_command_by_match_or_listing(search)
     rescue ArgumentError
       nil
     end)
end
import(*sets) click to toggle source

Imports all the commands from one or more sets. @param [Array<CommandSet>] sets Command sets, all of the commands of which

will be imported.

@return [Pry::CommandSet] Returns the reciever (a command set).

# File lib/pry/command_set.rb, line 149
def import(*sets)
  sets.each do |set|
    @commands.merge! set.to_hash
    helper_module.send :include, set.helper_module
  end
  self
end
import_from(set, *matches) click to toggle source

Imports some commands from a set @param [CommandSet] set Set to import commands from @param [Array<String>] matches Commands to import @return [Pry::CommandSet] Returns the reciever (a command set).

# File lib/pry/command_set.rb, line 161
def import_from(set, *matches)
  helper_module.send :include, set.helper_module
  matches.each do |match|
    cmd = set.find_command_by_match_or_listing(match)
    @commands[cmd.match] = cmd
  end
  self
end
keys()
Alias for: list_commands
list_commands() click to toggle source

@return [Array]

The list of commands provided by the command set.
# File lib/pry/command_set.rb, line 262
def list_commands
  @commands.keys
end
Also aliased as: keys
process_line(val, context = {}) click to toggle source

Process the given line to see whether it needs executing as a command. @param [String] val The line to execute @param [Hash] context The context to execute the commands with @return [CommandSet::Result]

# File lib/pry/command_set.rb, line 351
def process_line(val, context = {})
  if (command = find_command(val))
    context = context.merge(command_set: self)
    retval = command.new(context).process_line(val)
    Result.new(true, retval)
  else
    Result.new(false)
  end
end
rename_command(new_match, search, options = {}) click to toggle source

Rename a command. Accepts either match or listing for the search.

@param [String, Regexp] new_match The new match for the command. @param [String, Regexp] search The command's current match or listing. @param [Hash] options The optional configuration parameters,

accepts the same as the `command` method, but also allows the
command description to be passed this way too.

@example Renaming the `ls` command and changing its description.

Pry.config.commands.rename "dir", "ls", :description => "DOS friendly ls"
# File lib/pry/command_set.rb, line 227
def rename_command(new_match, search, options = {})
  cmd = find_command_by_match_or_listing(search)

  options = {
    listing: new_match,
    description: cmd.description
  }.merge!(options)

  @commands[new_match] = cmd.dup
  @commands[new_match].match = new_match
  @commands[new_match].description = options.delete(:description)
  @commands[new_match].options.merge!(options)
  @commands.delete(cmd.match)
end
to_h()
Alias for: to_hash
to_hash() click to toggle source
# File lib/pry/command_set.rb, line 267
def to_hash
  @commands.dup
end
Also aliased as: to_h
valid_command?(val) click to toggle source

Is the given line a command invocation? @param [String] val @return [Boolean]

# File lib/pry/command_set.rb, line 343
def valid_command?(val)
  !!find_command(val)
end

Private Instance Methods

helpers(&block) click to toggle source

Defines helpers methods for this command sets. Those helpers are only defined in this command set.

@yield A block defining helper methods @example

helpers do
  def hello
    puts "Hello!"
  end

  include OtherModule
end
# File lib/pry/command_set.rb, line 390
def helpers(&block)
  helper_module.class_eval(&block)
end