snippet-0.1.0.3: README.md

# Snippet

[![Release](https://codeberg.org/pbrisbin/snippet/badges/release.svg)](https://codeberg.org/pbrisbin/snippet/releases)
[![Hackage](https://img.shields.io/hackage/v/snippet.svg?style=flat)](https://hackage.haskell.org/package/snippet)
[![Stackage LTS](http://stackage.org/package/snippet/badge/lts)](http://stackage.org/lts/package/snippet)
[![Stackage Nightly](http://stackage.org/package/snippet/badge/nightly)](http://stackage.org/nightly/package/snippet)
[![CI](https://codeberg.org/pbrisbin/snippet/badges/workflows/ci.yml/badge.svg)](https://codeberg.org/pbrisbin/snippet/actions?workflows=ci.yml)

Pretty-print regions within source code files.

## Usage

<!--

```haskell
module Main (main) where
import Text.Markdown.Unlit ()
```

-->

```haskell
import Prelude

import Data.Foldable (traverse_)
import Prettyprinter (reAnnotate)
import Prettyprinter.Render.Terminal (putDoc)
import Snippet
import Snippet.Pretty

main :: IO ()
main = do
  let
    region = Region
      { startLine = 32
      , startColumn = Just 8
      , endLine = Just 64
      , endColumn = Nothing
      , message = Nothing
      , subRegion =
          Just
            Region
              { startLine = 34
              , startColumn = Just 5
              , endLine = Just 59
              , endColumn = Nothing
              , message = Just "Denotes a region in the snippet"
              , subRegion =
                  Just
                    Region
                      { startLine = 45
                      , startColumn = Just 27
                      , endLine = Nothing
                      , endColumn = Just 31
                      , message = Just "Would default to startLine"
                      , subRegion = Nothing
                      }
              }
      }

  -- Returns Nothing if file is missing/empty or region is invalid
  mSnippet <- snippetFromFile region "README.md"

  traverse_ (putDoc . reAnnotate annToAnsi . prettySnippet) mSnippet
```

The above `Region` focuses one of the `Just` constructors, within the `region`
binding, within the body of the `do` block. Rendering it with the default
`annToAnsi` looks like:

![](./example.png)

Supplying an alternative `annToAnsi` function is how you can adjust colors.

## Limitations

Drawing these regions is not an easy problem. Therefore, there are some
limitations to the kind of `Region` values we support:

1. One top-level region per snippet,
1. A region may only have zero or one sub-region,
1. A sub-region must be contained within its parent, and
1. A sub-region cannot share start or end lines or columns with its parent

One notable consequence is that a one-line region cannot contain sub-regions.

## License

This package is licensed AGPLv3. See [COPYING](./COPYING).