no_backsies 0.1.0 → 0.2.0

data/README.rdoc

@@ -25,24 +25,27 @@ project.
     include NoBacksies
 
     def self.doc(string)
-      callback :method_added do |method|
+      callback :method_added, :once=>true do |method|
         self.ann(method, :doc=>string)
       end
     end
 
-    doc "here"
-
-    def foo; end
+    doc "foo is cool"
+    def foo
+      # ...
+    end
   end
 
-  Y.ann(:foo, :doc) #=> "here"
+  Y.ann(:foo, :doc) #=> "foo is cool"
+
+See the QED documentation for more examples.
 
 
 == INSTALLATION
 
-Install the RubyGems package in the usual fahsion.
+Install the RubyGems package in the usual fashion.
 
-  $ gem install nobacksies
+  $ gem install no_backsies
 
 
 == LEGAL
@@ -53,4 +56,4 @@ Copyright (c) 2011 Thomas Sawyer
 
 Unless otherwise negotiated with the original author, NoBacksies is
 distributable under the terms of the Apache 2.0 license. See the
-Apache2.txt file for details.
+APACHE2.txt file for details.

data/lib/no_backsies.rb

@@ -82,8 +82,8 @@ module NoBacksies
 
   module CallbackMethods
     # Define a callback.
-    def callback(name, express={}, &block)
-      callbacks[name.to_sym] << block
+    def callback(name, options={}, &block)
+      callbacks[name.to_sym] << [block, options]
     end
 
     #
@@ -113,6 +113,24 @@ module NoBacksies
 
       @_callback_express
     end
+
+    # Invoke a callback.
+    def callback_invoke(name, *args)
+      name = name.to_sym
+      return unless callback_express[name]
+      callbacks[name].each do |block, options|
+        if options[:safe]
+          callback_express(name=>false) do
+            block.call(*args)            
+          end
+        else
+          block.call(*args)
+        end
+        if options[:once]
+          callbacks[name].delete([block, options])
+        end
+      end
+    end
   end
 
   # Callback system for #method_added.
@@ -125,10 +143,7 @@ module NoBacksies
 
     #
     def method_added(method)
-      return unless callback_express[:method_added]
-      callbacks[:method_added].each do |block|
-        block.call(method)
-      end
+      callback_invoke(:method_added, method)
     end
   end
 
@@ -142,10 +157,7 @@ module NoBacksies
 
     #
     def method_removed(method)
-      return unless callback_express[:method_removed]
-      callbacks[:method_removed].each do |block|
-        block.call(method)
-      end
+      callback_invoke(:method_removed, method)
     end
   end
 
@@ -159,10 +171,7 @@ module NoBacksies
 
     #
     def method_undefined(method)
-      return unless callback_express[:method_undefined]
-      callbacks[:method_undefined].each do |block|
-        block.call(method)
-      end
+      callback_invoke(:method_undefined, method)
     end
   end
 
@@ -176,10 +185,7 @@ module NoBacksies
 
     #
     def singleton_method_added(method)
-      return unless callback_express[:singleton_method_added]
-      callbacks[:singleton_method_added].each do |block|
-        block.call(method)
-      end
+      callback_invoke(:singleton_method_added, method)
     end
   end
 
@@ -193,10 +199,7 @@ module NoBacksies
 
     #
     def singleton_method_removed(method)
-      return unless callback_express[:singleton_method_removed]
-      callbacks[:singleton_method_removed].each do |block|
-        block.call(method)
-      end
+      callback_invoke(:singleton_method_removed, method)
     end
   end
 
@@ -210,10 +213,7 @@ module NoBacksies
 
     #
     def singleton_method_undefined(method)
-      return unless callback_express[:singleton_method_undefined]
-      callbacks[:singleton_method_undefined].each do |block|
-        block.call(method)
-      end
+      callback_invoke(:singleton_method_undefined, method)
     end
   end
 
@@ -227,10 +227,7 @@ module NoBacksies
 
     #
     def const_missing(const)
-      return unless callback_express[:cont_missing]
-      callbacks[:const_missing].each do |block|
-        block.call(const)
-      end
+      callback_invoke(:const_missing, method)
     end
   end
 
@@ -244,10 +241,7 @@ module NoBacksies
 
     #
     def included(mod)
-      return unless callback_express[:included]
-      callbacks[:included].each do |block|
-        block.call(mod)
-      end
+      callback_invoke(:included, method)
     end
   end
 
@@ -261,10 +255,7 @@ module NoBacksies
 
     #
     def extended(mod)
-      return unless callback_express[:extended]
-      callbacks[:extended].each do |block|
-        block.call(mod)
-      end
+      callback_invoke(:extended, method)
     end
   end
 
@@ -278,10 +269,7 @@ module NoBacksies
 
     #
     def extended(mod)
-      return unless callback_express[:inherited]
-      callbacks[:inherited].each do |block|
-        block.call(mod)
-      end
+      callback_invoke(:inherited, method)
     end
   end
 

data/qed/01_example.rdoc

@@ -1,6 +1,6 @@
 = Basic Example
 
-First require the 'nobacksies' library.
+First require the NoBacksies library.
 
   require 'no_backsies'
 

data/qed/02_express.rdoc

@@ -11,10 +11,6 @@ using the +callback_express+ method.
   class Z
     include NoBacksies::Callbacks
 
-    def self.list
-      @list ||= []
-    end
-
     callback :method_added do |method|
       callback_express :method_added=>false do
         define_method("#{method}!") do

data/qed/03_options.rdoc

@@ -0,0 +1,56 @@
+= 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!"
+

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: no_backsies
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Thomas Sawyer
@@ -62,6 +62,7 @@ files:
 - lib/no_backsies.rb
 - qed/01_example.rdoc
 - qed/02_express.rdoc
+- qed/03_options.rdoc
 - qed/applique/no_backsies.rb
 - README.rdoc
 has_rdoc: true