2011-12-31 06:50:04 -05:00
class Pry
2011-12-31 07:40:01 -05:00
# The super-class of all commands, new commands should be created by calling
# {Pry::CommandSet#command} which creates a BlockCommand or {Pry::CommandSet#command_class}
# which creates a ClassCommand. Please don't use this class directly.
2011-12-31 06:50:04 -05:00
class Command
# represents a void return value for a command
VOID_VALUE = Object . new
# give it a nice inspect
def VOID_VALUE . inspect ( ) " void " end
2011-12-31 07:40:01 -05:00
# Properties of the command itself (as passed as arguments to
# {CommandSet#command} or {CommandSet#command_class}).
2011-12-31 06:50:04 -05:00
class << self
attr_accessor :name
attr_accessor :description
attr_accessor :options
attr_accessor :block
end
2011-12-31 07:40:01 -05:00
# Make those properties accessible to instances
def name ; self . class . name ; end
def description ; self . class . description ; end
def block ; self . class . block ; end
def command_options ; self . class . options ; end
2011-12-31 09:13:59 -05:00
def command_name ; command_options [ :listing ] ; end
2011-12-31 07:40:01 -05:00
class << self
def inspect
" # <class(Pry::Command #{ name . inspect } )> "
end
# 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)
#
def subclass ( name , description , options , helpers , & block )
klass = Class . new ( self )
klass . send ( :include , helpers )
klass . name = name
klass . description = description
klass . options = options
klass . block = block
klass
end
# Store hooks to be run before or after the command body.
# @see {Pry::CommandSet#before_command}
# @see {Pry::CommandSet#after_command}
def hooks
@hooks || = { :before = > [ ] , :after = > [ ] }
end
end
# Properties of one execution of a command (passed by the {Pry::CommandProcessor} as a hash of
# context and expanded in {#initialize}
2011-12-31 06:50:04 -05:00
attr_accessor :output
attr_accessor :target
attr_accessor :captures
attr_accessor :eval_string
attr_accessor :arg_string
2011-12-31 07:40:01 -05:00
attr_accessor :context
2011-12-31 06:50:04 -05:00
attr_accessor :command_set
attr_accessor :command_processor
attr_accessor :_pry_
# 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"'
def run ( command_string , * args )
complete_string = " #{ command_string } #{ args . join ( " " ) } "
command_processor . process_commands ( complete_string , eval_string , target )
end
def commands
command_set . commands
end
def text
Pry :: Helpers :: Text
end
def void
VOID_VALUE
end
include Pry :: Helpers :: BaseHelpers
include Pry :: Helpers :: CommandHelpers
2011-12-31 07:40:01 -05:00
# Instantiate a command, in preparation for calling it.
#
# @param Hash context The runtime context to use with this command.
2011-12-31 09:13:59 -05:00
def initialize ( context = { } )
2011-12-31 06:50:04 -05:00
self . context = context
self . target = context [ :target ]
self . output = context [ :output ]
self . captures = context [ :captures ]
self . eval_string = context [ :eval_string ]
self . arg_string = context [ :arg_string ]
self . command_set = context [ :command_set ]
self . _pry_ = context [ :pry_instance ]
self . command_processor = context [ :command_processor ]
end
2011-12-31 09:13:59 -05:00
# The value of {self} inside the {target} binding.
def target_self ; target . eval ( 'self' ) ; end
2011-12-31 07:40:01 -05:00
# 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
2011-12-31 06:50:04 -05:00
def call_safely ( * args )
2011-12-31 07:40:01 -05:00
unless dependencies_met?
2011-12-31 06:50:04 -05:00
gems_needed = Array ( command_options [ :requires_gem ] )
gems_not_installed = gems_needed . select { | g | ! gem_installed? ( g ) }
output . puts " \n The 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. "
2011-12-31 07:40:01 -05:00
return void
end
if command_options [ :argument_required ] && args . empty?
raise CommandError , " The command ' #{ name } ' requires an argument. "
2011-12-31 06:50:04 -05:00
end
2011-12-31 07:40:01 -05:00
ret = call_with_hooks ( * args )
command_options [ :keep_retval ] ? ret : void
end
# Are all the gems required to use this command installed?
#
# @return Boolean
def dependencies_met?
@dependencies_met || = command_dependencies_met? ( command_options )
2011-12-31 06:50:04 -05:00
end
2011-12-31 07:40:01 -05:00
private
# Run the {#call} method and all the registered hooks.
#
# @param *String the arguments to #{call}
# @return Object the return value from #{call}
2011-12-31 06:50:04 -05:00
def call_with_hooks ( * args )
self . class . hooks [ :before ] . each do | block |
instance_exec ( * args , & block )
end
ret = call * args
self . class . hooks [ :after ] . each do | block |
ret = instance_exec ( * args , & block )
end
2011-12-31 07:40:01 -05:00
ret
2011-12-31 06:50:04 -05:00
end
end
2011-12-31 07:40:01 -05:00
# A super-class for Commands that are created with a single block.
#
# This class ensures that the block is called with the correct number of arguments
# and the right context.
#
# Create subclasses using {Pry::CommandSet#command}.
2011-12-31 06:50:04 -05:00
class BlockCommand < Command
# backwards compatibility
alias_method :opts , :context
def call ( * args )
instance_exec ( * correct_arg_arity ( block . arity , args ) , & block )
end
def correct_arg_arity ( arity , args )
case
when arity < 0
args
when arity == 0
[ ]
when arity > 0
args . values_at * ( 0 .. ( arity - 1 ) ) . to_a
end
end
end
2011-12-31 07:40:01 -05:00
# A super-class ofr Commands with structure.
#
# This class implements the bare-minimum functionality that a command should have,
# namely a --help switch, and then delegates actual processing to its subclasses.
#
# Create subclasses using {Pry::CommandSet#command_class}, and override the {options(opt)} method
# to set up an instance of Slop, and the {process} method to actually run the command. If
# necessary, you can also override {setup} which will be called before {options}, for example to
# require any gems your command needs to run, or to set up state.
2011-12-31 06:50:04 -05:00
class ClassCommand < Command
attr_accessor :opts
attr_accessor :args
2011-12-31 07:40:01 -05:00
# Set up {opts} and {args}, and then call {process}
#
# This function will display help if necessary.
#
# @param *String the arguments passed
# @return Object the return value of {process} or VOID_VALUE
2011-12-31 06:50:04 -05:00
def call ( * args )
setup
self . opts = slop
self . args = self . opts . parse! ( args )
if opts . present? ( :help )
output . puts slop . help
2011-12-31 07:40:01 -05:00
void
2011-12-31 06:50:04 -05:00
else
2011-12-31 07:40:01 -05:00
process
2011-12-31 06:50:04 -05:00
end
end
2011-12-31 07:40:01 -05:00
# Return an instance of Slop that can parse the options that this command accepts.
2011-12-31 06:50:04 -05:00
def slop
Slop . new do | opt |
options ( opt )
opt . on ( :h , :help , " Show this message. " )
end
end
2011-12-31 07:40:01 -05:00
# A function called just before {options(opt)} as part of {call}.
#
# This function can be used to set up any context your command needs to run, for example
# requiring gems, or setting default values for options.
#
# @example
# def setup;
# require 'gist'
# @action = :method
# end
def setup ; end
# A function to setup Slop so it can parse the options your command expects.
#
# NOTE: please don't do anything side-effecty in the main part of this method,
# as it may be called by Pry at any time for introspection reasons. If you need
# to set up default values, use {setup} instead.
#
# @example
# def options(opt)
# opt.banner "Gists methods or classes"
# opt.on(:c, :class, "gist a class") do
# @action = :class
# end
# end
def options ( opt ) ; end
# The actual body of your command should go here.
#
# The {opts} mehod can be called to get the options that Slop has passed,
# and {args} gives the remaining, unparsed arguments.
#
# The return value of this method is discarded unless the command was created
# with :keep_retval => true, in which case it is returned to the repl.
#
# @example
# def process
# if opts.present?(:class)
# gist_class
# else
# gist_method
# end
# end
def process ; raise CommandError , " command ' #{ name } ' not implemented " end
2011-12-31 06:50:04 -05:00
end
end