Monke reference

1. On the Generator page, open Examples in the bar above the rules and choose toki pona example to load a small working grammar.
2. The words appear by themselves: 50 of them. Press New words for a fresh set, or change the word count for more or fewer.
3. Find the rule named Vowel and add a terminal such as y with + Terminal. To add several at once, type them separated by spaces in Add several and press Enter. The new vowels show up in the words.
4. Made a mistake? Use your browser's Back button to undo the last edit.

Or open the small grammar in the next section with its Try it link.

Rules

A grammar is a list of named rules. A name starts with a letter or _ and continues with letters, digits or _, so V, Syllable and coda_2 all work. Names are case-sensitive and must be unique.

• Terminal rules (+ Terminal rule, named in blue) hold plain text, usually the sounds of your language. Each terminal is used as written, without quotes: a, ch and 好 are all fine.
• Pattern rules (+ Pattern rule, named in violet) hold patterns that combine other rules and text. A rule needs at least one pattern. Only pattern rules can have rewrites and exclusions.

Whenever a rule is used, Monke picks one of its terminals or patterns at random.

The start rule

Choose the Start rule in the bar above the rules; the rule's header then says start rule. Every word is generated from it, and it uses other rules by name. Rules the start rule never reaches don't affect the words, but they are still checked for errors.

Patterns

A pattern describes what a rule produces. Text goes in single quotes, rule names stand alone, and a dot joins parts in order. This rule makes a consonant, a vowel and sometimes an n:

C.V.('n')

Here is a complete grammar using it. It makes words such as ka, sonmi and tulipen.

Status line and errors

• Grammar has N possible branches counts the paths through the grammar, not distinct words: two choices giving the same text count twice, and rewrites and exclusions are not taken into account.
• Grammar has at least one cycle: A > B > A means rules refer back to themselves, so branches can't be counted. Generation still runs, but if the cycle has no way out it fails with an error.
• Invalid grammar: … names the problem and the rule, and marks the input at fault as invalid. Common causes: an unknown rule name, an invalid rule name, two rules with the same name, a rule with no patterns, unbalanced brackets or quotes, a missing dot between two parts, or an optional probability above 1.
• Exclusion rules are too restrictive appears when generating if a rule's exclusions rejected 100 outputs in a row.
• Rewrites of rule … did not settle appears when generating with repeated rewrites if they keep changing the output (see Rewrites).

Patterns, rewrites and exclusions share one syntax. Examples use the rules C and V from the grammar above.

Precedence and spacing

• The dot binds tighter than the slash: 'a'.'b' / 'c' gives ab or c. Use a group to choose inside a sequence: 'a'.['b' / 'c'] gives ab or ac.
• An optional holds one alternative. To make a choice optional, group it: (['n' / 's']).
• Spaces and line breaks outside quotes are ignored. Inside quotes they are part of the text.
• An empty pattern or '' produces nothing, which is a simple way to add an "empty" option to a rule.

Weights are ignored until you turn on Weights in the bar above the rules. Until then every alternative is equally likely and every optional is present half of the time.

Once enabled, each terminal and pattern row gets a weight field. Weights are relative: a weight of 2 is picked twice as often as a weight of 1. A weight of 0 is never picked, which is handy for switching a pattern off temporarily.

Inside a pattern, put *N after an alternative. Alternatives without one weigh 1, so these are equivalent:

'a'*2 / 'e'
'a' / 'e'*0.5

An optional is present half of the time by default. ('n'*0.2) makes it present 20% of the time. The probability must be between 0 and 1; a larger value is an error.

Quantifiers like {1:3} always pick each count with the same probability. To favour some lengths, use weighted alternatives instead, such as Syllable*3 / Syllable.Syllable.

Fewer repeats in a word

A repeat factor lowers the chance of picking the same thing again in a word. With weights on, every terminal and pattern row has a Repeat field next to its Weight (1 by default, no effect). A rule's rows are the alternatives of its choice: each time a row was already picked in the current word, its weight is multiplied by the factor. With 0.5 the second pick of the row is half as likely as the first, the third a quarter, and so on.

Inside a pattern, put ~F after an alternative, after its weight if it has one:'a'*2~0.5 / 'e'. With ['a'~0.2 / 'e']{3} a second a is five times less likely than the first. The count is kept per place in the grammar: the same alternative written in two patterns, or two rules, has two counts.

• Counts start again for every word. When an exclusion rejects a rule's output and it is generated again, what the rejected attempt picked no longer counts.
• A factor of 0 never blocks the first use: it only rules out repeats.
• Factors only change probabilities. Generate all and the number of possible branches are the same as without them, and with weights off they are ignored.

Rewrites change a rule's output after it is generated, like sound changes. Turn on Rewrites in a pattern rule's header to show and enable its rewrites; turned off, they are kept but ignored.

A rewrite has a match and a replacement, both written in pattern syntax.

How rewrites are applied

• Rewrites run in list order. Each one works on the output of the previous one.
• Each rewrite scans the word from left to right. After a replacement, scanning continues after the inserted text, so new text is never rewritten by the same rewrite.
• By default the list runs once, so an earlier rewrite never sees what a later one produced. Turn on Repeat rewrites in the bar above the rules to run the whole list again and again until a pass leaves the output unchanged. If the output still changes after 32 passes, for example because two rewrites undo each other, or grows past 10000 characters because a rewrite keeps adding text, generation stops with Rewrites of rule … did not settle. A replacement with a random choice can also keep changing the output.
• A match must contain at least one character; parts that can be empty, like optionals, only count together with something else.
• If several matches start at the same place, the first one found wins: alternatives are tried in the order written, optionals are tried present first, and quantifiers try the fewest repetitions first.
• A rule name in a match matches anything that rule's patterns can produce, regardless of weights. Its own rewrites and exclusions are not considered.
• Rewrites apply to the rule they belong to, each time it is used. Put a rewrite on the start rule to work on whole words.

Back-references

In a replacement, #n# inserts part n of the match, counting from 0. When the match is a sequence, each item joined by a dot is one part, even if it is a rule or group producing several letters. A match that is a single quoted text is part #0#.

A reference to a part the match can't have, such as #2# for 'a'.'b', is an error. When the number of parts depends on what matched, a missing part inserts nothing.

In a match, and in an exclusion, #n# matches exactly the text that part n matched, so C.#0# finds pp or tt but not pt. Parts are counted the same way, and a back-reference must come after the part it refers to: #0#.C is an error. The parts it can refer to are those of the outer sequence, even from inside a group: in C.V.[#0# / 'h'], the last part is the first consonant again or an h.

Examples

• Rewrite: 'n'.['p' / 'b' / 'm'] →becomes 'm'.#1#

  anpa →becomes ampa

  Assimilation: n becomes m before p, b or m. #1# keeps the consonant that matched.

• Rewrite: 'k'.'s' →becomes #1#.#0#

  aksa →becomes aska

  Metathesis: swap the two matched parts.

• Rewrite: 'h' →becomes ''

  ahah →becomes aa

  Deletion: replace with an empty atom.

• Rewrite: 'a' →becomes 'aa'

  ba →becomes baa

  Inserted text is not rewritten again, so this does not loop. With Repeat rewrites on, every pass adds an a, so generation fails.

• Rewrite 1: 's' →becomes 'z'

  Rewrite 2: 'z' →becomes 'r'

  sasa →becomes rara

  The second rewrite sees the output of the first.

• With rule P = 'a'.'b'

  Rewrite: 'x'.P.'c' →becomes #2#.#1#.#0#

  xabc →becomes cabx

  P counts as one part, whatever it contains: #0# is x, #1# is ab, #2# is c.

• With rule C = p / t / k / s / m / n / l

  Rewrite: C.#0# →becomes #0#

  appatta →becomes apata

  Degemination: in a match, #0# stands for the same text part 0 matched, so this finds doubled consonants.

• Rewrite: ^.'ŋ' →becomes 'n'

  ŋaŋa →becomes naŋa

  ^ matches only at the start, so only the first ŋ changes.

• Rewrite: 'h'.$ →becomes ''

  hah →becomes ha

  $ matches only at the end, so only the last h is dropped.

• With rule V = a / e / i / o / u

  Rewrite: ^.'ŋ'.V →becomes 'n'.#2#

  ŋoŋa →becomes noŋa

  A boundary is a part too, an empty one: ^ is #0#, ŋ is #1#, and the vowel is #2#.

• Rewrite 1: 'n'.'p' →becomes 'm'.#1#

  Rewrite 2: 'e' →becomes ''

  anepa →becomes anpa

  Rewrite 2 brings n and p together after rewrite 1 has already run, so the np stays.

• With Repeat rewrites on

  Rewrite 1: 'n'.'p' →becomes 'm'.#1#

  Rewrite 2: 'e' →becomes ''

  anepa →becomes ampa

  With Repeat rewrites on, a second pass runs rewrite 1 again on the new np. A third pass changes nothing, so it stops.

Exclusions reject outputs you don't want. Turn on Exclusions in a pattern rule's header to show and enable them; turned off, they are kept but ignored.

• An output is rejected if an exclusion matches anywhere inside it, not only if the whole output matches.
• All alternatives of a choice and all outputs of a referenced rule are checked, so V.V rejects any two vowels in a row.
• #n# matches the same text as part n of the exclusion, so C.#0# rejects any doubled consonant. Parts are counted as in rewrite back-references.
• Exclusions check the output after the rule's rewrites.
• A rejected output is generated again, only for that rule. After 100 rejections in a row, generation stops with Exclusion rules are too restrictive.

To limit an exclusion to the start or end of a word, use word boundaries. To limit it to another part of a word, put that part in its own rule and add the exclusion there. See the recipes below.

In a rewrite match or an exclusion, ^ matches the start and $ the end. They match a position, not a letter, so 'h'.$ matches an h only when it is last.

• The start and end are those of the output being checked: the output of the rule the rewrite or exclusion belongs to. On the start rule, that is the whole word. On a Syllable rule, ^ is the start of each syllable.
• With several rewrites, the edges are those of the output as it is when that rewrite runs.
• A boundary counts as a part for back-references, an empty one: in ^.'ŋ'.V, #0# is empty, #1# is ŋ and #2# is the vowel.
• A boundary alone matches nothing, since a match must contain at least one character.
• Boundaries can't be generated, so they are an error in a rule's patterns and in rewrite replacements. In terminal rules, ^ and $ are plain text.

Features keep sounds consistent across a word, like vowel harmony: once a word picks front vowels, every vowel in it is front. It takes four steps: declare a feature and its values, say which rules it tags, put values on their rows, then pick or filter.

1. Declaring features

Use + Feature in the Phonological features panel above the rules, name it, and add its values with + value, such as harmony with front and back. Feature and value names follow the rules for rule names: letters, digits and underscores, not starting with a digit. A value name can be used only once in the grammar, even across features, so a value on its own says which feature it belongs to. With Weights on, each value has a weight that sets how often a rule chooses it.

Deleting a feature or a value also removes it from every rule and row that used it. Browser Back undoes it. Filters written in patterns are text, so renaming or deleting does not change them.

2. Rule features

In a rule's header, the + after Tags by adds a feature that classifies that rule's rows: for a Vowel rule, harmony. Only the rules that list a feature are concerned by it:

• In a rule that lists the feature, every row has a definite status: it carries one or more of its values, or none of them. A row without a value is none of the values, like a neutral vowel that is neither front nor back.
• A rule that does not list the feature is only structure, like a Syllable rule. Filters and choices pass through it to the rules it uses.

3. Giving values to rows

Once a rule lists a feature, each of its terminal and pattern rows has a Feature values button, a tag icon, with a checkbox for each value of the rule's features. The row then shows its values in brackets, like [front]. A row can carry values of several features, such as [front, flat], and several values of one feature, counting as each of them. Removing a feature from a rule removes its values from that rule's rows.

4. Choosing a value

The + after Picks in a rule's header adds a feature the rule picks. Each time the rule is used, it picks one value of each feature it picks, before generating anything. In everything below it, its own rows and every rule it reaches, rows carrying another value of that feature are removed. Rows with none of the values stay: that is how a neutral vowel goes with both sides. The weights of what is left are shared out as usual.

• Pick on the start rule to keep a whole word consistent, or on a Syllable rule to pick again in each syllable.
• A rule below may pick the same feature again: its own pick applies to everything under it instead.
• Rewrites and exclusions work on the rule's output. Rule names in a rewrite replacement are generated with the rule's chosen values. When an exclusion rejects an output, the rule picks again.

5. Filters

A filter after a rule name narrows that rule and everything it reaches, in every rule listing the feature, with or without a choice:

• Vowel<front> means only front: rows without front are removed, rows with none of the values included.
• Vowel<!back> means anything but back: only rows carrying back are removed, so rows with none of the values stay.
• Several values of one feature allow any of them: Vowel<front, back>. Values of different features must all hold: Vowel<front, !round>.
• Filters work in patterns, rewrite matches and exclusions, and reach through rules that do not list the feature: Syllable<front> gives syllables with front vowels.

Filters and choices add up: what reaches a rule must pass every filter above it and match the chosen value. A filter only narrows, and a Choose below it picks only among the values the filters allow, so under <front> it always picks front and rows with none of the values stay out. Only a Choose replaces an earlier choice of the same feature.

With this Vowel rule, where e is front, o is back and a carries no value, and Syllable = 't'.Vowel, a Word pattern gives:

Several features

A rule can tag by and pick several features, and rows can carry values of each. Here a word is front or back and round or flat; y is front and round, and flat words are twice as likely.

Branching on a choice

Values on pattern rows pick between whole structures. Word chooses a class, noun twice as often as verb; nouns end in n or nothing, verbs in la or nothing.

6. Errors and warnings

Problems are found before generating and shown under the input at fault. With the vowel harmony grammar above, these Word patterns give:

• Consonant.Vowel<front>: No row of rule 'Vowel' can be used when harmony is back and must be front
• Consonant.Vowel<frnt>: Unknown feature value 'frnt' in the filter on 'Vowel'
• Consonant<front>.Vowel: The filter front on 'Consonant' has no effect: no rule it reaches is classified by harmony

Also errors: a rule left with no row at some spot, a Choose the filters above leave no value for, a row carrying a value of a feature its rule does not list, and invalid or duplicate names. Only warnings, listed under the word count: a feature or value without a name yet (ignored until it gets one), a feature nothing uses, a rule listing a feature none of its rows carries, a Choose no rule below it lists, and a rule reached where its feature is neither chosen nor filtered, which keeps all its rows. For example, Consonant.Vowel without choosing harmony gives: Feature 'harmony' is neither chosen nor filtered when rule 'Vowel' is used in 'Word'; all its rows are kept

Generate all lists the words for every value each choice can take. The number of possible branches counts each chosen value separately, so a word made only of rows without values is counted once per value.

Generator options

• The Count field sets how many words to make, from 1 to 10000.
• Paragraph and List choose between running text and one word per line. Copy copies the words in the current layout.
• Repeat rewrites, in the bar above the rules, runs each rule's rewrite list until it stops changing the output, instead of once (see Rewrites). It is saved in share links.
• The View settings menu (the gear next to Words) holds three options. Filter duplicates hides repeated words and shows how many are unique. Serif font switches the words and your patterns to a serif font, which makes some IPA characters easier to read. Always show reorder buttons is described under Reordering. The menu stays open while you toggle them; press Escape to close it.

Seed and automatic updates

The words are decided entirely by the Seed field, the grammar and the word count: the same three always give the same words, in the same order. The seed is saved in share links, so others see your exact list. Every grammar always has a seed; any text works. New words picks a new random seed and so a new set of words. For example, the first grammar above with the seed monke starts with meku, tin, pun, matunmon, mantun.

The words update by themselves, a quarter of a second after each edit that leaves the grammar valid, and straight away when you change the seed or word count. An edit therefore shows how the same draws change rather than a new random list. Screen readers are not told about these updates, to avoid talking over your typing; New words and Generate all announce how many words they made. Each New words press is an edit like any other, so Back restores the previous words. If a redraw takes more than a moment, the old words dim and the button shows a spinner until the new ones are ready.

Generate all

Generate all lists every distinct word the start rule can make, sorted, instead of random draws: useful to export a full syllable inventory. Rewrites and exclusions apply exactly as when generating, and weights only matter where they are zero. It stops after 10,000 words and says the list is truncated. It is unavailable when the grammar has a cycle (the list would be endless) or more than 1,000,000 branches; the reason is shown under the buttons.

For example, with terminals C = k, t, V = a, i and the root C.V.('n'), with the rewrite 'kin' → 'kim' and the exclusion 'ti', Generate all lists:

• ka
• kan
• ki
• kim
• ta
• tan

Errors and hints

When the grammar is invalid, the error appears under the input at fault (and in the generator panel), and that input is marked invalid for screen readers. Parse errors give the character position, counting from 1. Two common mistakes get a hint: a rule name one or two letters away from an existing one suggests it, and two terms side by side suggest the missing .. With the first grammar's rules, a Word pattern of:

• Syllable.Syllabel reports Unknown rule 'Syllabel' (rule : 'Word'). Did you mean `Syllable`?
• C.V 'n' reports Missing `.` between `V` and `'n'`? (rule : 'Word') at character 5
• C.[V / 'a' reports Expected ']' at the end of a group (rule : 'Word') at character 11

Share links

The whole configuration (rules, start rule, language name, weights, repeated rewrites, serif settings and seed) is encoded in the page address and updated as you edit. Share link in the bar above the rules copies it. Anyone opening it gets your grammar; nothing is stored on a server. Links made by older versions of Monke still open.

Files

Export, then Monke file, downloads the configuration as a .monke file named after the language. Import, then Monke file, loads one, including files exported by older versions. Importing replaces the current grammar. On small screens both are in one Files menu.

Examples loads the toki pona grammars or any recipe from this reference, and New starts an empty grammar. Both replace the current grammar.

Undo and redo

Every edit is a step in your browser history: Back undoes, Forward redoes. A burst of typing counts as one step. Loading an example, importing a file and choosing New are steps too.

Rules, terminals, patterns, rewrites and exclusions can be reordered. Order matters for rewrites; for the rest it only changes how things look.

• Drag an item by its grip handle, the three dots (on touch screens, press and hold first).
• Keyboard drag: focus the handle, press Space or Enter to pick the item up, move it with the arrow keys, then press Space or Enter to drop it, or Escape to cancel.
• Move buttons: rules always show up and down buttons (on small screens they are in the More actions menu at the end of the rule's header). Terminals, patterns and rewrites are rows with up and down buttons, and exclusions have left and right buttons; these appear when the item has keyboard focus. Turn on Always show reorder buttons in the View settings menu to keep them visible. This setting stays in your browser and is not part of share links.

Each rule header also has buttons to collapse the rule, duplicate it and delete it. A collapsed terminal rule lists its terminals in the header. On the Generator page, a Skip to generator link at the start jumps past the rules.

Each recipe is a complete grammar. Try it opens it in a new tab, so your current grammar is untouched.

If you know Awkwords, most ideas carry over. Awkwords subpatterns become rules and the main pattern becomes the root rule. The main differences: Monke names are not limited to one capital letter, parts are joined with dots, and all literal text is quoted.

Filters versus exclusions

An Awkwords filter, as in [VV]^aa, applies only to the fragment written just before the ^: a bracket, a subpattern letter or a run of letters. If that fragment generates exactly the filter text, the whole word is dropped, so you may get fewer words than you asked for. A Monke exclusion belongs to a rule: when the rule's output contains a match, that rule is generated again. When the filtered fragment is always generated, the words you get follow the same odds as the words Awkwords keeps. Inside an alternative or an optional they don't: Awkwords' dropped words make that alternative rarer, while a Monke retry keeps its odds.

To translate a filter, put the filtered fragment in its own rule and add the filter text as an exclusion of that rule. Containing and being equal are the same when no other output of the rule can contain the banned text, for example when every output has the same length. In this example from the Awkwords help, [VV]t[VV]^aa^ii^uu, only the second pair of vowels may not repeat a vowel.

Importing Awkwords files

On the Generator page, Import, then Awkwords, converts an Awkwords pattern into a Monke grammar. Choose an .awkw file saved by Awkwords, or paste a pattern. To paste subpatterns as well, write them one per line as a saved file does: V:a/i/u, then r:CV for the main pattern. The import replaces the current grammar; the browser's Back button undoes it.

• Each subpattern becomes a rule named by its letter, and the main pattern becomes the root rule Word. Plain alternatives become terminal rules.
• Brackets, optionals, escapes and weights are translated as in the table above. Weights are enabled when the pattern uses any.
• The number of words fills the word count; filter duplicates and new line each set Filter duplicates and the List style.
• Each filtered fragment becomes a rule named Filtered1, Filtered2, and so on, holding just that fragment, with one exclusion per filter.

An imported exclusion is written ^.'text'.$: ^ and $ pin it to the start and end of the rule's output, so it rejects the output only when it is exactly the filter text, as Awkwords did. For [a/ab]^a, the rule Filtered1 has the patterns a, ab and the exclusion ^.'a'.$, so it gives only ab. A plain exclusion 'a' would reject ab too. A filter made only of spaces rejects an empty result; that case uses a helper rule ending in Marked that adds an invisible marker, which a rewrite then removes.

When something does not translate exactly, the import lists notes in the output panel until you dismiss them. The most common ones:

• Probabilities may differ slightly: the filtered fragment is inside an alternative or an optional. You get the same words, but with different odds (see Filters versus exclusions).
• Removes every possible result or reject N% of results: Monke retries a rule 100 times, then reports it as too restrictive.
• No subpattern: a capital letter without a subpattern generated nothing in Awkwords; it becomes an empty rule.
• Empty alternative: a / at the end of a list, as in [a/], is kept as an empty alternative, although Awkwords 1.2 ignored it.
• Weight read as: a weight outside 1 to 128, or several in one alternative, is imported with the value Awkwords used.

Unmatched brackets stop the import with the line and column at fault, since Awkwords refused them too. A letter right after a filter, as in [VV]^aaC, is kept, although Awkwords skipped it.

Only in Monke

Repetition with {min:max}, rewrites with back-references, exclusions that match patterns instead of fixed text, optional probabilities, decimal weights and weighted rule patterns.