flowdown

lightweight markup language for conversation design

flowdown is a minimal markup language for writing conversations, specifically for the voiceflow platform. It can be thought of a 'voiceflow programming language' of sorts.

flowdown is designed to be both easy to read and write. Here is an example conversation:

Hello! Welcome to Flowdown Pizzaria, what can I do for you?
[capture $mode]
* $mode == "order pizza": -> @order
* $mode == "menu": [image https://flowdownpizza/menu.png]

@ order

    What type of pizza would you like?
    [capture $pizzaType]

    What size of pizza?
    [capture $pizzaSize]

    How would you like to recieve your pizza?
    [capture $pizzaMethod]
    * $pizzaMethod == "delivery": -> @delivery
    * $pizzaMethod == "take out": -> @take out

    Thank you for choosing Flowdown Pizzaria!
    -> @survey

@ delivery

    Can I get an address
    [capture $address]

    [set $price "0"]
    [set $deliveryTime "0"]
    [code calculatePrice.js]
    [code computeDeliveryRoute.js]

    Your final price is {$price} and you will get your pizza in about {$deliveryTime}! 

@ take out

    When would you like to pick up your food?
    [capture $pickupTime]

    [set $price "0"]
    [code calculatePrice.js]

    Your final price is {$price}.

@ survey

    Would you like to complete an optional survey?
    [capture $survey]
    * $survey == "yes": -> start survey
    * $survey == "no": -> end survey

    = start survey

        How would you rate today's experience?
        [capture $rating]

        Is there any feedback you would like to give?
        [capture $feedback]

    = end survey

        Thank you!

SETTING UP FOR DEVELOPMENT

First install the git hooks and run other development environment setup.

$ just devsetup

Then to run

$ just run

To read the documentation / language specification locally:

$ just book

EDITOR TOOLS

flowdown comes bundled with a vim plugin. To install (for vim-plug users), simply add the line

Plug 'MrPicklePinosaur/flowdown', { 'rtp': 'tools/vim' }

TODO / PLANNED FEATURES

• vim syntax highlight
• vscode plugin
• cli
• support for external files (audio, code)
• project configuration toml
• linker
• build binary
• format voiceflow blocks nicely

RESOURCES/RESEARCH

some resources that were used in the making of this project.

• md parser in OCaml
• peg grammar for md
• write a parser in rust blog
• pest peg grammar for md
• learn to build a parser for fun and profit

alternatives that were considered

• nom combinator parsing: too much work (i think)
• lalrpop: not used since md is not a regular language
• gnu bison: rather use a rust based tool