anise 0.6.0 → 0.7.0

data/README.md

@@ -0,0 +1,129 @@
+# Anise
+
+[Hompage](http://rubyworks.github.com/anise) /
+[Report Issue](http://github.com/rubyworks/anise/issues) /
+[Source Code](http://github.com/rubyworks/anise) /
+[Mailing List](http://groups.google.com/group/rubyworks-mailinglist) /
+[IRC Channel](http://chat.us.freenode.new/rubyworks)
+
+[![Build Status](https://secure.travis-ci.org/rubyworks/anise.png)](http://travis-ci.org/rubyworks/anise)
+
+
+## Introduction
+
+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.
+
+
+## Installation
+
+To install with RubyGems simply open a console and type:
+
+    gem install anise
+
+To manually install you will need Setup.rb (see http://setup.rubyforge.org).
+Then download the tarball package and do:
+
+    $ tar -xvzf anise-0.2.0.tgz
+    $ cd anise-0.2.0
+    $ sudo setup.rb all
+
+
+## Instruction
+
+The following example briefly demonstrates all three major features. To use
+any of them first require the `anise` library.
+
+     require 'anise'
+
+General annotations are provided by the `Anise::Annotations` module.
+
+    class X
+      extend Anise::Annotations
+
+      ann :grape, :class=>String
+    end
+
+    X.ann(:grape, :class)  #=> String
+
+Annotated attributes can be easily added to a class via the `Annotative::Attributes`
+module.
+
+    class X
+      extend Anise::Annotative::Attributes
+
+      attr :baz, Integer, :max => 10
+    end
+
+    X.ann(:baz)  #=> {:class=>Integer, :max=>10}
+
+Mewthod annotations can be had via the `AnnotatedMethods` module.
+
+    class X
+      extend Anise::Annotative::Methods
+
+      def self.doc(string)
+        method_annotation(:doc=>string)
+      end
+
+      doc "This is an entry."
+
+      def bar
+        # ...
+      end
+    end
+
+    X.ann(:bar)  #=> {:doc=>"This is an entry."}
+
+Any of these modules can be used in conjunction. Since both `AnnotatedMethods`
+and `AnnotatedAttributes` preclude `Annotations` all three can be used by simply
+using the later two.
+
+     class X
+       extend Anise::Annotative::Attributes
+       extend Anise::Annotative::Methods
+
+       ...
+     end
+
+Note also that the `Anise` module is clean and contains only modules and classes
+with detailed names starting the "Annotat-", so it is prefectly convenient for
+inclusion in the toplevel namespace or your own applications namespace.
+
+    module MyApp
+      include Anise
+
+      class Foo
+        extend Annotative::Attributes
+
+        ...
+      end
+    end
+
+
+## Development
+
+### Test Instructions
+
+Ainse has two test suites, one using [QED](http://rubyworks.github.com/qed) and
+the other using [Citron](http://rubyworks.github.com/citron) which is built on
+[RubyTest](http://rubyworks.github.com/rubytest).
+
+To run the QED demonstrations simple run:
+
+    $ qed
+
+To run the Citron-based unit tests use:
+
+    $ rubytest
+
+
+## Copyrights
+
+Copyright (c) 2008 Rubyworks. All rights reserved.
+
+This program is distributed under the terms of the **BSD-2-Clause** license.
+
+See LICNESE.txt file for details.

data/demo/01_annotations.md

@@ -0,0 +1,81 @@
+# Annotations
+
+## Creating and Reading Annotations
+
+Load the Anise library.
+
+    require 'anise'
+
+Given an example class X we can apply annotations to it using the #ann method. 
+
+    class X
+      extend Anise::Annotations
+
+      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
+
+## Annotation Added Callback
+
+Given a sample class Y, we can use a standard callback method #annotation_added().
+
+    class Y
+      extend Anise::Annotations
+
+      class << self
+        attr :last_callback
+
+        def annotation_added(ref, ns)
+          @last_callback = [ns, ref, ann(ref/ns)]
+        end
+      end
+    end
+
+Now if we add an annotation, we will see the callback catches it.
+
+    Y.ann :x1, :a=>1
+    Y.last_callback.should == [:ann, :x1, {:a => 1}]
+
+We will do it again to be sure.
+
+    Y.ann :x1, :b=>2
+    Y.last_callback.should == [:ann, :x1, {:a => 1, :b => 2}]
+
+## Using Callbacks for Attribute Defaults
+
+    class ::Module
+      def annotation_added(key, ns)
+        return unless ns == :ann
+        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 Z
+      extend Anise::Annotations
+
+      attr :a
+      ann :a, :default => 10
+    end
+
+    z = Z.new
+    z.a.should == 10
+    z.a.should == 10
+

data/demo/03_attributes.md

@@ -0,0 +1,14 @@
+# Annotative Attributes
+
+Create a class that uses the `Annotative::Attributes` mixin.
+
+    class X
+      extend Anise::Annotative::Attributes
+
+      attr :a, :count => 1
+    end
+
+Then we can see tht the attribute method `:a` has an annotation entry.
+
+    X.ann(:a, :count) #=> 1
+

data/demo/04_methods.md

@@ -0,0 +1,50 @@
+# Method Annotations
+
+Create a class that uses the `Annotative::Methods` mixin.
+
+    class X
+      extend Anise::Annotative::Methods
+
+      def self.doc(string)
+        method_annotation(:doc=>string.to_s)
+      end
+
+      doc "See what I mean?"
+
+      def see
+        puts "Yes, I see!"
+      end
+    end
+
+See that it is set.
+  
+    X.ann(:see, :doc)  #=> "See what I mean?"
+
+Method Annotators can override the standard annotation procedure
+with a custom procedure. In such case no annotations will actually
+be created unless the `#ann` is called in the procedure.
+
+    class Y
+      extend Anise::Annotative::Methods
+
+      def self.list
+        @list ||= []
+      end
+
+      def self.doc(string)
+        method_annotation do |method|
+          list << [method, string]
+        end
+      end
+
+      doc "See here!"
+    
+      def see
+        puts "Yes, I see!"
+      end
+    end
+
+See that it is set.
+  
+    Y.list #=> [[:see, "See here!"]]
+

data/demo/05_variables.md

@@ -0,0 +1,45 @@
+# Variable Annotations
+
+Create a class that uses the `Annotative::Variables` mixin.
+
+    class X
+      extend Anise::Annotative::Variables
+
+      variable_annotator :@doc
+
+      @doc = "See what I mean?"
+
+      def see
+        puts "Yes, I see!"
+      end
+    end
+
+See that it is set.
+  
+    X.ann(:see, :@doc).should == "See what I mean?"
+
+Variable annotations can override the standard annotation procedure with a
+custom procedure.
+
+    class Y
+      extend Anise::Annotative::Variables
+
+      def self.list
+        @list ||= []
+      end
+
+      variable_annotator :@doc do |method, value|
+        list << [method, value]
+      end
+
+      @doc = "See here!"
+
+      def see
+        puts "Yes, I see!"
+      end
+    end
+
+See that it is set.
+  
+    Y.list #=> [[:see, "See here!"]]
+

data/demo/applique/anise.rb

@@ -0,0 +1 @@
+require 'anise'

data/{qed/toplevel/01_annotations.qed → demo/toplevel/01_annotations.md}

@@ -1,13 +1,9 @@
-= Creating and Reading Annotations
+= TOPLEVEL Annotations
 
-Load the primary annotations library.
-
-  require 'anise/annotation'
-
-Including Annotations at the toplevel should make them available to all classes.
+Extending Object with `Annotations` should make them available to all classes.
 
   class ::Object
-    include Anise::Annotation
+    extend Anise::Annotations
   end
 
 Given a example class X we can apply annotations to it using the #ann method. 
@@ -19,12 +15,12 @@ Given a example class X we can apply annotations to it using the #ann method.
 
 We can then use #ann to lookup the set annotations.
 
-  X.ann(:x1,:a).should == 1
+   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.
+Alternatively the `Annotations` module could be included into the `Module` class.
 

data/demo/toplevel/03_attributes.md

@@ -0,0 +1,20 @@
+= TOPLEVEL Annotated Attributes
+
+Including `AnnotatedAttributes` at the toplevel, i.e. Object, will make
+annotated attributes univerally available.
+
+  class ::Object
+    extend Anise::Annotative::Attributes
+  end
+
+Create a class that uses it.
+
+  class X
+    attr :a, :count=>1
+  end
+
+  X.ann(:a, :count) #=> 1
+
+Alternatively the `Annotative::Attributes` module could be included into
+the `Module` class.
+

data/lib/anise.rb

@@ -1,62 +1,45 @@
-require 'anise/annotation'
-require 'anise/attribute'
-require 'anise/annotator'
-
-# = Anise
-#
 # Dynamic Annotations for Ruby.
 #
 #   require 'anise'
 #
+# Provides annotations:
+#
 #   class X
-#     include Anise
+#     extend Anise::Annotations
 #
-#     # Provides annotations
 #     ann :foo, :class=>String
+#   end
 #
-#     # Provides annotated attributes
-#     attr :bar, Integer, :max=>10
+# Provides method annotations:
+#
+#   class Y
+#     extend Anise::Annotator::Method
+#
+#     def self.doc(string)
+#       method_annotation(:doc=>string)
+#     end
 #
-#     # Provides method annotators.
-#     annotator :doc
 #     doc "foo is cool"
 #     def foo
 #       # ...
 #     end
 #   end
 #
+# Provides annotated attributes:
+#
+#   class Z
+#     extend Anise::Annotator::Attribute
+#
+#     attr :bar, Integer, :max=>10
+#   end
+#
 module Anise
-  extend self 
-
-  def included(base)
-    #super(base)
-    base.send(:include, Attribute)
-    base.send(:include, Annotator)
-    #base.extend Anise #ClassMethods
-  end
-
-  #module ClassMethods
-  #  def append_features(base)
-  #    super(base)
-  #    Attribute.append_features(base)
-  #    Annotator.append_features(base)
-  #    base.extend ClassMethods
-  #  end
-  #end
-
-  #
-  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
-
-  VERSION = metadata['version']  # becuase Ruby 1.8~ gets in the way :(
+  require 'anise/version'
+  require 'anise/core_ext'
+  require 'anise/annotations'
+  require 'anise/annotations/store'
+  require 'anise/annotative'
+  require 'anise/annotative/methods'
+  require 'anise/annotative/attributes'
+  require 'anise/annotative/variables'
 end
-