Interface all annotations must support. There are two things that each
annotation has to support.
Annotations have to support an as_text method. This should be a
single text string, without newlines representing the annotation,
mainly for human readability. It is not aimed at being able to
store/represent the annotation.
The second method allows annotations to at least attempt to represent
themselves as pure data for storage/display/whatever. The method
hash_tree should return an anonymous hash with XML-like formatting:
$hash = $annotation->hash_tree();
The formatting is as follows.
(1) For each key in the hash, if the value is a referenced array -
(2) For each element of the array if the value is a object -
Assume the object has the method "hash_tree";
(3) else if the value is a reference to a hash
Recurse again from point (1)
Assume the value is a scalar, and handle it directly as text
(5) else (if not an array) apply rules 2,3 and 4 to value
The XML path in tags is represented by the keys taken in the
hashes. When arrays are encountered they are all present in the path
level of this tag
This is a pretty natural representation of an object tree in an XML
style, without forcing everything to inherit off some super-generic
interface for representing things in the hash.