From b6bf2ee405170ab1590e76a5a085900fb0072d05 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 14 Mar 2016 08:49:45 -0700 Subject: [PATCH] a combined quick reference, aka "rosetta stone" Covers the essentials of Ledger/hledger/Beancount journal format. The master copy is in google docs for easier table editing, but this will likely change in future. --- Makefile | 19 +- quickref/a.beancount | 11 + quickref/a.hledger | 7 + quickref/a.ledger | 7 + quickref/images/.gitkeep | 0 quickref/index.html | 1105 ++++++++++++++++++++++++++++++++++++++ quickref/quickref.css | 41 ++ quickref/tests.shelltest | 11 + 8 files changed, 1199 insertions(+), 2 deletions(-) create mode 100644 quickref/a.beancount create mode 100644 quickref/a.hledger create mode 100644 quickref/a.ledger create mode 100644 quickref/images/.gitkeep create mode 100755 quickref/index.html create mode 100644 quickref/quickref.css create mode 100755 quickref/tests.shelltest diff --git a/Makefile b/Makefile index 017a90d..6cb95fe 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,9 @@ -all: $(patsubst %.md,%.html,$(wildcard *.md)) Makefile +all: mdtohtml + +mdtohtml: $(patsubst %.md,%.html,$(wildcard *.md)) Makefile watch: - fswatch -0 *.{md,tmpl} | xargs -0 -n1 -I{} make all + fswatch -l 0.1 -0 *.{md,tmpl} | xargs -0 -n1 -I{} make all livereload: livereloadx -p 10000 --static . @@ -17,3 +19,16 @@ PANDOC = pandoc # --from markdown --to html %.html: %.md index.tmpl $(PANDOC) --template index.tmpl $< -o $@ +quickref/index.html: + rm -rf quickref/QuickReferencefortheLedger-Likes + -mv ~/Desktop/QuickReferencefortheLedger-Likes quickref + cp quickref/QuickReferencefortheLedger-Likes/images/* quickref/images + cp quickref/QuickReferencefortheLedger-Likes/QuickReferencefortheLedgerLikes.html quickref/index.html + perl -p -i -e 's%%%' $@ + perl -p -i -e 's/>/>\n/g' $@ + perl -p -i -e 's/(/' $@ + perl -p -i -e 's/<\/body>/<\/div>\n<\/body>/' $@ + +# XXX not working +# watch-quickref: +# fswatch -l 0.1 -0 ~/Desktop/QuickReferencefortheLedger-Likes/QuickReferencefortheLedgerLikes.html | xargs -0 -n1 -I{} cat #echo make quickref.html diff --git a/quickref/a.beancount b/quickref/a.beancount new file mode 100644 index 0000000..10edf95 --- /dev/null +++ b/quickref/a.beancount @@ -0,0 +1,11 @@ +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 1.000,0001USD + Equity:Opening-Balances + +2016/1/5 txn "farmer's market" + Expenses:Groceries 50 USD + Assets:Checking diff --git a/quickref/a.hledger b/quickref/a.hledger new file mode 100644 index 0000000..36610ae --- /dev/null +++ b/quickref/a.hledger @@ -0,0 +1,7 @@ +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 diff --git a/quickref/a.ledger b/quickref/a.ledger new file mode 100644 index 0000000..36610ae --- /dev/null +++ b/quickref/a.ledger @@ -0,0 +1,7 @@ +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 diff --git a/quickref/images/.gitkeep b/quickref/images/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/quickref/index.html b/quickref/index.html new file mode 100755 index 0000000..c657ec6 --- /dev/null +++ b/quickref/index.html @@ -0,0 +1,1105 @@ + + + + + + + + + + + + +
+

+ +270px-Rosetta_Stone.JPG + +

+

+ + +

+

+ +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 + + +http://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 + +

+

+ + +More transaction features + +

+

+ + +Prices + +

+

+ + +Balance assertions, resets + +

+

+ + +Directives + +

+

+ + +account, open + +

+

+ + +close + +

+

+ + +commodity + +

+

+ + +

+

+ +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/1/5 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
+The final amount is optional
+ +

+		 +

+ +DATE [DESCRIPTION]
+    ACCOUNT    AMOUNT
+    ACCOUNT    [AMOUNT]
+
+ + +Same +

+

+ + +

+		 +

+ +DATE txn ["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.00
+1,000.0001 USD
+10 "prepaid classes"
+1.000.000,01
+10
+
+
+ + +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 can be + +. + + or + +, + +
+Digits can be grouped into thousands by + +, + + or + +. + +
+Amount styles influence the standard display style for each commodity +

+

+ + +

+		 +

+ +One of
+COMMODITY QUANTITY
+QUANTITY COMMODITY
+QUANTITY
+
+$10.00
+1,000.0001 USD
+10 "prepaid classes"
+1.000.000,01
+10
+12,34,567.89
+
+ + +Similar
+Digits can be grouped any way, not just thousands +

+

+ + +

+		 +

+ +QUANTITY COMMODITY
+
+
+
+
+10USD
+1000.0001 USD
+
+
+
+
+
+ + +COMMODITY is all capital letters, on the right, and required + +
+ + +Decimal point must be + +. + +
+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 [PRICES]
+    ...
+    [FLAG] ACCOUNT       AMOUNT [PRICES]
+
+ + +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 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 +

+		 +

+ + +

+		 +

+ + +

+		 +

+ + +

+
+
+ +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 COMMODITY UNITPRICE
+
+P 2015/8/9 GBP $1.55
+
+
+ + +Used by -V +

+		 +

+ +DATE price COMMODITY AMOUNT
+
+2014-07-09 price USD  1.08 CAD
+
+
+ + +Also set by transaction prices +

+
+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+
+ + diff --git a/quickref/quickref.css b/quickref/quickref.css new file mode 100644 index 0000000..7eae242 --- /dev/null +++ b/quickref/quickref.css @@ -0,0 +1,41 @@ +tr { + vertical-align:top; +} +/* TOC */ +/* update these class ids on each save */ +p { margin:0; } +p.c37 { visibility:hidden; } +p.c26 { margin-left:1em; } +p.c24 { margin-left:3em; } +p.c19 { margin-left:2em; } +/* heading cells */ +tr:first-child { + font-weight:bold; +} +td:first-child { + /* font-weight:bold; */ +} +tr:first-child a { + font-size:small; + /* white-space:nowrap; */ +} +td:first-child { + width:10%; +} +/* body cells */ +tr:not(:first-child) td:not(:first-child) span:first-child { + white-space:nowrap; + font-weight:bold; + color:navy; + font-family:monospace; + /* font-family:monaco; */ + /* font-size:small; */ +} +tr:not(:first-child) td:not(:first-child) span:not(:first-child) { + /* white-space:nowrap; */ + /* font-family:monospace; */ + font-size:small; +} +td:not(:first-child) { + width:30%; +} diff --git a/quickref/tests.shelltest b/quickref/tests.shelltest new file mode 100755 index 0000000..186b680 --- /dev/null +++ b/quickref/tests.shelltest @@ -0,0 +1,11 @@ +#!/usr/bin/env shelltest +# -*- sh -*- + + ledger -f a.ledger print +>>>=0 + + hledger -f a.hledger print +>>>=0 + + beancount -f a.beancount print +>>>=0