Skip to content

Commit 6c6981a

Browse files
committed
README: added an explanation of new interpolation blocks handling
1 parent 2d67b73 commit 6c6981a

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

README.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,27 @@ main = do
126126
| s | Replaces line breaks with spaces | qms, qns |
127127
```
128128

129+
## About interpolation blocks
130+
131+
Along with all specifics of any of the quoters (which supports interpolation
132+
blocks, which has `m` in their names) interpolation blocks work different. When
133+
curly bracket (`{`) opens everything inside until it closes (by `}`) is parsed
134+
as bare as possible to be given to
135+
[haskell-src-meta](http://hackage.haskell.org/package/haskell-src-meta)
136+
without any modifications, to be parsed as bare haskell code.
137+
138+
But you might need use curly brackets inside an interpolation block. I don't
139+
think it would be a good idea, because complicated logic there may cause code
140+
readability issues, but if you're sure you need it then you get it. You just
141+
need to escape closing bracket to prevent interpolation block from closing, like
142+
this: `\}`. I know it could parsed and opening curly brackets inside could be
143+
used to prevent closing by next `}` symbol, but I chose do it this way to
144+
prevent any unobvious tricky behavior (e.g. consider `}` appear inside a string,
145+
`[qm|foo {'x':'}':"y"} bar|]`, how that should be handled?). So I've decided to
146+
not make parser to be very smart, just to follow simple logic. You just need to
147+
explicitly escape every `}` symbol inside that isn't closer of an interpolation
148+
block (you could find an example below).
149+
129150
## About escaping
130151

131152
### Symbols that can be escaped
@@ -149,6 +170,10 @@ Backslash is used for escaping these:
149170
this list it is interpreted just as backslash symbol, keep in mind
150171
that `\\\` (without any of symbols from this list after)
151172
and `\\\\` are producing same result - `\\`)
173+
7. `\}` - closing bracket inside an interpolation block
174+
(it works **only** inside opened interpolation block)
175+
to prevent interpolation block from closing
176+
(useful to escape records modification)
152177

153178
### Escaping examples
154179

@@ -221,6 +246,17 @@ If you don't need interpolation - just replace `m` to `n` in quasi-quoter name:
221246
[qnb| foo {1+2} |] -- Result: "foo {1+2}"
222247
```
223248

249+
That's how you update some record inside interpolation block
250+
(you need to escape closing bracket):
251+
252+
```haskell
253+
{-# LANGUAGE QuasiQuotes #-}
254+
import Text.InterpolatedString.QM (qm)
255+
data Foo = Foo {bar :: Int, baz :: Int} deriving Show
256+
main = let foo = Foo 10 20 in putStrLn [qm| Foo is: {foo {baz = 30\}} |]
257+
-- Foo is: Foo {bar = 10, baz = 30}
258+
```
259+
224260
## Author
225261

226262
[Viacheslav Lotsmanov](https://github.com/unclechu)

0 commit comments

Comments
 (0)