270px-Rosetta_Stone.JPG

Syntax Quick Reference for the Ledger-Likes

Some information about the major Plain Text Accounting  implementations, drawn from existing docs and informal testing, that I needed to see in one place. Currently, it compares the main journal syntax for Ledger, hledger and Beancount. For more, see the manuals and cheatsheets linked below, or plaintextaccounting.org . I hope you find it useful.

First draft, created 2016/03, corrections to: sm on #hledger  or #ledger  or #beancount , or the google doc

Quick Reference for the Ledger-Likes

Journal Format

Basic example

Comments

Basic transactions

Dates

Account names

Amounts

More transaction features

Prices

Balance assertions

Balance assignments

Directives

account, open

close

commodity

market price

Journal Format

Legend :
Things in
[ ] are  optional.
Syntax should be the latest preferred syntax for each implementation, may be incomplete.
Some notes in the Ledger column are common to all.

Ledger
http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format
http://ricostacruz.com/cheatsheets/ledger.html

hledger
http://hledger.org/manual.html#journal

Beancount
http://furius.ca/beancount/doc/syntax
http://furius.ca/beancount/doc/cheatsheet

Basic example

; a comment

2016/1/1 set opening balance
   assets:checking       $500.00
   equity:opening balances

2016/1/5 farmer's market
   expenses:groceries     $50.00
   Assets:checking





Comments, directives, and/or transactions in any order

; a comment

2016/1/1 set opening balance
   assets:checking       $500.00
   equity:opening balances

2016/1/5 farmer's market
   expenses:groceries     $50.00
   assets:checking

; a comment

2016-01-01 open Assets:Checking
2016-01-01 open Equity:Opening-Balances
2016-01-01 open Expenses:Groceries

2016-01-01 txn "set opening balance"
   Assets:Checking         500.00 USD
   Equity:Opening-Balances

2016-01-05 txn "farmer's market"
   Expenses:Groceries     50 USD
   Assets:Checking

All referenced accounts must have an open directive

Comments

; comment
# comment
% comment
| comment
* comment and org-mode outline node

Non-comment lines may end with a comment
Indented comments are attached to the preceding transaction or posting

; comment
# comment
* comment and org-mode outline node

; comment
Any unrecognised line is also a comment




Basic transactions

DATE [DESCRIPTION]
   ACCOUNT    AMOUNT
   ACCOUNT    [AMOUNT]

A transaction contains any number of indented postings (usually two), whose amounts must sum to zero
At least two spaces required between account and amount
One amount may be omitted

DATE [DESCRIPTION]
   ACCOUNT    AMOUNT
   ACCOUNT    [AMOUNT]

Same

DATE txn [["PAYEE"] "DESCRIPTION"]
   ACCOUNT    AMOUNT
   ACCOUNT    [AMOUNT]

DESCRIPTION must be in double quotes, can be multiline
No need for two spaces between account and amount

Dates

YYYY-MM-DD
YYYY/MM/DD
YYYY.MM.DD
MM-DD
MM/DD
MM.DD

Other formats specified with  --input-date-format

YYYY-MM-DD
YYYY/MM/DD
YYYY.MM.DD
MM-DD
MM/DD
MM.DD

YYYY-MM-DD
YYYY/MM/DD
YYYY.MM.DD




Only YYYY-MM-DD with 8 digits is officially supported

Account names

TOPACCT[:SUBACCT[:...]]

Revenues:Salary
liabilities:credit card:CITI 1234
other assets:house

Account names begin with a letter
May contain single spaces
May contain subaccounts separated by :

TOPACCT[:SUBACCT[:...]]





Same

TOPACCT[:SUBACCT[:...]]

Income:Salary
Liabilities:CreditCard:CITI-1234
Assets:House

Top level account must be one of Assets, Liabilities, Equity, Income, Expenses
Each subaccount must be capitalised
Letters, digits and hyphen are allowed (no spaces)
 

Amounts

One of
COMMODITY QUANTITY
QUANTITY COMMODITY
QUANTITY

10
$10.00
1,000.0001 USD
10 "prepaid classes"



COMMODITY is a symbol, word or phrase; if it contains spaces or numbers, it must be in double quotes
It can be on the left or right, with or without a separating space
QUANTITY is a number with 0 or more decimal places
Decimal point is
.
Digits can be grouped into thousands by
,
Amount styles influence the standard display style for each commodity

One of
COMMODITY QUANTITY
QUANTITY COMMODITY
QUANTITY

10
$10.00
1,000.0001 USD
10 "prepaid classes"
1.000.000,01
12,34,567.89

Decimal point is .  or ,
Digit group separator is ,  or .
Any digit grouping can be used, not just thousands

QUANTITY COMMODITY




10USD
1000.0001 USD





COMMODITY is all capital letters, on the right, and required
Decimal point is .
Digit group separator
,  is allowed and ignored

More transaction   features

DATE [FLAG] [(CODE)] DESCRIPTION
   [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
   ...
   [FLAG] ACCOUNT  [AMOUNT [PRICE] [=BAL]]

FLAG (aka STATE) is empty, ! or * meaning uncleared, pending or cleared
CODE is any string, in parentheses
DESCRIPTION can be a payee name, narration, or both

DATE [FLAG] [(CODE)] DESCRIPTION
   [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]
   ...
   [FLAG] ACCOUNT  AMOUNT [PRICE] [=BAL]

DATE [txn|FLAG] [["PAYEE"] "DESCRIPTION"]
   [FLAG] ACCOUNT       AMOUNT [PRICE]
   ...
   [FLAG] ACCOUNT       AMOUNT [PRICE]

The txn keyword may be replaced by a FLAG
For just a payee, use "PAYEE" ""
 

Prices

One of
@ UNITPRICE
@@ TOTALPRICE
and/or one of
{LOTUNITPRICE}
{=FIXEDLOTUNITPRICE}
and/or
[LOTDATE]

A UNITPRICE or TOTALPRICE also records a market price on this date
A LOTDATE is written in square brackets

One of
@ FIXEDUNITPRICE
@@ FIXEDTOTALPRICE
and/or
{=FIXEDLOTUNITPRICE}




These do not record market prices
The lot price syntax is ignored

{LOTUNITPRICE[ / LOTDATE]}
and/or one of
@ UNITPRICE
@@ TOTALPRICE




Lot prices are remembered and form distinct commodities, other prices are not
If there is both a lot price and a regular price, the latter records a market price

Balance assertions

= AMOUNT (after posting amount & price)

2016-03-10
   Expenses:Food      $20
   Assets:Cash       $-20 = $80

Asserts the balance in this commodity
in this account, excluding subaccounts
at this point in the parse order

= AMOUNT (after posting amount & price)





Asserts the balance in this commodity
in this account, excluding subaccounts
on this day. Same day events are processed in parse order

DATE balance ACCOUNT AMOUNT

2014-08-09 balance Assets:Cash 562.00 USD
2014-08-09 balance Assets:Cash 210.00 CAD


Asserts the balance in this commodity
in this account, including subaccounts
at the start of this day

Balance assignments

= AMOUNT (no preceding/inferred posting amount)

2012-03-10 Adjustment
   Assets:Cash            = $50
   Expenses:Misc


Sets the posting amount so as to make the balance assertion true. (The other amountless posting allows the transaction to balance)

Directives

KEYWORD ARGS...
   [SUBDIRECTIVES]

account

alias
apply
assert
bucket
capture
check
comment
commodity
define
end
expr
fixed
include
P

payee
tag
test
year

Timeclock directives:
i
o
b
h

KEYWORD ARGS...


account (alias for apply)
alias
apply
comment
D
end
include

















[DATE] KEYWORD ARGS...
   [SUBDIRECTIVES]

DATE balance
DATE close
DATE commodity
DATE document
DATE event
DATE note
DATE open
DATE pad
DATE price
DATE txn
include
option
plugin
poptag
pushtag






account, open

account ACCOUNT

    [SUBDIRECTIVES]

account Revenues:Salary
account Expenses:Food:Chicken
   note chicken food expenses
   alias food
   payee ^(KFC|Popeyes)$
   check commodity == "$"
   assert commodity == "$"
   eval print("Hello!")
   default

Gives more error checking with --strict  or --pedantic
Optional subdirectives do more stuff

DATE open ACCOUNT [COMMODITY[,...]] [METHOD]

2014-05-01 open Assets:Cash USD,CAD









Every account posted to needs an open directive with prior date

close

DATE close ACCOUNT

commodity

commodity COMMODITY

commodity EUR
commodity $
  note American Dollars
  format $1,000.00
  nomarket
  default

Gives more error checking with --strict  or --pedantic
Optional subdirectives do more stuff

DATE commodity COMMODITY
   [METADATA]

1867-01-01 commodity CAD
   name: "Canadian Dollar"
   asset-class: "cash"



Attaches metadata to a commodity

market price

P DATE TIME COMMODITY UNITPRICE

P 2004/06/21 02:18:02 AAPL $32.91
P 2004/06/21 02:18:02 AU $400.00


Used by -V and -X
Also set by transaction prices

P DATE [TIME] COMMODITY UNITPRICE

P 2015/8/9 GBP $1.55


Used by -V
A time is ignored

DATE price COMMODITY AMOUNT

2014-07-09 price USD  1.08 CAD


Also set by transaction prices