Documentation

If you have some type that represents an AST node, it is often useful to add a polymorphic "annotation field" to it, which is used for things like source positions.

Specifically, suppose we have the following AST node type:

data Foo = Foo { _fooBar :: !Bar, _fooBaz :: !Baz } deriving (…)

Then an annotation field is added by the following process:

1. Add an extra (final) type parameter ann to the type.
2. Add an extra field _fooAnn :: !ann.
3. Derive instances of Functor, Foldable, and Traversable.
4. If the type is recursive, add a Plated instance. See Language.Ninja.AST.Expr for a complete example of this.
5. Write an Annotated instance with the canonical lens given by the _fooAnn field. There are plenty of examples around this library.

The end result then looks like:

data Foo ann
  = Foo
    { _fooAnn :: !ann
    , _fooBar :: !Bar
    , _fooBaz :: !Baz
    }
  deriving (…, Functor, Foldable, Traversable)

instance Annotated Foo where
  annotation' = …

Since: 0.1.0

This is just shorthand for annotation' id.

Since: 0.1.0