more robust beancount journal output

[simonmichael]

This makes conversion to Beancount format with print more robust, automating all the adjustments needed to convert a hledger journal to a valid Beancount journal that will be accepted by bean-check. The main thing that still requires human intervention is ensuring Beancount-compatible top level account names.

• ;tools: just branches/v
• imp:print:beancount: remove virtual postings automatically
• imp:print:beancount: add a second account name part if needed
• imp:print:beancount: remove redundant conversion postings automatically
• ;doc:output:beancount: updates
• imp:print:beancount: generate operating_currency directives from cost currencies
• imp:print:beancount: convert tags to BC metadata
• imp:print:beancount: don't add account tags to postings

Doc:

Beancount output

This is Beancount's journal format.
You can use this to export your hledger data to Beancount, eg to use the Fava web app.

hledger will try to adjust your data to suit Beancount, automatically.
Be cautious and check the conversion until you are confident it is good.
If you plan to export to Beancount often, you may want to follow its conventions, to make conversion easier:

• Beancount-friendly account names
• currency codes instead of currency symbols
• costs instead of conversion postings
• no virtual postings, etc.

Note there is one big adjustment you must handle yourself:
when exporting data for Beancount, your top level account names must be Assets, Liabilities, Equity, Income, and/or Expenses.
If needed you can use account aliases to rewrite your account names temporarily.
as in this hledger2beancount.conf config file.

Beancount account names

Aside from the top-level names, hledger will adjust your account names to make valid
Beancount account names,
by capitalising each part, replacing spaces with -, replacing other unsupported characters with C<HEXBYTES>,
prepending A to account name parts which don't begin with a letter or digit,
and appending :A to account names which have only one part.

Beancount commodity names

hledger will adjust your commodity names to make valid
Beancount commodity/currency names,
which must be 2-24 uppercase letters, digits, or ', ., _, -, beginning with a letter and ending with a letter or digit.
hledger will convert known currency symbols to ISO 4217 currency codes,
capitalise letters, replace spaces with -, replace other unsupported characters with C<HEXBYTES>,
and prepend or append C if needed.

Beancount virtual postings

Beancount doesn't allow virtual postings; if you have any, they will be omitted from beancount output.

Beancount metadata

hledger tags are converted to Beancount metadata lines attached to transactions and postings.
Metadata names and values are adjusted to be Beancount-compatible as needed.
(Names will begin with a lowercase letter, will be at least two characters long, and unsupported characters will be encoded.
Values will use Beancount's string type.)
Internal or user-created tags whose names begin with _ will not be converted.

Unlike normal print output, postings will explicitly show any tags inherited from their account, currently.
This is perhaps correct, but over-verbose (and somewhat inconsistent).

Note that in hledger, objects can have the same tag with multiple values.
Eg an assets:cash account might have both type:C and type:A tags.
In such cases, the values will be combined into one, separated by commas.

Beancount costs

Beancount doesn't allow redundant costs and conversion postings as hledger does.
If you have any of these, the conversion postings will be omitted.
Currently we support at most one cost + conversion postings group per transaction.

Beancount operating currency

Declaring an operating currency (or several) improves Beancount and Fava reports.
Currently hledger will declare each currency used in cost amounts as an operating currency.
If needed, replace these with your own declaration, like

option "operating_currency" "USD"