From 609b09e55300e9bbb5f13c940763e63121372f6f Mon Sep 17 00:00:00 2001 From: John Mair Date: Wed, 29 Dec 2010 22:14:12 +1300 Subject: [PATCH] updated docs --- lib/pry/pry_class.rb | 70 +++++++++++++++++++++++++++++++++++++++-- lib/pry/pry_instance.rb | 62 +++++++++++++++++++++++++----------- 2 files changed, 110 insertions(+), 22 deletions(-) diff --git a/lib/pry/pry_class.rb b/lib/pry/pry_class.rb index 8b50a700..11163263 100644 --- a/lib/pry/pry_class.rb +++ b/lib/pry/pry_class.rb @@ -1,18 +1,81 @@ +# @author John Mair (banisterfiend) class Pry # class accessors class << self + + # Get nesting data. + # This method should not need to be accessed directly. + # @return [Array] The unparsed nesting information. attr_reader :nesting - attr_accessor :last_result, :active_instance - attr_accessor :input, :output - attr_accessor :commands, :print, :hooks + + # Get last value evaluated by Pry. + # This method should not need to be accessed directly. + # @return [Object] The last result. + attr_accessor :last_result + + # Get the active Pry instance that manages the active Pry session. + # This method should not need to be accessed directly. + # @return [Pry] The active Pry instance. + attr_accessor :active_instance + + # Set/Get the object to use for input by default by all Pry instances. + # (see input.rb) + # @return [#read] The object to use for input by default by all + # Pry instances. + attr_accessor :input + + # Set/Get the object to use for output by default by all Pry instances. + # (see: output.rb) + # @return [#puts] The object to use for output by default by all + # Pry instances. + attr_accessor :output + + # Set/Get the object to use for commands by default by all Pry instances. + # (see commands.rb) + # @return [#commands] The object to use for commands by default by all + # Pry instances. + attr_accessor :commands + + # Set/Get the Proc to use for printing by default by all Pry + # instances. + # This is the 'print' componenent of the REPL. + # (see print.rb) + # @return [Proc] The Proc to use for printing by default by all + # Pry instances. + attr_accessor :print + + + # Set/Get the Hash that defines Pry hooks used by default by all Pry + # instances. + # (see print.rb) + # @return [Hash] The hooks used by default by all Pry instances. + # @example + # Pry.hooks :before_session => proc { puts "hello" }, + # :after_session => proc { puts "goodbye" } + attr_accessor :hooks + + # Set/Get the array of Procs to be used for the prompts by default by + # all Pry instances. + # (see prompts.rb) + # @return [Array] The array of Procs to be used for the + # prompts by default by all Pry instances. attr_accessor :default_prompt end + # Start a Pry REPL. + # @param [Object, Binding] target The receiver of the Pry session + # @param options (see Pry#initialize) + # @example + # Pry.start(Object.new, :input => MyInput.new) def self.start(target=TOPLEVEL_BINDING, options={}) new(options).repl(target) end + # A custom version of `Kernel#inspect`. + # This method should not need to be accessed directly. + # @param obj The object to view. + # @return [String] The string representation of `obj`. def self.view(obj) case obj when String, Hash, Array, Symbol, nil @@ -22,6 +85,7 @@ class Pry end end + # Set all the configurable options back to their default values def self.reset_defaults @input = Input.new @output = Output.new diff --git a/lib/pry/pry_instance.rb b/lib/pry/pry_instance.rb index df897b41..78762332 100644 --- a/lib/pry/pry_instance.rb +++ b/lib/pry/pry_instance.rb @@ -1,31 +1,55 @@ class Pry + # The list of configuration options. ConfigOptions = [:input, :output, :commands, :print, :default_prompt, :hooks] attr_accessor *ConfigOptions + # Create a new `Pry` object. + # @param [Hash] options The optional configuration parameters. + # @option options [#read] :input The object to use for input. (see input.rb) + # @option options [#puts] :output The object to use for output. (see output.rb) + # @option options [#commands] :commands The object to use for + # commands. (see commands.rb) + # @options options [Hash] :hooks The defined hook Procs (see hooks.rb) + # @option options [Array] :default_prompt The array of Procs + # to use for the prompts. + # @option options [Proc] :print The Proc to use for the 'print' componenent of the REPL def initialize(options={}) - options = ConfigOptions.each_with_object({}) { |v, h| h[v] = Pry.send(v) } - options.merge!(options) + default_options = ConfigOptions.each_with_object({}) { |v, h| h[v] = Pry.send(v) } + default_options.merge!(options) ConfigOptions.each do |key| - instance_variable_set("@#{key}", options[key]) + instance_variable_set("@#{key}", default_options[key]) end end + # Get nesting data. + # This method should not need to be accessed directly. + # @return [Array] The unparsed nesting information. def nesting self.class.nesting end + # Set nesting data. + # This method should not need to be accessed directly. + # @param v nesting data. def nesting=(v) self.class.nesting = v end + + # Execute the hook `hook_name`, if it is defined. + # @param [Symbol] hook_name The hook to execute + # @param [Array] args The arguments to pass to the hook. + def exec_hook(hook_name, *args, &block) + hooks[hook_name].call(*args, &block) if hooks[hook_name] + end - # Start a read-eval-print-loop + # Start a read-eval-print-loop. # If no parameter is given, default to top-level (main). - # @param [Object] target The receiver of the Pry session + # @param [Object, Binding] target The receiver of the Pry session # @return [Object] The target of the Pry session # @example # Pry.new.repl(Object.new) @@ -33,7 +57,7 @@ class Pry target = binding_for(target) target_self = target.eval('self') - hooks[:before_session].call(output, target_self) + exec_hook :before_session, output, target_self nesting_level = nesting.size @@ -51,7 +75,8 @@ class Pry end nesting.pop - hooks[:after_session].call(output, target_self) + + exec_hook :after_session, output, target_self # we only enter here if :breakout has been thrown if nesting_level != break_level @@ -61,9 +86,9 @@ class Pry target_self end - # Perform a read-eval-print + # Perform a read-eval-print. # If no parameter is given, default to top-level (main). - # @param [Object] target The receiver of the read-eval-print + # @param [Object, Binding] target The receiver of the read-eval-print # @example # Pry.new.rep(Object.new) def rep(target=TOPLEVEL_BINDING) @@ -73,9 +98,8 @@ class Pry # Perform a read-eval # If no parameter is given, default to top-level (main). - # @param [Object] target The receiver of the read-eval-print - # @return [Object] The result of the eval or an `Exception` object - # in case of error. + # @param [Object, Binding] target The receiver of the read-eval-print + # @return [Object] The result of the eval or an `Exception` object in case of error. # @example # Pry.new.re(Object.new) def re(target=TOPLEVEL_BINDING) @@ -95,7 +119,7 @@ class Pry # This is a multi-line read; so the read continues until a valid # Ruby expression is received. # Pry commands are also accepted here and operate on the target. - # @param [Object] target The receiver of the read. + # @param [Object, Binding] target The receiver of the read. # @return [String] The Ruby expression. # @example # Pry.new.r(Object.new) @@ -116,10 +140,10 @@ class Pry # Commands can be modified/configured by the user: see `Pry::Commands` # This method should not need to be invoked directly - it is called # by `Pry#r` - # @param [String] val The current line of input + # @param [String] val The current line of input. # @param [String] eval_string The cumulative lines of input for - # multi-line input - # @param [Object] target The receiver of the commands + # multi-line input. + # @param [Object] target The receiver of the commands. def process_commands(val, eval_string, target) def eval_string.clear() replace("") end @@ -142,7 +166,7 @@ class Pry # Returns the appropriate prompt to use. # This method should not need to be invoked directly. # @param [String] eval_string The cumulative lines of input for - # multi-line input + # multi-line input. # @param [Object] target The receiver of the Pry session. # @return [String] The prompt. def prompt(eval_string, target) @@ -159,7 +183,7 @@ class Pry require 'ripper' # Determine if a string of code is a valid Ruby expression. - # Ruby 1.9 uses Ripper parser. + # Ruby 1.9 uses Ripper, Ruby 1.8 uses RubyParser. # @param [String] code The code to validate. # @return [Boolean] Whether or not the code is a valid Ruby expression. # @example @@ -173,7 +197,7 @@ class Pry require 'ruby_parser' # Determine if a string of code is a valid Ruby expression. - # Ruby 1.8 uses RubyParser parser. + # Ruby 1.9 uses Ripper, Ruby 1.8 uses RubyParser. # @param [String] code The code to validate. # @return [Boolean] Whether or not the code is a valid Ruby expression. # @example