Thiorosan: Create the documentation subpage

2026-08-27T12:19:34Z

Create the documentation subpage

New page

This is the documentation for [[Module:Auphen]], the sound-change engine for the Yezur wiki. It applies an ordered ruleset of rewrite rules to a word and returns the result. It exports no <code>#invoke</code> entry point and is not called from wikitext: [[Module:Auphen/frame]] requires it, hands it the data for one language and backs [[Template:Auphen]], so that <code><nowiki>{{auphen|word|code}}</nowiki></code> estimates a pronunciation and <code><nowiki>{{auphen|word|code|ruleset}}</nowiki></code> runs a named ruleset. The categories, the glyph-to-sound table and the rulesets themselves are pure data on the <code>Module:Auphen/<code></code> pages; the engine holds no language-specific material. The rule notation is a port of PhoMo's; the behaviour log, the divergences from it and the module's provenance are kept on [[Module talk:Auphen]].

== Interface ==

{| class="wikitable"
! Call !! Purpose
|-
| <code>Auphen.new(categories, ipa_rules, opts)</code> || Builds an engine. <code>categories</code> maps each bracketed category name to an array of its members in declaration order; <code>ipa_rules</code> is the glyph-to-sound table as a string; <code>opts</code> holds the two settings below. Every argument may be omitted, and an engine built without <code>ipa_rules</code> does no glyph conversion.
|-
| <code>eng:run(ruleset, input, toIpa)</code> || Runs <code>ruleset</code> over <code>input</code> and returns the finished string. The input is split on spaces and on <code>~</code>, each part is processed as its own word with its own word edges, and the parts are rejoined with spaces. With <code>toIpa</code> true the input is first lower-cased, sentence-final punctuation and the colon become <code>|</code>, other punctuation is dropped, and <code>ipa_rules</code> is applied.
|-
| <code>eng:run_word(ruleset, word)</code> || Runs the ruleset over a single word. Returns the finished word and a trace holding, for each rule, its text, the word after it and whether it applied.
|-
| <code>eng.warnings</code> || Warnings gathered while loading and running: an invalid category name, a category reference that cannot be resolved, an affix category used without an index, an affix index that matches nothing, a rule skipped for exceeding the cap below. [[Module:Auphen/frame]] does not read them.
|-
| <code>opts.explodeCap</code> || The ceiling on the number of variants one segment of a rule may expand to, 5,000,000 by default. A segment above it expands to nothing and the rule is skipped with a warning rather than left to exhaust the parser.
|-
| <code>opts.dashToSpace</code> || When true, hyphens in the finished word become spaces.
|}

Neither option is reachable from wikitext: [[Module:Auphen/frame]] builds the engine without an <code>opts</code> table, so template calls run at the default cap and leave hyphens untouched.

== Rule lines ==

A ruleset is plain text, one rule to a line; a line containing no <code>/</code> is ignored. Each rule has up to five fields, separated by <code>/</code>:

target / change / environment / exception / else

{| class="wikitable"
! Field !! Purpose
|-
| target || What the rule matches. <code>#</code> alone means the whole word; an empty target matches at every slot from before the first character to after the last.
|-
| change || What the match becomes. An empty field deletes it.
|-
| environment || Conditions on the surrounding word; the rule applies only where one of them holds. An empty field imposes no condition.
|-
| exception || Conditions written the same way; where one holds, the rule is blocked.
|-
| else || Applied in place of the change wherever the environment fails or an exception holds. An empty field leaves the match alone.
|}

Rules run in order, each on the output of the last. The word is lower-cased before a rule sees it, and the finished word is re-cased to match the input: all lower, all upper, or otherwise capitalised. A rule whose target is <code>#</code> and whose change contains <code>#</code> or <code>@</code> is treated as an affixation instead of a replacement; such a rule has no target position, so a condition containing <code>_</code> never holds in one.

== Notation ==

{| class="wikitable"
! Notation !! Meaning
|-
| <code>[X]</code> || A category: a bracketed capital followed by up to two more letters, its members listed on the language's data page. Members are tried longest first when matching but map by position, so the ''n''th member of the target's category becomes the ''n''th member of the change's.
|-
| <code>[a,b,c]</code> || A category written in place, members comma-separated, without being declared.
|-
| <code>%</code> || In the change, the text that was matched, so that <code>%%</code> doubles it; where the target is <code>#</code> it is the whole word. In a condition, replaced by the matched text before the condition is tested.
|-
| <code>?</code> || The matched text reversed, or the whole word where the target is <code>#</code>; it is read the same way in a condition. As the whole change, <code>?</code>''n'' reverses that text from position ''n'', counting from the end where ''n'' is negative, and <code>?</code>''n''<code>^</code>''m'' reverses ''m'' characters from there.
|-
| <code>_</code> || The target's own slot, which makes the condition local: what stands left of <code>_</code> must precede the match and what stands right of it must follow. A condition without <code>_</code> is global and is tested against the whole word.
|-
| <code>*</code> || In a local condition, separates material that need not be adjacent: the segment nearest the slot must abut it, the others need only occur in order further out.
|-
| <code>#</code> || A word edge. The word is padded with <code>#</code> at each end, so a local condition tests an edge in place; in a global condition, material before the <code>#</code> must be word-initial and material after it word-final.
|-
| <code>=</code> || Counts occurrences, without overlap, in a global condition. <code>[V]=3</code> holds at exactly three, <code>[V]=>3</code> at three or more, <code>[V]=<3</code> at three or fewer.
|-
| <code>|</code> || Separates alternative conditions; the field holds if any one of them does.
|-
| <code>"</code> || As a condition on its own, holds when the previous rule applied.
|-
| <code>@</code>''n'' || Written at the end of the change, selects a single instance: the ''n''th match of the target, counted from the end where ''n'' is negative. Instances are numbered by a left-to-right, longest-first scan, so overlapping members of one category count once. An index on the else field is used where the change carries none.
|-
| <code>^</code>''m'' || After an index, the number of characters the change covers, counted from the start of the match rather than taken from the length of the target.
|-
| <code>!</code>''x'' || Makes the operator character ''x'' an ordinary literal. The <code>!</code> of the movement marker <code>>!</code> is not read as an escape.
|-
| <code>~</code> || A word boundary: each side is run as its own word and the output shows a space. A <code>~</code> produced by a rule becomes a plain space.
|}

== Affixation and movement ==

In an affixation rule the change is a template in which <code>#</code> stands for the word; positions are counted in characters from 1, and a negative position counts from the end. Apart from the movement forms, a template with no <code>#</code> in it leaves the word unchanged; an index and span with no material at all delete. Category references and <code>##</code> are resolved before the template is applied, and <code>%</code> and <code>?</code> are not read here.

{| class="wikitable"
! Change !! Effect
|-
| <code>x#</code> || Prefixes ''x''; <code>#x</code> suffixes it and <code>x#y</code> circumfixes.
|-
| <code>##</code> || Appends a copy of the word, each further <code>#</code> appending another. With an index the copy is that slice of the word — <code>^</code>''m'' giving its length, one character by default — and is placed directly after it.
|-
| <code>#x@</code>''n'' || Inserts ''x'' after character ''n''; <code>x#@</code>''n'' inserts it before.
|-
| <code>x#@</code>''n''<code>^</code>''m'' || Replaces ''m'' characters from position ''n'' with ''x'', or deletes them where the material is empty.
|-
| <code>#[X]@</code>''n'' || The ''n''th member of category X occurring in the word, used as affix material and here suffixed. The index is consumed by the category, so the template's <code>#</code> alone places the material.
|-
| <code>></code>''s''<code>@</code>''d''<code>^</code>''m'' || Moves ''m'' characters, one by default, from position ''s'' to position ''d'', the destination being counted in the word with the block already removed. <code>>!</code> in place of <code>></code> copies the block instead, counting the destination in the unchanged word.
|}

== Notes ==

<code>ipa_rules</code> is read as one <code>glyph/sound</code> pair per line, longest glyph first; anything it does not match passes through unchanged. It is applied only on the pronunciation path, where [[Module:Auphen/frame]] runs the data page's <code>pronounce</code> ruleset against its <code>ipacats</code> categories and wraps the result in slashes. A named ruleset is taken from <code>sets</code> and run against <code>cats</code>, over the orthography and with no glyph conversion. Either category set stands in for the other where a data page defines only one.

Worked examples for the languages with sound data are on [[Template:Auphen/testcases]], which calls <code><nowiki>{{#invoke:Auphen/frame|raw}}</nowiki></code> for unformatted output. A missing word or code, a code with no data page and an unknown ruleset are reported rather than raised: <code><nowiki>{{auphen}}</nowiki></code> renders the message as an error and files the page in [[:Category:Auphen errors]], while <code>raw</code> returns it as a plain <code>ERROR:</code> line.

Module:Auphen/doc - Revision history

Thiorosan: Create the documentation subpage