Custom Javascript

Between choices, nested choices, references, and modes, BML offers deep chance operation capabilities out of the box. For more advanced use-cases, BML allows you to define custom Javascript functions which act on your document through choices and modes.

ℹ️ Note

If you aren’t a comfortable Javascript programmer and you don’t immediately need these features, consider skipping this page.

eval blocks

Like modes, custom Javascript code is defined at the beginning of a document in an eval block. Eval blocks are evaluated as Javascript through the Function constructor. Functions are exposed to BML through a special provide({}) function.

eval {
    provide({
        test: (match, inlineCall) => {
            return 'Hello, world!'
        }
    });
}
{call test}
output:

Functions should have the signature:

(match: RegExpMatchArray | null,
 inlineCall: { input: string, index: number } | null) -> string

Custom functions are invoked using the call command from inline or mode choices. When called from a mode, the regexp match is passed to match; when called inline the complete document and index of the call command are passed to inlineCall.

eval {
    function preview(str) {
        return JSON.stringify(str.substring(0, 10) + '...');
    }

    provide({
        test: (match, inlineCall) => {
           if (match) {
               return `\
match found: ${JSON.stringify(match)}
match.input: ${preview(match.input)}
match.index: ${match.index}`;
           } else {
               return `\
inlineCall found:
inlineCall.input: ${preview(inlineCall.input)}
inlineCall.index: ${inlineCall.index}`;
           }
        }
    });
}
mode example {
    (foo) -> {call test}
}
{use example}
foo
------
{call test}
output:

🚀 Try it!

Try writing a custom function and mode which sometimes capitalizes the first letter of words starting with the letter A.