Madlang DSL for generating random text

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 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 and
GHC. Then:

 $ 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.

: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

 $ madlang run gambling.mad
 heads

Now let’s try something a little more complicated:

: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:

 $ 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.

: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:

: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:

:library
:define coin
    1.0 "heads"
    1.0 "tails"

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

:include gambling.mad
:define realisticGambling
    1.0 gambling-coin
    0.03 "on its side"
:return
    1.0 realisticGambling

Then run it with:

 $ madlang run realistic-gambling.mad

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

 $ 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:

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

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

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:

generateText :: IO Text
generateText = run randomText

Examples

There is a Shakespearean insult generator available to test out at my
site. For a look at using Madlang as an EDSL,
check out my recursion scheme
generator

Tooling

Vim

There is a vim plugin available here.

Project Templates

There is a project template bundled with
pi, which you can install with

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

and invoke with

 $ pi new madlang story

There is also a templated project
here that can be invoked via

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

Manpages

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

 $ 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. You will need to install
the standard libraries using

 $ madlang install

before running

 $ just name