anise 0.4.0 → 0.5.0

data/lib/anise.yml

@@ -0,0 +1,41 @@
+--- 
+spec_version: 1.0.0
+replaces: []
+
+loadpath: 
+- lib
+name: anise
+repositories: {}
+
+conflicts: []
+
+engine_check: []
+
+title: Anise
+contact: trans <transfire@gmail.com>
+resources: 
+  code: http://github.com/rubyworks/anise
+  mail: http://groups.google.com/group/rubyworks-mailinglist
+  home: http://rubyworks.github.com/anise
+maintainers: []
+
+requires: 
+- group: 
+  - test
+  name: qed
+  version: 0+
+- group: 
+  - build
+  name: syckle
+  version: 0+
+manifest: MANIFEST
+version: 0.5.0
+licenses: 
+- Apache 2.0
+copyright: Copyright (c) 2008 Thomas Sawyer
+authors: 
+- Thomas Sawyer
+organization: Rubyworks
+description: Anise is an Annotation System for the Ruby programming language. Unlike most other annotations systems it is not a comment-based or macro-based system that sits over-and-above the rest of the code. Rather, Anise is a dynamic annotations system operating at runtime.
+summary: Dynamic Annotation System
+created: "2008-02-21"

data/lib/anise/annotation.rb

@@ -1,14 +1,11 @@
 module Anise
 
-  # = Runtime Annotations
-  #
-  # The Annotation module is the heart of the Anise system.
-  # It provides the framework for annotating class or module related
-  # objects, typically symbols representing methods, with arbitrary
-  # metadata. These annotations do not do anything in themselves.
-  # They are simply data. But you can put them to use. For instance
-  # an attribute validator might check for an annotation called
-  # :valid and test against it.
+  # The Annotate module is the core of the Anise system. It provides the
+  # framework for annotating class or module related objects, typically
+  # symbols representing methods, with arbitrary metadata. These annotations
+  # do not do anything in themselves. They are simply data. But they can be
+  # put to good use. For instance an attribute validator might check for an
+  # annotation called :valid and test against it.
   #
   # == Synopsis
   #
@@ -48,12 +45,12 @@ module Anise
   # Or, we could even annotate the class itself.
   #
   #   class X
-  #     include Anise::Annotation
+  #     include Anise::Annotate
   #
   #     ann self, :valid => lambda{ |x| x.is_a?(Enumerable) }
   #   end
   #
-  # Altough annotations are arbitrary they are tied to the class or
+  # Although annotations are arbitrary they are tied to the class or
   # module they are defined against.
   #
   #--
@@ -66,125 +63,114 @@ module Anise
   #
   # TODO: The ann(x).name notation is kind of nice. Would like to add that
   #       back-in if reasonable. This would require @annotations to be an
-  #       OpenHash or OpenObject rather than just a Hash.
+  #       OpenHash or OpenObject rather than just a Hash though.
   #++
   module Annotation
 
+    #
+
     def self.append_features(base)
-      if base == ::Object
-        append_features(::Module)
-      elsif base == ::Module
-        unless ::Module < Annotation
-          super
-        end
-      else
-        base.extend self
-      end
+      base.extend ClassMethods
+      super(base)
     end
 
-    # Lookup an annotation. Unlike +annotations[ref]+
-    # this provides a complete annotation <i>heritage</i>,
-    # pulling annotations of the same reference name
-    # from ancestor classes and modules.
-    #
-    def annotation(ref=nil)
-      return(@annotations ||= {}) if ref.nil?
-
-      ref = ref.to_sym
-      ann = {}
-      ancestors.reverse_each do |anc|
-        next unless anc.is_a?(Annotation)
-        #anc.annotations[ref] ||= {}
-        if anc.annotations[ref]
-          ann.update(anc.annotations[ref]) #.merge(ann)
+    # Anise::Annotations Domain Language.
+
+    module ClassMethods
+
+      # Lookup an annotation. Unlike +annotations[ref]+
+      # this provides a complete annotation <i>heritage</i>,
+      # pulling annotations of the same reference name
+      # from ancestor classes and modules.
+
+      def annotation(ref=nil)
+        return(@annotations ||= {}) if ref.nil?
+
+        ref = ref.to_sym
+        ann = {}
+        ancestors.reverse_each do |anc|
+          next unless anc < Annotation
+          if h = anc.annotations[ref]
+            ann.merge!(h)
+          end
         end
+        return ann
       end
-      return ann
-      #ancs = ancestors.select{ |a| a.is_a?(Annotations) }
-      #ancs.inject({}) do |memo, ancestor|
-      #  ancestor.annotations[ref] ||= {}
-      #  ancestor.annotations[ref].merge(memo)
-      #end
-    end
 
-    # Plural alias for #annotation.
-    alias_method :annotations, :annotation
+      # Plural alias for #annotation.
 
-    # Stores this class' or module's annotations.
-    #
-    #def annotations
-    #  #$annotations[self]
-    #  @annotations ||= {}
-    #end
+      alias_method :annotations, :annotation
 
-    # Set or read annotations.
-    #
-    def ann(ref, keys_or_class=nil, keys=nil)
-      return annotation(ref) unless keys_or_class or keys
-
-      if Class === keys_or_class
-        keys ||= {}
-        keys[:class] = keys_or_class
-      else
-        keys = keys_or_class
-      end
+      # Set or read annotations.
 
-      if Hash === keys
-        ref  = ref.to_sym
-        keys = keys.inject({}){ |h,(k,v)| h[k.to_sym] = v; h} #rekey
-        annotations[ref] ||= {}
-        annotations[ref].update(keys)
-        # callback
-        annotation_added(ref)
-      else
-        key = keys.to_sym
-        annotation(ref)[key]
-      end
-    end
+      def ann(ref, keys_or_class=nil, keys=nil)
+        return annotation(ref) unless keys_or_class or keys
 
-    # To change an annotation's value in place for a given class or module
-    # it first must be duplicated, otherwise the change may effect annotations
-    # in the class or module's ancestors.
-    #
-    def ann!(ref, keys_or_class=nil, keys=nil)
-      #return annotation(ref) unless keys_or_class or keys
-      unless keys_or_class or keys
-        return annotations[ref] ||= {}
-      end
+        if Class === keys_or_class
+          keys ||= {}
+          keys[:class] = keys_or_class
+        else
+          keys = keys_or_class
+        end
 
-      if Class === keys_or_class
-        keys ||= {}
-        keys[:class] = keys_or_class
-      else
-        keys = keys_or_class
+        if Hash === keys
+          ref  = ref.to_sym
+          keys = keys.inject({}){ |h,(k,v)| h[k.to_sym] = v; h} #rekey
+          annotations[ref] ||= {}
+          annotations[ref].update(keys)
+          # callback
+          annotation_added(ref) #if method_defined?(:annotation_added)
+        else
+          key = keys.to_sym
+          annotation(ref)[key]
+        end
       end
 
-      if Hash === keys
-        ref  = ref.to_sym
-        keys = keys.inject({}){ |h,(k,v)| h[k.to_sym] = v; h} #rekey
-        annotations[ref] ||= {}
-        annotations[ref].update(keys)
-        # callback
-        annotation_added(ref) if method_defined?(:annotation_added)
-      else
-        key = keys.to_sym
-        annotations[ref] ||= {}
-        begin
-          annotations[ref][key] = annotation(ref)[key].dup
-        rescue TypeError
-          annotations[ref][key] = annotation(ref)[key]
+      # To change an annotation's value in place for a given class or module
+      # it first must be duplicated, otherwise the change may effect annotations
+      # in the class or module's ancestors.
+
+      def ann!(ref, keys_or_class=nil, keys=nil)
+        #return annotation(ref) unless keys_or_class or keys
+        unless keys_or_class or keys
+          return annotations[ref] ||= {}
+        end
+
+        if Class === keys_or_class
+          keys ||= {}
+          keys[:class] = keys_or_class
+        else
+          keys = keys_or_class
+        end
+
+        if Hash === keys
+          ref  = ref.to_sym
+          keys = keys.inject({}){ |h,(k,v)| h[k.to_sym] = v; h} #rekey
+          annotations[ref] ||= {}
+          annotations[ref].update(keys)
+          # callback
+          annotation_added(ref) #if method_defined?(:annotation_added)
+        else
+          key = keys.to_sym
+          annotations[ref] ||= {}
+          begin
+            annotations[ref][key] = annotation(ref)[key].dup
+          rescue TypeError
+            annotations[ref][key] = annotation(ref)[key]
+          end
         end
       end
-    end
 
-    # callback method
-    def annotation_added(name)
-      super if defined?(super)
+      # Callback method. This method is called for each new annotation.
+
+      def annotation_added(name)
+        super if defined?(super)
+      end
+
     end
 
   end
 
 end
 
-# 2006-11-07 trans  Created this ultra-concise version of annotations.
-# Copyright (c) 2005, 2008 TigerOps
+# Copyright (c) 2006-11-07 Thomas Sawyer

data/lib/anise/annotator.rb

@@ -1,10 +1,14 @@
 module Anise
-  require 'anise/annotation.rb'
+  require 'anise/annotation'
 
   # = Annotator
   #
-  # Annotator allows for the creation of dynamic <i>method
-  # annotations</i> which attach to the next method defined.
+  # The Annotator module allows for the creation of <i>method annotations</i>
+  # which attach to the next method defined.
+  #
+  # This idiom of annotator-before-definition was popularized by
+  # Rake's desc/task pair. The Annotator module makes it very easy
+  # to add similar capabilites to any program.
   #
   #   require 'anise/annotator'
   #
@@ -22,66 +26,58 @@ module Anise
   #
   #   X.ann(:see, :doc) #=> "See what I mean?"
   #
-  # This idiom of annotator before definition was popularized by
-  # Rake's desc/task pair. Annotator makes it very easy to add
-  # similar capabilites to any program.
-  #
-  # The library uses the #method_added callback, so be sure to
+  # Note that the library uses the #method_added callback, so be sure to
   # respect good practices of calling +super+ if you need to override
   # this method while using Annotator.
   #
-  # TODO: Ensure thread safety of the internal <code>@pending_annotations</code> variable.
+  #--
+  # TODO: Allow annotators to be inherited via module mixins.
   #
+  # TODO: Ensure thread-safety of <code>@_pending_annotations</code> variable.
+  #++
   module Annotator
 
+    #
     def self.append_features(base)
-      if base == Object
-        append_features(::Module)
-      elsif base == ::Module
-        unless Module < Annotator
-          ::Module.module_eval do
-            include Annotation
-          end
-          # can't include b/c it seem Module intercetps the call.
-          ::Module.module_eval do
-            def method_added(sym)
-              @pending_annotations ||= []
-              @pending_annotations.each do |name, args|
-                ann sym, name => args
-              end
-              @pending_annotations = []
-              #super if defined?(super)
-            end
+      Annotation.append_features(base) #unless base.is_a?(Annotation)
+      base.extend ClassMethods
+      super(base)
+    end
+
+    module ClassMethods
+
+      # Define an annotator.
+      def annotator(name, &block)
+        (class << self; self; end).module_eval do
+          define_method(name) do |*args|
+            @_pending_annotations ||= []
+            @_pending_annotations << [name, args, block]
           end
-          super
         end
-      else
-        base.extend Annotation #unless base.is_a?(Annotation)
-        base.extend self
       end
-    end
 
-    def annotator(name)
-      (class << self; self; end).module_eval do
-        define_method(name) do |*args|
-          @pending_annotations ||= []
-          @pending_annotations << [name, args]
+      # When a method is added, run all pending annotations.
+      def method_added(sym)
+        @_pending_annotations ||= []
+        @_pending_annotations.each do |name, args, block|
+          if block
+            block.call(sym, *args)
+          else
+            if args.size == 1
+              ann(sym, name=>args.first)
+            else
+              ann(sym, name=>args)
+            end
+          end
         end
+        @_pending_annotations = []
+        super if defined?(super)
       end
-    end
 
-    def method_added(sym)
-      @pending_annotations ||= []
-      @pending_annotations.each do |name, args|
-        ann sym, name => args
-      end
-      @pending_annotations = []
-      super if defined?(super)
     end
 
   end
 
 end
 
-# Copyright (c) 2005, 2008 TigerOps
-
+# Copyright (c) 2005,2011 Thomas Sawyer

data/lib/anise/attribute.rb

@@ -1,7 +1,7 @@
-#require 'facets/inheritor' # remove dependency
-
 module Anise
+  #require 'facets/inheritor' # removed dependency
   require 'anise/annotation'
+  require 'anise/module'
 
   # = Annotated Attributes
   #
@@ -22,35 +22,20 @@ module Anise
   # See annotation.rb for more information.
   #
   # NOTE: This library was designed to be backward compatible with
-  #       the standard versions of the same methods.
+  # the standard versions of the same methods.
   #
   module Attribute
 
+    #
     def self.append_features(base)
-      if base == ::Object
-        append_features(::Module)
-      elsif base == ::Module
-        unless ::Module <= self
-          ::Module.module_eval do
-            include Annotation
-            super(::Module)
-          end
-          annotatable_attribute_method_for_module(:attr)
-          annotatable_attribute_method_for_module(:attr_reader)
-          annotatable_attribute_method_for_module(:attr_writer)
-          annotatable_attribute_method_for_module(:attr_accessor)
-          annotatable_attribute_method_for_module(:attr_setter) if defined?(attr_setter)
-        end
-      else
-        base.extend Annotation
-        base.extend Attribute
-        base = (class << base; self; end)
-        #inheritor :instance_attributes, [], :|
-        annotatable_attribute_method(base, :attr)
-        annotatable_attribute_method(base, :attr_reader)
-        annotatable_attribute_method(base, :attr_writer)
-        annotatable_attribute_method(base, :attr_accessor)
-        annotatable_attribute_method(base, :attr_setter) if defined?(attr_setter)
+      super(base)
+      Annotation.append_features(base)
+      base.extend ClassMethods #Attribute
+
+      #inheritor :instance_attributes, [], :|
+      base_class = (class << base; self; end)
+      base_class.attribute_methods.each do |attr_method|
+        annotatable_attribute_method(base_class, attr_method)
       end
     end
 
@@ -90,99 +75,65 @@ module Anise
       end
     end
 
-    #
-    def self.annotatable_attribute_method_for_module(attr_method_name)
-      ::Module.module_eval do
-        alias_method "__#{attr_method_name}", attr_method_name
-
-        define_method(attr_method_name) do |*args|
-
-          args.flatten!
-
-          harg={}; while args.last.is_a?(Hash)
-            harg.update(args.pop)
-          end
-
-          raise ArgumentError if args.empty? and harg.empty?
-
-          if args.empty?  # hash mode
-            harg.each { |a,h| __send__(attr_method_name,a,h) }
-          else
-            klass = harg[:class] = args.pop if args.last.is_a?(Class)
-
-            __send__("__#{attr_method_name}", *args)
-
-            args.each{|a| ann(a.to_sym,harg)}
-
-            instance_attributes!.concat(args)  #merge!
-
-            # Use this callback to customize for your needs.
-            if respond_to?(:attr_callback)
-              attr_callback(self, args, harg)
-            end
+    # Anise::Attributes Doman Language.
+    module ClassMethods
 
-            # return the names of the attributes created
-            return args
+      # Instance attributes, including inherited attributes.
+      def instance_attributes
+        a = []
+        ancestors.each do |anc|
+          next unless anc < Attribute
+          if x = anc.instance_attributes!
+            a |= x
           end
         end
+        return a
       end
-    end
 
-    # Instance attributes, including inherited attributes.
-    def instance_attributes
-      a = []
-      ancestors.each do |anc|
-        next unless anc.is_a?(Attribute)
-        if x = anc.instance_attributes!
-          a |= x
-        end
+      # Local instance attributes.
+      def instance_attributes!
+        @instance_attributes ||= []
       end
-      return a
-    end
 
-    # Local instance attributes.
-    def instance_attributes!
-      @instance_attributes ||= []
-    end
-
-    # Return list of attributes that have a :class annotation.
-    #
-    #   class MyClass
-    #     attr_accessor :test
-    #     attr_accessor :name, String, :doc => 'Hello'
-    #     attr_accessor :age, Fixnum
-    #   end
-    #
-    #   MyClass.instance_attributes # => [:test, :name, :age, :body]
-    #   MyClass.classified_attributes # => [:name, :age]
-    #
-    def classified_attributes
-      instance_attributes.find_all do |a|
-        self.ann(a, :class)
+      # Return list of attributes that have a :class annotation.
+      #
+      #   class MyClass
+      #     attr_accessor :test
+      #     attr_accessor :name, String, :doc => 'Hello'
+      #     attr_accessor :age, Fixnum
+      #   end
+      #
+      #   MyClass.instance_attributes # => [:test, :name, :age, :body]
+      #   MyClass.classified_attributes # => [:name, :age]
+      #
+      def classified_attributes
+        instance_attributes.find_all do |a|
+          self.ann(a, :class)
+        end
       end
-    end
 
-    # This define a simple adjustment to #attr to allow it to handle the boolean argument and
-    # to be able to accept attributes. It's backward compatible and is not needed for Ruby 1.9
-    # which gets rid of the secondary argument.
-    #
-    def attr(*args)
-      args.flatten!
-      case args.last
-      when TrueClass
-        args.pop
-        attr_accessor(*args)
-      when FalseClass, NilClass
-        args.pop
-        attr_reader(*args)
-      else
-        attr_reader(*args)
+      # This define a simple adjustment to #attr to allow it to handle the boolean argument and
+      # to be able to accept attributes. It's backward compatible and is not needed for Ruby 1.9
+      # which gets rid of the secondary argument.
+      #
+      def attr(*args)
+        args.flatten!
+        case args.last
+        when TrueClass
+          args.pop
+          attr_accessor(*args)
+        when FalseClass, NilClass
+          args.pop
+          attr_reader(*args)
+        else
+          attr_reader(*args)
+        end
       end
+
     end
 
   end
 
 end
 
-# Copyright (c) 2005, 2008 TigerOps
-
+# Copyright (c) 2005, 2008 Thomas Sawyer