pry 0.4.0 → 0.4.1pre1

data/README.markdown

@@ -6,11 +6,20 @@ Pry
 _attach an irb-like session to any object at runtime_
 
 Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
-manipulation of objects during the running of a program. 
+manipulation of objects during the running of a program.
+
+In some sense it is the opposite of IRB in that you bring a REPL
+session to your code (with Pry) instead of bringing your code to a
+REPL session (as with IRB).
 
 It is not based on the IRB codebase, and implements some unique REPL
 commands such as `show_method` and `show_doc`
 
+Pry is also fairly flexible and allows significant user
+customization. It is trivial to set it to read from any
+object that has a `readline` method and write to any object that has a
+`puts` method - many other aspects of Pry are also configurable.
+
 * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
 * Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
 * See the [source code](http://github.com/banister/pry)
@@ -263,377 +272,10 @@ features, see the `examples/` directory.
 Customizing Pry
 ---------------
 
-Pry supports customization of the input, the output, the commands,
-the hooks, the prompt, and 'print' (the "P" in REPL).
-
-Global customization, which applies to all Pry sessions, is done
-through invoking class accessors on the `Pry` class, the accessors
-are:
-
-* `Pry.input=`
-* `Pry.output=`
-* `Pry.commands=`
-* `Pry.hooks=`
-* `Pry.prompt=`
-* `Pry.print=`
-
-Local customization (applied to a single Pry session) is done by
-passing config hash options to `Pry.start()` or to `Pry.new()`; also the
-same accessors as described above for the `Pry` class exist for a
-Pry instance so that customization can occur during runtime.
-
-### Input
-
-For input Pry accepts any object that implements the `readline` method. This
-includes `IO` objects, `StringIO`, `Readline` and custom objects. Pry
-initially defaults to using `Readline` for input.
-
-#### Example: Setting global input
-
-Setting Pry's global input causes all subsequent Pry instances to use
-this input by default:
-
-    Pry.input = StringIO.new("@x = 10\nexit")
-    Object.pry
-
-    Object.instance_variable_get(:@x) #=> 10
-
-The above will execute the code in the `StringIO`
-non-interactively. It gets all the input it needs from the `StringIO`
-and then exits the Pry session. Note it is important to end the
-session with 'exit' if you are running non-interactively or the Pry
-session will hang as it loops indefinitely awaiting new input.
-
-#### Example: Setting input for a specific session
-
-The settings for a specific session override the global settings
-(discussed above). There are two ways to set input for a specific pry session: At the
-point the session is started, or within the session itself (at runtime):
-
-##### At session start
-
-    Pry.start(Object, :input => StringIO.new("@x = 10\nexit"))
-    Object.instance_variable_get(:@x) #=> 10
-
-##### At runtime
-
-If you want to set the input object within the session itself you use
-the special `_pry_` local variable which represents the Pry instance
-managing the current session; inside the session we type:
-
-    _pry_.input = StringIO.new("@x = 10\nexit")
-
-Note we can also set the input object for the parent Pry session (if
-the current session is nested) like so:
-
-    _pry_.parent.input = StringIO.new("@x = 10\nexit")
-
-### Output
-
-For output Pry accepts any object that implements the `puts` method. This
-includes `IO` objects, `StringIO` and custom objects. Pry initially
-defaults to using `$stdout` for output.
-
-#### Example: Setting global output
-
-Setting Pry's global output causes all subsequent Pry instances to use
-this output by default:
-
-    Pry.output = StringIO.new
-
-#### Example: Setting output for a specific session
-
-As per Input, given above, we set the local output as follows:
-
-##### At session start
-
-    Pry.start(Object, :output => StringIO.new("@x = 10\nexit"))
-
-##### At runtime
-    
-    _pry_.output = StringIO.new
-
-### Commands
-
-Pry commands are not methods; they are commands that are intercepted
-and executed before a Ruby eval takes place. Pry comes with a default
-command set (`Pry::Commands`), but these commands can be augmented or overriden by
-user-specified ones.
-
-The Pry command API is quite sophisticated supporting features such as:
-command set inheritance, importing of specific commands from another
-command set, deletion of commands, calling of commands within other
-commands, and so on.
-
-A valid Pry command object must inherit from
-`Pry::CommandBase` (or one of its subclasses) and use the special command API:
-
-#### Example: Defining a command object and setting it globally
-
-    class MyCommands < Pry::CommandBase
-      command "greet", "Greet the user." do |name|
-        output.puts "Hello #{name.capitalize}, how are you?"
-      end
-    end
-
-    Pry.commands = MyCommands
-
-Then inside a pry session:
-
-    pry(main)> greet john
-    hello John, how are you?
-    => nil
-
-#### Example: Using a command object in a specific session
-
-As in the case of `input` and `output`:
-
-##### At session start:
-
-    Pry.start(self, :commands => MyCommands)
-
-##### At runtime:
-
-    _pry_.commands = MyCommands
-
-#### The command API
-
-The command API is defined by the `Pry::CommandBase` class (hence why
-all commands must inherit from it or a subclass). The API works as follows:
-
-##### `command` method
-
-The `command` method defines a new command, its parameter is the
-name of the command and an optional second parameter is a description of
-the command.
-
-The associated block defines the action to be performed. The number of
-parameters in the block determine the number of parameters that will
-be sent to the command (from the Pry prompt) when it is invoked. Note
-that all parameters that are received will be strings; if a parameter
-is not received it will be set to `nil`.
-
-    command "hello" do |x, y, z|
-      puts "hello there #{x}, #{y}, and #{z}!"
-    end
-
-Command aliases can also be defined - simply use an array of strings
-for the command name - all these strings will be valid names for the
-command.
-
-    command ["ls", "dir"], "show a list of local vars" do
-      output.puts target.eval("local_variables")
-    end
-
-##### `delete` method
-
-The `delete` method deletes a command or a group of a commands; it
-can be useful when inheriting from another command set when you decide
-to keep only a portion of inherited commands.
-
-    class MyCommands < Pry::Commands
-      delete "show_method", "show_imethod"
-    end
-
-##### `import_from` method
-
-The `import_from` method enables you to specifically select which
-commands will be copied across from another command set, useful when
-you only want a small number of commands and so inheriting and then
-deleting would be inefficient. The first parameter to `import_from`
-is the class to import from and the other paramters are the names of
-the commands to import:
-
-    class MyCommands < Pry::CommandBase
-      import_from Pry::Commands, "ls", "status", "!"
-    end
-
-##### `run` method
-
-The `run` command invokes one command from within another.
-The first parameter is the name of the command to invoke
-and the remainder of the parameters will be passed on to the command
-being invoked:
-
-    class MyCommands < Pry::Commands
-      command "ls_with_hello" do
-        output.puts "hello!"
-        run "ls"
-      end
-    end
-
-#### Utility methods for commands
-
-All commands can access the special `output` and `target` methods. The
-`output` method returns the `output` object for the active pry session.
-Ensuring that your commands invoke `puts` on this rather than using
-the top-level `puts` will ensure that all your session output goes to
-the same place.
-
-The `target` method returns the `Binding` object the Pry session is currently
-active on - useful when your commands need to manipulate or examine
-the state of the object. E.g, the "ls" command is implemented as follows
-
-    command "ls" do
-      output.puts target.eval("local_variables + instance_variables").inspect
-    end
-
-#### The opts hash
-
-These are miscellaneous variables that may be useful to your commands:
-
-* `opts[:val]` - The line of input that invoked the command.
-* `opts[:eval_string]` - The cumulative lines of input for multi-line input.
-* `opts[:nesting]` - Lowlevel session nesting information.
-* `opts[:commands]` - Lowlevel data of all Pry commands.
-
-(see commands.rb for examples of how some of these options are used)
-
-#### The `help` command
-
-The `Pry::CommandBase` class automatically defines a `help` command
-for you. Typing `help` in a Pry session will show a list of commands
-to the user followed by their descriptions. Passing a parameter to
-`help` with the command name will just return the description of that
-specific command. If a description is left out it will automatically
-be given the description "No description.".
-
-If the description is explicitly set to `""` then this command will
-not be displayed in `help`.
-
-### Hooks
-
-Currently Pry supports just two hooks: `before_session` and
-`after_session`. These hooks are invoked before a Pry session starts
-and after a session ends respectively. The default hooks used are
-stored in the `Pry::DEFAULT_HOOKS` and just output the text `"Beginning
-Pry session for <obj>"` and `"Ending Pry session for <obj>"`.
-
-#### Example: Setting global hooks
-
-All subsequent Pry instances will use these hooks as default:
-
-    Pry.hooks = {
-      :before_session => proc { |out, obj| out.puts "Opened #{obj}" },
-      :after_session => proc { |out, obj| out.puts "Closed #{obj}" }
-    }
-
-    5.pry
-
-Inside the session:
-
-    Opened 5
-    pry(5)> exit
-    Closed 5
-
-Note that the `before_session` and `after_session` procs receive the
-current session's output object and session receiver as parameters.
-
-#### Example: Setting hooks for a specific session
-
-Like all the other customization options, the global default (as
-explained above) can be overriden for a specific session, either at
-session start or during runtime.
-
-##### At session start
-
-    Pry.start(self, :hooks => { :before_session => proc { puts "hello world!" },
-                                :after_session => proc { puts "goodbye world!" }
-                              })
-
-##### At runtime
-
-    _pry_.hooks = { :before_session => proc { puts "puts "hello world!" } }
-
-### Prompts
-
-The Pry prompt is used by `Readline` and other input objects that
-accept a prompt. Pry can accept two prompt-types for every prompt; the
-'main prompt' and the 'wait prompt'. The main prompt is always used
-for the first line of input; the wait prompt is used in multi-line
-input to indicate that the current expression is incomplete and more lines of
-input are required. The default Prompt used by Pry is stored in the
-`Pry::DEFAULT_PROMPT` constant.
-
-A valid Pry prompt is either a single `Proc` object or a two element
-array of `Proc` objects. When an array is used the first element is
-the 'main prompt' and the last element is the 'wait prompt'. When a
-single `Proc` object is used it will be used for both the main prompt
-and the wait prompt.
-
-#### Example: Setting global prompt
-
-The prompt `Proc` objects are passed the receiver of the Pry session
-and the nesting level of that session as parameters (they can simply
-ignore these if they do not need them).
-
-    # Using one proc for both main and wait prompts
-    Pry.prompt = proc { |obj, nest_level| "#{obj}:#{nest_level}> " }
-
-    # Alternatively, provide two procs; one for main and one for wait
-    Pry.prompt = [ proc { "ENTER INPUT> " }, proc { "MORE INPUT REQUIRED!* " }]
-
-#### Example: Setting the prompt for a specific session
-
-##### At session start
-
-    Pry.start(self, :prompt => [proc { "ENTER INPUT> " },
-                                proc { "MORE INPUT REQUIRED!* " }])
-
-##### At runtime
-
-    _pry_.prompt = [proc { "ENTER INPUT> " },
-                    proc { "MORE INPUT REQUIRED!* " }]
-
-### Print
-
-The Print phase of Pry's READ-EVAL-PRINT-LOOP can be customized. The
-default action is stored in the `Pry::DEFAULT_PRINT` constant and it
-simply outputs the value of the current expression preceded by a `=>` (or the first
-line of the backtrace if the value is an `Exception` object.)
-
-The print object should be a `Proc` and the parameters passed to the
-`Proc` are the output object for the current session and the 'value'
-returned by the current expression.
-
-#### Example: Setting global print object
-
-Let's define a print object that displays the full backtrace of any
-exception and precedes the output of a value by the text `"Output is: "`:
-
-    Pry.print = proc do |output, value|
-                  case value
-                  when Exception
-                    output.puts value.backtrace
-                  else
-                    output.puts "Output is: #{value}"
-                  end
-                end
-
-#### Example: Setting the print object for a specific session
-
-##### At session start
-
-    Pry.start(self, :print => proc do |output, value|
-                                case value
-                                when Exception
-                                  output.puts value.backtrace
-                                else
-                                  output.puts "Output is: #{value.inspect}"
-                                end
-                              end)
+Pry allows a large degree of customization. 
 
-##### At runtime
+[Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
 
-    _pry_.print =  proc do |output, value|
-                     case value
-                     when Exception
-                       output.puts value.backtrace
-                     else
-                       output.puts "Output is: #{value.inspect}"
-                     end
-                   end
-    
 Contact
 -------
 

data/Rakefile

@@ -21,10 +21,11 @@ def apply_spec_defaults(s)
   s.require_path = 'lib'
   s.add_dependency("ruby_parser",">=2.0.5")
   s.add_dependency("method_source",">=0.2.0")
+  s.add_development_dependency("bacon",">=1.1.0")
   s.homepage = "http://banisterfiend.wordpress.com"
   s.has_rdoc = 'yard'
   s.files = Dir["ext/**/extconf.rb", "ext/**/*.h", "ext/**/*.c", "lib/**/*.rb",
-                     "test/*.rb", "CHANGELOG", "README.markdown", "Rakefile"]
+                     "test/*.rb", "CHANGELOG", "README.markdown", "Rakefile", ".gemtest"]
 end
 
 task :test do

data/lib/pry/command_base.rb

@@ -5,7 +5,6 @@ class Pry
   class CommandBase
     class << self
       attr_accessor :commands
-      attr_accessor :command_info
       attr_accessor :opts, :output, :target
 
       # private because we want to force function style invocation. We require

data/lib/pry/version.rb

@@ -1,3 +1,3 @@
 class Pry
-  VERSION = "0.4.0"
+  VERSION = "0.4.1pre1"
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: pry
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  hash: 274698070
+  prerelease: true
   segments: 
   - 0
   - 4
-  - 0
-  version: 0.4.0
+  - 1pre1
+  version: 0.4.1pre1
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -14,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-22 00:00:00 +13:00
+date: 2011-01-24 00:00:00 +13:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -25,6 +26,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 5
         segments: 
         - 2
         - 0
@@ -40,6 +42,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 23
         segments: 
         - 0
         - 2
@@ -47,6 +50,22 @@ dependencies:
         version: 0.2.0
   type: :runtime
   version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bacon
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :development
+  version_requirements: *id003
 description: attach an irb-like session to any object at runtime
 email: jrmair@gmail.com
 executables: []
@@ -72,6 +91,7 @@ files:
 - CHANGELOG
 - README.markdown
 - Rakefile
+- .gemtest
 has_rdoc: yard
 homepage: http://banisterfiend.wordpress.com
 licenses: []
@@ -86,17 +106,21 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
+      hash: 25
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: