anise 0.1.1 → 0.2.0

data/COPYING

@@ -1,168 +1,166 @@
-.
+= GNU LESSER GENERAL PUBLIC LICENSE
 
-                GNU LESSER GENERAL PUBLIC LICENSE
-                     Version 3, 29 June 2007
+<b>Version 3, 29 June 2007</b>
 
-   Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
-   Everyone is permitted to copy and distribute verbatim copies
-   of this license document, but changing it is not allowed.
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
 
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
 
-    This version of the GNU Lesser General Public License incorporates
-  the terms and conditions of version 3 of the GNU General Public
-  License, supplemented by the additional permissions listed below.
+== 0. Additional Definitions. 
 
-    0. Additional Definitions. 
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
 
-    As used herein, "this License" refers to version 3 of the GNU Lesser
-  General Public License, and the "GNU GPL" refers to version 3 of the GNU
-  General Public License.
-
-    "The Library" refers to a covered work governed by this License,
-  other than an Application or a Combined Work as defined below.
-
-    An "Application" is any work that makes use of an interface provided
-  by the Library, but which is not otherwise based on the Library.
-  Defining a subclass of a class defined by the Library is deemed a mode
-  of using an interface provided by the Library.
-
-    A "Combined Work" is a work produced by combining or linking an
-  Application with the Library.  The particular version of the Library
-  with which the Combined Work was made is also called the "Linked
-  Version".
-
-    The "Minimal Corresponding Source" for a Combined Work means the
-  Corresponding Source for the Combined Work, excluding any source code
-  for portions of the Combined Work that, considered in isolation, are
-  based on the Application, and not on the Linked Version.
-
-    The "Corresponding Application Code" for a Combined Work means the
-  object code and/or source code for the Application, including any data
-  and utility programs needed for reproducing the Combined Work from the
-  Application, but excluding the System Libraries of the Combined Work.
-
-    1. Exception to Section 3 of the GNU GPL.
-
-    You may convey a covered work under sections 3 and 4 of this License
-  without being bound by section 3 of the GNU GPL.
-
-    2. Conveying Modified Versions.
-
-    If you modify a copy of the Library, and, in your modifications, a
-  facility refers to a function or data to be supplied by an Application
-  that uses the facility (other than as an argument passed when the
-  facility is invoked), then you may convey a copy of the modified
-  version:
-
-     a) under this License, provided that you make a good faith effort to
-     ensure that, in the event an Application does not supply the
-     function or data, the facility still operates, and performs
-     whatever part of its purpose remains meaningful, or
-
-     b) under the GNU GPL, with none of the additional permissions of
-     this License applicable to that copy.
-
-    3. Object Code Incorporating Material from Library Header Files.
-
-    The object code form of an Application may incorporate material from
-  a header file that is part of the Library.  You may convey such object
-  code under terms of your choice, provided that, if the incorporated
-  material is not limited to numerical parameters, data structure
-  layouts and accessors, or small macros, inline functions and templates
-  (ten or fewer lines in length), you do both of the following:
-
-     a) Give prominent notice with each copy of the object code that the
-     Library is used in it and that the Library and its use are
-     covered by this License.
-
-     b) Accompany the object code with a copy of the GNU GPL and this license
-     document.
-
-    4. Combined Works.
-
-    You may convey a Combined Work under terms of your choice that,
-  taken together, effectively do not restrict modification of the
-  portions of the Library contained in the Combined Work and reverse
-  engineering for debugging such modifications, if you also do each of
-  the following:
-
-     a) Give prominent notice with each copy of the Combined Work that
-     the Library is used in it and that the Library and its use are
-     covered by this License.
-
-     b) Accompany the Combined Work with a copy of the GNU GPL and this license
-     document.
-
-     c) For a Combined Work that displays copyright notices during
-     execution, include the copyright notice for the Library among
-     these notices, as well as a reference directing the user to the
-     copies of the GNU GPL and this license document.
-
-     d) Do one of the following:
-
-         0) Convey the Minimal Corresponding Source under the terms of this
-         License, and the Corresponding Application Code in a form
-         suitable for, and under terms that permit, the user to
-         recombine or relink the Application with a modified version of
-         the Linked Version to produce a modified Combined Work, in the
-         manner specified by section 6 of the GNU GPL for conveying
-         Corresponding Source.
-
-         1) Use a suitable shared library mechanism for linking with the
-         Library.  A suitable mechanism is one that (a) uses at run time
-         a copy of the Library already present on the user's computer
-         system, and (b) will operate properly with a modified version
-         of the Library that is interface-compatible with the Linked
-         Version. 
-
-     e) Provide Installation Information, but only if you would otherwise
-     be required to provide such information under section 6 of the
-     GNU GPL, and only to the extent that such information is
-     necessary to install and execute a modified version of the
-     Combined Work produced by recombining or relinking the
-     Application with a modified version of the Linked Version. (If
-     you use option 4d0, the Installation Information must accompany
-     the Minimal Corresponding Source and Corresponding Application
-     Code. If you use option 4d1, you must provide the Installation
-     Information in the manner specified by section 6 of the GNU GPL
-     for conveying Corresponding Source.)
-
-    5. Combined Libraries.
-
-    You may place library facilities that are a work based on the
-  Library side by side in a single library together with other library
-  facilities that are not Applications and are not covered by this
-  License, and convey such a combined library under terms of your
-  choice, if you do both of the following:
-
-     a) Accompany the combined library with a copy of the same work based
-     on the Library, uncombined with any other library facilities,
-     conveyed under the terms of this License.
-
-     b) Give prominent notice with the combined library that part of it
-     is a work based on the Library, and explaining where to find the
-     accompanying uncombined form of the same work.
-
-    6. Revised Versions of the GNU Lesser General Public License.
-
-    The Free Software Foundation may publish revised and/or new versions
-  of the GNU Lesser General Public License from time to time. Such new
-  versions will be similar in spirit to the present version, but may
-  differ in detail to address new problems or concerns.
-
-    Each version is given a distinguishing version number. If the
-  Library as you received it specifies that a certain numbered version
-  of the GNU Lesser General Public License "or any later version"
-  applies to it, you have the option of following the terms and
-  conditions either of that published version or of any later version
-  published by the Free Software Foundation. If the Library as you
-  received it does not specify a version number of the GNU Lesser
-  General Public License, you may choose any version of the GNU Lesser
-  General Public License ever published by the Free Software Foundation.
-
-    If the Library as you received it specifies that a proxy can decide
-  whether future versions of the GNU Lesser General Public License shall
-  apply, that proxy's public statement of acceptance of any version is
-  permanent authorization for you to choose that version for the
-  Library.
+"The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+== 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+== 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+a) under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+== 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+a) Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+== 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+a) Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+c) For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+d-0) Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+
+d-1) Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that (a) uses at run time
+a copy of the Library already present on the user's computer
+system, and (b) will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version. 
+
+e) Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option 4d0, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option 4d1, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+== 5. Combined Libraries.
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+a) Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+== 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
 

data/HISTORY

@@ -1,16 +1,18 @@
-== 0.0.0 // 2008-03-04
+2008-10-23   trans <transfire@gmail.com>
 
-* Started project.
+        * cleaned up work directory
+        * working on version 0.2.x
+        * added notes and ridoc reap services
+        * renamed some libs
 
 
-# Keep a running list of changes by version and date here.
-# This is uploaded as the ChangeLog in the release process.
-# It's better to keep a manual log, rather then use the log
-# generated by the SCM because the SCM log will have gritty
-# details with which end-users will not be concerned.
-#
-# If you want to use the SCM log anyway, you can of course
-# do so. Just "cp log/Changelog.txt CHANGES" prior to release.
-# (We might provide an automated option for this in the
-# future, but for now its a manual task.)
+2008-10-21   trans <transfire@gmail.com>
+
+        * Annotations is now module rather than a direct core extenstion to Module
+
+
+2008-10-17   trans <transfire@gmail.com>
+
+        * added .gitignore
+        * initial commit
 

data/MANIFEST

@@ -1,9 +1,13 @@
 test
-test/test_toplevel_attribute.rb
 test/test_attribute.rb
-test/test_annotatable.rb
+test/test_annotator.rb
 test/suite.rb
-test/test_toplevel_annotatable.rb
+test/test_annotator_toplevel.rb
+test/test_annotations.rb
+test/test_attribute_toplevel.rb
+test/test_anise.rb
+test/test_anise_toplevel.rb
+test/test_annotations_toplevel.rb
 RELEASE
 README
 HISTORY
@@ -18,9 +22,9 @@ meta/authors
 meta/contact
 lib
 lib/anise
-lib/anise/attributes.rb
-lib/anise/annotations.rb
-lib/anise/annotatable.rb
+lib/anise/attribute.rb
+lib/anise/annotation.rb
+lib/anise/annotator.rb
 lib/anise.rb
 VERSION
 COPYING

data/README

@@ -1,36 +1,32 @@
-= Annotable
+= Anise
 
   http://anise.rubyforge.org
 
 
 == INTRODUCTION
 
-Annotable is an Annotations Systems for the Ruby programming
-lanaguage. Unlike other annotations system it is not a comment-based
-system. Rather, it is a dynamic annotations system operating at runtime.
+Anise is an Annotations Systems for the Ruby programming lanaguage.
+Unlike most other annotations systems it is not a comment-based
+system, or a "macro" system that sits over-and-above the rest of the 
+code. Rather, Anise is a dynamic annotations system operating at runtime.
 
 
-== RELEASE NOTES
+== RELEASE NOTES & RECENT CHANGES
 
 Please see the RELEASE file.
 
 
-== RECENT CHANGES
-
-Please see the HISTORY file.
-
-
 == INSTALLATION
 
 To install with RubyGems simply open a console and type:
 
-  gem install annotable
+  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.4.0.tgz
-  $ cd annotated-0.4.0.tgz
+  $ cd annotated-0.4.0
   $ sudo setup.rb all
 
 
@@ -41,7 +37,7 @@ unit tests.
 
   $ turn test/test_*
 
-But we have include a script test/suite.rb so you can easily run the
+But we have include a script +test/suite.rb+ so you can easily run the
 unit tests with the testrb command:
 
   $ testrb test/suite.rb

data/RELEASE

@@ -1,11 +1,20 @@
-= Anise 0.1 hits the streets.
+= Anise 0.2.0 hits the streets.
 
-This is the initial release of Anise.
+  http://anise.rubyforge.org
+
+This is the initial public release of Anise.
 
 Anise is a spin off the the Facets annotations.rb library.
 It includes the Annotations functionality, and adds
-a mixin, Annotatable, that makes it easy to add new
+a mixin, Annotator, that makes it easy to add new
 annotations on the fly.
 
-  http://anise.rubyforge.org
+---
+
+### 0.2.0 // 2008-09-23
+
+2 Major Enhancments
+
+  * All parts of lib are now modules and not core extensions.
+  * Names of modules are more consistant.
 

data/VERSION

@@ -1 +1 @@
-anise 0.1.1 beta (2008-09-27)
+anise 0.2.0 beta (2008-09-27)

data/lib/anise/annotation.rb

@@ -0,0 +1,160 @@
+module Anise
+
+  # = Runtime Annotations
+  #
+  # The Annotation module is the heart 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 you can put them to use. For instance
+  # an attribute validator might check for an annotation called
+  # :valid and test against it.
+  #
+  # == Synopsis
+  #
+  #   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(vale)
+  #             raise "Invalid value #{value} for #{iv}"
+  #           end
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # Or, we could even annotate the class itself.
+  #
+  #   class X
+  #     include Anise::Annotation
+  #
+  #     ann self, :valid => lambda{ |x| x.is_a?(Integer) }
+  #   end
+  #
+  # Altough annotations are arbitrary they are tied to the class or
+  # module they are defined within.
+  #
+  #--
+  # 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.
+  #++
+  module Annotation
+
+    def self.append_features(base)
+      base.extend self
+    end
+
+    # Stores this classes or modules annotations.
+    #
+    def annotations
+      #$annotations[self]
+      @annotations ||= {}
+    end
+
+    # 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)
+      ref = ref.to_sym
+      ann = {}
+      ancestors.reverse_each do |anc|
+        next unless anc.is_a?(Annotation)
+        #anc.annotations[ref] ||= {}
+        if anc.annotations[ref]
+          ann.update(anc.annotations[ref]) #.merge(ann)
+        end
+      end
+      return ann
+      #ancs = ancestors.select{ |a| a.is_a?(Annotations) }
+      #ancs.inject({}) do |memo, ancestor|
+      #  ancestor.annotations[ref] ||= {}
+      #  ancestor.annotations[ref].merge(memo)
+      #end
+    end
+
+    # 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)
+      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
+      return annotations[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)
+      else
+        key = keys.to_sym
+        annotations[ref][key] = annotation(ref)[key].dup
+      end
+    end
+
+  end
+
+end
+
+# 2006-11-07 trans  Created this ultra-concise version of annotations.
+# Copyright (c) 2005, 2008 TigerOps
+