Permalink
Browse files

added import_from, delete, run to command API. Also added examples, a…

…dded more tests, and changed the way that commands work using split instead of regex captures. Also added output and trget methods to Pry::CommandBase
  • Loading branch information...
banister committed Jan 20, 2011
1 parent ec66e9b commit 548b4f82d8bab7d52759d34b1c69350eaac6c4f3
View
@@ -343,31 +343,36 @@ 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` and use the special command API:
#### Example: Defining a command object and setting it globally
class MyCommands < Pry::CommandBase
- command "hello", "Output hello to the user." do |name|
- opts[:output].puts "hello #{name}!"
+ 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)> hello john
- hello john!
+ 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:
-nnnnn
+
Pry.start(self, :commands => MyCommands)
##### At runtime:
@@ -377,9 +382,9 @@ nnnnn
#### The command API
The command API is defined by the `Pry::CommandBase` class (hence why
-all commands must inherit from it). The API works as follows:
+all commands must inherit from it or a subclass). The API works as follows:
-The `command` method defines a new command, its parameter is the
+* 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.
@@ -398,23 +403,64 @@ for the command name - all these strings will be valid names for the
command.
command ["ls", "dir"], "show a list of local vars" do
- opts[:output].puts opts[:target].eval("local_variables")
+ output.puts target.eval("local_variables")
end
+* 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
+
+* 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
+
+* 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:
-#### opts hash
+ 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
-Note that in the example above we are using `opts[:output]` for output; this is the output
-object in use by the current pry session. Other hash values accessible
-within a `command` block include:
+ 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 own commands:
-* `opts[:output]` - The session's output object.
* `opts[:val]` - The line of input that invoked the command.
* `opts[:eval_string]` - The cumulative lines of input for multi-line input.
-* `opts[:target]` - The object the Pry session is currently on.
-* `opts[:captures]` - The array of regex captures generated by the command (if any).
* `opts[:nesting]` - Lowlevel session nesting information.
-* `opts[:command_info]` - Lowlevel information about all Pry commands.
+* `opts[:commands]` - Lowlevel data of all Pry commands.
(see commands.rb for examples of how some of these options are used)
@@ -424,7 +470,11 @@ 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.
+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
@@ -0,0 +1,27 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+# inherit standard command set, but tweak them by deleting some and
+# overriding others
+class MyCommands < Pry::CommandBase
+
+ # Override ls command
+ command "ls", "An unhelpful ls" do
+ output.puts "No, i refuse to display any useful information."
+ end
+
+ # Invoke one command from within another using `run`
+ command "status2" do |x|
+ output.puts "About to show status, are you ready?"
+ run "status", x
+ output.puts "Finished showing status."
+ end
+
+ import_from Pry::Commands, "quit", "show_method", "ls"
+end
+
+# Start a Pry session using the commands defined in MyCommands
+# Type 'help' in Pry to get a list of the commands and their descriptions
+Pry.start(TOPLEVEL_BINDING, :commands => MyCommands)
@@ -0,0 +1,36 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+class MathCommands < Pry::CommandBase
+ command "greet", "Greet a person, e.g: greet john" do |name|
+ output.puts "Good afternoon #{name.capitalize}! Do you like Math?"
+ end
+
+ command "add", "Add a list of numbers together, e.g: add 1 2 3 4" do |*args|
+ output.puts "Total: #{args.map(&:to_f).inject(&:+)}"
+ end
+
+ command "multiply", "Multiply a list of numbers together, e.g: multiply 1 2 3 4" do |*args|
+ output.puts "Total: #{args.map(&:to_f).inject(&:*)}"
+ end
+
+ # Explicitly giving a description of "" to prevent command being
+ # displayed in 'help'
+ command "exit", "" do
+ throw :breakout, 0
+ end
+end
+
+# Since we provide math commands, let's have mathematical
+# before_session and after_session hooks, and a mathematical prompt
+math_prompt = proc { "math> " }
+math_hooks = {
+ :before_session => proc { |output, *| output.puts "Welcome! Let's do some math! Type 'help' for a list of commands." },
+ :after_session => proc { |output, *| output.puts "Goodbye!" }
+}
+
+# Start a Pry session using the commands defined in MyCommands
+# Type 'help' in Pry to get a list of the commands and their descriptions
+Pry.start(TOPLEVEL_BINDING, :commands => MathCommands, :prompt => math_prompt, :hooks => math_hooks)
View
@@ -0,0 +1,12 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+my_hooks = {
+ :before_session => proc { |out, obj| out.puts "Opening #{obj}." },
+ :after_session => proc { |out, obj| out.puts "Closing #{obj}." }
+}
+
+# Start a Pry session using the hooks hash defined in my_hooks
+Pry.start(TOPLEVEL_BINDING, :hooks => my_hooks)
@@ -0,0 +1,70 @@
+# Note: this requires you to have Gosu and TexPlay installed.
+# `gem install gosu`
+# `gem install texplay`
+#
+# Extra instructions for installing Gosu on Linux can be found here:
+# http://code.google.com/p/gosu/wiki/GettingStartedOnLinux
+#
+# Instructions for using TexPlay can be found here:
+# http://banisterfiend.wordpress.com/2008/08/23/texplay-an-image-manipulation-tool-for-ruby-and-gosu/
+#
+# Have fun! :)
+
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "texplay"
+require "#{direc}/../lib/pry"
+
+WIDTH = 640
+HEIGHT = 480
+
+IMAGE_PROMPT = [ proc { "(image edit)> " }, proc { "(image edit)* " } ]
+
+class ImageCommands < Pry::CommandBase
+ command "drawing_methods", "Show a list of TexPlay methods" do
+ output.puts "#{Pry.view(TexPlay.public_instance_methods)}"
+ end
+
+ command "exit", "Exit the program." do
+ output.puts "Thanks for dropping by!"
+ exit
+ end
+
+ import_from Pry::Commands, "ls", "ls_methods", "!"
+end
+
+class WinClass < Gosu::Window
+
+ def initialize
+ super(WIDTH, HEIGHT, false)
+ @img = TexPlay.create_image(self, 200, 200)
+ @img.rect 0, 0, @img.width - 1, @img.height - 1
+
+ @binding = @img.__binding__
+
+ @pry_instance = Pry.new(:commands => ImageCommands, :prompt => IMAGE_PROMPT)
+ end
+
+ def draw
+ @img.draw_rot(WIDTH / 2, HEIGHT / 2, 1, 0, 0.5, 0.5)
+ end
+
+ def update
+ exit if button_down?(Gosu::KbEscape)
+
+ # We do not want a REPL session as the loop prevents the image
+ # being updated; instead we do a REP session, and let the image
+ # update each time the user presses enter. We maintain the same
+ # binding object to keep locals between calls to `Pry#rep()`
+ @pry_instance.rep(@binding)
+ end
+end
+
+puts "Welcome to ImageEdit; type `help` for a list of commands and `drawing_methods` for a list of drawing methods available."
+puts "--"
+puts "Example: Try typing 'circle width/2, height/2, 95, :color => :blue, :fill => true'"
+puts "If you want to save your image, type: save(\"img.png\")"
+
+WinClass.new.show
+
View
@@ -0,0 +1,10 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+# Create a StringIO that contains the input data
+str_input = StringIO.new("puts 'hello world!'\nputs \"I am in \#{self}\"\nexit")
+
+# Start a Pry session on the Fixnum 5 using the input data in str_input
+Pry.start(5, :input => str_input)
View
@@ -0,0 +1,14 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+# Create a StringIO to contain the output data
+str_output = StringIO.new
+
+# Start a Pry session on the Fixnum 5 using str_output to store the
+# output (not writing to $stdout)
+Pry.start(5, :output => str_output)
+
+# Display all the output accumulated during the session
+puts str_output.string
@@ -0,0 +1,9 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+my_print = proc { |out, value| out.puts "Output is: #{value.inspect}" }
+
+# Start a Pry session using the print object defined in my_print
+Pry.start(TOPLEVEL_BINDING, :print => my_print)
View
@@ -0,0 +1,12 @@
+direc = File.dirname(__FILE__)
+
+require 'rubygems'
+require "#{direc}/../lib/pry"
+
+# Remember, first prompt in array is the main prompt, second is the wait
+# prompt (used for multiline input when more input is required)
+my_prompt = [ proc { |obj, *| "inside #{obj}> " },
+ proc { |obj, *| "inside #{obj}* "} ]
+
+# Start a Pry session using the prompt defined in my_prompt
+Pry.start(TOPLEVEL_BINDING, :prompt => my_prompt)
Oops, something went wrong.

0 comments on commit 548b4f8

Please sign in to comment.