turkmen-num2words 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1 @@
1
+ * text=auto eol=lf
@@ -0,0 +1,57 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ test:
13
+ name: test (${{ matrix.os }}, py${{ matrix.python }})
14
+ runs-on: ${{ matrix.os }}
15
+ strategy:
16
+ fail-fast: false
17
+ matrix:
18
+ os: [ubuntu-latest, windows-latest, macos-latest]
19
+ python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
20
+ exclude:
21
+ # ubuntu-latest (26.04) has no 3.9 x64 build; cover 3.9 on 22.04 below.
22
+ - os: ubuntu-latest
23
+ python: "3.9"
24
+ include:
25
+ - os: ubuntu-22.04
26
+ python: "3.9"
27
+ steps:
28
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
29
+ with:
30
+ persist-credentials: false
31
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
32
+ with:
33
+ python-version: ${{ matrix.python }}
34
+ - run: python -m pip install -e ".[dev]"
35
+ - run: ruff check .
36
+ - run: ruff format --check .
37
+ - run: pytest -q
38
+
39
+ js:
40
+ name: js (${{ matrix.os }}, node${{ matrix.node }})
41
+ runs-on: ${{ matrix.os }}
42
+ strategy:
43
+ fail-fast: false
44
+ matrix:
45
+ os: [ubuntu-latest, windows-latest, macos-latest]
46
+ node: ["18", "20", "22"]
47
+ defaults:
48
+ run:
49
+ working-directory: js
50
+ steps:
51
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
52
+ with:
53
+ persist-credentials: false
54
+ - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
55
+ with:
56
+ node-version: ${{ matrix.node }}
57
+ - run: node --test
@@ -0,0 +1,90 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ jobs:
11
+ build:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
15
+ with:
16
+ persist-credentials: false
17
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
18
+ with:
19
+ python-version: "3.13"
20
+ - run: python -m pip install build && python -m build
21
+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
22
+ with:
23
+ name: dist
24
+ path: dist/
25
+
26
+ github-release:
27
+ needs: build
28
+ runs-on: ubuntu-latest
29
+ permissions:
30
+ contents: write
31
+ steps:
32
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
33
+ with:
34
+ persist-credentials: false
35
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
36
+ with:
37
+ name: dist
38
+ path: dist/
39
+ - name: Extract changelog section
40
+ env:
41
+ TAG: ${{ github.ref_name }}
42
+ run: |
43
+ awk -v h="## [${TAG#v}]" 'index($0, h) == 1 {f=1; next} /^## / && f {exit} f' CHANGELOG.md > notes.md
44
+ cat notes.md
45
+ - uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4
46
+ with:
47
+ body_path: notes.md
48
+ files: dist/*
49
+
50
+ pypi:
51
+ # Enable by creating a PyPI trusted publisher for this repo and setting repo variable PYPI_PUBLISH=true.
52
+ if: ${{ vars.PYPI_PUBLISH == 'true' }}
53
+ needs: build
54
+ runs-on: ubuntu-latest
55
+ environment: pypi
56
+ permissions:
57
+ id-token: write
58
+ steps:
59
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
60
+ with:
61
+ name: dist
62
+ path: dist/
63
+ - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
64
+
65
+ npm:
66
+ # Enable by setting repo variable NPM_PUBLISH=true. Publishes via npm OIDC
67
+ # trusted publishing (no token): configure a trusted publisher on the npmjs
68
+ # package (@garag0l/turkmen-num2words) for repo garag0l/turkmen-num2words,
69
+ # workflow release.yml.
70
+ if: ${{ vars.NPM_PUBLISH == 'true' }}
71
+ needs: build
72
+ runs-on: ubuntu-latest
73
+ permissions:
74
+ id-token: write
75
+ contents: read
76
+ defaults:
77
+ run:
78
+ working-directory: js
79
+ steps:
80
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
81
+ with:
82
+ persist-credentials: false
83
+ - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
84
+ with:
85
+ node-version: "22"
86
+ registry-url: "https://registry.npmjs.org"
87
+ # OIDC trusted publishing needs npm >= 11.5.1; node 22 ships npm 10.x.
88
+ - run: npm install -g npm@12.2.3
89
+ - run: node --test
90
+ - run: npm publish --access public --provenance
@@ -0,0 +1,8 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .ruff_cache/
8
+ .pytest_cache/
@@ -0,0 +1,29 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.1] - 2026-11-21
8
+
9
+ ### Added
10
+ - JavaScript / TypeScript port in `js/`: the zero-dependency ESM package
11
+ `@garag0l/turkmen-num2words` (`numberToTurkmen`) with TypeScript types and the
12
+ `tm-num` CLI. It shares the Python package's rules and test values and
13
+ reproduces Gray's worked example `1 352 647` exactly.
14
+ - CI job for the JS package across Linux/macOS/Windows on Node 18/20/22.
15
+ - Release workflow publishes the npm package via OIDC trusted publishing.
16
+
17
+ ## [0.1.0] - 2026-11-21
18
+
19
+ Initial release.
20
+
21
+ ### Added
22
+ - `number_to_turkmen(n)` in the `turkmen_num2words` package (zero dependencies):
23
+ converts integers to Turkmen Latin cardinal words for `-(10**12) < n < 10**12`.
24
+ - `tm-num` command-line tool (args, stdin, multiple numbers, error exit codes).
25
+ - Composition grounded in Wiktionary's Turkmen numerals and reproducing Gray's
26
+ worked example `1 352 647` exactly; `ýüz`/`müň` drop "bir", `million`/
27
+ `milliard` keep it. Every decision and spelling variant is in
28
+ `docs/numbers.md`.
29
+ - CI across Linux/macOS/Windows on Python 3.9–3.13.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Murat Bekgi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,142 @@
1
+ Metadata-Version: 2.5
2
+ Name: turkmen-num2words
3
+ Version: 0.1.1
4
+ Summary: Convert integers to Turkmen (Latin) cardinal-number words.
5
+ Project-URL: Homepage, https://github.com/garag0l/turkmen-num2words
6
+ Project-URL: Issues, https://github.com/garag0l/turkmen-num2words/issues
7
+ Author: Murat Bekgi
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: nlp,num2words,numbers,spellout,turkmen,turkmenistan
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Natural Language :: Turkish
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Text Processing :: Linguistic
17
+ Requires-Python: >=3.9
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest; extra == 'dev'
20
+ Requires-Dist: ruff; extra == 'dev'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # turkmen-num2words
24
+
25
+ **Spell out integers in Turkmen: `1234` → `"müň iki ýüz otuz dört"`.**
26
+
27
+ [![CI](https://github.com/garag0l/turkmen-num2words/actions/workflows/ci.yml/badge.svg)](https://github.com/garag0l/turkmen-num2words/actions/workflows/ci.yml)
28
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
29
+ ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
30
+ ![Node 18+](https://img.shields.io/badge/node-18%2B-blue)
31
+ ![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
32
+
33
+ A zero-dependency library and CLI that converts integers into Turkmen
34
+ cardinal-number words, in the modern Latin alphabet. Useful for text-to-speech,
35
+ language learning, receipts and invoices, and spelling out amounts. Available
36
+ for both **Python** and **JavaScript/TypeScript**.
37
+
38
+ ```console
39
+ $ tm-num 1352647
40
+ bir million üç ýüz elli iki müň alty ýüz kyrk ýedi
41
+ $ tm-num 0 100 1000 -5
42
+ nol
43
+ ýüz
44
+ müň
45
+ minus bäş
46
+ ```
47
+
48
+ ## Why trust the output
49
+
50
+ The numbers come straight from primary sources, and the library reproduces the
51
+ one authoritative worked example exactly:
52
+
53
+ > **1 352 647** → `bir million üç ýüz elli iki müň alty ýüz kyrk ýedi`
54
+ > — *A Short Descriptive Grammar of Turkmen*, R. Gray (SIL).
55
+
56
+ Every spelling and composition decision — why `100` is `ýüz` (not `bir ýüz`) but
57
+ `1 000 000` is `bir million`, which spelling of 90 and zero are standard, where
58
+ the range stops — is documented in [docs/numbers.md](docs/numbers.md), with the
59
+ alternatives listed for transparency.
60
+
61
+ ## Install
62
+
63
+ ```bash
64
+ pipx install turkmen-num2words # for the tm-num command
65
+ # or
66
+ pip install turkmen-num2words # for the library
67
+ ```
68
+
69
+ Python 3.9+, no third-party dependencies.
70
+
71
+ ## Use
72
+
73
+ ```python
74
+ from turkmen_num2words import number_to_turkmen
75
+
76
+ number_to_turkmen(21) # 'ýigrimi bir'
77
+ number_to_turkmen(100) # 'ýüz'
78
+ number_to_turkmen(2000) # 'iki müň'
79
+ number_to_turkmen(1000000) # 'bir million'
80
+ number_to_turkmen(-5) # 'minus bäş'
81
+ ```
82
+
83
+ ```bash
84
+ tm-num 42 # one number
85
+ tm-num 7 42 100 # several (one line each)
86
+ echo "99 100" | tm-num # from stdin
87
+ ```
88
+
89
+ ### JavaScript / TypeScript
90
+
91
+ The npm package [`@garag0l/turkmen-num2words`](https://www.npmjs.com/package/@garag0l/turkmen-num2words)
92
+ (in [`js/`](js/)) shares the same rules and test values.
93
+
94
+ ```bash
95
+ npm install @garag0l/turkmen-num2words
96
+ ```
97
+
98
+ ```js
99
+ import { numberToTurkmen } from "@garag0l/turkmen-num2words";
100
+
101
+ numberToTurkmen(1234); // "müň iki ýüz otuz dört"
102
+ numberToTurkmen(-5); // "minus bäş"
103
+ ```
104
+
105
+ ```bash
106
+ npx tm-num 1234 # müň iki ýüz otuz dört
107
+ ```
108
+
109
+ ## Range
110
+
111
+ Supports `-(10¹²) < n < 10¹²`. Values at or beyond 10¹² raise `ValueError`,
112
+ because the Turkmen word for a trillion isn't reliably attested — the library
113
+ refuses to guess rather than print something wrong.
114
+
115
+ ## Tested
116
+
117
+ - A table of known values from `0` through `999 999 999 999`, the Gray compound
118
+ example, the `ýüz/müň` drop-"bir" rule vs `million/milliard` keep-"bir",
119
+ negatives, range limits, and type errors.
120
+ - The CLI (args, stdin, multiple numbers, error exit codes).
121
+ - CI on Linux/macOS/Windows across Python 3.9–3.13.
122
+
123
+ ## Roadmap
124
+
125
+ - Ordinals (`birinji`, `ikinji`, …) with correct vowel harmony.
126
+ - Pairs well with [turkmen-translit](https://github.com/garag0l/turkmen-translit)
127
+ for full Turkmen text handling.
128
+
129
+ ## Contributing
130
+
131
+ Issues and PRs welcome — especially sourced corrections to spellings or the
132
+ trillion-and-up scale words.
133
+
134
+ ```bash
135
+ python -m venv .venv && . .venv/bin/activate
136
+ pip install -e ".[dev]"
137
+ pytest && ruff check .
138
+ ```
139
+
140
+ ## License
141
+
142
+ [MIT](LICENSE). Built by [Murat Bekgi](https://muratbekgi.com).
@@ -0,0 +1,120 @@
1
+ # turkmen-num2words
2
+
3
+ **Spell out integers in Turkmen: `1234` → `"müň iki ýüz otuz dört"`.**
4
+
5
+ [![CI](https://github.com/garag0l/turkmen-num2words/actions/workflows/ci.yml/badge.svg)](https://github.com/garag0l/turkmen-num2words/actions/workflows/ci.yml)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
+ ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
8
+ ![Node 18+](https://img.shields.io/badge/node-18%2B-blue)
9
+ ![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
10
+
11
+ A zero-dependency library and CLI that converts integers into Turkmen
12
+ cardinal-number words, in the modern Latin alphabet. Useful for text-to-speech,
13
+ language learning, receipts and invoices, and spelling out amounts. Available
14
+ for both **Python** and **JavaScript/TypeScript**.
15
+
16
+ ```console
17
+ $ tm-num 1352647
18
+ bir million üç ýüz elli iki müň alty ýüz kyrk ýedi
19
+ $ tm-num 0 100 1000 -5
20
+ nol
21
+ ýüz
22
+ müň
23
+ minus bäş
24
+ ```
25
+
26
+ ## Why trust the output
27
+
28
+ The numbers come straight from primary sources, and the library reproduces the
29
+ one authoritative worked example exactly:
30
+
31
+ > **1 352 647** → `bir million üç ýüz elli iki müň alty ýüz kyrk ýedi`
32
+ > — *A Short Descriptive Grammar of Turkmen*, R. Gray (SIL).
33
+
34
+ Every spelling and composition decision — why `100` is `ýüz` (not `bir ýüz`) but
35
+ `1 000 000` is `bir million`, which spelling of 90 and zero are standard, where
36
+ the range stops — is documented in [docs/numbers.md](docs/numbers.md), with the
37
+ alternatives listed for transparency.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pipx install turkmen-num2words # for the tm-num command
43
+ # or
44
+ pip install turkmen-num2words # for the library
45
+ ```
46
+
47
+ Python 3.9+, no third-party dependencies.
48
+
49
+ ## Use
50
+
51
+ ```python
52
+ from turkmen_num2words import number_to_turkmen
53
+
54
+ number_to_turkmen(21) # 'ýigrimi bir'
55
+ number_to_turkmen(100) # 'ýüz'
56
+ number_to_turkmen(2000) # 'iki müň'
57
+ number_to_turkmen(1000000) # 'bir million'
58
+ number_to_turkmen(-5) # 'minus bäş'
59
+ ```
60
+
61
+ ```bash
62
+ tm-num 42 # one number
63
+ tm-num 7 42 100 # several (one line each)
64
+ echo "99 100" | tm-num # from stdin
65
+ ```
66
+
67
+ ### JavaScript / TypeScript
68
+
69
+ The npm package [`@garag0l/turkmen-num2words`](https://www.npmjs.com/package/@garag0l/turkmen-num2words)
70
+ (in [`js/`](js/)) shares the same rules and test values.
71
+
72
+ ```bash
73
+ npm install @garag0l/turkmen-num2words
74
+ ```
75
+
76
+ ```js
77
+ import { numberToTurkmen } from "@garag0l/turkmen-num2words";
78
+
79
+ numberToTurkmen(1234); // "müň iki ýüz otuz dört"
80
+ numberToTurkmen(-5); // "minus bäş"
81
+ ```
82
+
83
+ ```bash
84
+ npx tm-num 1234 # müň iki ýüz otuz dört
85
+ ```
86
+
87
+ ## Range
88
+
89
+ Supports `-(10¹²) < n < 10¹²`. Values at or beyond 10¹² raise `ValueError`,
90
+ because the Turkmen word for a trillion isn't reliably attested — the library
91
+ refuses to guess rather than print something wrong.
92
+
93
+ ## Tested
94
+
95
+ - A table of known values from `0` through `999 999 999 999`, the Gray compound
96
+ example, the `ýüz/müň` drop-"bir" rule vs `million/milliard` keep-"bir",
97
+ negatives, range limits, and type errors.
98
+ - The CLI (args, stdin, multiple numbers, error exit codes).
99
+ - CI on Linux/macOS/Windows across Python 3.9–3.13.
100
+
101
+ ## Roadmap
102
+
103
+ - Ordinals (`birinji`, `ikinji`, …) with correct vowel harmony.
104
+ - Pairs well with [turkmen-translit](https://github.com/garag0l/turkmen-translit)
105
+ for full Turkmen text handling.
106
+
107
+ ## Contributing
108
+
109
+ Issues and PRs welcome — especially sourced corrections to spellings or the
110
+ trillion-and-up scale words.
111
+
112
+ ```bash
113
+ python -m venv .venv && . .venv/bin/activate
114
+ pip install -e ".[dev]"
115
+ pytest && ruff check .
116
+ ```
117
+
118
+ ## License
119
+
120
+ [MIT](LICENSE). Built by [Murat Bekgi](https://muratbekgi.com).
@@ -0,0 +1,67 @@
1
+ # Turkmen number-word decisions
2
+
3
+ Every spelling and composition choice this library makes, with its source.
4
+
5
+ ## Sources
6
+
7
+ - **Wiktionary, Appendix:Turkmen numerals** — 0 = `nol`; units; tens; `ýüz`
8
+ (100, listed alone, not `bir ýüz`); `müň` (1000).
9
+ - **R. Gray, *A Short Descriptive Grammar of Turkmen* (SIL)** — the worked
10
+ compound `1,352,647 = "bir million üç ýüz elli iki müň alty ýüz kyrk ýedi"`,
11
+ which this library reproduces exactly (pinned in the tests).
12
+ - **Wiktionary translation table** — `milliard` for 10⁹ (long-scale, as in many
13
+ European languages and via Russian).
14
+
15
+ ## Letters
16
+
17
+ | Value | Word | | Value | Word |
18
+ |---|---|---|---|---|
19
+ | 0 | nol | | 10 | on |
20
+ | 1 | bir | | 20 | ýigrimi |
21
+ | 2 | iki | | 30 | otuz |
22
+ | 3 | üç | | 40 | kyrk |
23
+ | 4 | dört | | 50 | elli |
24
+ | 5 | bäş | | 60 | altmyş |
25
+ | 6 | alty | | 70 | ýetmiş |
26
+ | 7 | ýedi | | 80 | segsen |
27
+ | 8 | sekiz | | 90 | togsan |
28
+ | 9 | dokuz | | 100 | ýüz |
29
+ | | | | 1000 | müň |
30
+ | | | | 10⁶ | million |
31
+ | | | | 10⁹ | milliard |
32
+
33
+ ## Composition
34
+
35
+ - A multiplier comes **before** its scale word: `iki ýüz` (200), `üç müň` (3000).
36
+ - `ýüz` (100) and `müň` (1000) **drop** the multiplier when it is 1:
37
+ `100 → ýüz`, `1000 → müň` (not `bir ýüz`, not `bir müň`).
38
+ - The borrowed scale words `million` and `milliard` **keep** the multiplier:
39
+ `1 000 000 → bir million`, `1 000 000 000 → bir milliard`. This matches Gray's
40
+ example and the wider Turkic pattern (cf. Turkish *yüz / bin* vs *bir milyon*).
41
+ - Tens and units are separate words: `otuz iki` (32), `togsan dokuz` (99).
42
+ - Negative numbers are prefixed with `minus` (a loan; the common spoken form).
43
+
44
+ ## Range
45
+
46
+ Supported: `-(10¹²) < n < 10¹²`. The Turkmen term for 10¹² (trillion) is not
47
+ reliably attested in the sources above, so values at or beyond 10¹² raise
48
+ `ValueError` rather than guess.
49
+
50
+ ## Spelling variants (not used, recorded for transparency)
51
+
52
+ - **0:** some learner materials show `nul` (Russian влияние); the standard
53
+ literary form is `nol`.
54
+ - **10⁶:** `milýon` appears in some sources; this library uses `million`
55
+ (Gray's grammar).
56
+ - **90:** `dogsan` appears dialectally; the standard form is `togsan`.
57
+
58
+ If you need a different convention for your domain, open an issue — these are
59
+ easy to make configurable.
60
+
61
+ ## Not yet covered
62
+
63
+ - Ordinals (`birinji`, `ikinji`, …), which add a vowel-harmonic suffix.
64
+ - Fractions and decimals.
65
+
66
+ These are deliberately out of scope for 0.1.0 so the cardinal output stays
67
+ fully verified.
@@ -0,0 +1,54 @@
1
+ # @garag0l/turkmen-num2words
2
+
3
+ Spell out integers in **Turkmen** (modern Latin) cardinal words. Zero
4
+ dependencies, ESM, with TypeScript types. The JavaScript port of the Python
5
+ package [`turkmen-num2words`](https://github.com/garag0l/turkmen-num2words);
6
+ both share the same rules and test values.
7
+
8
+ ```js
9
+ import { numberToTurkmen } from "@garag0l/turkmen-num2words";
10
+
11
+ numberToTurkmen(1234); // "müň iki ýüz otuz dört"
12
+ numberToTurkmen(1352647); // "bir million üç ýüz elli iki müň alty ýüz kyrk ýedi"
13
+ numberToTurkmen(-5); // "minus bäş"
14
+ ```
15
+
16
+ ## Install
17
+
18
+ ```sh
19
+ npm install @garag0l/turkmen-num2words
20
+ ```
21
+
22
+ ## CLI
23
+
24
+ ```sh
25
+ npx tm-num 1234 # müň iki ýüz otuz dört
26
+ npx tm-num 7 42 100 # one line per number
27
+ echo "99 100" | npx tm-num # read integers from stdin
28
+ ```
29
+
30
+ ## API
31
+
32
+ ### `numberToTurkmen(n)`
33
+
34
+ Returns the Turkmen cardinal words for the integer `n`. Supports
35
+ `-(10 ** 12) < n < 10 ** 12`.
36
+
37
+ - Throws `TypeError` if `n` is not a safe integer.
38
+ - Throws `RangeError` if `n` is outside the supported range. The Turkmen term
39
+ for 10¹² is not reliably attested, so the library refuses it rather than
40
+ guess.
41
+
42
+ ## How the words are built
43
+
44
+ A multiplier precedes its scale word (`iki ýüz`, `üç müň`). The scale words
45
+ `ýüz` (100) and `müň` (1000) **drop** the multiplier `bir` when it is 1, while
46
+ the borrowed `million` (10⁶) and `milliard` (10⁹) **keep** it — so `100` is
47
+ `ýüz` but `1 000 000` is `bir million`. Every decision and the spelling variants
48
+ are documented in [`docs/numbers.md`](../docs/numbers.md). The composition is
49
+ grounded in Wiktionary's Appendix:Turkmen numerals and reproduces the worked
50
+ example from R. Gray's *A Short Descriptive Grammar of Turkmen* exactly.
51
+
52
+ ## License
53
+
54
+ MIT © Murat Bekgi. For authorized testing and defense only.
@@ -0,0 +1,66 @@
1
+ #!/usr/bin/env node
2
+ // CLI for @garag0l/turkmen-num2words. Mirrors the Python tm-num command.
3
+ //
4
+ // tm-num 1234 -> müň iki ýüz otuz dört
5
+ // tm-num 7 42 100 -> one line per number
6
+ // echo "99 100" | tm-num -> read integers from stdin
7
+
8
+ import { numberToTurkmen } from "../src/index.js";
9
+
10
+ const USAGE = `tm-num — spell out integers in Turkmen (modern Latin)
11
+
12
+ Usage:
13
+ tm-num 1234 convert one integer
14
+ tm-num 7 42 100 convert several (one line each)
15
+ echo "99 100" | tm-num read integers from stdin
16
+ tm-num --help | --version
17
+ `;
18
+
19
+ function emit(token) {
20
+ if (!/^[+-]?\d+$/.test(token)) {
21
+ return { line: `error: not an integer: ${JSON.stringify(token)}`, error: true };
22
+ }
23
+ try {
24
+ return { line: numberToTurkmen(Number(token)), error: false };
25
+ } catch (err) {
26
+ return { line: `error: ${err.message}`, error: true };
27
+ }
28
+ }
29
+
30
+ async function readStdin() {
31
+ const chunks = [];
32
+ for await (const chunk of process.stdin) chunks.push(chunk);
33
+ return Buffer.concat(chunks).toString("utf8");
34
+ }
35
+
36
+ async function main(argv) {
37
+ const tokens = [];
38
+ for (const arg of argv) {
39
+ if (arg === "--help" || arg === "-h") {
40
+ process.stdout.write(USAGE);
41
+ return 0;
42
+ }
43
+ if (arg === "--version" || arg === "-V") {
44
+ const { readFileSync } = await import("node:fs");
45
+ const pkg = JSON.parse(
46
+ readFileSync(new URL("../package.json", import.meta.url), "utf8"),
47
+ );
48
+ process.stdout.write(`turkmen-num2words ${pkg.version}\n`);
49
+ return 0;
50
+ }
51
+ tokens.push(arg);
52
+ }
53
+
54
+ const words = tokens.length ? tokens : (await readStdin()).split(/\s+/).filter(Boolean);
55
+ if (words.length === 0) return 0;
56
+
57
+ let hadError = false;
58
+ for (const token of words) {
59
+ const { line, error } = emit(token);
60
+ if (error) hadError = true;
61
+ process.stdout.write(line + "\n");
62
+ }
63
+ return hadError ? 1 : 0;
64
+ }
65
+
66
+ main(process.argv.slice(2)).then((code) => process.exit(code));
@@ -0,0 +1,48 @@
1
+ {
2
+ "name": "@garag0l/turkmen-num2words",
3
+ "version": "0.1.1",
4
+ "description": "Spell out integers in Turkmen (modern Latin) cardinal words. Zero dependencies.",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "types": "src/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./src/index.d.ts",
11
+ "default": "./src/index.js"
12
+ }
13
+ },
14
+ "bin": {
15
+ "tm-num": "bin/tm-num.js"
16
+ },
17
+ "files": [
18
+ "src",
19
+ "bin",
20
+ "README.md"
21
+ ],
22
+ "scripts": {
23
+ "test": "node --test"
24
+ },
25
+ "keywords": [
26
+ "turkmen",
27
+ "turkmenistan",
28
+ "numbers",
29
+ "number-to-words",
30
+ "num2words",
31
+ "cardinal",
32
+ "nlp"
33
+ ],
34
+ "author": "Murat Bekgi",
35
+ "license": "MIT",
36
+ "homepage": "https://github.com/garag0l/turkmen-num2words#readme",
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "git+https://github.com/garag0l/turkmen-num2words.git",
40
+ "directory": "js"
41
+ },
42
+ "bugs": {
43
+ "url": "https://github.com/garag0l/turkmen-num2words/issues"
44
+ },
45
+ "engines": {
46
+ "node": ">=18"
47
+ }
48
+ }
@@ -0,0 +1,24 @@
1
+ // Type declarations for @garag0l/turkmen-num2words.
2
+
3
+ /** The word for zero ("nol"). */
4
+ export declare const ZERO: string;
5
+
6
+ /** The prefix used for negative numbers ("minus"). */
7
+ export declare const NEGATIVE_PREFIX: string;
8
+
9
+ /** Exclusive upper bound of the supported range (10 ** 12). */
10
+ export declare const MAX: number;
11
+
12
+ /**
13
+ * Return the Turkmen (modern Latin) cardinal words for the integer `n`.
14
+ *
15
+ * Supports `-(10 ** 12) < n < 10 ** 12`.
16
+ *
17
+ * @throws {TypeError} if `n` is not a safe integer.
18
+ * @throws {RangeError} if `n` is outside the supported range.
19
+ *
20
+ * @example
21
+ * numberToTurkmen(1234); // "müň iki ýüz otuz dört"
22
+ * numberToTurkmen(-5); // "minus bäş"
23
+ */
24
+ export declare function numberToTurkmen(n: number): string;
@@ -0,0 +1,4 @@
1
+ // Public API for @garag0l/turkmen-num2words (zero dependencies, ESM).
2
+ // Mirrors the Python package turkmen_num2words.
3
+
4
+ export { numberToTurkmen, ZERO, NEGATIVE_PREFIX, MAX } from "./numbers.js";
@@ -0,0 +1,103 @@
1
+ // Convert integers to their Turkmen (modern Latin) cardinal-number words.
2
+ // Zero dependencies, ESM. Mirrors the Python package turkmen_num2words; see
3
+ // ../../docs/numbers.md for every decision and the spelling variants.
4
+ //
5
+ // Grounded in Wiktionary's Appendix:Turkmen numerals and R. Gray's "A Short
6
+ // Descriptive Grammar of Turkmen" (SIL), whose worked example
7
+ // 1,352,647 = "bir million üç ýüz elli iki müň alty ýüz kyrk ýedi" this module
8
+ // reproduces exactly (see test/numbers.test.js).
9
+ //
10
+ // Composition rule (same family as Turkish): a multiplier precedes its scale
11
+ // word (iki ýüz, üç müň). The scale words ýüz (100) and müň (1000) DROP the
12
+ // multiplier "bir" when it is 1, while the borrowed scale words million (1e6)
13
+ // and milliard (1e9) KEEP it (1,000,000 = "bir million").
14
+
15
+ export const ZERO = "nol";
16
+ export const NEGATIVE_PREFIX = "minus";
17
+
18
+ // Units 1-9 (index 0 unused).
19
+ const UNITS = ["", "bir", "iki", "üç", "dört", "bäş", "alty", "ýedi", "sekiz", "dokuz"];
20
+
21
+ // Tens 10-90 indexed by the tens digit (1 -> 10, ... 9 -> 90).
22
+ const TENS = ["", "on", "ýigrimi", "otuz", "kyrk", "elli", "altmyş", "ýetmiş", "segsen", "togsan"];
23
+
24
+ const HUNDRED = "ýüz";
25
+
26
+ // Scale words for each 1000-group, from the least significant.
27
+ // [word, keepBir]: ýüz/müň drop "bir" at 1; million/milliard keep it.
28
+ const SCALES = [
29
+ ["", false], // 1e0 group: the final 0-999
30
+ ["müň", false], // 1e3
31
+ ["million", true], // 1e6
32
+ ["milliard", true], // 1e9
33
+ ];
34
+
35
+ // 1e12; the Turkmen term for 10**12 is not reliably attested, so we stop here.
36
+ export const MAX = 1000 ** SCALES.length;
37
+
38
+ function belowThousand(n) {
39
+ // Words for 1..999 (n must be in that range).
40
+ const parts = [];
41
+ const hundreds = Math.floor(n / 100);
42
+ const rest = n % 100;
43
+ if (hundreds) {
44
+ if (hundreds > 1) parts.push(UNITS[hundreds]); // 100 -> "ýüz"; 200 -> "iki ýüz"
45
+ parts.push(HUNDRED);
46
+ }
47
+ if (rest) {
48
+ const tens = Math.floor(rest / 10);
49
+ const units = rest % 10;
50
+ if (tens) parts.push(TENS[tens]);
51
+ if (units) parts.push(UNITS[units]);
52
+ }
53
+ return parts.join(" ");
54
+ }
55
+
56
+ /**
57
+ * Return the Turkmen cardinal words for the integer `n`.
58
+ *
59
+ * Supports -(10**12) < n < 10**12. Throws RangeError outside that range
60
+ * (the Turkmen term for 10**12 is not reliably attested) and TypeError for
61
+ * anything that is not a safe integer.
62
+ */
63
+ export function numberToTurkmen(n) {
64
+ if (typeof n !== "number" || !Number.isInteger(n)) {
65
+ throw new TypeError(`expected an integer, got ${describe(n)}`);
66
+ }
67
+ if (n === 0) return ZERO;
68
+ if (n < 0) return `${NEGATIVE_PREFIX} ${numberToTurkmen(-n)}`;
69
+ if (n >= MAX) {
70
+ throw new RangeError(
71
+ `${n} is out of range; supported range is 0 .. ${MAX - 1} ` +
72
+ "(the Turkmen word for 10**12 is not reliably attested)",
73
+ );
74
+ }
75
+
76
+ // Split into 1000-groups, least significant first.
77
+ const groups = [];
78
+ let rem = n;
79
+ while (rem) {
80
+ groups.push(rem % 1000);
81
+ rem = Math.floor(rem / 1000);
82
+ }
83
+
84
+ const chunks = []; // most significant first
85
+ for (let idx = groups.length - 1; idx >= 0; idx -= 1) {
86
+ const value = groups[idx];
87
+ if (value === 0) continue;
88
+ const [scaleWord, keepBir] = SCALES[idx];
89
+ if (scaleWord === "") {
90
+ chunks.push(belowThousand(value));
91
+ } else if (value === 1 && !keepBir) {
92
+ chunks.push(scaleWord); // müň / ýüz: drop "bir"
93
+ } else {
94
+ chunks.push(`${belowThousand(value)} ${scaleWord}`);
95
+ }
96
+ }
97
+ return chunks.join(" ");
98
+ }
99
+
100
+ function describe(value) {
101
+ if (typeof value === "number") return `the non-integer number ${value}`;
102
+ return typeof value;
103
+ }
@@ -0,0 +1,99 @@
1
+ import assert from "node:assert/strict";
2
+ import { test } from "node:test";
3
+
4
+ import { numberToTurkmen as tn, MAX } from "../src/index.js";
5
+
6
+ // Verified against Wiktionary Appendix:Turkmen numerals and Gray's grammar.
7
+ const KNOWN = {
8
+ 0: "nol",
9
+ 1: "bir",
10
+ 2: "iki",
11
+ 3: "üç",
12
+ 4: "dört",
13
+ 5: "bäş",
14
+ 6: "alty",
15
+ 7: "ýedi",
16
+ 8: "sekiz",
17
+ 9: "dokuz",
18
+ 10: "on",
19
+ 11: "on bir",
20
+ 15: "on bäş",
21
+ 19: "on dokuz",
22
+ 20: "ýigrimi",
23
+ 21: "ýigrimi bir",
24
+ 32: "otuz iki",
25
+ 40: "kyrk",
26
+ 55: "elli bäş",
27
+ 60: "altmyş",
28
+ 70: "ýetmiş",
29
+ 80: "segsen",
30
+ 90: "togsan",
31
+ 99: "togsan dokuz",
32
+ 100: "ýüz",
33
+ 101: "ýüz bir",
34
+ 150: "ýüz elli",
35
+ 200: "iki ýüz",
36
+ 555: "bäş ýüz elli bäş",
37
+ 999: "dokuz ýüz togsan dokuz",
38
+ 1000: "müň",
39
+ 1001: "müň bir",
40
+ 1234: "müň iki ýüz otuz dört",
41
+ 2000: "iki müň",
42
+ 352000: "üç ýüz elli iki müň",
43
+ 1000000: "bir million",
44
+ 2000000: "iki million",
45
+ 1000000000: "bir milliard",
46
+ };
47
+
48
+ test("known values match primary sources", () => {
49
+ for (const [n, expected] of Object.entries(KNOWN)) {
50
+ assert.equal(tn(Number(n)), expected, `n=${n}`);
51
+ }
52
+ });
53
+
54
+ test("Gray worked example (the authoritative compound)", () => {
55
+ assert.equal(tn(1352647), "bir million üç ýüz elli iki müň alty ýüz kyrk ýedi");
56
+ });
57
+
58
+ test("ýüz/müň drop bir, million/milliard keep it", () => {
59
+ assert.equal(tn(100), "ýüz"); // not "bir ýüz"
60
+ assert.equal(tn(1000), "müň"); // not "bir müň"
61
+ assert.equal(tn(1000000), "bir million");
62
+ assert.equal(tn(1000000000), "bir milliard");
63
+ });
64
+
65
+ test("negatives", () => {
66
+ assert.equal(tn(-1), "minus bir");
67
+ assert.equal(tn(-100), "minus ýüz");
68
+ assert.equal(tn(-1352647), "minus bir million üç ýüz elli iki müň alty ýüz kyrk ýedi");
69
+ });
70
+
71
+ test("maximum supported value", () => {
72
+ assert.equal(
73
+ tn(999999999999),
74
+ "dokuz ýüz togsan dokuz milliard " +
75
+ "dokuz ýüz togsan dokuz million " +
76
+ "dokuz ýüz togsan dokuz müň " +
77
+ "dokuz ýüz togsan dokuz",
78
+ );
79
+ });
80
+
81
+ test("out-of-range throws RangeError", () => {
82
+ assert.throws(() => tn(MAX), RangeError);
83
+ assert.throws(() => tn(1000000000000), RangeError);
84
+ assert.throws(() => tn(-MAX), RangeError);
85
+ });
86
+
87
+ test("non-integers throw TypeError", () => {
88
+ for (const bad of [1.5, NaN, Infinity, "5", null, undefined, true, 10n]) {
89
+ assert.throws(() => tn(bad), TypeError, `input=${String(bad)}`);
90
+ }
91
+ });
92
+
93
+ test("output never has double spaces or edge whitespace", () => {
94
+ for (let n = 0; n <= 2000; n += 1) {
95
+ const out = tn(n);
96
+ assert.doesNotMatch(out, /\s{2,}/, `n=${n}`);
97
+ assert.equal(out, out.trim(), `n=${n}`);
98
+ }
99
+ });
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "turkmen-num2words"
7
+ dynamic = ["version"]
8
+ description = "Convert integers to Turkmen (Latin) cardinal-number words."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Murat Bekgi" }]
14
+ keywords = ["turkmen", "turkmenistan", "numbers", "num2words", "nlp", "spellout"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Natural Language :: Turkish",
20
+ "Programming Language :: Python :: 3",
21
+ "Topic :: Text Processing :: Linguistic",
22
+ ]
23
+ dependencies = []
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/garag0l/turkmen-num2words"
27
+ Issues = "https://github.com/garag0l/turkmen-num2words/issues"
28
+
29
+ [project.scripts]
30
+ tm-num = "turkmen_num2words.cli:main"
31
+
32
+ [project.optional-dependencies]
33
+ dev = ["pytest", "ruff"]
34
+
35
+ [tool.hatch.version]
36
+ path = "src/turkmen_num2words/__init__.py"
37
+
38
+ [tool.hatch.build.targets.wheel]
39
+ packages = ["src/turkmen_num2words"]
40
+
41
+ [tool.ruff]
42
+ line-length = 100
@@ -0,0 +1,13 @@
1
+ """turkmen-num2words: integers to Turkmen (Latin) cardinal words.
2
+
3
+ >>> from turkmen_num2words import number_to_turkmen
4
+ >>> number_to_turkmen(1352647)
5
+ 'bir million üç ýüz elli iki müň alty ýüz kyrk ýedi'
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from .numbers import number_to_turkmen
11
+
12
+ __all__ = ["__version__", "number_to_turkmen"]
13
+ __version__ = "0.1.1"
@@ -0,0 +1,65 @@
1
+ """CLI for turkmen-num2words.
2
+
3
+ tm-num 1234 -> müň iki ýüz otuz dört
4
+ tm-num 7 42 100 -> one line per number
5
+ echo "99\n100" | tm-num -> read integers from stdin (one per line)
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import sys
12
+
13
+ from . import __version__
14
+ from .numbers import number_to_turkmen
15
+
16
+
17
+ def build_parser() -> argparse.ArgumentParser:
18
+ p = argparse.ArgumentParser(
19
+ prog="tm-num",
20
+ description="Convert integers to Turkmen cardinal-number words.",
21
+ )
22
+ p.add_argument("numbers", nargs="*", help="integers to convert (or read stdin)")
23
+ p.add_argument("--version", action="version", version=f"turkmen-num2words {__version__}")
24
+ return p
25
+
26
+
27
+ def _emit(value: str) -> str:
28
+ try:
29
+ n = int(value)
30
+ except ValueError:
31
+ return f"error: not an integer: {value!r}"
32
+ try:
33
+ return number_to_turkmen(n)
34
+ except (ValueError, TypeError) as exc:
35
+ return f"error: {exc}"
36
+
37
+
38
+ def main(argv: list[str] | None = None) -> int:
39
+ args = build_parser().parse_args(argv)
40
+ tokens: list[str] = []
41
+ if args.numbers:
42
+ tokens = args.numbers
43
+ else:
44
+ tokens = sys.stdin.read().split()
45
+ if not tokens:
46
+ return 0
47
+
48
+ reconfigure = getattr(sys.stdout, "reconfigure", None)
49
+ if callable(reconfigure):
50
+ try:
51
+ reconfigure(encoding="utf-8")
52
+ except (ValueError, OSError):
53
+ pass
54
+
55
+ had_error = False
56
+ for tok in tokens:
57
+ line = _emit(tok)
58
+ if line.startswith("error:"):
59
+ had_error = True
60
+ sys.stdout.write(line + "\n")
61
+ return 1 if had_error else 0
62
+
63
+
64
+ if __name__ == "__main__":
65
+ raise SystemExit(main())
@@ -0,0 +1,104 @@
1
+ """Convert integers to their Turkmen (modern Latin) cardinal-number words.
2
+
3
+ Grounded in:
4
+ - Wiktionary, Appendix:Turkmen numerals (0 nol; units; tens; ýüz; müň).
5
+ - A Short Descriptive Grammar of Turkmen (R. Gray, SIL), whose worked example
6
+ 1,352,647 = "bir million üç ýüz elli iki müň alty ýüz kyrk ýedi" this module
7
+ reproduces exactly (see tests).
8
+
9
+ Composition rule (same family as Turkish): a multiplier precedes its scale word
10
+ (iki ýüz, üç müň). The scale words ýüz (100) and müň (1000) DROP the multiplier
11
+ "bir" when it is 1 (so 100 = "ýüz", 1000 = "müň"), while the borrowed scale words
12
+ million (1e6) and milliard (1e9) KEEP it (1,000,000 = "bir million"). See
13
+ docs/numbers.md for every decision and the spelling variants.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ ZERO = "nol"
19
+ NEGATIVE_PREFIX = "minus"
20
+
21
+ # Units 1-9.
22
+ _UNITS = ["", "bir", "iki", "üç", "dört", "bäş", "alty", "ýedi", "sekiz", "dokuz"]
23
+
24
+ # Tens 10-90 indexed by the tens digit (index 1 -> 10, ... 9 -> 90).
25
+ _TENS = ["", "on", "ýigrimi", "otuz", "kyrk", "elli", "altmyş", "ýetmiş", "segsen", "togsan"]
26
+
27
+ _HUNDRED = "ýüz"
28
+
29
+ # Scale words for each 1000-group, from the least significant.
30
+ # (word, keep_bir): ýüz/müň drop "bir" at 1; million/milliard keep it.
31
+ _SCALES = [
32
+ ("", False), # 1e0 group: the final 0-999
33
+ ("müň", False), # 1e3
34
+ ("million", True), # 1e6
35
+ ("milliard", True), # 1e9
36
+ ]
37
+
38
+ _MAX = 1000 ** len(_SCALES) # 1e12; trillion term is unverified, so we stop here.
39
+
40
+
41
+ def _below_thousand(n: int) -> str:
42
+ """Words for 1..999 (n must be in that range)."""
43
+ parts: list[str] = []
44
+ hundreds, rest = divmod(n, 100)
45
+ if hundreds:
46
+ # 100 -> "ýüz"; 200 -> "iki ýüz".
47
+ if hundreds > 1:
48
+ parts.append(_UNITS[hundreds])
49
+ parts.append(_HUNDRED)
50
+ if rest:
51
+ tens, units = divmod(rest, 10)
52
+ if tens:
53
+ parts.append(_TENS[tens])
54
+ if units:
55
+ parts.append(_UNITS[units])
56
+ return " ".join(parts)
57
+
58
+
59
+ def number_to_turkmen(n: int) -> str:
60
+ """Return the Turkmen cardinal words for the integer ``n``.
61
+
62
+ Supports -(10**12) < n < 10**12. Raises ValueError outside that range
63
+ (the Turkmen term for 10**12 is not reliably attested).
64
+
65
+ >>> number_to_turkmen(0)
66
+ 'nol'
67
+ >>> number_to_turkmen(1234)
68
+ 'müň iki ýüz otuz dört'
69
+ >>> number_to_turkmen(-5)
70
+ 'minus bäş'
71
+ """
72
+ if not isinstance(n, int) or isinstance(n, bool):
73
+ raise TypeError(f"expected int, got {type(n).__name__}")
74
+ if n == 0:
75
+ return ZERO
76
+ if n < 0:
77
+ return f"{NEGATIVE_PREFIX} {number_to_turkmen(-n)}"
78
+ if n >= _MAX:
79
+ raise ValueError(
80
+ f"{n} is out of range; supported range is 0 .. {_MAX - 1} "
81
+ "(the Turkmen word for 10**12 is not reliably attested)"
82
+ )
83
+
84
+ # Split into 1000-groups, least significant first.
85
+ groups: list[int] = []
86
+ rem = n
87
+ while rem:
88
+ rem, g = divmod(rem, 1000)
89
+ groups.append(g)
90
+
91
+ chunks: list[str] = [] # most significant first
92
+ for idx in range(len(groups) - 1, -1, -1):
93
+ value = groups[idx]
94
+ if value == 0:
95
+ continue
96
+ scale_word, keep_bir = _SCALES[idx]
97
+ if scale_word == "":
98
+ chunks.append(_below_thousand(value))
99
+ elif value == 1 and not keep_bir:
100
+ # müň (and ýüz, handled above): drop "bir".
101
+ chunks.append(scale_word)
102
+ else:
103
+ chunks.append(f"{_below_thousand(value)} {scale_word}")
104
+ return " ".join(chunks)
@@ -0,0 +1,43 @@
1
+ import io
2
+
3
+ import pytest
4
+
5
+ from turkmen_num2words.cli import main
6
+
7
+
8
+ def test_single(capsys):
9
+ assert main(["1234"]) == 0
10
+ assert capsys.readouterr().out == "müň iki ýüz otuz dört\n"
11
+
12
+
13
+ def test_multiple(capsys):
14
+ assert main(["0", "7", "100"]) == 0
15
+ assert capsys.readouterr().out == "nol\nýedi\nýüz\n"
16
+
17
+
18
+ def test_negative(capsys):
19
+ assert main(["-5"]) == 0
20
+ assert capsys.readouterr().out == "minus bäş\n"
21
+
22
+
23
+ def test_stdin(capsys, monkeypatch):
24
+ monkeypatch.setattr("sys.stdin", io.StringIO("99 100"))
25
+ assert main([]) == 0
26
+ assert capsys.readouterr().out == "togsan dokuz\nýüz\n"
27
+
28
+
29
+ def test_not_an_integer_sets_error_exit(capsys):
30
+ assert main(["abc"]) == 1
31
+ assert "not an integer" in capsys.readouterr().out
32
+
33
+
34
+ def test_out_of_range_sets_error_exit(capsys):
35
+ assert main(["1000000000000"]) == 1
36
+ assert "out of range" in capsys.readouterr().out
37
+
38
+
39
+ def test_version(capsys):
40
+ with pytest.raises(SystemExit) as e:
41
+ main(["--version"])
42
+ assert e.value.code == 0
43
+ assert "turkmen-num2words" in capsys.readouterr().out
@@ -0,0 +1,98 @@
1
+ import pytest
2
+
3
+ from turkmen_num2words import number_to_turkmen as tn
4
+
5
+ # Verified against Wiktionary Appendix:Turkmen numerals and Gray's grammar.
6
+ KNOWN = {
7
+ 0: "nol",
8
+ 1: "bir",
9
+ 2: "iki",
10
+ 3: "üç",
11
+ 4: "dört",
12
+ 5: "bäş",
13
+ 6: "alty",
14
+ 7: "ýedi",
15
+ 8: "sekiz",
16
+ 9: "dokuz",
17
+ 10: "on",
18
+ 11: "on bir",
19
+ 15: "on bäş",
20
+ 19: "on dokuz",
21
+ 20: "ýigrimi",
22
+ 21: "ýigrimi bir",
23
+ 32: "otuz iki",
24
+ 40: "kyrk",
25
+ 55: "elli bäş",
26
+ 60: "altmyş",
27
+ 70: "ýetmiş",
28
+ 80: "segsen",
29
+ 90: "togsan",
30
+ 99: "togsan dokuz",
31
+ 100: "ýüz",
32
+ 101: "ýüz bir",
33
+ 150: "ýüz elli",
34
+ 200: "iki ýüz",
35
+ 555: "bäş ýüz elli bäş",
36
+ 999: "dokuz ýüz togsan dokuz",
37
+ 1000: "müň",
38
+ 1001: "müň bir",
39
+ 1234: "müň iki ýüz otuz dört",
40
+ 2000: "iki müň",
41
+ 352000: "üç ýüz elli iki müň",
42
+ 1000000: "bir million",
43
+ 2000000: "iki million",
44
+ 1000000000: "bir milliard",
45
+ }
46
+
47
+
48
+ @pytest.mark.parametrize("n,expected", KNOWN.items())
49
+ def test_known_values(n, expected):
50
+ assert tn(n) == expected
51
+
52
+
53
+ def test_gray_worked_example():
54
+ # The authoritative compound example this library is validated against.
55
+ assert tn(1352647) == "bir million üç ýüz elli iki müň alty ýüz kyrk ýedi"
56
+
57
+
58
+ def test_hundred_and_thousand_drop_bir_but_million_keeps_it():
59
+ assert tn(100) == "ýüz" # not "bir ýüz"
60
+ assert tn(1000) == "müň" # not "bir müň"
61
+ assert tn(1000000) == "bir million" # keeps "bir"
62
+ assert tn(1000000000) == "bir milliard" # keeps "bir"
63
+
64
+
65
+ def test_negatives():
66
+ assert tn(-1) == "minus bir"
67
+ assert tn(-100) == "minus ýüz"
68
+ assert tn(-1352647) == "minus bir million üç ýüz elli iki müň alty ýüz kyrk ýedi"
69
+
70
+
71
+ def test_max_supported():
72
+ assert tn(999999999999) == (
73
+ "dokuz ýüz togsan dokuz milliard "
74
+ "dokuz ýüz togsan dokuz million "
75
+ "dokuz ýüz togsan dokuz müň "
76
+ "dokuz ýüz togsan dokuz"
77
+ )
78
+
79
+
80
+ def test_out_of_range_raises():
81
+ with pytest.raises(ValueError):
82
+ tn(10**12)
83
+ with pytest.raises(ValueError):
84
+ tn(-(10**12))
85
+
86
+
87
+ def test_type_errors():
88
+ with pytest.raises(TypeError):
89
+ tn(1.5)
90
+ with pytest.raises(TypeError):
91
+ tn(True) # bool is not accepted as an int here
92
+
93
+
94
+ def test_no_double_spaces_and_trimmed():
95
+ for n in [0, 7, 100, 1000, 1000000, 1001001, 1352647, 999999999999]:
96
+ s = tn(n)
97
+ assert " " not in s
98
+ assert s == s.strip()