anise 0.6.0 → 0.7.0

data/.ruby

@@ -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/.yardopts

@@ -0,0 +1,7 @@
+--title "Anise"
+--output-dir doc
+--private
+--protected
+lib/
+-
+[A-Z][A-Z]*.*

data/DEMO.md

@@ -0,0 +1,242 @@
+# 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
+
+
+# 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
+
+
+# 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!"]]
+
+
+# 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!"]]
+
+
+= TOPLEVEL Annotations
+
+Extending Object with `Annotations` should make them available to all classes.
+
+  class ::Object
+    extend Anise::Annotations
+  end
+
+Given a example class X we can apply annotations to it using the #ann method. 
+
+  class X
+    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
+
+Alternatively the `Annotations` module could be included into the `Module` class.
+
+
+= 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/{HISTORY.rdoc → HISTORY.md}

@@ -1,6 +1,27 @@
-= RELEASE HISTORY
+# RELEASE HISTORY
 
-== 0.6.0 / 2011-05-16
+## 0.7.0 / 2012-03-26
+
+This release has some major API changes. Most significantly a number
+of modules have been renamed. The `Method` module has been renamed to
+`Annotative::Methods`. Likewise the `Attribute` module has been ranamed
+to `Annotative::Attributes`, and so on. These have been renamed so that
+including `Anise` in the toplevel will not cause conflicts with any
+other modules or classes an application or library might be using.
+In addition these modules now must use `extend` rather then `include`
+to be mixed into a class or module, since they conatin only class methods.
+
+Changes:
+
+* Rename Annotations module to Annotations::Store.
+* Rename Annotation module to Annotations.
+* Rename Method module to Annotative::Methods.
+* Rename Attribute module to Annotative::Attributes.
+* Add #method_annotation for use in custom class method.
+* Discourage #method_annotator in favor of #method_annotation.
+
+
+## 0.6.0 / 2011-05-16
 
 This release fixes an bug in which append_features cant be called b/c
 it is a private method. This release also renames `ClassMethods`
@@ -12,7 +33,7 @@ Changes:
 * Rename ClassMethods to Aid.
 
 
-== 0.5.0 / 2011-04-30
+## 0.5.0 / 2011-04-30
 
 The primary changes in this release are behind the scenes implementation
 improvements. The most significant of which is the simplification of
@@ -28,7 +49,7 @@ Changes:
 * Annotators can override method_added callback.
 
 
-== 0.4.0 / 2009-05-28
+## 0.4.0 / 2009-05-28
 
 This version adds a callback method called #annotation_added
 --a striaght-forward callback method patterned after Ruby's 
@@ -40,7 +61,7 @@ Changes:
 * Added annotation_added callback.
 
 
-== 0.2.1 / 2008-10-31
+## 0.2.1 / 2008-10-31
 
 Project reorganization release --mostly some file names have changed.
 
@@ -49,7 +70,7 @@ Changes:
 * Renamed some lib files.
 
 
-== 0.2.0 / 2008-10-28
+## 0.2.0 / 2008-10-28
 
 By making Annotations a module, it can not be used in only the clases
 it is needed.
@@ -59,7 +80,7 @@ Changes:
 * Annotations is a module rather than a core extenstion to Module.
 
 
-== 0.1.1 / 2008-10-17
+## 0.1.1 / 2008-10-17
 
 Ahoy, mate! This is the first release of Anise.
 

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Anise - Dynamic Annotations for Ruby (http://rubyworks.github.com/anise)
+
+Copyright (c) 2008 Rubyworks, Thomas Sawyer
+
+(spdx) BSD-2-Clause License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY Thomas Sawyer ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+NO EVENT SHALL Thomas Sawyer OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+