Option Directive¶

Options are global configuration directives declared without a date.

Syntax¶

option "name" "value"

Options MAY appear anywhere in the file. All options are collected before processing directives.

Core Configuration¶

title¶

Type: String
Default: (none)
Repeatable: No
Description: The title of this ledger. Shows in reports.

option "title" "Personal Finances 2024"

operating_currency¶

Type: String
Default: (none)
Repeatable: Yes
Description: Main currencies for reporting. Creates dedicated columns in reports.

option "operating_currency" "USD"
option "operating_currency" "EUR"

Account Root Names¶

Customize the five root account type names.

Option	Default	Description
`name_assets`	"Assets"	Root name for asset accounts
`name_liabilities`	"Liabilities"	Root name for liability accounts
`name_equity`	"Equity"	Root name for equity accounts
`name_income`	"Income"	Root name for income accounts
`name_expenses`	"Expenses"	Root name for expense accounts

Example:

option "name_income" "Revenue"
option "name_equity" "Capital"

Special Equity Accounts¶

Used by OPEN/CLOSE statement operators in BQL.

Option	Default	Purpose
`account_previous_balances`	"Opening-Balances"	Summarize prior balances
`account_previous_earnings`	"Earnings:Previous"	Prior retained earnings
`account_previous_conversions`	"Conversions:Previous"	Prior conversion residuals
`account_current_earnings`	"Earnings:Current"	Current period net income
`account_current_conversions`	"Conversions:Current"	Current conversion residuals
`account_rounding`	(disabled)	Accumulate rounding errors

Tolerance & Precision¶

inferred_tolerance_default¶

Type: Currency:Decimal mapping
Default: (per-currency defaults)
Repeatable: Yes
Description: Default tolerance when not inferrable from amounts.

option "inferred_tolerance_default" "CHF:0.01"
option "inferred_tolerance_default" "JPY:1"

tolerance_multiplier¶

Type: Decimal
Default: 0.5
Repeatable: No
Description: Multiplier applied to inferred tolerances.

Note: Previously named inferred_tolerance_multiplier (deprecated).

infer_tolerance_from_cost¶

Type: Boolean
Default: TRUE
Repeatable: No
Description: Expand tolerance to include values inferred from cost currencies.

Booking¶

booking_method¶

Type: String
Default: "STRICT"
Values: "STRICT", "STRICT_WITH_SIZE", "FIFO", "LIFO", "HIFO", "AVERAGE", "NONE"
Repeatable: No
Description: Default booking method for all accounts. Can be overridden per-account in open directive.

option "booking_method" "FIFO"

Documents¶

documents¶

Type: Path
Default: (none)
Repeatable: Yes
Description: Directory roots to search for document files.

option "documents" "/home/user/documents/financial"
option "documents" "receipts/"

Document files MUST match pattern: YYYY-MM-DD.description.extension

Rendering¶

render_commas¶

Type: Boolean
Default: TRUE
Repeatable: No
Description: Include thousand separators in number output.

long_string_maxlines¶

Type: Integer
Default: 64
Repeatable: No
Description: Line threshold for multi-line string warnings.

Currency Conversion¶

conversion_currency¶

Type: String
Default: "NOTHING"
Repeatable: No
Description: Imaginary currency used for conversions at zero rate. Allows currency exchanges without explicit prices.

option "conversion_currency" "NOTHING"

Plugins¶

plugin_processing_mode¶

Type: String
Default: "default"
Values: "default", "raw"
Repeatable: No
Description: "default" enables built-in plugins; "raw" runs only user plugins.

Deprecated/Removed Options¶

The following options existed in earlier versions but are no longer valid:

Option	Status
`experiment_explicit_tolerances`	Removed (now default behavior)
`use_legacy_fixed_tolerances`	Removed
`encoding`	Removed (UTF-8 only)

Deprecated Options¶

These options are deprecated and SHOULD NOT be used in new files:

Option	Replacement
`default_tolerance`	`inferred_tolerance_default`
`tolerance`	No effect; use tolerance options above
`plugin` (as option)	Use `plugin` directive instead

Option Value Types¶

Type	Format	Example
String	Quoted text	`"My Ledger"`
Boolean	TRUE/FALSE (case-insensitive)	`"TRUE"`, `"false"`
Decimal	Numeric string	`"0.5"`
Path	File path (relative to ledger)	`"receipts/"`
Currency:Value	Colon-separated pair	`"CHF:0.01"`

Processing Order¶

Parse all option directives from all files (including includes)
Apply options in order encountered
Later values override earlier for non-repeatable options
Repeatable options accumulate values

Validation¶

Unknown option names produce ParserError
Invalid option values produce ParserError
Duplicate non-repeatable options: later values override earlier ones