Language.Ninja.Misc.Annotated

A typeclass for AST nodes that are annotated with a polymorphic field, which provides a canonical lens into that field.

Since: 0.1.0

Documentation

class Functor ty => Annotated ty where

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

Minimal complete definition

annotation'

Methods

annotation' :: (ann -> ann') -> Lens (ty ann) (ty ann') ann ann'

Given a function that is used when fmaping any subterms, return a lens into the "annotation" field.

When writing an instance, keep in mind that annotation' id should just be the typical definition for a lens into the annotation field.

It should also be true that for any f :: B -> C and g :: A -> B,

annotation' (f . g) == annotation' f . annotation' g

Since: 0.1.0

Instances

Annotated Expr

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (Expr ann) (Expr ann') ann ann'

Annotated Rule

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (Rule ann) (Rule ann') ann ann'

Annotated Deps

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (Deps ann) (Deps ann') ann ann'

Annotated Build

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (Build ann) (Build ann') ann ann'

Annotated Ninja

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (Ninja ann) (Ninja ann') ann ann'

Annotated LBuild

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (LBuild ann) (LBuild ann') ann ann'

Annotated LName

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (LName ann) (LName ann') ann ann'

Annotated Lexeme

The usual definition for Annotated.

Since: 0.1.0

Methods

annotation' :: (ann -> ann') -> Lens (Lexeme ann) (Lexeme ann') ann ann'

annotation :: Annotated ty => Lens' (ty ann) ann

This is just shorthand for annotation' id.

Since: 0.1.0