96 lines
2.3 KiB
Markdown
96 lines
2.3 KiB
Markdown
## Custom Packs
|
|
|
|
ForeignThon lets you extend or override any installed language pack locally — no PyPI account, no new package required. You can also scaffold a completely new language from scratch.
|
|
|
|
---
|
|
|
|
## Local override
|
|
|
|
Create a `custom.json` in your project root with only the keys you want to change:
|
|
|
|
```json
|
|
{
|
|
"builtins": {
|
|
"show": "print"
|
|
},
|
|
"keywords": {
|
|
"when": "if"
|
|
}
|
|
}
|
|
```
|
|
|
|
Then reference it in `.foreignthon.toml`:
|
|
|
|
```toml
|
|
[foreignthon]
|
|
lang = "es"
|
|
custom_pack = "custom.json"
|
|
```
|
|
|
|
Custom keys are merged on top of the installed pack. Installed pack keys are preserved — only the keys you define in `custom.json` are overridden.
|
|
|
|
!!! tip
|
|
ForeignThon walks up the directory tree to find `.foreignthon.toml`, so you can place it at the project root and run `fpy` from any subdirectory.
|
|
|
|
---
|
|
|
|
## Scaffold a new language
|
|
|
|
If no pack exists for your language yet:
|
|
|
|
```bash
|
|
fpy new myproject --lang custom
|
|
```
|
|
|
|
You will be prompted for:
|
|
|
|
- Language code (e.g. `ru`, `fr`, `ar`)
|
|
- English name (e.g. `Russian`)
|
|
- Native name (e.g. `Русский`)
|
|
|
|
This generates a `custom.json` based on the official template — every Python keyword, builtin, exception, and stdlib module is listed with the English value as a placeholder. Replace the **keys** with your language's words.
|
|
|
|
```json
|
|
{
|
|
"keywords": {
|
|
"if": "if", ← replace the key, keep the value
|
|
"for": "for",
|
|
"def": "def",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
The `.foreignthon.toml` is automatically wired to use this file.
|
|
|
|
---
|
|
|
|
## Pack schema
|
|
|
|
A standalone pack must have these top-level sections:
|
|
|
|
| Section | Purpose |
|
|
|---|---|
|
|
| `meta` | Name, code, version, authors |
|
|
| `keywords` | Python reserved words |
|
|
| `builtins` | Built-in functions |
|
|
| `exceptions` | Built-in exception classes |
|
|
| `error_messages` | Translations for bilingual error output |
|
|
| `stdlib` | Common standard library module names |
|
|
| `postfix_keywords` | English keywords to rewrite in `--postfix` output |
|
|
|
|
Validate your pack at any time:
|
|
|
|
```bash
|
|
fpy pack custom.json
|
|
# ✓ Pack 'Russian' is valid.
|
|
```
|
|
|
|
---
|
|
|
|
## Publishing
|
|
|
|
Once your `custom.json` is complete and working, you can turn it into a proper `foreignthon-xx` package on PyPI so others can install it with `pip install foreignthon-xx`.
|
|
|
|
See [Contributing → Language Packs](contributing/language-packs.md) for the full guide.
|