anise 0.6.0 → 0.7.0

data/lib/anise/annotation.rb

@@ -1,175 +0,0 @@
-module Anise
-
-  # 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
-  #
-  #   require 'anise/annotation'
-  #
-  #   class X
-  #     include Anise::Annotation
-  #
-  #     attr :a
-  #
-  #     ann :a, :desc => "A Number"
-  #   end
-  #
-  #   X.ann(:a, :desc)  #=> "A Number"
-  #
-  # As stated, annotations need not only annotate methods, they are
-  # arbitrary, so they can be used for any purpose. For example, we
-  # may want to annotate instance variables.
-  #
-  #   class X
-  #     include Anise::Annotation
-  #
-  #     ann :@a, :valid => lambda{ |x| x.is_a?(Integer) }
-  #
-  #     def validate
-  #       instance_variables.each do |iv|
-  #         if validator = self.class.ann(iv)[:valid]
-  #           value = instance_variable_get(iv)
-  #           unless validator.call(value)
-  #             raise "Invalid value #{value} for #{iv}"
-  #           end
-  #         end
-  #       end
-  #     end
-  #   end
-  #
-  # Or, we could even annotate the class itself.
-  #
-  #   class X
-  #     include Anise::Annotate
-  #
-  #     ann self, :valid => lambda{ |x| x.is_a?(Enumerable) }
-  #   end
-  #
-  # Although annotations are arbitrary they are tied to the class or
-  # module they are defined against.
-  #
-  #--
-  # TODO: By using a global variable rather the definining a class
-  #       instance variable for each class/module, it is possible to
-  #       quicky scan all annotations for the entire system. To do
-  #       the same without this would require scanning through
-  #       the ObjectSpace. Should we do this?
-  #         $annotations = Hash.new { |h,k| h[k] = {} }
-  #
-  # 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 though.
-  #++
-  module Annotation
-
-    #
-
-    def self.included(base)
-      base.extend Aid
-    end
-
-    # Anise::Annotations Domain Language.
-
-    module Aid
-
-      # 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
-
-      # Plural alias for #annotation.
-
-      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
-
-        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
-
-      # 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
-
-      # Callback method. This method is called for each new annotation.
-
-      def annotation_added(name)
-        super if defined?(super)
-      end
-
-    end
-
-  end
-
-end
-
-# Copyright (c) 2006-11-07 Thomas Sawyer

data/lib/anise/annotator.rb

@@ -1,82 +0,0 @@
-module Anise
-  require 'anise/annotation'
-
-  # = Annotator
-  #
-  # 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'
-  #
-  #   class X
-  #     include Anise::Annotator
-  #
-  #     annotator :doc
-  #
-  #     doc "See what I mean?"
-  #
-  #     def see
-  #       puts "Yes, I see!"
-  #     end
-  #   end
-  #
-  #   X.ann(:see, :doc) #=> "See what I mean?"
-  #
-  # 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: Allow annotators to be inherited via module mixins.
-  #
-  # TODO: Ensure thread-safety of <code>@_pending_annotations</code> variable.
-  #++
-  module Annotator
-
-    #
-    def self.included(base)
-      base.send(:include, Annotation) #unless base.is_a?(Annotation)
-      base.extend Aid
-    end
-
-    module Aid
-
-      # 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
-        end
-      end
-
-      # 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
-
-  end
-
-end
-
-# Copyright (c) 2005,2011 Thomas Sawyer

data/lib/anise/attribute.rb

@@ -1,138 +0,0 @@
-module Anise
-  #require 'facets/inheritor' # removed dependency
-  require 'anise/annotation'
-  require 'anise/module'
-
-  # = Annotated Attributes
-  #
-  # This framework modifies the major attr_* methods to allow easy
-  # addition of annotations. It modifies the built in attribute methods
-  # (attr, attr_reader, attr_writer and attr_accessor), to allow
-  # annotations to be added to them directly rather than requiring
-  # a separate #ann statement.
-  #
-  #   require 'anise/attribute'
-  #
-  #   class X
-  #     include Anise::Attribute
-  #
-  #     attr :a, :valid => lambda{ |x| x.is_a?(Integer) }
-  #   end
-  #
-  # See annotation.rb for more information.
-  #
-  # NOTE: This library was designed to be backward compatible with
-  # the standard versions of the same methods.
-  #
-  module Attribute
-
-    #
-    def self.included(base)
-      base.send(:include, Annotation) #.append_features(base)
-      base.extend Aid
-
-      #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
-
-    #
-    def self.annotatable_attribute_method(base, attr_method_name)
-      base.module_eval do
-        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)
-
-            #attr_method.call(*args)
-            super(*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
-
-            # return the names of the attributes created
-            return args
-          end
-        end
-      end
-    end
-
-    # Anise::Attributes Doman Language.
-    module Aid
-
-      # 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
-
-      # 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)
-        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)
-        end
-      end
-
-    end
-
-  end
-
-end
-
-# Copyright (c) 2005, 2008 Thomas Sawyer

data/qed/01_annotations.qed

@@ -1,26 +0,0 @@
-= Creating and Reading Annotations
-
-Load the primary annotations library.
-
-  require 'anise/annotation'
-
-Given a example class X we can apply annotations to it using the #ann method. 
-
-  class X
-    include Anise::Annotation
-
-    ann :x1, :a=>1
-    ann :x1, :b=>2
-  end
-
-We can then use #ann to lookup the set annotations.
-
-  X.ann(:x1,:a).should == 1
-
-The #ann method is a public interface, so we can define annotation externally as well.
-
-   X.ann :x1, :a => 2
-   X.ann(:x1, :a).should == 2
-
-QED.
-

data/qed/02_annotation_added.rdoc

@@ -1,60 +0,0 @@
-= Annotation Added Callback
-
-Load the annotations, which supports callbacks out of the box.
-
-  require 'anise/annotation'
-
-Given a sample class X, we can use a standard callback method #annotation_added().
-
-  class X
-    include Anise::Annotation
-
-    class << self
-      attr :last_callback
-
-      def annotation_added(name)
-        @last_callback = [name, ann(name)]
-      end
-    end
-  end
-
-Now if we add an annotation, we will see the callback catches it.
-
-  X.ann :x1, :a=>1
-  X.last_callback.should == [:x1, {:a => 1}]
-
-We'll do it again to be sure.
-
-  X.ann :x1, :b=>2
-  X.last_callback.should == [:x1, {:a => 1, :b => 2}]
-
-== Using Callbacks for Attribute Defaults
-
-  class ::Module
-    def annotation_added(key)
-      base = self
-      if value = ann(key, :default)
-        define_method(key) do
-          instance_variable_set("@#{key}", value) unless instance_variable_defined?("@#{key}")
-          base.module_eval{ attr key }
-          instance_variable_get("@#{key}")
-        end 
-      end
-    end
-  end
-
-Try it out.
-
-  class Y
-    include Anise::Annotation
-
-    attr :a
-    ann :a, :default => 10
-  end
-
-  x = Y.new
-  x.a.should == 10
-  x.a.should == 10
-
-QED.
-