Module | Anise::Annotations |
In: |
lib/anise/annotations/store.rb
lib/anise/annotations.rb |
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.
Get/set annotations.
@examples
ann :ref, :key=>value ann :ref/:ns, :key=>value ann :ref, :key ann :ref/:ns, :key
Get/set annotations in-place. Use this method instead of `ann` when performing mass updates.