leddy(5)

# NAME

*leddy* - file format and syntax reference

# DESCRIPTION

*leddy* uses a general ledger format similar to, but distinct from, other
common plain text accounting tools. This document assumes a general knowledge
of accounting principles, but no specific knowledge of other plain text
accounting tools.

*leddy* expects plain text files with a particular syntax in valid UTF-8. If
any aspect of the file is unexpected, *leddy* will report this to the user with
a line number and exit.

Lines beginning with '#' are interpreted as comments and ignored. Blank lines
and lines containing only whitespace are also ignored.

# ENTRIES AND DETAILS

An entry in a *leddy* ledger file is comprised of one _header_ line and two or
more _detail_ lines. The header line contains the date in ISO-8601 (YYYY-MM-DD)
format, followed by one space, followed by the name or description of the entry
in question. For example, to write a _header_ representing a fast food purchase:

	2023-01-02 Taco Bell

*leddy* is unopinionated about the content of the line after the date and one
space character that should follow it.

A _detail_ line contains four elements, each separated by one or more spaces:

1. leading whitespace, typically one tab character++
2. a valid account string++
3. the amount to debit or credit the account++
4. the currency or commodity that the amount is denominated in

Here is one possible complete fast food purchase entry, to finish our example:

	2023-01-02 Taco Bell++
		Expenses:Food:Restaurants  5.00 USD++
		Liabilities:Cards:Chase   -5.00 USD

There is no limit to the number of detail lines you can include in an entry. It
is typically ideal to keep them as specific as possible, but complex events,
especially those involving taxes, equities, and debts can validly involve many.
Here is an example of how you may handle the monthly payment on a loan that
accrues interest:

	2023-10-28 Navient++
		Assets:Checking:Chase     -402.00 USD++
		Expenses:Fees:Interest      68.00 USD++
		Liabilities:Loans:Student  334.00 USD

Here, we represent a payment of 402.00 USD, of which 68.00 went toward interest
and the remaining toward the principal balance. When summed up, all details on
an entry must balance, i.e. they must sum to zero. *leddy* will always verify
this and refuse to report anything if any entries in the ledger do not balance.

Other plain text accounting tools typically allow you to optionally omit the
amount and currency of exactly one detail line, and the parser will infer that
the entry is intended to balance and insert the necessary debit or credit to
make the entry balance. *leddy* does not allow this; all detail amounts and
currencies must be explicit.

There is one exception to the typical *leddy* balancing behavior related to
multi-currency entries. See *MULTI-CURRENCY*.

## ACCOUNTS

Accounts are strings that represent the location, application, or context of a
balance of money. They should contain at least two segments. The first segment
is always one of _Assets_, _Liabilities_, _Equity_, _Income_ or _Expenses_.
*leddy* enforces this. Subsequent segments can be organized however the user
wishes. Users are encouraged to consult educational accounting resources as
needed when considering how to best structure accounts.

As shown in the examples throughout this document, segments are colon-delimited.
Segments cannot contain spaces.

## AMOUNTS AND CURRENCIES

A currency must always follow every amount, and be separated from that amount
by exactly one space.

*leddy* handles amounts as integers internally, with precision determined by
the number of integers past the decimal point, if any. This ensures that no
floating point errors occur in processing.

Each account-currency combination must have a consistent number of integers past
the decimal point every time it appears. In other words, the below combination
of entries is invalid even though, in concept, they both make sense:

	2023-01-01 Entry One++
		Expenses:Fees:Interest      50 USD++
		Liabilities:Loans:Personal -50.00 USD

	2023-01-02 Entry Two++
		Expenses:Fees:Interest      50.00 USD++
		Liabilities:Loans:Student  -50.00 USD

In parsing this, *leddy* would complain that the precision between entries on
the Expenses:Fees:Interest account differs from the first time it saw it. This
check is designed to prevent common data entry mistakes, and simplifies the
internal handling of balances.

Currencies here are fiat currencies, but *leddy* is unopinionated about this.
Holdings of stocks, precious metals, crypto assets, or anything else with value 
can and should be represented as a currency in this model.

# MULTI-CURRENCY

*leddy* has no knowledge of the outside world and therefore no way of knowing
the exchange rates between different declared currencies. Therefore, it trusts
the user to input valid, balanced entries when multiple currencies are
involved.

When two currencies are used in one entry, *leddy* assumes the entry is balanced
and calculates an implied exchange rate between the two currencies that makes
the entry balance. These exchange rates can be observed in the *fx* report;
see *leddy*(1).

Lastly, *leddy* must make each currency balance. To achieve this, *leddy*
inserts two new details into the entry that net each currency to zero, into a
special _Equity:Conversions_ account. This account does not need to be declared
and is automatically created when needed. This is the only time *leddy* will
implicitly alter the representation of an entry. (Of course, it doesn't edit
the ledger file.) The effect is that the _Equity:Conversions_ account will
tabulate the net gain or loss of each currency from conversions into other
currencies.

Note the _Equity:Conversions_ account is not otherwise special, can be manually
declared and interacted with, etc. just like any other account.

Entries are allowed to contain up to two currencies in total. Three or more is
not supported. This is because it would be impossible to implicitly calculate
exchange rates if three or more currencies were in the same entry, because
infinitely many valid solutions would exist.