no_backsies 0.3.0 → 0.3.1

data/HISTORY.rdoc

@@ -2,7 +2,13 @@
 
 == 0.3.0 | 2011-07-06
 
-Switch to BSD 2-Clause license.
+This release is made primarily because the program is now
+distributed under the BSD 2-Clause license.
+
+Changes:
+
+* Changed licenses to BSD 2-Clause.
+* Cleaned up project files.
 
 
 == 0.2.0 | 2011-04-29 (Later on Wedding Day)

data/QED.rdoc

@@ -0,0 +1,383 @@
+= Basic Example
+
+First require the NoBacksies library.
+
+  require 'no_backsies'
+
+Include the Callbacks module in a class and define
+a callback procedure.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_added do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+  end
+
+We can see that +list+ holds the methods added.
+
+  Y.list.assert == [:foo, :bar]
+
+
+= Callback Expression
+
+NoBacksies makes it easier to control callback expression. This
+is useful in the prevention of infinite recursion. For instance,
+infinite recursion is a common problem when a +method_added+ callback
+defines a new method.
+
+Here is an example that demonstrates how to work around this problem
+using the +callback_express+ method.
+
+  class Z
+    include NoBacksies::Callbacks
+
+    callback :method_added do |method|
+      callback_express :method_added=>false do
+        define_method("#{method}!") do
+          send(method) + "!"
+        end
+      end
+    end
+
+    def foo; "foo"; end
+    def bar; "bar"; end
+  end
+
+In this example, a new `Z` object will get an automatically defined bang method
+for every explicitly defined method.
+
+  z = Z.new
+  z.foo  #=> "foo"
+  z.foo! #=> "foo!"
+  z.bar  #=> "bar"
+  z.bar! #=> "bar!"
+
+
+= Callback Options
+
+== Once Callback Option
+
+NoBacksies supports special callback options. The first is +:once+.
+By setting +:once+ to +true+, the callback will be used one time and
+then removed.
+
+  class Q
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_added, :once=>true do |method|
+      list << method
+    end
+
+    def foo; "foo"; end
+    def bar; "bar"; end
+  end
+
+Here we see that only :foo has been added to the list.
+
+  Q.list #=> [:foo]
+
+== Safe Callback Option
+
+The other option supported is +:safe+. When +:safe+ is set to true
+the callback is automatically wrapped in an #callback_express block
+that sets the expression of the callback to false while it is being
+processed. This means we can rewrite our first example more succinctly.
+
+  class Z2
+    include NoBacksies::Callbacks
+
+    callback :method_added, :safe=>true do |method|
+      define_method("#{method}!") do
+        send(method) + "!"
+      end
+    end
+
+    def foo; "foo"; end
+    def bar; "bar"; end
+  end
+
+In this example, a new `Z` object will get an automatically defined bang method
+for every explicitly defined method.
+
+  z = Z2.new
+  z.foo  #=> "foo"
+  z.foo! #=> "foo!"
+  z.bar  #=> "bar"
+  z.bar! #=> "bar!"
+
+
+== Method Added
+
+Given a class that defines a no-backsies +method_added+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_added do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+
+
+== Method Removed
+
+Given a class that defines a no-backsies +method_removed+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_removed do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+
+    remove_method(:foo)
+    remove_method(:bar)
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+
+
+== Method Undefined
+
+Given a class that defines a no-backsies +method_undefined+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_undefined do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+
+    undef_method(:foo)
+    undef_method(:bar)
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+
+
+== Singleton Method Added
+
+Given a class that defines a no-backsies +singleton_method_added+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :singleton_method_added do |method|
+      list << method
+    end
+
+    def self.foo; end
+    def self.bar; end
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+
+
+== Singleton Method Removed
+
+Given a class that defines a no-backsies +singleton_method_removed+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :singleton_method_removed do |method|
+      list << method
+    end
+
+    def self.foo; end
+    def self.bar; end
+
+    class << self
+      remove_method(:foo)
+      remove_method(:bar)
+    end
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+
+
+== Singleton Method Undefined
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :singleton_method_undefined do |method|
+      list << method
+    end
+
+    def self.foo; end
+    def self.bar; end
+
+    class << self
+      undef_method(:foo)
+      undef_method(:bar)
+    end
+  end
+
+  Y.list #=> [:foo, :bar]
+
+
+= Constant Missing
+
+Given a class that defines a no-backsies +const_missing+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :const_missing do |const|
+      list << const
+    end
+
+    FOO
+    BAR
+
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:FOO, :BAR]
+
+
+= Included
+
+Given a class that defines a no-backsies +included+ callback.
+
+  module U
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :included do |mod|
+      list << mod
+    end
+  end
+
+  class X
+    include U
+  end
+
+  class Y
+    include U
+  end
+
+Then the results are as follows.
+
+  U.list #=> [X, Y]
+
+
+= Extended
+
+Given a class that defines a no-backsies +extended+ callback.
+
+  module U
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :extended do |mod|
+      list << mod
+    end
+  end
+
+  class X
+    extend U
+  end
+
+  class Y
+    extend U
+  end
+
+Then the results are as follows.
+
+  U.list #=> [X, Y]
+
+
+= Inherited
+
+Given a class that defines a no-backsies +inherited+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :inherited do |base|
+      list << base
+    end
+  end
+
+  z = Class.new(Y)
+
+Then the results are as follows.
+
+  Y.list #=> [z]
+
+

data/README.rdoc

@@ -2,7 +2,7 @@
 
 == DESCRIPTION
 
-NoBackies is a callback layer built on top of Ruby's built-in callback
+NoBacksies is a callback layer built on top of Ruby's built-in callback
 methods. It makes it possible to add new callbacks very easily, without
 having to fuss with more nuanced issues of defining and redefining callback
 methods.

data/lib/no_backsies.rb

@@ -58,7 +58,6 @@
 module NoBacksies
 
   #
-
   module Callbacks
     # Apply all supported callback modules.
     def self.append_features(base)
@@ -72,6 +71,7 @@ module NoBacksies
       base.extend ConstMissing
       base.extend Included
       base.extend Extended
+      base.extend Inherited
     end
   end
 
@@ -227,7 +227,7 @@ module NoBacksies
 
     #
     def const_missing(const)
-      callback_invoke(:const_missing, method)
+      callback_invoke(:const_missing, const)
     end
   end
 
@@ -241,7 +241,7 @@ module NoBacksies
 
     #
     def included(mod)
-      callback_invoke(:included, method)
+      callback_invoke(:included, mod)
     end
   end
 
@@ -255,7 +255,7 @@ module NoBacksies
 
     #
     def extended(mod)
-      callback_invoke(:extended, method)
+      callback_invoke(:extended, mod)
     end
   end
 
@@ -268,8 +268,8 @@ module NoBacksies
     end
 
     #
-    def extended(mod)
-      callback_invoke(:inherited, method)
+    def inherited(base)
+      callback_invoke(:inherited, base)
     end
   end
 

data/qed/callbacks/01_method_added.rdoc

@@ -0,0 +1,23 @@
+== Method Added
+
+Given a class that defines a no-backsies +method_added+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_added do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+

data/qed/callbacks/02_method_removed.rdoc

@@ -0,0 +1,26 @@
+== Method Removed
+
+Given a class that defines a no-backsies +method_removed+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_removed do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+
+    remove_method(:foo)
+    remove_method(:bar)
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+

data/qed/callbacks/03_method_undefined.rdoc

@@ -0,0 +1,26 @@
+== Method Undefined
+
+Given a class that defines a no-backsies +method_undefined+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :method_undefined do |method|
+      list << method
+    end
+
+    def foo; end
+    def bar; end
+
+    undef_method(:foo)
+    undef_method(:bar)
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+

data/qed/callbacks/04_singleton_method_added.rdoc

@@ -0,0 +1,23 @@
+== Singleton Method Added
+
+Given a class that defines a no-backsies +singleton_method_added+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :singleton_method_added do |method|
+      list << method
+    end
+
+    def self.foo; end
+    def self.bar; end
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+

data/qed/callbacks/05_singleton_method_removed.rdoc

@@ -0,0 +1,28 @@
+== Singleton Method Removed
+
+Given a class that defines a no-backsies +singleton_method_removed+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :singleton_method_removed do |method|
+      list << method
+    end
+
+    def self.foo; end
+    def self.bar; end
+
+    class << self
+      remove_method(:foo)
+      remove_method(:bar)
+    end
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:foo, :bar]
+

data/qed/callbacks/06_singleton_method_undefined.rdoc

@@ -0,0 +1,24 @@
+== Singleton Method Undefined
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :singleton_method_undefined do |method|
+      list << method
+    end
+
+    def self.foo; end
+    def self.bar; end
+
+    class << self
+      undef_method(:foo)
+      undef_method(:bar)
+    end
+  end
+
+  Y.list #=> [:foo, :bar]
+

data/qed/callbacks/07_const_missing.rdoc

@@ -0,0 +1,24 @@
+= Constant Missing
+
+Given a class that defines a no-backsies +const_missing+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :const_missing do |const|
+      list << const
+    end
+
+    FOO
+    BAR
+
+  end
+
+Then the results are as follows.
+
+  Y.list #=> [:FOO, :BAR]
+

data/qed/callbacks/08_included.rdoc

@@ -0,0 +1,28 @@
+= Included
+
+Given a class that defines a no-backsies +included+ callback.
+
+  module U
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :included do |mod|
+      list << mod
+    end
+  end
+
+  class X
+    include U
+  end
+
+  class Y
+    include U
+  end
+
+Then the results are as follows.
+
+  U.list #=> [X, Y]
+

data/qed/callbacks/09_extended.rdoc

@@ -0,0 +1,28 @@
+= Extended
+
+Given a class that defines a no-backsies +extended+ callback.
+
+  module U
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :extended do |mod|
+      list << mod
+    end
+  end
+
+  class X
+    extend U
+  end
+
+  class Y
+    extend U
+  end
+
+Then the results are as follows.
+
+  U.list #=> [X, Y]
+

data/qed/callbacks/10_inherited.rdoc

@@ -0,0 +1,22 @@
+= Inherited
+
+Given a class that defines a no-backsies +inherited+ callback.
+
+  class Y
+    include NoBacksies::Callbacks
+
+    def self.list
+      @list ||= []
+    end
+
+    callback :inherited do |base|
+      list << base
+    end
+  end
+
+  z = Class.new(Y)
+
+Then the results are as follows.
+
+  Y.list #=> [z]
+

metadata

@@ -2,7 +2,7 @@
 name: no_backsies
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Thomas Sawyer
@@ -35,7 +35,7 @@ dependencies:
   type: :development
   version_requirements: *id002
 description: |-
-  NoBackies is a callback layer built on top of Ruby's built-in callback
+  NoBacksies is a callback layer built on top of Ruby's built-in callback
   methods. It makes it possible to add new callbacks very easily, without
   having to fuss with more nuanced issues of defining and redefining callback
   methods.
@@ -52,11 +52,22 @@ files:
 - qed/02_express.rdoc
 - qed/03_options.rdoc
 - qed/applique/no_backsies.rb
+- qed/callbacks/01_method_added.rdoc
+- qed/callbacks/02_method_removed.rdoc
+- qed/callbacks/03_method_undefined.rdoc
+- qed/callbacks/04_singleton_method_added.rdoc
+- qed/callbacks/05_singleton_method_removed.rdoc
+- qed/callbacks/06_singleton_method_undefined.rdoc
+- qed/callbacks/07_const_missing.rdoc
+- qed/callbacks/08_included.rdoc
+- qed/callbacks/09_extended.rdoc
+- qed/callbacks/10_inherited.rdoc
 - HISTORY.rdoc
 - README.rdoc
+- QED.rdoc
 - COPYING.rdoc
 - NOTICE.rdoc
-homepage: http://rubyworks.github.com/anise]
+homepage: http://rubyworks.github.com/no_backsies
 licenses: []
 
 post_install_message: