---++ Introduction

Stratego uses terms to represent the abstract syntax of programs or documents. A term consists of a constructor 
and a list of argument terms. Sometimes it is useful to record additional information about a term without adapting 
its structure, i.e., creating a constructor with additional arguments. For this purpose terms can be annotated.
Support for TermAnnotations has been available from StrategoRelease07. 

In Stratego a term always has a list of annotations. This is the empty list if a term doesn't have any annotations.
term annotation uses the syntax

<verbatim>
  t1 { a1 }
</verbatim>

where term a1 is an annotation of term t1. If you want to add more
annotations to a term you can use the same syntax you would use for the content of a list:

<verbatim>
  t1 { a1, a2, a3 }
</verbatim>

---++ Annotations in match and build

The annotations of a term can be retrieved in a pattern match and set in a build. For example
the following build will create a term =Plus(1, 2)= with the term =Int= as the only annotation.

<verbatim>
  !Plus(1, 2){Int}
</verbatim>

Naturally the annotation syntax can also be used in a match:

<verbatim>
  ?Plus(1, 2){Int}
</verbatim>

Note however that this match only accepts =Plus(1, 2)= terms with just one annotation, which 
should be the empty contstructor application =Int=. This match will thus not allow other 
annotations.

---++ Annotations in RewriteRules

Because a RewriteRule is just sugar for a StrategyDefinition, the usage of annotations in rules
is just as you would expect. The following rule checks that the two subterms of the Plus have annotation Int 
and then attaches the annotation Int to the whole term:

<verbatim>
  TypeCheck :
	 Plus(e1{Int}, e2{Int}) -> Plus(e1, e2){Int}
</verbatim>

---++ Annotations in CongruenceOperators

Also congruences over annotations are supported. Thus, if =s1= and =s2= are strategies, 
then =s1{s2}= is also a strategy, which applies s1 to the term and s2 to its annotations.
Notice that s2 is applied to the =annotations=. Therefor you have to use a list
congruence =[s3]= if you want to apply s3 to the only annotation of s3. If you want to
apply a strategy to all annotations, you can use a map.

Some examples:
<verbatim>
	<id{[inc]}>		Plus(1, 2){3}		 => Plus(1, 2){4}
	<id{[inc, inc]}> Plus(1, 2){3, 4}	 => Plus(1, 2){4, 5}
	<id{map(inc)}>	Plus(1, 2){3, 4, 5} => Plus(1, 2){4, 5, 6}
</verbatim>

---++ Frequent problems

---+++ Annotation is list

Remember that if you apply a =!Plus(1, 2){x}=, the term x will be the only annotation. This is also
the case if x is a list. Example:

<verbatim>
	SomeRule: xs -> Plus(5, 6){xs}

	<SomeRule> ["a", "b", "c"] => Plus(5, 6){["a", "b", "c"]}
</verbatim>

Notice that in this example the result is not =Plus(5, 6){"a", "b", "c"}=. The Plus term
will have just one annotation, which is the list =["a", "b", "c"]=. You can use ListMatching to solve 
this problem:

<verbatim>
	SomeRule: [xs*] -> Plus(5, 6){xs*}

	<SomeRule> ["a", "b", "c"] => Plus(5, 6){"a", "b", "c"}
</verbatim>

You can also use ListMatching inside the annotation part of a match:
<verbatim>
	Incr: Int(x){as*} -> Int(<inc> x){as*}

	<Incr> Int(5){Int} => Int(6){Int}
</verbatim>

---+++ Preserving annotations

Because annotations are not part of the structure there is a huge risk
of losing them. For example the following RewriteRule will already
drop the annotations of the Int term.

<verbatim>
	Incr: Int(x) -> Int(<inc> x)
</verbatim>

You can create a strategy into an annotation preserving strategy
with =preserve-annos= in the annotations module of the StrategoStandardLibrary.

The GenericTermTraversal operators =all=, =some= and =one= and 
CongruenceOperators preserve annotations. If the =Incr= rule is implemented
as congruence, the annotations will be preserved:

<verbatim>
	Incr = Int(inc)

	<Incr> Int(5){Int} => Int(6){Int}
</verbatim>

-- Main.MartinBravenboer - 25 Jan 2003

----
CategoryGlossary