# cjkfmt
[](https://crates.io/crates/cjkfmt)
[](https://github.com/sgryjp/cjkfmt/actions)
## Installation
### Cargo
- Install the rust toolchain in order to have cargo installed by following
[this](https://www.rust-lang.org/tools/install) guide.
- run `cargo install cjkfmt`
## Formatting Files
To replace named files with their formatted content, use the `--write` option:
```console
cjkfmt format --write README.md docs/example.md
```
Omitting `--write` leaves the source files unchanged and sends formatted content to stdout.
### Language Selection
Named files are classified by their final extension: `.md` and `.markdown` select Markdown, and
`.json` selects JSON. Matching is case-insensitive for ASCII letters. Other named paths require an
explicit `--language markdown` or `--language json`; an explicit selection always takes precedence
over the filename. `format` applies Markdown-prose spacing only to Markdown input, while JSON and
unrecognized input still receive the general line-wrapping pass.
When reading stdin without `--language`, `check` and `debug-cst` assume Markdown. `format` uses a
conservative default and skips Markdown-prose spacing. Use `--language markdown` or
`--language json` to select the stdin language explicitly.
## Configuration
cjkfmt can be configured in several ways, with configuration options applied in the following order
of precedence (highest to lowest):
1. Command line options
2. Environment variables prefixed with `CJKFMT_`
3. JSON configuration file `.cjkfmt.json` found in the current or ancestor directories
4. JSON configuration file `.cjkfmt.json` in the user's configuration directory
(`XDG_CONFIG_HOME` if set, otherwise `$HOME`)
5. Default values
The configuration file is searched for in the current directory and, if not found, in each parent
directory up to the root. Only the first file found will be used.
### Configuration Options
Currently, the following configuration options are available:
| `ambiguous_width` | Width of Unicode Ambiguous characters (`narrow` or `wide`) | `wide` |
| `max_width` | Maximum line width to allow | 80 |
| `spacing.alphabets` | Require, prohibit, or ignore spaces around full-/half-width alphabets | `ignore` |
| `spacing.digits` | Require, prohibit, or ignore spaces around full-/half-width digits | `ignore` |
Depending on the configuration source, the option names are formatted slightly differently:
- JSON configuration files
- Use underscores between words.
Example: `max_width`
- Environment variables
- Write names in ALL CAPITAL LETTERS with underscores between words,
and always start with `CJKFMT_`.
Example: `CJKFMT_MAX_WIDTH`
- Command line options
- Use hyphens between words, and put two dashes before the option name.
Examples: `--max-width 100`, `--ambiguous-width narrow`,
`--spacing-alphabets require`, and `--spacing-digits prohibit`
### Example Configuration File
The `format` command applies the spacing rules to Markdown prose, including visible text inside
emphasis and links. Code spans, fenced code blocks, URLs, HTML, and other non-prose inline content
are left unchanged. For the implementation-level character classification and the difference between
`check` and `format`, see [the spacing implementation notes](docs/design/spacing.md).
Below is an example configuration file `.cjkfmt.json`.
```json
{
"ambiguous_width": "wide",
"max_width": 100,
"spacing": {
"alphabets": "require",
"digits": "ignore"
}
}
```
## License
Licensed under either of
- Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license
([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
See [CONTRIBUTING.md](CONTRIBUTING.md).