Module:Auphen/doc

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 #invoke 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 {{auphen|word|code}} estimates a pronunciation and {{auphen|word|code|ruleset}} runs a named ruleset. The categories, the glyph-to-sound table and the rulesets themselves are pure data on the Module:Auphen/<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

Call	Purpose
Auphen.new(categories, ipa_rules, opts)	Builds an engine. categories maps each bracketed category name to an array of its members in declaration order; ipa_rules is the glyph-to-sound table as a string; opts holds the two settings below. Every argument may be omitted, and an engine built without ipa_rules does no glyph conversion.
eng:run(ruleset, input, toIpa)	Runs ruleset over input and returns the finished string. The input is split on spaces and on ~, each part is processed as its own word with its own word edges, and the parts are rejoined with spaces. With toIpa true the input is first lower-cased, sentence-final punctuation and the colon become |, other punctuation is dropped, and ipa_rules is applied.
eng:run_word(ruleset, word)	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.
eng.warnings	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.
opts.explodeCap	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.
opts.dashToSpace	When true, hyphens in the finished word become spaces.

Neither option is reachable from wikitext: Module:Auphen/frame builds the engine without an opts 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 / is ignored. Each rule has up to five fields, separated by /:

target / change / environment / exception / else

Field	Purpose
target	What the rule matches. # 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 # and whose change contains # or @ is treated as an affixation instead of a replacement; such a rule has no target position, so a condition containing _ never holds in one.

Notation

Notation	Meaning
[X]	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 nth member of the target's category becomes the nth member of the change's.
[a,b,c]	A category written in place, members comma-separated, without being declared.
%	In the change, the text that was matched, so that %% doubles it; where the target is # it is the whole word. In a condition, replaced by the matched text before the condition is tested.
?	The matched text reversed, or the whole word where the target is #; it is read the same way in a condition. As the whole change, ?n reverses that text from position n, counting from the end where n is negative, and ?n^m reverses m characters from there.
_	The target's own slot, which makes the condition local: what stands left of _ must precede the match and what stands right of it must follow. A condition without _ is global and is tested against the whole word.
*	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.
#	A word edge. The word is padded with # at each end, so a local condition tests an edge in place; in a global condition, material before the # must be word-initial and material after it word-final.
=	Counts occurrences, without overlap, in a global condition. [V]=3 holds at exactly three, [V]=>3 at three or more, [V]=<3 at three or fewer.
|	Separates alternative conditions; the field holds if any one of them does.
"	As a condition on its own, holds when the previous rule applied.
@n	Written at the end of the change, selects a single instance: the nth 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.
^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.
!x	Makes the operator character x an ordinary literal. The ! of the movement marker >! is not read as an escape.
~	A word boundary: each side is run as its own word and the output shows a space. A ~ produced by a rule becomes a plain space.

Affixation and movement

In an affixation rule the change is a template in which # 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 # in it leaves the word unchanged; an index and span with no material at all delete. Category references and ## are resolved before the template is applied, and % and ? are not read here.

Change	Effect
x#	Prefixes x; #x suffixes it and x#y circumfixes.
##	Appends a copy of the word, each further # appending another. With an index the copy is that slice of the word — ^m giving its length, one character by default — and is placed directly after it.
#x@n	Inserts x after character n; x#@n inserts it before.
x#@n^m	Replaces m characters from position n with x, or deletes them where the material is empty.
#[X]@n	The nth 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 # alone places the material.
>s@d^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. >! in place of > copies the block instead, counting the destination in the unchanged word.

Notes

ipa_rules is read as one glyph/sound 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 pronounce ruleset against its ipacats categories and wraps the result in slashes. A named ruleset is taken from sets and run against cats, 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 {{#invoke:Auphen/frame|raw}} for unformatted output. A missing word or code, a code with no data page and an unknown ruleset are reported rather than raised: {{auphen}} renders the message as an error and files the page in Category:Auphen errors, while raw returns it as a plain ERROR: line.