README.md in putter-0.3.0 vs README.md in putter-0.4.0
- old
+ new
@@ -1,13 +1,11 @@
# Putter
It rhymes with gooder, not gutter.
-Putter is a tool for more easily implementing puts debugging. Instead of littering files with various puts statements, you can wrap an object with a follower and print out anytime a method is called on that object. This will follow the object throughout its path in the stack.
+Putter is a tool for more easily implementing puts debugging. Instead of littering files with various puts statements, you can wrap an object with a follower or watcher and print out anytime a method is called on that object. This will follow the object throughout its path in the stack.
-For now Putter can only follow a specific the speficic object that it wraps. It currently does not watch a class to see what objects were passed to it unless that specific instance of the class is passed through the stack.
-
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -24,15 +22,15 @@
## Usage
There are two ways to use putter. `Putter.follow` and `Putter.watch`.
-### Putter.follow
+### `Putter.follow`
-`Putter.follow` will allow you to create a wrapper around an object and then you can pass that wrapped object around. The advantage to using follow is that if a method is called that doesn't exist, or a method is created at runtime, the wrapped object will intercept those calls. This works on both instances and classes. However, following a class will not result in created instances of that class being followed.
+`Putter.follow` will allow you to create a wrapper around an object and then you can pass that wrapped object around. The advantage to using `follow` is that if a method is called that doesn't exist, or a method is created at runtime, the wrapped object will intercept those calls. This works on both instances and classes.
-Additionally, following an object will not allow you to intercept calls to a class that occurred outside the wrapped object. For that functionality, use `Putter.watch`
+However, following a class will not result in created instances of that class being followed. Additionally, following an object will not allow you to intercept calls to a class that occurred outside the wrapped object. For that functionality, use `Putter.watch`.
`Putter.follow` usage:
```ruby
class MyObject
@@ -60,20 +58,20 @@
#### `Putter.follow` Options
```ruby
Putter.follow(
object_to_follow,
- label: "My object", # Label to use after "Putter Debugging: My object". Will be "ClassName" for classes or "ClassName instance" for instances
- methods: ["value"], # If the value is nil, then all methods will be watched. Otherwise, this is an array of methods to print debugging input for
+ label: "My object", # Optional - Label to use after "Putter Debugging: My object". Will be "ClassName" for classes or "ClassName instance" for instances
+ methods: ["my_method"], # Optional - If array is empty, then all methods will be watched. Otherwise, this is an array of methods to print debugging input for
)
```
-### Putter.watch
+### `Putter.watch`
-`Putter.watch` can be used on classes to follow created instances of the class or to intercept method calls that occur throughout your application.
+`Putter.watch` can be used on classes to follow created instances of the class or to intercept class method calls that occur throughout your application.
-`Putter.follow` usage:
+`Putter.watch` usage:
```ruby
class MyObject
def self.hello_class(arg, punc)
"The class says hello #{arg.to_s}#{punc}"
@@ -91,45 +89,47 @@
```
Will output:
```bash
-Putter Debugging: Object ./putter/README.md:96 -- Method: :hello_class, Args: [:world, "!"], Result: "The class says hello world!"
-Putter Debugging: Object instance 1 ./putter/README.md:97 -- Method: :hello_instance, Args: [:world, "!"], Result: "The instance says hello world!"
+Putter Debugging: MyObject ./putter/README.md:96 -- Method: :hello_class, Args: ["world", "!"], Result: The class says hello world!
+Putter Debugging: MyObject ./putter/README.md:96 -- Method: :new, Args: [], Result: #<MyObject:0x0000000000>
+Putter Debugging: MyObject instance 1 ./putter/README.md:97 -- Method: :hello_instance, Args: ["world", "!"], Result: The instance says hello world!
```
-#### `Putter.follow` Options
+#### `Putter.watch` Options
```ruby
Putter.watch(
- ClassToFollow,
- label: "My object", # Label to use after "Putter Debugging: My object". Will be "ClassName" for classes or "ClassName instance #" for instances
+ ClassToWatch,
+ label: "My class", # Optional - Label to use after "Putter Debugging: My class". Will be "ClassName" for classes or "ClassName instance #" for instances
+ methods: ["my_method"], # Optional - If array is empty, then all methods will be watched. Otherwise, this is an array of methods to print debugging input for
)
```
## Configuration
Putter currently has 3 configuration options:
```ruby
Putter.configure do |config|
- # 'print_strategy' takes a block that receives five arguments with the label, line,
- # method, args array, and result respectively. This block will be used after each method
+ # 'print_strategy' takes a block that receives a data object with the label, line,
+ # method, args string, and result respectively. This block will be used after each method
# is called, it must contain puts or logger calls, to print or any other method callbacks
# that are helpful.
# Defaults to Putter::PrintStrategy::Default
- config.print_strategy = Proc.new do |label, line, method, args, result|
- puts "#{line} - Label: #{label}, Method: #{method}, Args: #{args}, Result: #{result}"
+ config.print_strategy = Proc.new do |data|
+ puts "#{data.line} - Label: #{data.label}, Method: #{data.method}, Args: #{data.args}, Result: #{data.result}"
end
# 'ignore_methods_from' takes an array of class names and will ignore both class and instance methods
# from those classes when adding methods to the proxy and adding debug output
# Defaults to [Object]
config.ignore_methods_from = [Object, ActiveRecord::Base]
# 'methods_whitelist' takes an array of methods and will always proxy and debug those methods
# regardless of whether or not the class is ignored and regardless of what methods are passed
- # in when running 'Putter.follow'
+ # in when running 'Putter.follow' or 'Putter.watch'
config.methods_whitelist = [:to_s]
end
```
## Planned Features