@kensio/pinyinjs 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -11,6 +11,26 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
 
 ### Added
 
+- **`slug`,** hanzi to a URL-safe slug: 我想学中文。 is
+  `wo3-xiang3-xue2-zhong1wen2`. Built on the decode rather than on a finished
+  string, which is the whole point of it — 银行 is `yin2hang2` and not
+  `yin2xing2`, the separators fall on the word boundaries 分词连写 found, and
+  西安 keeps its 隔音符号 as a break so a toneless slug is `xi-an` rather than
+  `xian`, which is a different word. Tones are written by default because
+  dropping them collides, and `hash` puts a short hash of the _hanzi_ on the end
+  for the homophones tones cannot separate: 权利 and 权力 are both `quan2li4`.
+  The options generalise it past URLs to search keys and identifiers, which the
+  [slug page](docs/slug/) tabulates. `pinyinjs slug` at the command line.
+
+- **`TEACHING_JIAO` and `COUNTED_MEASURE`,** two more lattice rules, and
+  `QUANTITY_CHARACTERS`, the 汉字 a quantity is written with that the second of
+  them asks about. See the fixes below for what they do and what they measure.
+- **`counts` on the numeral options.** Whether the number stands immediately in
+  front of something it counts, which is what makes a lone 2 两:
+  `numeralHanzi(2, { counts: true })` is `两` and `numeralHanzi(2)` is `二`.
+  Unlike `liang` it is not a variable choice — 二个 is simply wrong — but
+  nothing about the number says whether it is counting, so the caller says.
+  `convert` sets it from the character after the digits.
 - **`SYLLABLE_TONES` and `isAttestedTone`.** Which tones each of the 424
   syllables is actually written in, extracted from the merged dictionary and
   held to it by a build assertion. 424 syllables in five tones would be 2,120
@@ -24,14 +44,63 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
   en.wiktionary's Mandarin pronunciation blocks, in bopomofo, Wade-Giles, Yale
   and GR with their tones, and all 50 rows of Wikipedia's _Help:IPA/Mandarin_
   key. The 417-row syllabary already checked was toneless, so it could say
-  nothing about tone marks, the neutral tone, 儿化 or how a word is joined —
+  nothing about tone marks, the neutral tone, 儿化 or how a word is joined,
   which is where the four fixes below were found.
 
 ### Fixed
 
+- **教 was `jiào` even where it was teaching.** 他在北京大学教了三年书 came out
+  `jiàole sān nián shū`, and 我教英语, 谁教你法语 and 她教我如何游泳 with it.
+  The dictionary stores 教 as `jiào` with `jiāo` as an alternate, and `jiào` is
+  right for the compounds — 教育, 教师, 宗教, 主教 — which are words and reach
+  their reading through the word; what is left is the 教 standing as a word of
+  its own, and that one is the verb. The object is what says so: a pronoun, a
+  noun or a name after it, or an aspect particle, since only a verb takes 了,
+  过 or 得. Forcing the character's own reading was not enough on its own,
+  because a two-character reading carries its 教 into the position from
+  outside — 王老师教我们汉语 read `jiào` off 师教 and 来教我 off 来教 — so an
+  untagged pair ending in 教 goes too, while every tagged word keeps its
+  reading: 任教, 宗教, 主教, 佛教, 传教, 执教, 请教, 家教. Over 88,866 lines
+  181 教 decode as a word of their own and every one read `jiào`; 158 are now
+  `jiāo`, three of them wrongly — 统一教创始人, 方法教深思 and 做到了教政分离,
+  where a nominal compound takes an object's shape. CPP's polyphone score is
+  89.05%, up from 89.04%.
+- **A 量词 was swallowed by the word behind it.** 三个人 was `sān gèrén`, three
+  _personals_, because 个人 is a common noun and nothing weighed it against the
+  个 belonging to the 三 in front of it. It is now `sān gè rén`, and so are
+  两家人, 三杯水, 四匹马, 十八层楼 and 一段长时间. What makes it decidable is
+  that the dictionary tags the 量词: 个, 次, 天 and 杯 are `q`, while the
+  characters that only look like measure words in this position are not — 分 is
+  a verb, 部 and 成 are nouns, 年 and 点 are numerals — so 五分钟, 三部分,
+  五成分, 五年级 and 三点钟 are untouched, and those are exactly the words a
+  blanket rule would break. Nor does an ordinal count anything (第三集团军), nor
+  a numeral inside a longer word (唯一道路), and a number and its measure
+  written solid survive whole where the dictionary has them: 一辈子, 一会儿,
+  一口气 and 两口子 are unchanged. Over 88,866 lines the rule forbids 561 edges
+  and moves 53 decodes, three of them wrongly — 一批评, 这一名词 and 六七股灾,
+  where the 一 and the 六七 count nothing. Exactly one reading changes in the
+  whole corpus and it is a fix: 已经下了两天雨了 read 天雨 as `tiān yù`.
+- **The Han after a number was decoded without it.** 2个人 was `liǎng gèrén`
+  while 两个人 written out was already `liǎng gè rén`, because a Han run was
+  decoded on its own and had no idea a number preceded it. A run is now decoded
+  with the 汉字 the digits stand for in front of it, and reported without them,
+  so digits and 汉字 reach the same decode. `decodeRun` and `decodeRunScored`
+  take that context as a fourth argument; where a reading would straddle the
+  join — 1点儿事, whose 一点儿 is one `yìdiǎnr` over both sides of it — the run
+  is decoded alone, as before.
+- **A lone 2 in front of a 量词 was read 二.** 我们买了2个西瓜 came out as
+  `wǒmen mǎile èr gè xīguā`, and a 2 standing immediately in front of what it
+  counts is 两: it is now `liǎng gè`, and 2岁 is `liǎng suì`, 2点 `liǎng diǎn`
+  and 2万人 `liǎng wàn rén`, the same 两 that 2,000 and 2:00 already got. The
+  measure words a 2 can count with are an open list, so 两 is the default and
+  the exceptions are named — 月, 日, 号, 楼, 路, 班 and 期, where the digit
+  labels a position rather than counting (2月 is `èr yuè`), an ordinal, which
+  the 第 in front of it marks (第2次 is `dì èr cì`), and 十 and 百, which follow
+  二 as 20 and 200 already do. A 2 inside a larger number is untouched: 12个 is
+  still `shí'èr gè`.
 - **A decimal lost the grouping of its counted part.** 一共75.5元 was
   `yígòng qī shí wǔ diǎn wǔ yuán`, with the 75 in loose syllables, and is now
-  `yígòng qīshíwǔ diǎn wǔ yuán` — the same word 一共75元 already got. Only what
+  `yígòng qīshíwǔ diǎn wǔ yuán`, the same word 一共75元 already got. Only what
   follows the 点 is read a digit at a time, and that part is unchanged: 3.14 is
   still `sān diǎn yī sì`, and sandhi still stops at the point.
 - **A decimal point was read as a full stop.** 一共75.5元 came back as
@@ -42,14 +111,14 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
   is now `ㄋㄚˇㄦ`: the mark belongs to the nucleus and the suffix is not part of
   what it marks. A mark written after the ㄦ is still read.
 - **Wade-Giles put the tone digit on the 儿化 suffix,** so 花儿 huār was
-  `hua-êrh¹` — a first-tone 兒. It is now `hua¹-'rh`, with the digit on the
+  `hua-êrh¹`, a first-tone 兒. It is now `hua¹-'rh`, with the digit on the
   syllable the tone belongs to and the suffix written as the reduced `'rh` that
   keeps it apart from 女儿 nǚ'ér's `nü³-êrh²`.
 - **Gwoyeu Romatzyh wrote 儿化 as a plain `-l` suffix.** GR fuses it into the
   rime instead, and the rules are now implemented as _Spelling in Gwoyeu
   Romatzyh_ gives them: 玩儿 wánr is `wal` rather than `wanl`, 事儿 shìr is
   `shell`, 今儿 jīnr is `jiel`. The fusion is many-to-one, so `jiel` is 今儿 and
-  鸡儿 both and 128 forms no longer round-trip — every one of them a form the
+  鸡儿 both and 128 forms no longer round-trip, every one of them a form the
   language does not write.
 - **Gwoyeu Romatzyh wrote `.mhe` for a neutral 么.** The `-h-` is the first tone
   of a sonorant initial, and a neutral syllable is in no tone at all; the basic
@@ -58,23 +127,23 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
   follows the broader IPA column of _Comparison of Standard Chinese
   transcription systems_, which is where its ground truth comes from; the two
   pages differ at the medials, -ang, the empty rhyme and the diphthongs. No
-  output changed — the claim did.
+  output changed, only the claim.
 - **`--system ipa` capitalised the IPA.** 我去银行。他姓王。 came out as
   `Uo˨˩˦ ... Tʰa˥ ɕiŋ˥˩ Uaŋ˧˥`, with the sentence capital and the proper noun
   carried over from the pinyin as though a transcription spelled words. IPA
-  letters are symbols rather than an alphabet — `[T]` is not `[t]` in a larger
-  size but a symbol the IPA does not have — so the capitals are now dropped for
+  letters are symbols rather than an alphabet, since `[T]` is not `[t]` in a
+  larger size but a symbol the IPA does not have, so the capitals are now dropped for
   IPA and bopomofo and kept for the three romanisations. `toTranscription`
   takes `{ capitals: false }` for callers writing their own.
 - **A compound lost the zh-TW reading its own parts carry.** 垃圾分類 read
   `lājīfēnlèi` under `zh-TW`, because CC-CEDICT marks `Taiwan pr.` on 垃圾 and
-  垃圾桶 and on no other compound, and the decoder prefers the longer word — so
+  垃圾桶 and on no other compound, and the decoder prefers the longer word, so
   the entry that had the delta was never consulted. 101 compounds now compose
   one from their constituents, 垃圾 accounting for 14 of them and 比肩, 玳瑁,
   从容, 骨头, 蜗牛 and 说服 for most of the rest. Three guards keep it honest:
   the constituent has to survive segmentation (運行狀況 contains 行狀 but reads
   運行 + 狀況), it has to be read in the compound exactly as its own entry reads
-  it, and it has to be a whole word — never a bare character, since 會's `huǐ`
+  it, and it has to be a whole word rather than a bare character, since 會's `huǐ`
   would rewrite 三合會 as `sānhéhuǐ` and 3,743 entries would compose that way
   against the 101 that whole words compose.
 - **A character's zh-TW delta was often a choice between its 普通话 senses.**
@@ -83,25 +152,25 @@ which a dictionary rebuild can change, and the artifact format under `data/`.
   is a locale shift: CC-CEDICT lists 地[de5] and 地[di4] as separate entries, so
   `dì` is what 地 reads in 普通话 when it means the ground, and the adverbial
   particle is `de` in Taipei too. A delta the word already has as a 普通话 sense
-  is now refused — 71 characters and 3 words lose one, 都, 着, 应, 差, 称, 斗,
-  舍, 薄 and 万 among them — while 和 `hàn`, 期 `qí`, 垃 `lè` and 髮 `fǎ` stay,
+  is now refused, so 71 characters and 3 words lose one, 都, 着, 应, 差, 称, 斗,
+  舍, 薄 and 万 among them, while 和 `hàn`, 期 `qí`, 垃 `lè` and 髮 `fǎ` stay,
   no 普通话 sense reading any of those that way. A `Taiwan pr.` note is also
   only read off a sense matching the reading the entry settled on, which drops
   16 more: the note on 著's chess-move sense, which reads `zhāo`, had been
   giving the aspect particle 着 a 國語 reading of `zhuó`.
 - **A locale delta overwrote a reading it was not measured against.** The delta
   describes the entry's own 普通话 reading, so a polyphone the decode read some
-  other way — 得 forced to the modal `děi` rather than the particle `de` its
-  entry stores — now keeps what the decode worked out instead of being rewritten
-  from the entry.
+  other way, such as 得 forced to the modal `děi` rather than the particle `de`
+  its entry stores, now keeps what the decode worked out instead of being
+  rewritten from the entry.
 
 ### Changed
 
 - **Reading a romanisation narrows on the tone that was written.**
   `readWadeGiles("lo²")` was `[luó, ló]` and is now `[luó]`: 咯 is a
   sentence-final particle and is only ever neutral, so ló is not a syllable
-  Mandarin has. The same goes for `readWadeGilesLoosely` — `pan²` is pán alone
-  — and for `readYale`, `readIpa` and `readGwoyeu`, where it settles the 儿化
+  Mandarin has. The same goes for `readWadeGilesLoosely`, where `pan²` is pán
+  alone, and for `readYale`, `readIpa` and `readGwoyeu`, where it settles the 儿化
   collisions the same way (`ell` is 二 èr, there being no first-tone 兒).
   Narrowing never empties a list: a tone no candidate is written in leaves the
   candidates alone, since that says the tone is wrong rather than the spelling.
@@ -123,7 +192,7 @@ decoder internals and the build pipeline.
 - **Transcription systems, all five, in both directions.** Bopomofo, Wade-Giles,
   Yale, Gwoyeu Romatzyh and IPA at the syllable level, plus hanzi → any of them
   end to end via `convert --system` and `convertToWadeGiles`. Checked against
-  417 rows of an outside syllabary in every system — 3,336 cells.
+  417 rows of an outside syllabary in every system, which is 3,336 cells.
 - **Reading ambiguous Wade-Giles.** `readWadeGilesLoosely` allows for the
   apostrophes and diacritics real texts drop, and `splitWadeGiles` puts back the
   hyphens they lose. Measured: 52.07% of written syllables lose their identity
@@ -134,7 +203,7 @@ decoder internals and the build pipeline.
   follows them.
 - **Orthography rules.** The 重叠 hyphen for AABB and repeated words, the 成语
   hyphen from a curated list of 117, 老王 → `Lǎo Wáng`, and GB/T 16159 5.1 in
-  full — 毛泽东 is `Máo Zédōng`, 北京大学 is `Běijīng Dàxué`, on boundaries
+  full, so 毛泽东 is `Máo Zédōng` and 北京大学 is `Běijīng Dàxué`, on boundaries
   CC-CEDICT's own capitalisation states.
 - **Typed rule overrides on the lattice** (`READING_RULES`), with the modal 得
   and attested 儿化 as the first two.
@@ -167,17 +236,17 @@ decoder internals and the build pipeline.
 
 ### Accuracy at 1.0.0
 
-Over the 110-case gold corpus, which is committed to the repository — not to
-the published package — and scored by `pnpm accuracy`:
+Over the 118-case gold corpus, which is committed to the repository rather than
+to the published package, and scored by `pnpm accuracy`:
 
 |                  |   lattice | greedy baseline |
 | ---------------- | --------: | --------------: |
-| exact match      | **97.3%** |           90.9% |
-| reading accuracy |     99.7% |           98.7% |
-| spacing (F1)     | **99.7%** |           96.3% |
+| exact match      | **97.5%** |           88.1% |
+| reading accuracy |     99.7% |           98.3% |
+| spacing (F1)     | **99.8%** |           96.3% |
 
 Every figure in that table is asserted against the scorer by
-`src/changelog.test.ts`, because a number nothing executes goes stale — which is
+`src/changelog.test.ts`, because a number nothing executes goes stale, which is
 what happened to this project's README table across three releases.
 
 `pnpm polyphones` reports 89.04% for the lattice against greedy's 88.82% over

package/README.md

@@ -29,6 +29,9 @@ Wǒ yào qù Běijīng.
 $ pinyinjs convert --notation numbers 银行
 yin2hang2
 
+$ pinyinjs slug 我想学中文。
+wo3-xiang3-xue2-zhong1wen2
+
 $ pinyinjs explain 银行
 银行  yínháng
   yín     locked
@@ -53,6 +56,7 @@ běijīng     běijīng   ㄅㄟˇ ㄐㄧㄥ     pei³-ching¹ běijīng   beeij
 | ------------ | --------------------------------------------------- |
 | `convert`    | hanzi to pinyin                                     |
 | `html`       | the same, as HTML                                   |
+| `slug`       | hanzi to a URL-safe slug                            |
 | `explain`    | each syllable, how settled it was, and what it beat |
 | `lookup`     | what the dictionary holds for a word                |
 | `syllable`   | take written pinyin apart                           |
@@ -70,7 +74,7 @@ A command given no arguments reads standard input, one text per line, so
 dictionary at all and start without loading one.
 
 At a terminal each syllable is written in its tone's colour, in
-[MDBG](https://www.mdbg.net)'s palette — red, yellow, green, blue, and the
+[MDBG](https://www.mdbg.net)'s palette of red, yellow, green, blue, and the
 terminal's own colour for the neutral tone. It is off for a pipe, `NO_COLOR` is
 honoured, `--colour` and `--no-colour` force it either way, and `--json` is
 never coloured. See [the command line](docs/cli/#colour).
@@ -85,9 +89,8 @@ $ pinyinjs convert 银行
 yínháng
 ```
 
-Everything else has columns for a person to read. Add `--json` — to any
-command — and it writes one JSON document per answer instead, which is what
-`jq` wants:
+Everything else has columns for a person to read. Add `--json` to any command
+and it writes one JSON document per answer instead, which is what `jq` wants:
 
 ```console
 $ pinyinjs explain 长江大桥 --json | jq -c '.syllables[] | select(.state != "locked")'
@@ -149,16 +152,16 @@ first, convert with it, and reload as `full` arrives.
 convert(dictionary, "银行"); // "yínháng"
 convert(dictionary, "行长"); // "hángzhǎng"
 convert(dictionary, "我要去北京。"); // "Wǒ yào qù Běijīng."
-convert(dictionary, "3D银行"); // "sān D yínháng" — the digit is read, the letter is not
+convert(dictionary, "3D银行"); // "sān D yínháng", the digit is read, the letter is not
 ```
 
 A reading the dictionary cannot settle on its own is settled by context, with
 typed rules over the lattice rather than tweaks to the output:
 
 ```ts
-convert(dictionary, "我得走了"); // "wǒ děi zǒule" — modal 得
-convert(dictionary, "他跑得很快"); // "tā pǎo de hěn kuài" — the particle
-convert(dictionary, "那边儿"); // "nà biānr" — 儿 does not stand on its own
+convert(dictionary, "我得走了"); // "wǒ děi zǒule", modal 得
+convert(dictionary, "他跑得很快"); // "tā pǎo de hěn kuài", the particle
+convert(dictionary, "那边儿"); // "nà biānr", 儿 does not stand on its own
 ```
 
 See [converting](docs/converting/#rules-where-the-cost-model-cannot-reach).
@@ -226,7 +229,7 @@ writes in a way no rule reaches.
 
 ```ts
 convert(dictionary, "他看了"); // "tā kànle"
-convert(dictionary, "我还给你了。"); // "Wǒ huán gěi nǐ le." — sentence-final 了
+convert(dictionary, "我还给你了。"); // "Wǒ huán gěi nǐ le.", sentence-final 了
 convert(dictionary, "作者"); // "zuòzhě"
 convert(dictionary, "南京市"); // "Nánjīng Shì"
 convert(dictionary, "南京市", { grouping: false }); // "Nánjīngshì"
@@ -246,7 +249,7 @@ a boundary inside it.
 ```ts
 convert(dictionary, "干干净净"); // "gāngān-jìngjìng"
 convert(dictionary, "研究研究"); // "yánjiū-yánjiū"
-convert(dictionary, "爸爸妈妈"); // "bàba māma" — that shape, but two words
+convert(dictionary, "爸爸妈妈"); // "bàba māma", that shape, but two words
 ```
 
 **A 成语 that can be read as two disyllables** takes the same hyphen, from a
@@ -254,7 +257,7 @@ curated list of 117; the rest are written solid, as the standard writes them.
 
 ```ts
 convert(dictionary, "风平浪静"); // "fēngpíng-làngjìng"
-convert(dictionary, "不亦乐乎"); // "búyìlèhū" — cannot be halved
+convert(dictionary, "不亦乐乎"); // "búyìlèhū", cannot be halved
 ```
 
 **Digits are read**, and the rest of a non-Han run passes through exactly as
@@ -266,7 +269,7 @@ convert(dictionary, "1988年之后"); // "yī jiǔ bā bā nián zhīhòu"
 convert(dictionary, "95%的人"); // "bǎifēnzhījiǔshíwǔ de rén"
 convert(dictionary, "3D打印"); // "sān D dǎyìn"
 convert(dictionary, "6:30起床"); // "liù diǎn sānshí fēn qǐchuáng"
-convert(dictionary, "16:9的"); // "16:9de" — a ratio is not a quantity
+convert(dictionary, "16:9的"); // "16:9de", a ratio is not a quantity
 ```
 
 `numbers: "keep"` leaves every digit alone. See [numbers](docs/numerals/).
@@ -282,13 +285,13 @@ import { convertPieces, isUncertain, writeSyllable } from "@kensio/pinyinjs";
 const pieces = convertPieces(dictionary, "银行");
 pieces.map((piece) => piece.text); // ["yín", "háng"]
 pieces[1]?.syllable; // { initial: "h", final: "ang", tone: 2 }
-pieces[0]?.confidence?.isLocked; // true — nothing else can be read here
+pieces[0]?.confidence?.isLocked; // true, nothing else can be read here
 pieces[1]?.confidence?.alternatives.map((found) =>
   found.reading.map((syllable) => writeSyllable(syllable)).join(""),
 ); // ["xíng", "héng", "hàng"]
 ```
 
-A piece with no `syllable` is the text between two of them — a space, or a run
+A piece with no `syllable` is the text between two of them: a space, or a run
 that was never Han. `joinPieces(pieces)` gives back exactly what `convert`
 returns.
 
@@ -306,8 +309,8 @@ const guesses = (text: string) =>
     (piece) => piece.confidence !== undefined && isUncertain(piece.confidence),
   );
 
-guesses("行").map((piece) => piece.text); // ["xíng"] — nothing but a prior chose it
-guesses("银行").map((piece) => piece.text); // [] — the word settles both syllables
+guesses("行").map((piece) => piece.text); // ["xíng"], nothing but a prior chose it
+guesses("银行").map((piece) => piece.text); // [], the word settles both syllables
 ```
 
 An alternative's `cost` says how much more the cheapest conversion taking it
@@ -327,7 +330,7 @@ convertToHtml(dictionary, "行");
 One element per syllable, with `py-tone-1` to `py-tone-5` (5 is the neutral
 tone), and `py-uncertain` plus the rejected readings where the decoder was
 guessing. Text that is not Han is escaped, not marked up. No styles are
-included — write your own:
+included, so write your own:
 
 ```css
 .py-tone-1 {
@@ -348,12 +351,12 @@ have.
 const entry = dictionary.lookup("头发");
 entry?.reading; // [{ initial: "t", final: "ou", tone: 2 }, { initial: "f", final: "a", tone: 5 }]
 entry?.isProperNoun; // false
-entry?.partOfSpeech; // "n" — jieba's tag
+entry?.partOfSpeech; // "n", jieba's tag
 
 dictionary.lookup("頭髮")?.reading; // the same reading, found under 繁體
 dictionary.lookup("重複")?.reading; // 重複 and 重覆 are both keys for 重复
-dictionary.hasPrefix("银"); // true — does any word start with this?
-dictionary.readingsOf("行"); // xíng, háng, héng, hàng — likeliest first
+dictionary.hasPrefix("银"); // true, does any word start with this?
+dictionary.readingsOf("行"); // xíng, háng, héng, hàng, likeliest first
 ```
 
 Both scripts are keys in the same dictionary, so nothing is converted before a
@@ -367,12 +370,12 @@ The syllable layer needs no dictionary and no network.
 import { isSyllable, readSyllable, writeSyllable } from "@kensio/pinyinjs";
 
 readSyllable("jiù"); // { initial: "j", final: "iou", tone: 4 }
-readSyllable("jiu4"); // the same — both notations parse
+readSyllable("jiu4"); // the same, both notations parse
 readSyllable("lv4"); // { initial: "l", final: "ü", tone: 4 }
 readSyllable("hello"); // undefined
-readSyllable("běi3"); // undefined — one notation at a time
+readSyllable("běi3"); // undefined, one notation at a time
 
-isSyllable("wánr"); // true — 儿化 is a suffix, not a syllable of its own
+isSyllable("wánr"); // true, 儿化 is a suffix, not a syllable of its own
 ```
 
 Initials and finals are the _underlying_ forms rather than the spelling, so 就 is
@@ -390,7 +393,7 @@ Input takes either notation, the `v` and `u:` conventions for ü, and raised ton
 digits. Output is standard diacritics unless asked otherwise.
 
 Parsing answers whether a spelling is _well formed_, not whether Mandarin uses
-it — `shong` parses and is not a real syllable. The attested inventory is
+it: `shong` parses and is not a real syllable. The attested inventory is
 separate:
 
 ```ts
@@ -410,7 +413,7 @@ splitSyllables("nǐhǎo"); // ["nǐ", "hǎo"]
 splitSyllables("Xī'ān"); // ["Xī", "ān"]
 splitSyllables("yinhang"); // ["yin", "hang"]
 splitSyllables("guórén"); // ["guó", "rén"], not ["guór", "én"]
-splitSyllables("hǎiōu"); // ["hǎi", "ōu"] — missing apostrophe, read anyway
+splitSyllables("hǎiōu"); // ["hǎi", "ōu"], missing apostrophe, read anyway
 readWord("yínháng"); // the same, parsed into Syllable objects
 ```
 
@@ -436,20 +439,21 @@ written at all.
 
 ## Numbers
 
-Reading a number needs no dictionary — arithmetic and about twenty readings —
-so this works with nothing loaded.
+Reading a number needs no dictionary, just arithmetic and about twenty
+readings, so this works with nothing loaded.
 
 ```ts
 import { numeralHanzi, percentHanzi, readNumeral } from "@kensio/pinyinjs";
 
 numeralHanzi(12345); // "一万两千三百四十五"
-numeralHanzi(1005); // "一千零五" — a skipped place is spoken
-numeralHanzi(2000); // "两千" — a leading lone 2 before a big unit
-percentHanzi(95); // "百分之九十五" — the order reverses
+numeralHanzi(1005); // "一千零五", a skipped place is spoken
+numeralHanzi(2000); // "两千", a leading lone 2 before a big unit
+numeralHanzi(2, { counts: true }); // "两", as in 两个西瓜, never 二个
+percentHanzi(95); // "百分之九十五", the order reverses
 ```
 
-The same digits are read two ways and nothing in the number says which — 2026年
-is spelled out and 2026个 is counted — so the style is the caller's:
+The same digits are read two ways and nothing in the number says which, since
+2026年 is spelled out and 2026个 is counted, so the style is the caller's:
 
 ```ts
 numeralHanzi(2026); // "两千零二十六"
@@ -484,7 +488,7 @@ writeIpa(jiu); // "tɕiou˥˩"
 ```
 
 Gwoyeu Romatzyh is the odd one, and it needs no tone mark because the tone is
-spelled into the syllable — which is why 陝西 is Shaanxi in English and 山西 is
+spelled into the syllable, which is why 陝西 is Shaanxi in English and 山西 is
 Shanxi:
 
 ```ts
@@ -496,7 +500,7 @@ Reading Wade-Giles back gives an **array**, because real text drops the
 apostrophes and diacritics that carry the distinctions:
 
 ```ts
-readWadeGilesLoosely("chi¹"); // [jī, qī] — chi is jī, ch'i is qī
+readWadeGilesLoosely("chi¹"); // [jī, qī]: chi is jī, ch'i is qī
 readWadeGilesLoosely("chu¹"); // [zhū, chū, jū, qū]
 ```
 
@@ -514,7 +518,7 @@ array, so it can be switched off and works across word boundaries.
 import { applySandhi, readWord } from "@kensio/pinyinjs";
 
 const buShi = readWord("bùshì") ?? [];
-applySandhi(buShi); // bú shì — 不 flattens before a fourth tone
+applySandhi(buShi); // bú shì, 不 flattens before a fourth tone
 applySandhi(buShi, { yiBu: false }); // unchanged
 
 const niHao = readWord("nǐhǎo") ?? [];
@@ -546,6 +550,7 @@ Both scripts are dictionary keys, so only the locale is an option to pass.
 | `convert(dictionary, text, options?)`                | hanzi → pinyin                                    |
 | `convertPieces(dictionary, text, ...)`               | the same, per syllable, with confidence           |
 | `convertToHtml(dictionary, text, ...)`               | the same, as HTML                                 |
+| `slug(dictionary, text, options?)`                   | hanzi → a URL-safe slug                           |
 | `joinPieces(pieces)` / `toHtml(pieces)`              | render pieces                                     |
 | `isUncertain(confidence)`                            | was this syllable a guess?                        |
 | `dictionary.lookup / hasPrefix / readingsOf`         | query the dictionary                              |

package/dist/cli/arguments.d.ts

@@ -2,6 +2,7 @@ import type { ConvertOptions } from "../decode/convert.js";
 import type { ColourDepth } from "./colour.js";
 import type { Tier } from "../dictionary/tiers.js";
 import type { HtmlOptions } from "../format/html.js";
+import type { SlugOptions } from "../format/slug.js";
 /**
  * Every flag the CLI accepts.
  *
@@ -40,12 +41,39 @@ declare const FLAGS: {
     readonly "keep-numbers": {
         readonly type: "boolean";
     };
+    readonly "read-numbers": {
+        readonly type: "boolean";
+    };
     readonly "third-tone": {
         readonly type: "boolean";
     };
     readonly "no-sandhi": {
         readonly type: "boolean";
     };
+    readonly tones: {
+        readonly type: "string";
+    };
+    readonly separator: {
+        readonly type: "string";
+    };
+    readonly syllables: {
+        readonly type: "string";
+    };
+    readonly umlaut: {
+        readonly type: "string";
+    };
+    readonly hash: {
+        readonly type: "boolean";
+    };
+    readonly "hash-length": {
+        readonly type: "string";
+    };
+    readonly "max-length": {
+        readonly type: "string";
+    };
+    readonly fallback: {
+        readonly type: "string";
+    };
     readonly greedy: {
         readonly type: "boolean";
     };
@@ -110,6 +138,16 @@ export declare const GLOBAL_FLAGS: readonly FlagName[];
  * converts anything.
  */
 export declare const CONVERT_FLAGS: readonly FlagName[];
+/**
+ * The flags `slug` takes, beyond the global ones.
+ *
+ * It shares the reading flags with the conversion commands and none of the
+ * writing ones: a slug settles its own notation, capitals, apostrophes and
+ * spacing, and a `--capitals` that changed nothing would be worse than an
+ * error. `--read-numbers` rather than `--keep-numbers` because a slug keeps
+ * digits by default, which is the one place it departs from `convert`.
+ */
+export declare const SLUG_FLAGS: readonly FlagName[];
 /**
  * The flags a parse produced, before any command has looked at them.
  */
@@ -195,6 +233,13 @@ export declare function dictionaryChoice(flags: Flags): DictionaryChoice;
  * stay the CLI's defaults and there is one place they are written down.
  */
 export declare function convertOptions(flags: Flags): ConvertOptions;
+/**
+ * Turn the slug flags into the options the library takes.
+ *
+ * `--hash-length` implies `--hash`, because asking how long the hash should be
+ * and not getting one is not a reading anybody intends.
+ */
+export declare function slugOptions(flags: Flags): SlugOptions;
 /**
  * The same, plus the two flags that only mean anything in HTML.
  */

package/dist/cli/arguments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arguments.d.ts","sourceRoot":"","sources":["../../src/cli/arguments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"arguments.d.ts","sourceRoot":"","sources":["../../src/cli/arguments.ts"],"names":[],"mappings":"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"}