no_backsies 0.1.0

data/README.rdoc

@@ -0,0 +1,56 @@
+= No Backsies
+
+== DESCRIPTION
+
+NoBackies 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.
+
+
+== RESOURCES
+
+* home: http://rubyworks.github.com/nobacksies
+* code: http://github.com/rubyworks/nobacksies
+* mail: http://groups.google.com/group/rubyworks-mailinglist
+
+
+== EXAMPLE
+
+Here is an example take from the Anise[http://rubyworks.github.com/anise]
+project.
+
+  class Y
+    include Anise
+    include NoBacksies
+
+    def self.doc(string)
+      callback :method_added do |method|
+        self.ann(method, :doc=>string)
+      end
+    end
+
+    doc "here"
+
+    def foo; end
+  end
+
+  Y.ann(:foo, :doc) #=> "here"
+
+
+== INSTALLATION
+
+Install the RubyGems package in the usual fahsion.
+
+  $ gem install nobacksies
+
+
+== LEGAL
+
+(Apache 2.0 License)
+
+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.

data/lib/no_backsies.rb

@@ -0,0 +1,289 @@
+# NoBacksies module ecapsulates all supported callback mixins.
+#
+# NoBackseis::Callbacks can be mixed-in and all supported callbacks will
+# be applied to the class or module. 
+# 
+#   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
+#
+#   Y.list.assert #=> [:foo, :bar]
+#
+# Using callbacks can easily lead to infinite loops. NoBacksies makes it
+# easier to control callback expression via 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
+#           send(method) + "!"
+#         end
+#       end
+#     end
+#
+#     def foo; "foo"; end
+#     def bar; "bar"; end
+#   end
+#
+#   y = Y.new
+#   y.foo! #=> "foo!"
+#
+# NOTE: Currently the NoBackies module only supports class level callbacks.
+# We will look into adding instance level callbacks in a future version.
+#
+#--
+# TODO: What about adding `super if defined?(super)` to callback methods?
+# Should this be standard? Should it occur before or after? Or should
+# in be controlled via a special callback, e.g. `callback method_added, :super`?
+#++
+
+module NoBacksies
+
+  #
+
+  module Callbacks
+    # Apply all supported callback modules.
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend MethodAdded
+      base.extend MethodRemoved
+      base.extend MethodUndefined
+      base.extend SingletonMethodAdded
+      base.extend SingletonMethodRemoved
+      base.extend SingletonMethodUndefined
+      base.extend ConstMissing
+      base.extend Included
+      base.extend Extended
+    end
+  end
+
+  # The CallbackMethods module adds the callback methods which are used
+  # define and access callback definitions. Mixing-in this module is
+  # handled automatically, so you do not need to worry with it. In other
+  # words, consider the module *private*.
+
+  module CallbackMethods
+    # Define a callback.
+    def callback(name, express={}, &block)
+      callbacks[name.to_sym] << block
+    end
+
+    #
+    def callbacks
+      @_callbacks ||= (
+        anc = ancestors[1..-1].find do |anc|
+          anc.callbacks rescue nil  # TODO: Need faster way!
+        end
+        anc ? anc.callbacks.dup : Hash.new{|h,k| h[k]=[]}
+      )
+    end
+
+    # Returns Hash of true/false activity state of callbacks.
+    #
+    # TODO: Should expression be inherited?
+    def callback_express(express={}, &block)
+      @_callback_express ||= Hash.new{|h,k| h[k]=true}
+
+      if block
+        tmp = @_callback_express.dup
+        express.each{ |k,v| @_callback_express[k.to_sym] = !!v }
+        block.call
+        @_callback_express = tmp
+      else
+        express.each{ |k,v| @_callback_express[k.to_sym] = !!v }
+      end
+
+      @_callback_express
+    end
+  end
+
+  # Callback system for #method_added.
+  module MethodAdded
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def method_added(method)
+      return unless callback_express[:method_added]
+      callbacks[:method_added].each do |block|
+        block.call(method)
+      end
+    end
+  end
+
+  # Callback system for #method_removed.
+  module MethodRemoved
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def method_removed(method)
+      return unless callback_express[:method_removed]
+      callbacks[:method_removed].each do |block|
+        block.call(method)
+      end
+    end
+  end
+
+  # Callback system for #method_removed.
+  module MethodUndefined
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def method_undefined(method)
+      return unless callback_express[:method_undefined]
+      callbacks[:method_undefined].each do |block|
+        block.call(method)
+      end
+    end
+  end
+
+  # Callback system for #method_added.
+  module SingletonMethodAdded
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def singleton_method_added(method)
+      return unless callback_express[:singleton_method_added]
+      callbacks[:singleton_method_added].each do |block|
+        block.call(method)
+      end
+    end
+  end
+
+  # Callback system for #method_removed.
+  module SingletonMethodRemoved
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def singleton_method_removed(method)
+      return unless callback_express[:singleton_method_removed]
+      callbacks[:singleton_method_removed].each do |block|
+        block.call(method)
+      end
+    end
+  end
+
+  # Callback system for #method_removed.
+  module SingletonMethodUndefined
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def singleton_method_undefined(method)
+      return unless callback_express[:singleton_method_undefined]
+      callbacks[:singleton_method_undefined].each do |block|
+        block.call(method)
+      end
+    end
+  end
+
+  # Callback system for #const_missing.
+  module ConstMissing
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def const_missing(const)
+      return unless callback_express[:cont_missing]
+      callbacks[:const_missing].each do |block|
+        block.call(const)
+      end
+    end
+  end
+
+  # Callback system for #included.
+  module Included
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def included(mod)
+      return unless callback_express[:included]
+      callbacks[:included].each do |block|
+        block.call(mod)
+      end
+    end
+  end
+
+  # Callback system for #extended.
+  module Extended
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def extended(mod)
+      return unless callback_express[:extended]
+      callbacks[:extended].each do |block|
+        block.call(mod)
+      end
+    end
+  end
+
+  # Callback system for #inherited.
+  module Inherited
+    #
+    def self.append_features(base)
+      base.extend CallbackMethods
+      base.extend self
+    end
+
+    #
+    def extended(mod)
+      return unless callback_express[:inherited]
+      callbacks[:inherited].each do |block|
+        block.call(mod)
+      end
+    end
+  end
+
+end
+

data/qed/01_example.rdoc

@@ -0,0 +1,28 @@
+= 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]
+

data/qed/02_express.rdoc

@@ -0,0 +1,38 @@
+= 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
+
+    def self.list
+      @list ||= []
+    end
+
+    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!"
+

data/qed/applique/no_backsies.rb

@@ -0,0 +1,2 @@
+require 'no_backsies'
+

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: no_backsies
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Thomas Sawyer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-29 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: syckle
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: qed
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: |-
+  NoBackies 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.
+email: transfire@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/no_backsies.rb
+- qed/01_example.rdoc
+- qed/02_express.rdoc
+- qed/applique/no_backsies.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://rubyworks.github.com/nobacksies
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- NoBacksies API
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  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: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: no_backsies
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Better handling of Ruby callbacks
+test_files: []
+