New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an annotation API #19

Merged
merged 6 commits into from Jan 27, 2015

Conversation

Projects
None yet
3 participants
@elliottt
Contributor

elliottt commented Jan 24, 2015

Inspired by the annotated-wl-pretty library used in Idris, this change provides a new API through the Text.PrettyPrint.Annotated module hierarchy that allows the annotation of documents. This amounts to adding a new annotate function that allows arbitrary metadata to be associated with sub-documents, as well as some new rendering functions:

  • renderSpans Render a String as well as a list of annotations about that string, which identify sub-strings within it
  • renderDecorated Render a String while interpreting the start and end of annotated regions as parts of that string
  • renderDecoratedM Produce a monadic action, where the start and end of annotated regions are interpreted in that context

The current state of this change is:

  • The test suite has been updated and is passing
  • The original interface through Text.PrettyPrint, Text.PrettyPrint.HughesPJ, and Text.PrettyPrint.HughesPJClass has been preserved, and should not break existing code
  • All of the new changes are exposed through the Text.PrettyPrint.Annotated, Text.PrettyPrint.Annotated.HughesPJ, and Text.PrettyPrint.Annotated.HughesPJClass modules

Trevor Elliott added some commits Jan 24, 2015

Trevor Elliott
Add annotations to the Doc type
 * Parameterize the Doc type by the type of annotations present
 * Add the Span type for describing annotated regions in the resulting String
 * Add renderSpans, and fullRenderAnn, for rendering with annotations
Trevor Elliott
Add renderDecorated, and renderDecoratedM
  Also, go back to storing the annotation value in the AnnotEnd constructor, as
that makes it easier to use that value when processing both the start and end of
an annotation.
@david-christiansen

This comment has been minimized.

Show comment
Hide comment
@david-christiansen

david-christiansen Jan 26, 2015

For those who are curious as to how these annotations can be useful, I wrote a blog post about how we use them in Idris: http://www.davidchristiansen.dk/2014/09/06/pretty-printing-idris/

The basic idea is that the annotations track semantic information about their document, which can then be rendered differently in different contexts. In Idris, we use it to have semantic coloring at the console (for example, showing type constructors and data constructors in different colors), while richer output contexts such as the Emacs REPL or tryidris.org can make information like docstrings and type annotations for names available in tooltips. It's also possible to do things like normalizing terms that occur in error messages.

It's great to see that @elliottt has implemented this for the HughesPJ interface - hopefully we'll see better REPLs all around!

david-christiansen commented Jan 26, 2015

For those who are curious as to how these annotations can be useful, I wrote a blog post about how we use them in Idris: http://www.davidchristiansen.dk/2014/09/06/pretty-printing-idris/

The basic idea is that the annotations track semantic information about their document, which can then be rendered differently in different contexts. In Idris, we use it to have semantic coloring at the console (for example, showing type constructors and data constructors in different colors), while richer output contexts such as the Emacs REPL or tryidris.org can make information like docstrings and type annotations for names available in tooltips. It's also possible to do things like normalizing terms that occur in error messages.

It's great to see that @elliottt has implemented this for the HughesPJ interface - hopefully we'll see better REPLs all around!

@dterei

This comment has been minimized.

Show comment
Hide comment
@dterei

dterei Jan 27, 2015

Member

Awesome! Looks really good, please address one comment and then I'm happy to merge.

Member

dterei commented Jan 27, 2015

Awesome! Looks really good, please address one comment and then I'm happy to merge.

@elliottt

This comment has been minimized.

Show comment
Hide comment
@elliottt

elliottt Jan 27, 2015

Contributor

OK, I just pushed a commit that makes the TextDetails field of the NoAnnot constructor strict.

Contributor

elliottt commented Jan 27, 2015

OK, I just pushed a commit that makes the TextDetails field of the NoAnnot constructor strict.

dterei added a commit that referenced this pull request Jan 27, 2015

@dterei dterei merged commit b718d1f into haskell:master Jan 27, 2015

1 check was pending

continuous-integration/travis-ci The Travis CI build is in progress
Details

@elliottt elliottt deleted the elliottt:annotations branch Jan 27, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment