https://github.com/vmchale/madlang
Madlang is a language for generative literature
https://github.com/vmchale/madlang
generative-art generative-literature haskell language
Last synced: 9 months ago
JSON representation
Madlang is a language for generative literature
- Host: GitHub
- URL: https://github.com/vmchale/madlang
- Owner: vmchale
- License: bsd-3-clause
- Created: 2017-01-08T02:24:28.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2018-07-10T07:08:22.000Z (over 7 years ago)
- Last Synced: 2025-04-04T08:01:37.969Z (10 months ago)
- Topics: generative-art, generative-literature, haskell, language
- Language: Haskell
- Homepage:
- Size: 2.23 MB
- Stars: 51
- Watchers: 4
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Madlang DSL for generating random text
[](https://ci.appveyor.com/project/vmchale/madlang)
[](https://travis-ci.org/vmchale/madlang)
[](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
```