anise 0.6.0 → 0.7.0

data/lib/anise.yml

@@ -1,41 +1,62 @@
---- 
-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: 
+---
+source:
+- meta
+authors:
+- name: trans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2008'
+  license: BSD-2-Clause
+requirements:
+- name: qed
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+- name: citron
+  groups:
   - test
-  name: qed
-  version: 0+
-- group: 
+  development: true
+- name: detroit
+  groups:
   - build
-  name: redline
-  version: 0+
-manifest: MANIFEST
-version: 0.6.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.
+  development: true
+dependencies: []
+alternatives: []
+conflicts: []
+repositories:
+- uri: http://github.com/rubyworks/anise.git
+  scm: git
+  name: public
+resources:
+- uri: http://rubyworks.githuib.com/anise
+  name: home
+  type: home
+- uri: http://github.com/rubyworks/anise
+  name: code
+  type: code
+- uri: http://github.com/rubyworks/anise/issues
+  name: bugs
+  type: bugs
+- uri: http://chat.us.freenode.net/rubyworks
+  name: chat
+  type: chat
+- uri: http://groups.google.com/groups/rubyworks-mailinglist
+  name: mail
+  type: mail
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2008-02-21'
 summary: Dynamic Annotation System
-created: "2008-02-21"
+title: Anise
+version: 0.7.0
+name: anise
+description: Anise is an annotations systems for the Ruby programming lanaguage.
+organization: Rubyworks
+date: '2012-04-20'

data/lib/anise/annotations.rb

@@ -0,0 +1,132 @@
+module Anise
+
+  # TODO: The ann(x).name notation is kind of nice. Would like to add that
+  #       back-in if reasonable.
+
+  # The Annotation provides a framework for annotating class and 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.
+  #
+  # The standard annotator is `:ann` and is the defualt value of  annotating
+  # methods.
+  #
+  #   class X
+  #     extend Anise::Annotations
+  #
+  #     ann :a, :desc => "A Number"
+  #
+  #     attr :a
+  #   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
+  #     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
+  #     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.
+  #
+  # Creating custom annotators used to entail using a special `#annotator` method,
+  # but this limited the way custom annotators could operate. The new way
+  # is to define a custom class method that calls the usual `#ann` method,
+  # but add in a namespace.
+  #
+  #   class X
+  #     def self.cool(ref, *keys)
+  #       ann "#{ref}/cool", *keys
+  #     end
+  #   end
+  #
+  #   X.cool(:a, :desc) #=> "Awesome!"
+  #
+  # The result is exactly the same as before, but now the custom annotator
+  # has complete control over the process.
+  #
+  module Annotations
+
+    #
+    # Access to a class or module's annotations.
+    #
+    def annotations
+      @annotations ||= Store.new(self)
+    end
+
+    #
+    # Callback method. This method is called for each new annotation.
+    #
+    def annotation_added(ref, ns=:ann)
+      super(ref, ns) if defined?(super)
+    end
+
+    # Get/set annotations.
+    #
+    # @examples
+    #   ann :ref, :key=>value
+    #   ann :ref/:ns, :key=>value
+    #
+    #   ann :ref, :key
+    #   ann :ref/:ns, :key
+    #
+    def ann(ref, *keys)
+      if ref.to_s.index('/')
+        ref, ns = ref.to_s.split('/')
+      else
+        ns = :ann
+      end
+      ref, ns = ref.to_sym, ns.to_sym
+
+      if keys.empty?
+        annotations.lookup(ref, ns)
+      else
+        annotations.annotate(ns, ref, *keys)
+      end
+    end
+
+    #
+    # Get/set annotations in-place. Use this method instead of `#ann`
+    # when performing mass updates.
+    #
+    def ann!(ref, *keys)
+      if ref.to_s.index('/')
+        ref, ns = ref.to_s.split('/')
+      else
+        ns = :ann
+      end
+      ref, ns = ref.to_sym, ns.to_sym
+
+      if keys.empty?
+        annotations[ref, ns]
+      else
+        annotations.annotate!(ns, ref, *keys)
+      end
+    end
+
+  end
+
+end
+
+# Copyright (c) 2006 Rubyworks. All rights reserved. (BSD-2-Clause License)

data/lib/anise/annotations/store.rb

@@ -0,0 +1,136 @@
+module Anise
+
+  module Annotations
+
+    # The {Annotations::Store} class tracks annotations on a per-class bases.
+    #
+    class Store
+
+      # Setup new Annotations instance.
+      #
+      # @param space [Class,Module]
+      #   Class or Module to have annotations.
+      #
+      def initialize(space)
+        @space = space
+        @table = Hash.new { |h,k| h[k]={} }
+      end
+
+      # Ancestors of spaceal class/module.
+      def ancestors
+        @space.ancestors
+      end
+
+      # Annotations local to spaceal class/module.
+      def local
+        @table
+      end
+
+      # Access to local table.
+      def [](ref, ns=:ann)
+        @table[ns][ref]
+      end
+
+      # Lookup an annotation. Unlike `self[ref]`
+      # this provides a complete annotation _heritage_,
+      # pulling annotations of the same reference name
+      # from ancestor classes and modules.
+      #
+      # Unlike the other annotation methods, this method takes
+      # the `ref` argument before the `ns` argument. This is
+      # it allow `ns` to default to the common annotator `ann`.
+      #
+      # @param ref [Object] Annotation reference key.
+      #
+      # @param ns [Symbol] Annotation namespace.
+      #
+      def lookup(ref=nil, ns=:ann)
+        return @table if ref.nil?
+
+        ref, ns = ref.to_sym, (ns || :ann).to_sym
+
+        ann = {}
+        ancestors.reverse_each do |anc|
+          next unless anc.is_a?(Annotations)
+          if h = anc.annotations.local[ns][ref]
+            ann.merge!(h)
+          end
+        end
+        return ann
+      end
+
+      # Set or read annotations.
+      #
+      # IMPORTANT! Do not use this for in-place modifications.
+      # Use #annotate! instead.
+      # 
+      # @pararm ns [Symbol] Annotation namespace.
+      #
+      # @param ref [Object] Annotation reference key.
+      #
+      # @since 0.7.0
+      def annotate(ns, ref, keys_or_class, keys=nil)
+        if Class === keys_or_class
+          keys ||= {}
+          keys[:class] = keys_or_class
+        else
+          keys = keys_or_class
+        end
+
+        if Hash === keys
+          update(ns, ref, keys)
+        else
+          key = keys.to_sym
+          lookup(ref, ns)[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.
+      #
+      # @pararm ns [Symbol] Annotation namespace.
+      #
+      # @param ref [Object] Annotation reference key.
+      #
+      # @since 0.7.0
+      def annotate!(ns, ref, keys_or_class, keys=nil)
+        if Class === keys_or_class
+          keys ||= {}
+          keys[:class] = keys_or_class
+        else
+          keys = keys_or_class
+        end
+
+        if Hash === keys
+          update(ns, ref, keys)
+        else
+          key = keys.to_sym
+          @table[ns][ref] ||= {}
+          begin
+            @table[ns][ref][key] = lookup(ref, ns)[key].dup
+          rescue TypeError
+            @table[ns][ref][key] = lookup(ref, ns)[key]
+          end
+        end
+      end
+
+      # Update annotations for a given namespace and reference.
+      def update(ns, ref, hash)
+        ref  = ref.to_sym
+
+        @table[ns][ref] ||= {}
+
+        hash.each do |k,v|
+          @table[ns][ref][k.to_sym] = v
+        end
+
+        # callback
+        @space.annotation_added(ref, ns) #if method_defined?(:annotation_added)
+      end
+
+    end
+
+  end
+
+end

data/lib/anise/annotative.rb

@@ -0,0 +1,7 @@
+module Anise
+
+  module Annotative
+
+  end
+
+end

data/lib/anise/annotative/attributes.rb

@@ -0,0 +1,147 @@
+module Anise
+
+  module Annotative
+
+    # The {Annotative::Attributes} mixin modifies the attr_* methods to allow easy
+    # addition of annotations for attributes. It modifies the built in
+    # attribute methods (attr, attr_reader, attr_writer and attr_accessor),
+    # and any other custom `attr_*` methods, to allow annotations to be
+    # added to them directly rather than requiring a separate annotating
+    # statement.
+    #
+    #   class X
+    #     extend Anise::Annotative::Attributes
+    #
+    #     attr :a, :valid => lambda{ |x| x.is_a?(Integer) }
+    #   end
+    #
+    # See {Annotation} module for more information.
+    #
+    # @todo Currently annotated attributes alwasy use the standard
+    #       annotator (:ann). In the future we might make this customizable.
+    #
+    module Attributes
+
+      include Annotations
+
+      #
+      # When included into a class or module, {Annotation} is also
+      # included and {Attribute::Aid} extends the class/module.
+      #
+      # @param base [Class, Module]
+      #   The class or module to get features.
+      #
+      def self.extended(base)
+        #inheritor :instance_attributes, [], :|
+        base_class = (class << base; self; end)
+        #base_class.attribute_methods.each do |attr_method|
+        base.attribute_methods.each do |attr_method|
+          define_annotated_attribute(base_class, attr_method)
+        end
+      end
+
+      # TODO: Might #define_annotated_attribute make an acceptable class extension?
+
+      #
+      # Define an annotated attribute method, given an existing
+      # non-annotated attribute method.
+      #
+      def self.define_annotated_attribute(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)
+
+              super(*args) #attr_method.call(*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
+
+      #
+      # Instance attributes, including inherited attributes.
+      #
+      def instance_attributes
+        a = []
+        ancestors.each do |anc|
+          next unless anc < Attributes
+          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 defines 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 (or was suppose to!).
+      #
+      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) 2006,2011 Thomas Sawyer. All rights reserved. (BSD-2-Clause License)