References

Forks can also be context-aware by referencing each other. First, label a fork by opening it with an id followed by a colon.

I have {thing: (some things), (nothing)} to say

After executing a fork, BML remembers which branch it took. Future forks can depend on this earlier result by opening the block with the id again, this time prefixed with an @ sign. Now instead of listing choices, you can declare mappings from the original choice result to any other text.

I have {thing: (some things), (nothing)} to say

and I am saying {@thing: 0 -> (them), 1 -> (it)}.

output:

The numbers to the left of the arrows are indexes referring to the branch taken in the referred fork. Here, the 0 branch will be taken if the thing fork took its first branch. Similarly, the 1 branch will be taken if the referred fork took its second branch.

ℹ️ Note

References use 0-based indexing. This is likely to be a bit confusing for non-programmers, but it is necessary to harmonize with the Javascript code that can be embedded in documents. It may be helpful to think of 0-based indexes as offsets from the starting position.

Mappings can be many-to-one—that is, multiple branch indexes can be associated with a single result. Where you would write a single branch index, simply write a comma-separated list of them.

I have {thing: (some things), (something), (nothing)} to say
and I am saying {@thing: 0 -> (them), 1, 2 -> (it)}.

output:

You can also add fallback options that apply to any other choice not mapped. Simply include a branch, or multiple, without any associated index. In this way we can simplify the above code as:

I have {thing: (some things), (something), (nothing)} to say
and I am saying {@thing: 0 -> (them), (it)}.

output:

Fallbacks are necessary when referencing forks that may not always execute, like nested forks.

{
    (I have {thing: (something), (nothing)} to say),
    (John Cage wrote about Silence)
}
{@thing:
    0 -> (and I am not saying it),
    1 -> (and I am saying it),
    (and in his "Lecture on Nothing" he wrote this)}

output:

We can also ask BML to repeat the referenced fork result verbatim using a bare reference without any mappings. This is especially useful for copying nested fork results.

{choice:
    (I have {(something), (nothing)} to say),
    (John Cage wrote about Silence)
}
{@choice}

output:

Finally, we can ask BML to silently execute forks without inserting their results by prefixing their id with a # sign. This is great for complex documents where we might want to separate out the definition of a complex fork from its use where it might interfere with the legibility of a sentence.

{#thing: (some things), (something), (nothing)}
I have {@thing} to say
and I am saying {@thing: 0 -> (them), (it)}.

output:

🚀 Try it!

Try writing some references in the sandbox!

One common use for references is handling varying plurality. Write a named fork that can be either singular or plural, then use a reference to describe it in a grammatically correct way. (e.g. “I bought 1/2 apple/s”)
Another potential use is with gendered pronouns where a described person may be of varying gender. Write a named fork with several names, and use a reference to write corresponding pronouns for the selected name. Try using a fallback option for gender neutral names.
Try using bare references ({@test}) to copy the result of a nested fork.
Try using silent forks ({#test: ...} {@test}) to separate the declaration and use of a fork.