anise 0.6.0 → 0.7.0

data/lib/anise/annotative/methods.rb

@@ -0,0 +1,131 @@
+module Anise
+
+  module Annotative
+
+    # TODO: Ensure thread-safety of <code>@_pending_annotations</code> variable.
+
+    # The Annotator::Method module allows for the creation of annotations
+    # which attach to the next method defined.
+    #
+    # This idiom of annotation-before-definition was popularized by Rake's
+    # `desc`/`task` pair. This module can be used to add similar capabilites
+    # to any class or module.
+    #
+    #     class X
+    #       extend Anise::Annotative::Methods
+    #
+    #       def self.doc(string)
+    #         method_annotation(:doc => string)
+    #       end
+    #
+    #       doc "See what I mean?"
+    #
+    #       def see
+    #         puts "Yes, I see!"
+    #       end
+    #     end
+    #
+    #     X.ann(:see, :doc) #=> "See what I mean?"
+    #
+    # One can get a bit more control over the creation of annotations
+    # by using a block. In this case it is up the code to actually
+    # create the annotation.
+    #
+    #     def self.doc(string)
+    #       method_annotation do |meth|
+    #         ann meth, :doc => string
+    #       end
+    #     end
+    #
+    # 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.
+    #
+    module Methods
+
+      include Annotations
+
+      #
+      # This a temporary store used to create method annotations.
+      #
+      def self.pending_annotations
+        @_pending_annotations ||= Hash.new{ |h,k| h[k] = [] }
+      end
+
+      #
+      # Define a method annotation.
+      #
+      # @example
+      #   method_annotator :doc
+      #
+      # @param name [Symbol]
+      #   Name of annotation.
+      #
+      def method_annotator(name, &block)
+        (class << self; self; end).module_eval do
+          define_method(name) do |*args|
+            anns = { name => (args.size > 1 ? args : args.first) }
+            Methods.pending_annotations[self] << [anns, block]
+          end
+        end
+      end
+
+      #
+      #
+      #
+      def annotator(name, &block)
+        if name.to_s.start_with?('@')
+          if defined?(super)
+            super(name, &block)
+          else
+            raise ArgumentError, "not a valid method name -- #{name}"
+          end
+        else
+          method_annotator(name, &block)
+        end
+      end
+
+      #
+      # Setup a pending method annotation.
+      #
+      # @param [Hash] annotations
+      #   The annotation settings.
+      #
+      def method_annotation(*args, &block)
+        anns = (Hash === args.last ? args.pop : {})
+        Methods.pending_annotations[self] << [anns, block]
+      end
+
+      #
+      # When a method is added, run all pending annotations.
+      #
+      # @param [Symbol] sym
+      #   The name of the method added.
+      #
+      def method_added(sym)
+        annotations = Methods.pending_annotations[self]
+        annotations.each do |anns, block|
+          if block
+            block.call(sym)
+          else
+            anns.each do |name, value|
+              if name.to_s.index('/')
+                name, ns = name.to_s.split('/')
+              else
+                ns = :ann
+              end
+              ann(sym/ns, name=>value)
+            end
+          end
+        end
+        Methods.pending_annotations[self] = []
+        super if defined?(super)
+      end
+
+    end
+
+  end
+
+end
+
+# Copyright (c) 2006 Rubyworks. All rights reserved. (BSD-2-Clause License)

data/lib/anise/annotative/variables.rb

@@ -0,0 +1,99 @@
+module Anise
+
+  module Annotative
+
+    # I bet you never imagined Ruby could suport `@style` annotations.
+    # Well, I am here to tell you otherwise.
+    #
+    # The {VariableAnnotator} module allows class instance variable to be
+    # used method annotations which attach to the next defined method.
+    #
+    #   class X
+    #     extend Anise::Annotative::Variables
+    #
+    #     variable_annotator :@doc
+    #     variable_annotator :@returns
+    #
+    #     @doc = "See what I mean?"
+    #     @returns = NilClass
+    #
+    #     def see
+    #       puts "Yes, I see!"
+    #     end
+    #   end
+    #
+    #   X.ann(:see, :@doc) #=> "See what I mean?"
+    #
+    # This library uses the #method_added callback, so be sure to respect
+    # good practices of calling +super+ if you need to override this method.
+    #
+    # **IMPORTANT!!!** This library is an interesting expirement, but it remains
+    # to be determined if it makes sense for general use.
+    #
+    module Variables
+
+      include Annotations
+   
+      #
+      # Open method annotations.
+      #
+      # @example
+      #   variable_annotator :@doc
+      #
+      # @param ns [Symbol]
+      #   Annotator to use. Default is `:ann`.
+      #
+      def variable_annotator(iv, &block)
+        # TODO: should none iv raise an error instead?
+        iv = "@#{iv}".to_sym if iv.to_s !~ /^@/
+
+        # TODO: use an annotation to record the annotators
+        #ann(:variable_annotator, iv=>block)
+
+        @_variable_annotations ||= {}
+        @_variable_annotations[iv] = block
+      end
+
+      #
+      def annotator(iv, &block)
+        if not iv.to_s.start_with?('@')
+          if defined?(super)
+            super(iv, &block)
+          else
+            raise ArgumentError, "not a valid instance variable -- #{iv}"
+          end
+        else
+          variable_annotator(iv, ns, &block)
+        end
+      end
+
+      #
+      # When a method is added, run all pending annotations.
+      #
+      def method_added(sym)
+        @_variable_annotations ||= {}
+        @_variable_annotations.each do |iv, block|
+          if iv.to_s.index('/')
+            iv, ns = iv.to_s.split('/')
+          else
+            ns = :ann
+          end
+          value = instance_variable_get(iv)
+          if block
+            block.call(sym, value)
+          else
+            ann(sym/ns, iv=>value)
+          end
+          # TODO: can we undefine the instance variable?
+          instance_variable_set(iv, nil)
+        end
+        super(sym) if defined?(super)
+      end
+
+    end
+
+  end
+
+end
+
+# Copyright (c) 2006 Rubyworks. All rights reserved. (BSD-2-Clause License)

data/lib/anise/{module.rb → core_ext.rb}

@@ -1,7 +1,11 @@
+#require 'facets/inheritor' # removed dependency
+
 class Module
+  #
   # Module extension to return attribute methods. These are all methods
   # that start with `attr_`. This method can be overriden in special cases
   # to work with attribute annotations.
+  #
   def attribute_methods
     list = []
     public_methods(true).each do |m|
@@ -17,3 +21,29 @@ class Module
   end
 end
 
+class Symbol
+  #
+  # Create new combination symbol with slash.
+  #
+  # @example
+  #   :foo/:bar  #=> :'foo/bar'
+  # 
+  def /(other)
+    "#{self}/#{other}".to_sym
+  end
+end
+
+class String
+  #
+  # Create new combination string with slash.
+  #
+  # @example
+  #   'foo'/'bar'  #=> 'foo/bar'
+  # 
+  def /(other)
+    "#{self}/#{other}"
+  end
+end
+
+# Copyright (c) 2006 Rubyworks. All rights reserved. (BSD-2-Clause License)
+

data/lib/anise/universal.rb

@@ -0,0 +1,6 @@
+require 'anise'
+
+class Module
+  include Anise::Annotations
+end
+

data/lib/anise/version.rb

@@ -0,0 +1,17 @@
+module Anise
+
+  #
+  def self.metadata
+    @metadata ||= (
+      require 'yaml'
+      YAML.load(File.new(File.dirname(__FILE__) + '/../anise.yml'))
+    )
+  end
+
+  #
+  def self.const_missing(name)
+    metadata[name.to_s.downcase] || super(name)
+  end
+
+end
+

data/test/case_annotations.rb

@@ -0,0 +1,173 @@
+testcase Anise::Annotations do
+
+  context "annotations can be defined" do
+
+    cX = Class.new do
+      extend Anise::Annotations
+      def x1 ; end
+      ann :x1, :a=>1
+      ann :x1, :b=>2
+    end
+
+    test "01" do
+      cX.ann(:x1,:a) == cX.ann(:x1,:a)
+    end
+
+    test "02" do
+      cX.ann(:x1,:a).object_id == cX.ann(:x1,:a).object_id
+    end
+
+    test "03" do
+      cX.ann(:x1,:a) == 1
+    end
+
+    test "04" do
+      cX.ann :x1, :a => 2
+      cX.ann(:x1,:a) == 2
+    end
+
+  end
+
+  context "parent annotations pass to subclass" do
+
+    cX = Class.new do
+      extend Anise::Annotations
+      def x1 ; end
+      ann :x1, :a=>1
+      ann :x1, :b=>2
+    end
+
+    cY = Class.new(cX)
+
+    test "01" do
+      cY.ann(:x1,:a) == cY.ann(:x1,:a)
+    end
+
+    test "02" do
+      cY.ann(:x1,:a).object_id == cY.ann(:x1,:a).object_id
+    end
+
+    test "03" do
+      cY.ann(:x1,:a) == 1
+    end
+
+    test "04" do
+      cY.ann(:x1,:b) == 2
+    end
+
+    test "05" do
+      cY.ann :x1,:a => 2
+      cY.ann(:x1,:a) == 2 &&
+      cY.ann(:x1,:b) == 2
+    end
+
+  end
+
+  context "subclass can override parent annotation" do
+
+    cX = Class.new do
+      extend Anise::Annotations
+      ann :foo, Integer
+    end
+
+    cY = Class.new(cX) do
+      ann :foo, String
+    end
+
+    test "01" do
+      cX.ann(:foo, :class) == Integer
+    end
+
+    test "02" do
+      cY.ann(:foo, :class) == String
+    end
+
+  end
+
+  context "subclass can override while parent also passes thru" do
+
+    cX = Class.new do
+      extend Anise::Annotations
+      ann :foo, :doc => "hello"
+      ann :foo, :bar => []
+    end
+
+    cY = Class.new(cX) do
+      ann :foo, :class=>String, :doc=>"bye"
+    end
+
+    test "01" do
+      cX.ann(:foo,:doc) == "hello"
+    end
+
+    test "02" do
+      cX.ann(:foo) == {:doc=>"hello", :bar=>[]}
+    end
+
+    test "03" do
+      cX.ann(:foo,:bar) << "1"
+      cX.ann(:foo,:bar) == ["1"]
+    end
+
+    test "04" do
+      cY.ann(:foo,:doc) == "bye"
+    end
+
+    test "05" do
+      #Y.ann(:foo,:bar) == nil
+      cY.ann(:foo,:bar) == ["1"]
+    end
+
+    test "06" do
+      cY.ann(:foo, :doc => "cap")
+      cY.ann(:foo, :doc) == "cap"
+    end
+
+    test "07" do
+      cY.ann!(:foo,:bar) << "2"
+
+      cY.ann(:foo,:bar) == ["1", "2"] &&
+      cY.ann(:foo,:bar) == ["1", "2"] &&
+      cX.ann(:foo,:bar) == ["1"]
+    end
+
+  end
+
+  context "example of using annotations for validation" do
+
+    cX = Class.new do
+      extend Anise::Annotations
+
+      attr :a
+
+      ann :@a, :valid => lambda{ |x| x.is_a?(Integer) }
+      ann :a,  :class => Integer
+
+      def initialize(a)
+        @a = a
+      end
+
+      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
+
+    test "annotation class" do
+      cX.ann(:a, :class) == Integer
+    end
+
+    test "annotation validate" do
+      r = cX.new(1)
+      r.validate
+    end
+
+  end
+
+end