class Pry::CommandSet
This class is used to create sets of commands. Commands can be imported from different sets, aliased, removed, etc.
Attributes
Public Class Methods
@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
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
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 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
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
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
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
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
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
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
# File lib/pry/command_set.rb, line 131 def each(&block) @commands.each(&block) end
@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 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
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
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
@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
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 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
# File lib/pry/command_set.rb, line 267 def to_hash @commands.dup end
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
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