Beanfmt

中文文档

A fast beancount file formatter with CJK double-width character support.

Features

• Column-aligned currencies and costs with CJK-aware display width
• Thousands separator normalization (add, remove, or keep)
• Brace spacing control for cost annotations
• Date-based entry sorting
• Recursive formatting of included files (with glob support)
• Multi-platform: CLI, Python library, WASM module, and VSCode extension

Installation

CLI

cargo install beanfmt

Python

pip install beanfmt

VSCode Extension

Search for beanfmt in the VSCode Marketplace, or install from the command line:

code --install-extension beanfmt.beanfmt-beancount-formatter

From Source

cargo install --path .                 # CLI
maturin develop --features python      # Python (requires maturin)

Note: python and wasm features are mutually exclusive.

Usage

CLI

# Format from stdin
cat ledger.beancount | beanfmt

# Format a file (print to stdout)
beanfmt ledger.beancount

# Format in-place
beanfmt -w ledger.beancount

# Recursively format all included files in-place
beanfmt --recursive -w ledger.beancount

# Custom alignment columns
beanfmt --currency-column 60 --cost-column 65 ledger.beancount

# Add thousands separators and sort by date
beanfmt --thousands add --sort ledger.beancount

Options

Configuration File

Beanfmt supports TOML configuration files with a three-layer merge priority (low → high):

1. Built-in defaults
2. Global config: $XDG_CONFIG_HOME/beanfmt/config.toml (defaults to ~/.config/beanfmt/config.toml)
3. Project config: .beanfmt.toml or beanfmt.toml (searched upward from the current directory)
4. CLI arguments (highest priority)

Example .beanfmt.toml:

indent = 2
currency_column = 60
cost_column = 65
thousands = "add"
spaces_in_braces = true
fixed_cjk_width = true
sort = "asc"    # "asc", "desc", "off", or true/false
sort_timeless = "begin"  # "begin" or "end"
sort_exclude = ["open", "close"]  # excluded types act as sort barriers

All fields are optional. Unspecified fields inherit from the next lower priority layer. Use --no-config to skip all configuration file loading. See beanfmt.toml for a full reference with comments.

Python

import beanfmt

# Format a string
output = beanfmt.format(source, currency_column=60, sort=True)

# Format a file
output = beanfmt.format_file("ledger.beancount")

# Reusable options
opts = beanfmt.Options(currency_column=60, thousands_separator="add")
output = beanfmt.format(source, options=opts)

# Recursive formatting — returns list of (path, content) tuples
results = beanfmt.format_recursive("ledger.beancount")

WASM

import { format, format_default } from "beanfmt";

// Format with default options
const output = format_default(source);

// Format with full options
const output = format(source, 4, 70, 75, "keep", false, true, "off", "begin", undefined);

VSCode

Install the extension, then configure in settings.json:

"[beancount]": {
    "editor.defaultFormatter": "beanfmt.beanfmt-beancount-formatter",
    "editor.formatOnSave": true
}

Available settings:

License

MIT