summaryrefslogtreecommitdiff
path: root/README.md
blob: d1c2c6aae2644ede121fb7ec3f39d26c8acc1363 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# Text.InterpolatedString.QQ2

[![Build Status](https://api.travis-ci.org/isovector/interpolatedstring-qq2.svg?branch=master)](https://travis-ci.org/isovector/interpolatedstring-qq2)
[![Hackage](https://img.shields.io/hackage/v/interpolatedstring-qq2.svg?logo=haskell)](https://hackage.haskell.org/package/interpolatedstring-qq2)

QuasiQuoter for QQ2-style multi-line interpolated strings with "q", "qq" and
"qc" support.

## Description

QuasiQuoter for interpolated strings using Perl 6 syntax.

The q form does one thing and does it well: It contains a multi-line string with
no interpolation at all:

```haskell
{-# LANGUAGE QuasiQuotes, ExtendedDefaultRules #-}
import Text.InterpolatedString.QQ2 (q)
foo :: String -- Text, ByteString etc also works
foo = [q|

Well here is a
    multi-line string!

|]
```

Any instance of the IsString class is permitted.

The qc form interpolates curly braces: expressions inside #{} will be
directly interpolated if it's a Char, String, Text or ByteString, or
it will have show called if it is not.

Escaping of '{' is done with backslash.

For interpolating numeric expressions without an explicit type signature,
use the ExtendedDefaultRules lanuage pragma, as shown below:

```haskell
{-# LANGUAGE QuasiQuotes, ExtendedDefaultRules #-}
import Text.InterpolatedString.QQ2 (qc)
bar :: String
bar = [qc| Well #{"hello" ++ " there"} #{6 * 7} |]
```

bar will have the value " Well hello there 42 ".

If you want control over how show works on your types, define a custom
ShowQ instance:

For example, this instance allows you to display interpolated lists of strings as
a sequence of words, removing those pesky brackets, quotes, and escape sequences.

```haskell
{-# LANGUAGE FlexibleInstances #-}
import Text.InterpolatedString.QQ2 (qc, ShowQ(..))
instance ShowQ [String] where
    showQ = unwords
```

qc permits output to any types with both IsString and Monoid
instances.

```haskell
{-# LANGUAGE QuasiQuotes, OverloadedStrings #-}
import Text.InterpolatedString.QQ2 (qc)
import Data.Text (Text)
import Data.ByteString.Char8 (ByteString)
qux :: ByteString
qux = [qc| This will convert #{"Text" :: Text} to #{"ByteString" :: ByteString} |]
```