Madlibs DSL for templating text (http://polemic.vmchale.com/madlang)

root / README.md

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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
# Madlang DSL for generating random text

[![Windows build status](https://ci.appveyor.com/api/projects/status/github/vmchale/madlang?svg=true)](https://ci.appveyor.com/project/vmchale/madlang)
[![Build Status](https://travis-ci.org/vmchale/madlang.svg?branch=master)](https://travis-ci.org/vmchale/madlang)
[![Hackage](https://img.shields.io/hackage/v/madlang.svg)](http://hackage.haskell.org/package/madlang)

This is the Madlang DSL for generating text. You specify a template, and Madlang
will create randomized text from the template.

Madlang is an interpreted language, written in Haskell. Madlang can be used as
an EDSL for Haskell or using the command-line interpreter.

Madlang is intended to explore computational creativity and provide an easy
way to get started with generative literature.

## Installation

### Binary Releases

Head over to the [releases
page](https://github.com/vmchale/madlang/releases/latest) and grab a binary for
your platform. 

### Cabal

If you do not see you platform listed, you will have to install from source.
Download [cabal](https://www.haskell.org/cabal/download.html) and
[GHC](https://www.haskell.org/ghc/download.html). Then:

```bash
 $ cabal update
 $ cabal new-install madlang
```

You may need to add `$HOME/.local/bin` to your `PATH`. To do so:

```
 $ echo 'export PATH=$HOME/.local/bin:$PATH' >> $HOME/.bashrc
 $ source $HOME/.bashrc
```

## Tutorial

The smallest program possible in Madlang is simply a return declaration, viz.

```madlang
:return
    1.0 "heads"
    1.0 "tails"
```

The `:return` tells us this that this will be the final value when run, while
the numbers in front of the strings denote relative weights. Save this as
`gambling.mad`, and run

```bash
 $ madlang run gambling.mad
 heads
```

Now let's try something a little more complicated:

```madlang
:define person
    1.0 "me"
    1.0 "you"

:return
    1.0 "The only one of us walking out of this room alive is going to be " person "."
```

A bit more sinister, perhaps. The `:define` statement there declares a new
*identifier*, which we can later reference. Save this as `fate.mad` and run:

```bash
 $ madlang run fate.mad
 The only one of us walking out of this room alive is going to be you.
```

We can also refer to another identifier within a `:define` block.

```madlang
:define coin
    1.0 "heads"
    1.0 "tails"

:define realisticCoin
    1.0 coin
    0.03 "on its side"

:return realisticCoin
```

In addition to identifiers, we can also define *categories*. Categories are just
groups of identifiers. We can define one like so:

```madlang
:define color
    1.0 "yellow"
    1.0 "blue"

:define texture
    1.0 "soft"
    1.0 "scratchy"
    1.0 "dimpled"

:category adjective
    | color
    | texture

:return
    1.0 adjective
```

Then, when we can `adjective`, it will pick one of "yellow", "blue",…
"dimpled" with equal probability.

Finally, one of the most powerful features of `madlang` is the ability to
include libraries in a file. Open the following and save it as `gambling.mad`:

```madlang
:library

:define coin
    1.0 "heads"
    1.0 "tails"
```

Then, open the following and save it in the same directory as
`realistic-gambling.mad`:

```madlang
:include gambling.mad

:define realisticGambling
    1.0 gambling-coin
    0.03 "on its side"

:return
    1.0 realisticGambling
```

Then run it with:

```bash
 $ madlang run realistic-gambling.mad
```

`madlang` comes with several libraries prepackaged. You can install
them for the current user with:

```bash
 $ madlang install
```

Try this out:

```
:include colors.mad

:define weirdDog
    1.0 colors-color "dog"

:return
    1.0 "On my walk today I saw a " weirdDog "."
```

### EDSL

You can use Madlang as a Haskell EDSL, generating values of type `RandTok`.
This can be done a couple ways. One is to use the file embedder:

```haskell
randomText :: RandTok
randomText = $(madFile "mad-src/some-bot.mad")
```

While the other is to use the `madlang` quasi-quoter:

```haskell
randomText :: RandTok
randomText = [madlang|
:include adjectives.mad

:return
    1.0 "I am feeling very " adjectives-adjective " today."
|]
```

You can then transform this into a random text file with:

```haskell
generateText :: IO Text
generateText = run randomText
```

### Examples

There is a Shakespearean insult generator available to test out at [my
site](http://blog.vmchale.com/madlang). For a look at using Madlang as an EDSL,
check out my [recursion scheme
generator](https://github.com/vmchale/recursion-schemata)

## Tooling

### Vim

There is a vim plugin available [here](https://github.com/vmchale/madlang-vim).

### Project Templates

There is a project template bundled with
[pi](https://github.com/vmchale/project-init), which you can install with

```bash
 $ curl -LSfs https://japaric.github.io/trust/install.sh | sh -s -- --git vmchale/project-init
```

and invoke with

```bash
 $ pi new madlang story
```

There is also a templated project
[here](https://github.com/vmchale/madlang-miso) that can be invoked via

```bash
pi git vmchale/https://github.com/vmchale/madlang-miso story
```

### Manpages

You can view documentation for `madlang` on Linux, Mac, or BSD by typing:

```bash
 $ man madlang
```

## Contributions

### Guide

Contributions, bug reports, and feature requests are emphatically welcome.
Please see the `CONTRIBUTING.md` guide for more specific details.

### Release Naming

Releases are named using the `releases.mad` file found
[here](https://hub.darcs.net/vmchale/madlang-releases). You will need to install
the standard libraries using

```bash
 $ madlang install
```

before running

```bash
 $ just name
```