module Anise::Annotations

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.

Public Instance Methods

ann(ref, *keys) click to toggle source

Get/set annotations.

@examples

ann :ref, :key=>value
ann :ref/:ns, :key=>value

ann :ref, :key
ann :ref/:ns, :key
# File lib/anise/annotations.rb, line 94
def ann(ref, *keys)
  if ref.to_s.index('/')
    ref, ns = ref.to_s.split('/')
  else
    ns = :ann
  end
  ref, ns = ref.to_sym, ns.to_sym

  if keys.empty?
    annotations.lookup(ref, ns)
  else
    annotations.annotate(ns, ref, *keys)
  end
end
ann!(ref, *keys) click to toggle source

Get/set annotations in-place. Use this method instead of ‘#ann` when performing mass updates.

# File lib/anise/annotations.rb, line 113
def ann!(ref, *keys)
  if ref.to_s.index('/')
    ref, ns = ref.to_s.split('/')
  else
    ns = :ann
  end
  ref, ns = ref.to_sym, ns.to_sym

  if keys.empty?
    annotations[ref, ns]
  else
    annotations.annotate!(ns, ref, *keys)
  end
end
annotation_added(ref, ns=:ann) click to toggle source

Callback method. This method is called for each new annotation.

Calls superclass method
# File lib/anise/annotations.rb, line 81
def annotation_added(ref, ns=:ann)
  super(ref, ns) if defined?(super)
end
annotations() click to toggle source

Access to a class or module’s annotations.

# File lib/anise/annotations.rb, line 74
def annotations
  @annotations ||= Store.new(self)
end