# 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. For `check` and `debug-cst`,
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 and, by default, runs the general line-wrapping pass for selected Markdown and
JSON input. Unsupported named paths are returned unchanged by `format` unless an explicit
`--language` override selects a language.
When reading stdin without `--language`, `check` and `debug-cst` assume Markdown. `format` does not
select a language, so it skips both Markdown-prose spacing and line wrapping. Use `--language
markdown` or `--language json` to select the stdin language explicitly.
### Line Wrapping
Line wrapping defaults to `split`, preserving the existing safe wrapping behavior. Set it to
`preserve` to keep existing physical lines while still applying configured Markdown spacing. This
mode does not add, remove, or join line breaks, normalize line endings, or change final-newline
presence. JSON has no spacing edits, so it remains byte-identical in `preserve` mode.
The option is available in JSON configuration, the environment, and the CLI:
```json
{ "line_wrapping": "preserve" }
```
```console
CJKFMT_LINE_WRAPPING=preserve cjkfmt format --language markdown README.md
cjkfmt --line-wrapping preserve format --language markdown README.md
```
`check` reports W001 for overlong physical input lines regardless of this setting or whether a
safe wrapping opportunity exists. Formatting does not guarantee that W001 is clear: preserved
lines may remain overlong, and spacing edits can make a line exceed `max_width`.
## Exit Status
`cjkfmt check` exits with status 0 when it completes without diagnostics, status 1 when it completes
with one or more diagnostics, and status 2 when checking cannot be completed because of invalid
arguments or configuration, input errors, or another operational failure.
## 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` |
| `line_wrapping` | Preserve lines or split at safe points | `split` |
| `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`,
`--line-wrapping preserve`, `--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",
"line_wrapping": "split",
"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).