simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-11-07 21:15:19 +03:00
Code Issues Projects Releases Wiki Activity

update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2018-12-02 17:26:18 -08:00
parent 67d7c82e9f
commit 40713ee7aa
24 changed files with 1334 additions and 734 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-api/hledger-api.1
View File

@ -1,5 +1,5 @@
.TH "hledger\-api" "1" "September 2018" "hledger\-api 1.11.99" "hledger User Manuals"
.TH "hledger\-api" "1" "December 2018" "hledger\-api 1.12" "hledger User Manuals"

8
hledger-api/hledger-api.info
View File

@ -3,8 +3,8 @@ This is hledger-api.info, produced by makeinfo version 6.5 from stdin.

File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-api(1) hledger-api 1.11.99
**********************************
hledger-api(1) hledger-api 1.12
*******************************
hledger-api is a simple web API server, intended to support client-side
web apps operating on hledger data. It comes with a series of simple
@ -80,7 +80,7 @@ options as shown above.

Tag Table:
Node: Top72
Node: OPTIONS1666
Ref: #options1751
Node: OPTIONS1660
Ref: #options1745

End Tag Table

2
hledger-api/hledger-api.txt
View File

@ -117,4 +117,4 @@ SEE ALSO
hledger-api 1.11.99 September 2018 hledger-api(1)
hledger-api 1.12 December 2018 hledger-api(1)

2
hledger-lib/hledger_csv.5
View File

@ -1,5 +1,5 @@
.TH "hledger_csv" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals"
.TH "hledger_csv" "5" "December 2018" "hledger 1.12" "hledger User Manuals"

60
hledger-lib/hledger_csv.info
View File

@ -3,8 +3,8 @@ This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.

File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)
hledger_csv(5) hledger 1.11.99
******************************
hledger_csv(5) hledger 1.12
***************************
hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a
@ -317,33 +317,33 @@ one rules file will be used for all the CSV files being read.

Tag Table:
Node: Top72
Node: CSV RULES2169
Ref: #csv-rules2277
Node: skip2539
Ref: #skip2633
Node: date-format2805
Ref: #date-format2932
Node: field list3438
Ref: #field-list3575
Node: field assignment4280
Ref: #field-assignment4435
Node: conditional block4939
Ref: #conditional-block5093
Node: include5989
Ref: #include6119
Node: newest-first6350
Ref: #newest-first6464
Node: CSV TIPS6875
Ref: #csv-tips6969
Node: CSV ordering7087
Ref: #csv-ordering7205
Node: CSV accounts7386
Ref: #csv-accounts7524
Node: CSV amounts7778
Ref: #csv-amounts7924
Node: CSV balance assertions8699
Ref: #csv-balance-assertions8881
Node: Reading multiple CSV files9086
Ref: #reading-multiple-csv-files9256
Node: CSV RULES2163
Ref: #csv-rules2271
Node: skip2533
Ref: #skip2627
Node: date-format2799
Ref: #date-format2926
Node: field list3432
Ref: #field-list3569
Node: field assignment4274
Ref: #field-assignment4429
Node: conditional block4933
Ref: #conditional-block5087
Node: include5983
Ref: #include6113
Node: newest-first6344
Ref: #newest-first6458
Node: CSV TIPS6869
Ref: #csv-tips6963
Node: CSV ordering7081
Ref: #csv-ordering7199
Node: CSV accounts7380
Ref: #csv-accounts7518
Node: CSV amounts7772
Ref: #csv-amounts7918
Node: CSV balance assertions8693
Ref: #csv-balance-assertions8875
Node: Reading multiple CSV files9080
Ref: #reading-multiple-csv-files9250

End Tag Table

2
hledger-lib/hledger_csv.txt
View File

@ -249,4 +249,4 @@ SEE ALSO
hledger 1.11.99 September 2018 hledger_csv(5)
hledger 1.12 December 2018 hledger_csv(5)

315
hledger-lib/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_journal" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals"
.TH "hledger_journal" "5" "December 2018" "hledger 1.12" "hledger User Manuals"
@ -547,16 +547,57 @@ Use include or concatenate the files instead.
The asserted balance must be a simple single\-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi\-commodity) account balance.
We could call this a partial balance assertion.
This is compatible with Ledger, and makes it possible to make assertions
about accounts containing multiple commodities.
.PD 0
.P
.PD
This is how assertions work in Ledger also.
We could call this a \[lq]partial\[rq] balance assertion.
.PP
To assert each commodity's balance in such a multi\-commodity account,
you can add multiple postings (with amount 0 if necessary).
But note that no matter how many assertions you add, you can't be sure
the account does not contain some unexpected commodity.
(We'll add support for this kind of total balance assertion if there's
demand.)
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance.
.PP
You can make a stronger kind of balance assertion, by writing a double
equals sign (\f[C]==EXPECTEDBALANCE\f[]).
This \[lq]complete\[rq] balance assertion asserts the absence of other
commodities (or, that their balance is 0, which to hledger is
equivalent.)
.IP
.nf
\f[C]
2013/1/1
\ \ a\ \ \ $1
\ \ a\ \ \ \ 1€
\ \ b\ \ $\-1
\ \ c\ \ \ \-1€
2013/1/2\ \ ;\ These\ assertions\ succeed
\ \ a\ \ \ \ 0\ \ =\ \ $1
\ \ a\ \ \ \ 0\ \ =\ \ \ 1€
\ \ b\ \ \ \ 0\ ==\ $\-1
\ \ c\ \ \ \ 0\ ==\ \ \-1€
2013/1/3\ \ ;\ This\ assertion\ fails\ as\ \[aq]a\[aq]\ also\ contains\ 1€
\ \ a\ \ \ \ 0\ ==\ \ $1
\f[]
.fi
.PP
It's not yet possible to make a complete assertion about a balance that
has multiple commodities.
One workaround is to isolate each commodity into its own subaccount:
.IP
.nf
\f[C]
2013/1/1
\ \ a:usd\ \ \ $1
\ \ a:euro\ \ \ 1€
\ \ b
2013/1/2
\ \ a\ \ \ \ \ \ \ \ 0\ ==\ \ 0
\ \ a:usd\ \ \ \ 0\ ==\ $1
\ \ a:euro\ \ \ 0\ ==\ \ 1€
\f[]
.fi
.SS Assertions and subaccounts
.PP
Balance assertions do not count the balance from subaccounts; they check
@ -853,10 +894,9 @@ T}@T{
T}@T{
any text
T}@T{
declare an account name & optional account code
document account names, declare account types & display order
T}@T{
account code: balance reports (except \f[C]balance\f[] single\-column
mode)
all entries in all files, before or after
T}
T{
\f[C]alias\f[]
@ -951,13 +991,8 @@ lw(8.9n) lw(61.1n).
T{
subdirective
T}@T{
optional indented directive or unparsed text lines immediately following
a parent directive
T}
T{
account code
T}@T{
numeric code influencing account display order in most balance reports
optional indented directive line immediately following a parent
directive
T}
T{
number notation
@ -1143,58 +1178,108 @@ The \f[C]\-V/\-\-value\f[] flag can be used to convert reported amounts
to another commodity using these prices.
.SS Declaring accounts
.PP
The \f[C]account\f[] directive predeclares account names.
The simplest form is \f[C]account\ ACCTNAME\f[], eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\f[]
.fi
\f[C]account\f[] directives can be used to pre\-declare some or all
accounts.
Though not required, they can provide several benefits:
.IP \[bu] 2
They can document your intended chart of accounts, providing a
reference.
.IP \[bu] 2
They can store extra information about accounts (account numbers, notes,
etc.)
.IP \[bu] 2
They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
.IP \[bu] 2
They control account display order in reports, allowing non\-alphabetic
sorting (eg Revenues to appear above Expenses).
.IP \[bu] 2
They help with account name completion in the add command,
hledger\-iadd, hledger\-web, ledger\-mode etc.
.PP
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
.PD 0
.P
.PD
In future it will also help detect misspelled accounts.
.PP
An account directive can also have indented subdirectives following it,
which are currently ignored.
Here is the full syntax:
.IP
.nf
\f[C]
;\ account\ ACCTNAME
;\ \ \ [OPTIONALSUBDIRECTIVES]
account\ assets:bank:checking
\ \ a\ comment
\ \ some\-tag:12345
account\ ACCTNAME\ \ [ACCTTYPE]
\ \ [COMMENTS]
\f[]
.fi
.SS Account display order
.PP
Account directives have another purpose: they set the order in which
accounts are displayed, in hledger reports, hledger\-ui accounts screen,
hledger\-web sidebar etc.
For example, say you have these top\-level accounts:
The simplest form just declares a hledger\-style account name, eg:
.IP
.nf
\f[C]
$\ accounts\ \-1
assets
equity
expenses
liabilities
misc
other
revenues
account\ assets:bank:checking
\f[]
.fi
.SS Account types
.PP
hledger recognises five types of account: asset, liability, equity,
revenue, expense.
This is useful for certain accounting\-aware reports, in particular
balancesheet, incomestatement and cashflow.
.PP
If you name your top\-level accounts with some variation of
\f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[],
\f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are
detected automatically.
.PP
More generally, you can declare an account's type by adding one of the
letters \f[C]ALERX\f[] to its account directive, separated from the
account name by two or more spaces.
Eg:
.IP
.nf
\f[C]
account\ assets\ \ \ \ \ \ \ A
account\ liabilities\ \ L
account\ equity\ \ \ \ \ \ \ E
account\ revenues\ \ \ \ \ R
account\ expenses\ \ \ \ \ X
\f[]
.fi
.PP
By default, they are displayed in alphabetical order.
But if you add the following account directives to the journal:
Note: if you ever override the types of those auto\-detected english
account names mentioned above, you might need to help the reports a bit:
.IP
.nf
\f[C]
;\ make\ "liabilities"\ not\ have\ the\ liability\ type,\ who\ knows\ why
account\ liabilities\ \ \ E
;\ better\ ensure\ some\ other\ account\ has\ the\ liability\ type,\
;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\
account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ L
\f[]
.fi
.PP
)
.SS Account comments
.PP
An account directive can also have indented comments on following lines,
eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\ \ ;\ acctno:12345
\ \ ;\ a\ comment
\f[]
.fi
.PP
We also allow (and ignore) Ledger\-style subdirectives, with no leading
semicolon, for compatibility.
.PP
Tags in account comments, like \f[C]acctno\f[] above, currently have no
effect.
.SS Account display order
.PP
Account directives also set the order in which accounts are displayed in
reports, the hledger\-ui accounts screen, the hledger\-web sidebar, etc.
Normally accounts are listed in alphabetical order, but if you have eg
these account directives in the journal:
.IP
.nf
\f[C]
@ -1206,27 +1291,25 @@ account\ expenses
\f[]
.fi
.PP
the display order changes to:
you'll see those accounts listed in declaration order, not
alphabetically:
.IP
.nf
\f[C]
$\ accounts\ \-1
$\ hledger\ accounts\ \-1
assets
liabilities
equity
revenues
expenses
misc
other
\f[]
.fi
.PP
Ie, declared accounts first, in the order they were declared, followed
by any undeclared accounts in alphabetic order.
Undeclared accounts, if any, are displayed last, in alphabetical order.
.PP
Note that sorting is done at each level of the account tree (within each
group of sibling accounts under the same parent).
This directive:
And currently, this directive:
.IP
.nf
\f[C]
@ -1237,6 +1320,10 @@ account\ other:zoo
would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s
subaccounts, but not the position of \f[C]other\f[] among the top\-level
accounts.
This means: \- you will sometimes declare parent accounts (eg
\f[C]account\ other\f[] above) that you don't intend to post to, just to
customize their display order \- sibling accounts stay together (you
couldn't display \f[C]x:y\f[] in between \f[C]a:b\f[] and \f[C]a:c\f[]).
.SS Rewriting accounts
.PP
You can define account alias rules which rewrite your account names, or
@ -1419,16 +1506,25 @@ date must fall on a natural boundary of the interval.
Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
\f[C]monthly\ from\ 2018/1/15\f[] is not.
.PP
If you write a transaction description or same\-line comment, it must be
separated from the period expression by \f[B]two or more spaces\f[].
Eg:
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not).
They will be relative to today's date, unless a Y default year directive
is in effect, in which case they will be relative to Y/1/1.
.PP
Period expressions must be terminated by \f[B]two or more spaces\f[] if
followed by additional fields.
For example, the periodic transaction given below includes a transaction
description \[lq]paycheck\[rq], which is separated from the period
expression by a double space.
If not for the second space, hledger would attempt (and fail) to parse
\[lq]paycheck\[rq] as a part of the period expression.
.IP
.nf
\f[C]
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
~\ every\ 2\ weeks\ from\ 2018/6\ to\ 2018/9\ \ paycheck
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
~\ every\ 2\ weeks\ from\ 2018/6/4\ to\ 2018/9\ \ paycheck
\ \ \ \ assets:bank:checking\ \ \ $1500
\ \ \ \ income:acme\ inc
\f[]
@ -1495,50 +1591,81 @@ Currently, this means adding extra postings (also known as
\[lq]automated postings\[rq]).
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
.PP
A transaction modifier rule looks a bit like a normal journal entry,
except the first line is an equal sign (\f[C]=\f[]) followed by a query
(mnemonic: \f[C]=\f[] suggests matching something.):
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that matches
certain postings (mnemonic: \f[C]=\f[] suggests matching).
And each \[lq]posting\[rq] is actually a posting\-generating rule:
.IP
.nf
\f[C]
=\ expenses:gifts
\ \ \ \ budget:gifts\ \ *\-1
\ \ \ \ assets:budget\ \ *1
=\ QUERY
\ \ \ \ ACCT\ \ AMT
\ \ \ \ ACCT\ \ [AMT]
\ \ \ \ ...
\f[]
.fi
.PP
The posting amounts can be of the form \f[C]*N\f[], which means \[lq]the
amount of the matched transaction's first posting, multiplied by N\[rq].
They can also be ordinary fixed amounts.
Fixed amounts with no commodity symbol will be given the same commodity
as the matched transaction's first posting.
The posting rules look just like normal postings, except the amount can
be:
.IP \[bu] 2
a normal amount with a commodity symbol, eg \f[C]$2\f[].
This will be used as\-is.
.IP \[bu] 2
a number, eg \f[C]2\f[].
The commodity symbol (if any) from the matched posting will be added to
this.
.IP \[bu] 2
a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N).
The matched posting's amount (and total price, if any) will be
multiplied by N.
.IP \[bu] 2
a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N,
and symbol S).
The matched posting's amount will be multiplied by N, and its commodity
symbol will be replaced with S.
.PP
This example adds a corresponding (unbalanced) budget posting to every
transaction involving the \f[C]expenses:gifts\f[] account:
Some examples:
.IP
.nf
\f[C]
=\ expenses:gifts
\ \ \ \ (budget:gifts)\ \ *\-1
;\ every\ time\ I\ buy\ food,\ schedule\ a\ dollar\ donation
=\ expenses:food
\ \ \ \ (liabilities:charity)\ \ \ $\-1
2017\-12\-14
\ \ expenses:gifts\ \ $20
\ \ assets
;\ when\ I\ buy\ a\ gift,\ also\ deduct\ that\ amount\ from\ a\ budget\ envelope\ subaccount
=\ expenses:gifts
\ \ \ \ assets:checking:gifts\ \ *\-1
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ *1
2017/12/1
\ \ expenses:food\ \ \ \ $10
\ \ assets:checking
2017/12/14
\ \ expenses:gifts\ \ \ $20
\ \ assets:checking
\f[]
.fi
.IP
.nf
\f[C]
$\ hledger\ print\ \-\-auto
2017/12/01
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
\ \ \ \ assets:checking
\ \ \ \ (liabilities:charity)\ \ \ \ \ \ $\-1
2017/12/14
\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
\ \ \ \ (budget:gifts)\ \ \ \ \ \ \ \ \ \ \ \ $\-20
\ \ \ \ assets
\ \ \ \ assets:checking
\ \ \ \ assets:checking:gifts\ \ \ \ \ \-$20
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20
\f[]
.fi
.PP
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
Postings added by transaction modifiers participate in transaction
balancing, missing amount inference and balance assertions, like regular
postings.
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with

494
hledger-lib/hledger_journal.info
View File

@ -4,8 +4,8 @@ stdin.

File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_journal(5) hledger 1.11.99
**********************************
hledger_journal(5) hledger 1.12
*******************************
hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard
@ -524,16 +524,46 @@ File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a
partial balance assertion. This is compatible with Ledger, and makes it
possible to make assertions about accounts containing multiple
commodities.
(possibly multi-commodity) account balance.
This is how assertions work in Ledger also. We could call this a
"partial" balance assertion.
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)
To assert the balance of more than one commodity in an account, you
can write multiple postings, each asserting one commodity's balance.
You can make a stronger kind of balance assertion, by writing a
double equals sign ('==EXPECTEDBALANCE'). This "complete" balance
assertion asserts the absence of other commodities (or, that their
balance is 0, which to hledger is equivalent.)
2013/1/1
a $1
a 1€
b $-1
c -1€
2013/1/2 ; These assertions succeed
a 0 = $1
a 0 = 1€
b 0 == $-1
c 0 == -1€
2013/1/3 ; This assertion fails as 'a' also contains 1€
a 0 == $1
It's not yet possible to make a complete assertion about a balance
that has multiple commodities. One workaround is to isolate each
commodity into its own subaccount:
2013/1/1
a:usd $1
a:euro 1€
b
2013/1/2
a 0 == 0
a:usd 0 == $1
a:euro 0 == 1€

File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions
@ -766,11 +796,9 @@ links to more detailed docs.
directiveend subdirectivespurpose can affect (as of
directive 2018/06)
-----------------------------------------------------------------------------
'account' any declare an account name & account code:
text optional account code balance reports
(except 'balance'
single-column
mode)
'account' any document account names, all entries in
text declare account types & all files, before
display order or after
'alias' 'end rewrite account names following
aliases' inline/included
entries until end
@ -821,10 +849,8 @@ account' apply account names inline/included
And some definitions:
subdirectiveoptional indented directive or unparsed text lines
immediately following a parent directive
account numeric code influencing account display order in most
code balance reports
subdirectiveoptional indented directive line immediately following a
parent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
@ -853,7 +879,6 @@ times though.
* Default commodity::
* Market prices::
* Declaring accounts::
* Account display order::
* Rewriting accounts::
* Default parent account::
@ -1003,52 +1028,106 @@ P 2010/1/1 € $1.40
another commodity using these prices.

File: hledger_journal.info, Node: Declaring accounts, Next: Account display order, Prev: Market prices, Up: Directives
File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives
1.14.7 Declaring accounts
-------------------------
The 'account' directive predeclares account names. The simplest form is
'account ACCTNAME', eg:
'account' directives can be used to pre-declare some or all accounts.
Though not required, they can provide several benefits:
* They can document your intended chart of accounts, providing a
reference.
* They can store extra information about accounts (account numbers,
notes, etc.)
* They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
* They control account display order in reports, allowing
non-alphabetic sorting (eg Revenues to appear above Expenses).
* They help with account name completion in the add command,
hledger-iadd, hledger-web, ledger-mode etc.
Here is the full syntax:
account ACCTNAME [ACCTTYPE]
[COMMENTS]
The simplest form just declares a hledger-style account name, eg:
account assets:bank:checking
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger-iadd, hledger-web, and ledger-mode.
In future it will also help detect misspelled accounts.
* Menu:
An account directive can also have indented subdirectives following
it, which are currently ignored. Here is the full syntax:
; account ACCTNAME
; [OPTIONALSUBDIRECTIVES]
account assets:bank:checking
a comment
some-tag:12345
* Account types::
* Account comments::
* Account display order::

File: hledger_journal.info, Node: Account display order, Next: Rewriting accounts, Prev: Declaring accounts, Up: Directives
File: hledger_journal.info, Node: Account types, Next: Account comments, Up: Declaring accounts
1.14.8 Account display order
----------------------------
1.14.7.1 Account types
......................
Account directives have another purpose: they set the order in which
accounts are displayed, in hledger reports, hledger-ui accounts screen,
hledger-web sidebar etc. For example, say you have these top-level
accounts:
hledger recognises five types of account: asset, liability, equity,
revenue, expense. This is useful for certain accounting-aware reports,
in particular balancesheet, incomestatement and cashflow.
$ accounts -1
assets
equity
expenses
liabilities
misc
other
revenues
If you name your top-level accounts with some variation of 'assets',
'liabilities'/'debts', 'equity', 'revenues'/'income', or 'expenses',
their types are detected automatically.
By default, they are displayed in alphabetical order. But if you add
the following account directives to the journal:
More generally, you can declare an account's type by adding one of
the letters 'ALERX' to its account directive, separated from the account
name by two or more spaces. Eg:
account assets A
account liabilities L
account equity E
account revenues R
account expenses X
Note: if you ever override the types of those auto-detected english
account names mentioned above, you might need to help the reports a bit:
; make "liabilities" not have the liability type, who knows why
account liabilities E
; better ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities
account - L
)

File: hledger_journal.info, Node: Account comments, Next: Account display order, Prev: Account types, Up: Declaring accounts
1.14.7.2 Account comments
.........................
An account directive can also have indented comments on following lines,
eg:
account assets:bank:checking
; acctno:12345
; a comment
We also allow (and ignore) Ledger-style subdirectives, with no
leading semicolon, for compatibility.
Tags in account comments, like 'acctno' above, currently have no
effect.

File: hledger_journal.info, Node: Account display order, Prev: Account comments, Up: Declaring accounts
1.14.7.3 Account display order
..............................
Account directives also set the order in which accounts are displayed in
reports, the hledger-ui accounts screen, the hledger-web sidebar, etc.
Normally accounts are listed in alphabetical order, but if you have eg
these account directives in the journal:
account assets
account liabilities
@ -1056,32 +1135,36 @@ account equity
account revenues
account expenses
the display order changes to:
you'll see those accounts listed in declaration order, not
alphabetically:
$ accounts -1
$ hledger accounts -1
assets
liabilities
equity
revenues
expenses
misc
other
Ie, declared accounts first, in the order they were declared,
followed by any undeclared accounts in alphabetic order.
Undeclared accounts, if any, are displayed last, in alphabetical
order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). This directive:
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of 'zoo' among 'other''s subaccounts,
but not the position of 'other' among the top-level accounts.
but not the position of 'other' among the top-level accounts. This
means: - you will sometimes declare parent accounts (eg 'account other'
above) that you don't intend to post to, just to customize their display
order - sibling accounts stay together (you couldn't display 'x:y' in
between 'a:b' and 'a:c').

File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Account display order, Up: Directives
File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
1.14.9 Rewriting accounts
1.14.8 Rewriting accounts
-------------------------
You can define account alias rules which rewrite your account names, or
@ -1109,7 +1192,7 @@ hledger-web.

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
1.14.9.1 Basic aliases
1.14.8.1 Basic aliases
......................
To set an account alias, use the 'alias' directive in your journal file.
@ -1132,7 +1215,7 @@ alias checking = assets:bank:wells fargo:checking

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.9.2 Regex aliases
1.14.8.2 Regex aliases
......................
There is also a more powerful variant that uses a regular expression,
@ -1157,7 +1240,7 @@ whitespace.

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.9.3 Multiple aliases
1.14.8.3 Multiple aliases
.........................
You can define as many aliases as you like using directives or
@ -1173,7 +1256,7 @@ following order:

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts
1.14.9.4 'end aliases'
1.14.8.4 'end aliases'
......................
You can clear (forget) all currently defined aliases with the 'end
@ -1184,8 +1267,8 @@ end aliases

File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
1.14.10 Default parent account
------------------------------
1.14.9 Default parent account
-----------------------------
You can specify a parent account which will be prepended to all accounts
within a section of the journal. Use the 'apply account' and 'end apply
@ -1245,13 +1328,22 @@ the date replaced by a tilde ('~') followed by a period expression
date must fall on a natural boundary of the interval. Eg 'monthly from
2018/1/1' is valid, but 'monthly from 2018/1/15' is not.
If you write a transaction description or same-line comment, it must
be separated from the period expression by *two or more spaces*. Eg:
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case they
will be relative to Y/1/1.
; 2 or more spaces
; ||
; vv
~ every 2 weeks from 2018/6 to 2018/9 paycheck
Period expressions must be terminated by *two or more spaces* if
followed by additional fields. For example, the periodic transaction
given below includes a transaction description "paycheck", which is
separated from the period expression by a double space. If not for the
second space, hledger would attempt (and fail) to parse "paycheck" as a
part of the period expression.
; 2 or more spaces
; ||
; vv
~ every 2 weeks from 2018/6/4 to 2018/9 paycheck
assets:bank:checking $1500
income:acme inc
@ -1330,38 +1422,64 @@ automatically to certain transactions. Currently, this means adding
extra postings (also known as "automated postings"). Transaction
modifiers are enabled by the '--auto' flag.
A transaction modifier rule looks a bit like a normal journal entry,
except the first line is an equal sign ('=') followed by a query
(mnemonic: '=' suggests matching something.):
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that matches
certain postings (mnemonic: '=' suggests matching). And each "posting"
is actually a posting-generating rule:
= QUERY
ACCT AMT
ACCT [AMT]
...
The posting rules look just like normal postings, except the amount
can be:
* a normal amount with a commodity symbol, eg '$2'. This will be
used as-is.
* a number, eg '2'. The commodity symbol (if any) from the matched
posting will be added to this.
* a numeric multiplier, eg '*2' (a star followed by a number N). The
matched posting's amount (and total price, if any) will be
multiplied by N.
* a multiplier with a commodity symbol, eg '*$2' (a star, number N,
and symbol S). The matched posting's amount will be multiplied by
N, and its commodity symbol will be replaced with S.
Some examples:
; every time I buy food, schedule a dollar donation
= expenses:food
(liabilities:charity) $-1
; when I buy a gift, also deduct that amount from a budget envelope subaccount
= expenses:gifts
budget:gifts *-1
assets:budget *1
assets:checking:gifts *-1
assets:checking *1
The posting amounts can be of the form '*N', which means "the amount
of the matched transaction's first posting, multiplied by N". They can
also be ordinary fixed amounts. Fixed amounts with no commodity symbol
will be given the same commodity as the matched transaction's first
posting.
2017/12/1
expenses:food $10
assets:checking
This example adds a corresponding (unbalanced) budget posting to
every transaction involving the 'expenses:gifts' account:
= expenses:gifts
(budget:gifts) *-1
2017-12-14
expenses:gifts $20
assets
2017/12/14
expenses:gifts $20
assets:checking
$ hledger print --auto
2017/12/01
expenses:food $10
assets:checking
(liabilities:charity) $-1
2017/12/14
expenses:gifts $20
(budget:gifts) $-20
assets
assets:checking
assets:checking:gifts -$20
assets:checking $20
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
Postings added by transaction modifiers participate in transaction
balancing, missing amount inference and balance assertions, like regular
postings.

File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -1393,93 +1511,97 @@ Code

Tag Table:
Node: Top76
Node: FILE FORMAT2378
Ref: #file-format2502
Node: Transactions2789
Ref: #transactions2910
Node: Postings3594
Ref: #postings3721
Node: Dates4716
Ref: #dates4831
Node: Simple dates4896
Ref: #simple-dates5022
Node: Secondary dates5388
Ref: #secondary-dates5542
Node: Posting dates7105
Ref: #posting-dates7234
Node: Status8608
Ref: #status8728
Node: Description10436
Ref: #description10574
Node: Payee and note10893
Ref: #payee-and-note11007
Node: Account names11249
Ref: #account-names11392
Node: Amounts11879
Ref: #amounts12015
Node: Virtual Postings15032
Ref: #virtual-postings15191
Node: Balance Assertions16411
Ref: #balance-assertions16586
Node: Assertions and ordering17482
Ref: #assertions-and-ordering17668
Node: Assertions and included files18368
Ref: #assertions-and-included-files18609
Node: Assertions and multiple -f options18942
Ref: #assertions-and-multiple--f-options19196
Node: Assertions and commodities19328
Ref: #assertions-and-commodities19563
Node: Assertions and subaccounts20259
Ref: #assertions-and-subaccounts20491
Node: Assertions and virtual postings21012
Ref: #assertions-and-virtual-postings21219
Node: Balance Assignments21361
Ref: #balance-assignments21542
Node: Transaction prices22662
Ref: #transaction-prices22831
Node: Comments25099
Ref: #comments25233
Node: Tags26403
Ref: #tags26521
Node: Directives27923
Ref: #directives28066
Node: Comment blocks33948
Ref: #comment-blocks34093
Node: Including other files34269
Ref: #including-other-files34449
Node: Default year34857
Ref: #default-year35026
Node: Declaring commodities35449
Ref: #declaring-commodities35632
Node: Default commodity36859
Ref: #default-commodity37035
Node: Market prices37671
Ref: #market-prices37836
Node: Declaring accounts38677
Ref: #declaring-accounts38856
Node: Account display order39406
Ref: #account-display-order39596
Node: Rewriting accounts40617
Ref: #rewriting-accounts40805
Node: Basic aliases41539
Ref: #basic-aliases41685
Node: Regex aliases42389
Ref: #regex-aliases42560
Node: Multiple aliases43278
Ref: #multiple-aliases43453
Node: end aliases43951
Ref: #end-aliases44098
Node: Default parent account44199
Ref: #default-parent-account44367
Node: Periodic transactions45251
Ref: #periodic-transactions45433
Node: Forecasting with periodic transactions46644
Ref: #forecasting-with-periodic-transactions46887
Node: Budgeting with periodic transactions48574
Ref: #budgeting-with-periodic-transactions48813
Node: Transaction Modifiers49272
Ref: #transaction-modifiers49435
Node: EDITOR SUPPORT50691
Ref: #editor-support50809
Node: FILE FORMAT2372
Ref: #file-format2496
Node: Transactions2783
Ref: #transactions2904
Node: Postings3588
Ref: #postings3715
Node: Dates4710
Ref: #dates4825
Node: Simple dates4890
Ref: #simple-dates5016
Node: Secondary dates5382
Ref: #secondary-dates5536
Node: Posting dates7099
Ref: #posting-dates7228
Node: Status8602
Ref: #status8722
Node: Description10430
Ref: #description10568
Node: Payee and note10887
Ref: #payee-and-note11001
Node: Account names11243
Ref: #account-names11386
Node: Amounts11873
Ref: #amounts12009
Node: Virtual Postings15026
Ref: #virtual-postings15185
Node: Balance Assertions16405
Ref: #balance-assertions16580
Node: Assertions and ordering17476
Ref: #assertions-and-ordering17662
Node: Assertions and included files18362
Ref: #assertions-and-included-files18603
Node: Assertions and multiple -f options18936
Ref: #assertions-and-multiple--f-options19190
Node: Assertions and commodities19322
Ref: #assertions-and-commodities19557
Node: Assertions and subaccounts20745
Ref: #assertions-and-subaccounts20977
Node: Assertions and virtual postings21498
Ref: #assertions-and-virtual-postings21705
Node: Balance Assignments21847
Ref: #balance-assignments22028
Node: Transaction prices23148
Ref: #transaction-prices23317
Node: Comments25585
Ref: #comments25719
Node: Tags26889
Ref: #tags27007
Node: Directives28409
Ref: #directives28552
Node: Comment blocks34159
Ref: #comment-blocks34304
Node: Including other files34480
Ref: #including-other-files34660
Node: Default year35068
Ref: #default-year35237
Node: Declaring commodities35660
Ref: #declaring-commodities35843
Node: Default commodity37070
Ref: #default-commodity37246
Node: Market prices37882
Ref: #market-prices38047
Node: Declaring accounts38888
Ref: #declaring-accounts39064
Node: Account types40021
Ref: #account-types40170
Node: Account comments41244
Ref: #account-comments41429
Node: Account display order41750
Ref: #account-display-order41923
Node: Rewriting accounts43045
Ref: #rewriting-accounts43230
Node: Basic aliases43964
Ref: #basic-aliases44110
Node: Regex aliases44814
Ref: #regex-aliases44985
Node: Multiple aliases45703
Ref: #multiple-aliases45878
Node: end aliases46376
Ref: #end-aliases46523
Node: Default parent account46624
Ref: #default-parent-account46790
Node: Periodic transactions47674
Ref: #periodic-transactions47856
Node: Forecasting with periodic transactions49559
Ref: #forecasting-with-periodic-transactions49802
Node: Budgeting with periodic transactions51489
Ref: #budgeting-with-periodic-transactions51728
Node: Transaction Modifiers52187
Ref: #transaction-modifiers52350
Node: EDITOR SUPPORT54331
Ref: #editor-support54449

End Tag Table

421
hledger-lib/hledger_journal.txt
View File

@ -405,16 +405,46 @@ FILE FORMAT
Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a par-
tial balance assertion. This is compatible with Ledger, and makes it
possible to make assertions about accounts containing multiple commodi-
ties.
(possibly multi-commodity) account balance.
This is how assertions work in Ledger also. We could call this a "par-
tial" balance assertion.
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance.
You can make a stronger kind of balance assertion, by writing a double
equals sign (==EXPECTEDBALANCE). This "complete" balance assertion
asserts the absence of other commodities (or, that their balance is 0,
which to hledger is equivalent.)
2013/1/1
a $1
a 1
b $-1
c -1
2013/1/2 ; These assertions succeed
a 0 = $1
a 0 = 1
b 0 == $-1
c 0 == -1
2013/1/3 ; This assertion fails as 'a' also contains 1
a 0 == $1
It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity
into its own subaccount:
2013/1/1
a:usd $1
a:euro 1
b
2013/1/2
a 0 == 0
a:usd 0 == $1
a:euro 0 == 1
Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they
@ -614,40 +644,51 @@ FILE FORMAT
tive directive rec- 2018/06)
tives
-------------------------------------------------------------------------------------------------
account any declare an account name & account code: bal-
text optional account code ance reports
(except balance
single-column mode)
account any document account names, all entries in all
text declare account types & dis- files, before or
play order after
alias end aliases rewrite account names following
inline/included
entries until end
of current file or
of current file or
end directive
apply account end apply account prepend a common parent to following
apply account end apply account prepend a common parent to following
account names inline/included
entries until end
of current file or
of current file or
end directive
comment end comment ignore part of journal following
inline/included
entries until end
of current file or
of current file or
end directive
commodity format declare a commodity and its number notation:
commodity format declare a commodity and its number notation:
number notation & display following entries
style in that commodity
in all files; dis-
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
less entries and
entries in that
commodity in all
commodity in all
files; display
style: amounts of
that commodity in
@ -658,7 +699,7 @@ FILE FORMAT
commodity commodity in
reports, when -V is
used
Y declare a year for yearless following
Y declare a year for yearless following
dates inline/included
entries until end
of current file
@ -666,16 +707,11 @@ FILE FORMAT
And some definitions:
subdirec- optional indented directive or unparsed text lines immedi-
tive ately following a parent directive
account numeric code influencing account display order in most bal-
code ance reports
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@ -683,37 +719,37 @@ FILE FORMAT
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
writing file options in a different order. It can be surprising at
times though.
Comment blocks
A line containing just comment starts a commented region of the file,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -733,8 +769,8 @@ FILE FORMAT
assets
Declaring commodities
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -744,8 +780,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
@ -757,19 +793,19 @@ FILE FORMAT
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
The D directive sets a default commodity (and display format), to be
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
@ -784,9 +820,9 @@ FILE FORMAT
a decimal point.
Market prices
The P directive declares a market price, which is an exchange rate
The P directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@ -797,55 +833,97 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, giving the price in commodity B of one unit of commodity A.
These two market price directives say that one euro was worth 1.35 US
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35
P 2010/1/1 $1.40
The -V/--value flag can be used to convert reported amounts to another
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
The account directive predeclares account names. The simplest form is
account ACCTNAME, eg:
account directives can be used to pre-declare some or all accounts.
Though not required, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer-
ence.
o They can store extra information about accounts (account numbers,
notes, etc.)
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command,
hledger-iadd, hledger-web, ledger-mode etc.
Here is the full syntax:
account ACCTNAME [ACCTTYPE]
[COMMENTS]
The simplest form just declares a hledger-style account name, eg:
account assets:bank:checking
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger-iadd, hledger-web, and ledger-mode.
In future it will also help detect misspelled accounts.
Account types
hledger recognises five types of account: asset, liability, equity,
revenue, expense. This is useful for certain accounting-aware reports,
in particular balancesheet, incomestatement and cashflow.
An account directive can also have indented subdirectives following it,
which are currently ignored. Here is the full syntax:
If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
; account ACCTNAME
; [OPTIONALSUBDIRECTIVES]
More generally, you can declare an account's type by adding one of the
letters ALERX to its account directive, separated from the account name
by two or more spaces. Eg:
account assets A
account liabilities L
account equity E
account revenues R
account expenses X
Note: if you ever override the types of those auto-detected english
account names mentioned above, you might need to help the reports a
bit:
; make "liabilities" not have the liability type, who knows why
account liabilities E
; better ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities
account - L
)
Account comments
An account directive can also have indented comments on following
lines, eg:
account assets:bank:checking
a comment
some-tag:12345
; acctno:12345
; a comment
We also allow (and ignore) Ledger-style subdirectives, with no leading
semicolon, for compatibility.
Tags in account comments, like acctno above, currently have no effect.
Account display order
Account directives have another purpose: they set the order in which
accounts are displayed, in hledger reports, hledger-ui accounts screen,
hledger-web sidebar etc. For example, say you have these top-level
accounts:
$ accounts -1
assets
equity
expenses
liabilities
misc
other
revenues
By default, they are displayed in alphabetical order. But if you add
the following account directives to the journal:
Account directives also set the order in which accounts are displayed
in reports, the hledger-ui accounts screen, the hledger-web sidebar,
etc. Normally accounts are listed in alphabetical order, but if you
have eg these account directives in the journal:
account assets
account liabilities
@ -853,27 +931,30 @@ FILE FORMAT
account revenues
account expenses
the display order changes to:
you'll see those accounts listed in declaration order, not alphabeti-
cally:
$ accounts -1
$ hledger accounts -1
assets
liabilities
equity
revenues
expenses
misc
other
Ie, declared accounts first, in the order they were declared, followed
by any undeclared accounts in alphabetic order.
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). This directive:
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts.
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
Rewriting accounts
You can define account alias rules which rewrite your account names, or
@ -1004,105 +1085,143 @@ FILE FORMAT
date must fall on a natural boundary of the interval. Eg
monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not.
If you write a transaction description or same-line comment, it must be
separated from the period expression by two or more spaces. Eg:
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
; 2 or more spaces
; ||
; vv
~ every 2 weeks from 2018/6 to 2018/9 paycheck
Period expressions must be terminated by two or more spaces if followed
by additional fields. For example, the periodic transaction given
below includes a transaction description "paycheck", which is separated
from the period expression by a double space. If not for the second
space, hledger would attempt (and fail) to parse "paycheck" as a part
of the period expression.
; 2 or more spaces
; ||
; vv
~ every 2 weeks from 2018/6/4 to 2018/9 paycheck
assets:bank:checking $1500
income:acme inc
Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates
With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
the generating period expression.
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
forecast period:
o begins on the later of
o the report start date if specified with -b/-p/date:
o the day after the latest normal (non-periodic) transaction in the
o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
o ends on the report end date if specified with -e/-p/date:, or 180
o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
actions with periodic rules, and every so often copy the output of
actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
For more details, see: balance: Budget report and Cookbook: Budgeting
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
Transaction Modifiers
Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding
Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding
extra postings (also known as "automated postings"). Transaction modi-
fiers are enabled by the --auto flag.
A transaction modifier rule looks a bit like a normal journal entry,
except the first line is an equal sign (=) followed by a query
(mnemonic: = suggests matching something.):
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each
"posting" is actually a posting-generating rule:
= QUERY
ACCT AMT
ACCT [AMT]
...
The posting rules look just like normal postings, except the amount can
be:
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
o a numeric multiplier, eg *2 (a star followed by a number N). The
matched posting's amount (and total price, if any) will be multiplied
by N.
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
Some examples:
; every time I buy food, schedule a dollar donation
= expenses:food
(liabilities:charity) $-1
; when I buy a gift, also deduct that amount from a budget envelope subaccount
= expenses:gifts
budget:gifts *-1
assets:budget *1
assets:checking:gifts *-1
assets:checking *1
The posting amounts can be of the form *N, which means "the amount of
the matched transaction's first posting, multiplied by N". They can
also be ordinary fixed amounts. Fixed amounts with no commodity symbol
will be given the same commodity as the matched transaction's first
posting.
2017/12/1
expenses:food $10
assets:checking
This example adds a corresponding (unbalanced) budget posting to every
transaction involving the expenses:gifts account:
= expenses:gifts
(budget:gifts) *-1
2017-12-14
expenses:gifts $20
assets
2017/12/14
expenses:gifts $20
assets:checking
$ hledger print --auto
2017/12/01
expenses:food $10
assets:checking
(liabilities:charity) $-1
2017/12/14
expenses:gifts $20
(budget:gifts) $-20
assets
assets:checking
assets:checking:gifts -$20
assets:checking $20
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
Postings added by transaction modifiers participate in transaction bal-
ancing, missing amount inference and balance assertions, like regular
postings.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
@ -1151,4 +1270,4 @@ SEE ALSO
hledger 1.11.99 September 2018 hledger_journal(5)
hledger 1.12 December 2018 hledger_journal(5)

2
hledger-lib/hledger_timeclock.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals"
.TH "hledger_timeclock" "5" "December 2018" "hledger 1.12" "hledger User Manuals"

4
hledger-lib/hledger_timeclock.info
View File

@ -4,8 +4,8 @@ stdin.

File: hledger_timeclock.info, Node: Top, Up: (dir)
hledger_timeclock(5) hledger 1.11.99
************************************
hledger_timeclock(5) hledger 1.12
*********************************
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as

2
hledger-lib/hledger_timeclock.txt
View File

@ -77,4 +77,4 @@ SEE ALSO
hledger 1.11.99 September 2018 hledger_timeclock(5)
hledger 1.12 December 2018 hledger_timeclock(5)

2
hledger-lib/hledger_timedot.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals"
.TH "hledger_timedot" "5" "December 2018" "hledger 1.12" "hledger User Manuals"

8
hledger-lib/hledger_timedot.info
View File

@ -4,8 +4,8 @@ stdin.

File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_timedot(5) hledger 1.11.99
**********************************
hledger_timedot(5) hledger 1.12
*******************************
Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. It is convenient for
@ -110,7 +110,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4

Tag Table:
Node: Top76
Node: FILE FORMAT813
Ref: #file-format914
Node: FILE FORMAT807
Ref: #file-format908

End Tag Table

2
hledger-lib/hledger_timedot.txt
View File

@ -124,4 +124,4 @@ SEE ALSO
hledger 1.11.99 September 2018 hledger_timedot(5)
hledger 1.12 December 2018 hledger_timedot(5)

2
hledger-ui/hledger-ui.1
View File

@ -1,5 +1,5 @@
.TH "hledger\-ui" "1" "September 2018" "hledger\-ui 1.11.99" "hledger User Manuals"
.TH "hledger\-ui" "1" "December 2018" "hledger\-ui 1.12" "hledger User Manuals"

32
hledger-ui/hledger-ui.info
View File

@ -3,8 +3,8 @@ This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.

File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-ui(1) hledger-ui 1.11.99
********************************
hledger-ui(1) hledger-ui 1.12
*****************************
hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some
@ -396,19 +396,19 @@ to cancel the reload attempt.)

Tag Table:
Node: Top71
Node: OPTIONS1090
Ref: #options1187
Node: KEYS4606
Ref: #keys4701
Node: SCREENS7957
Ref: #screens8042
Node: Accounts screen8132
Ref: #accounts-screen8260
Node: Register screen10476
Ref: #register-screen10631
Node: Transaction screen12628
Ref: #transaction-screen12786
Node: Error screen13656
Ref: #error-screen13778
Node: OPTIONS1084
Ref: #options1181
Node: KEYS4600
Ref: #keys4695
Node: SCREENS7951
Ref: #screens8036
Node: Accounts screen8126
Ref: #accounts-screen8254
Node: Register screen10470
Ref: #register-screen10625
Node: Transaction screen12622
Ref: #transaction-screen12780
Node: Error screen13650
Ref: #error-screen13772

End Tag Table

2
hledger-ui/hledger-ui.txt
View File

@ -404,4 +404,4 @@ SEE ALSO
hledger-ui 1.11.99 September 2018 hledger-ui(1)
hledger-ui 1.12 December 2018 hledger-ui(1)

2
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "hledger\-web" "1" "September 2018" "hledger\-web 1.11.99" "hledger User Manuals"
.TH "hledger\-web" "1" "December 2018" "hledger\-web 1.12" "hledger User Manuals"

8
hledger-web/hledger-web.info
View File

@ -3,8 +3,8 @@ This is hledger-web.info, produced by makeinfo version 6.5 from stdin.

File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-web(1) hledger-web 1.11.99
**********************************
hledger-web(1) hledger-web 1.12
*******************************
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens
@ -212,7 +212,7 @@ this, insert a '--' argument before.)

Tag Table:
Node: Top72
Node: OPTIONS3160
Ref: #options3245
Node: OPTIONS3154
Ref: #options3239

End Tag Table

2
hledger-web/hledger-web.txt
View File

@ -251,4 +251,4 @@ SEE ALSO
hledger-web 1.11.99 September 2018 hledger-web(1)
hledger-web 1.12 December 2018 hledger-web(1)

127
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger" "1" "September 2018" "hledger 1.11.99" "hledger User Manuals"
.TH "hledger" "1" "December 2018" "hledger 1.12" "hledger User Manuals"
@ -344,46 +344,125 @@ line.
To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a
\f[C]\-\-\f[] argument.
For more, see Save frequently used options.
.SS Special characters
.SS Special characters in arguments and queries
.PP
Option and argument values which contain problematic characters should
be escaped with double quotes, backslashes, or (best) single quotes.
Problematic characters means spaces, and also characters which are
significant to your command shell, such as less\-than/greater\-than.
In shell command lines, option and argument values which contain
\[lq]problematic\[rq] characters, ie spaces, and also characters
significant to your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[],
\f[C])\f[], \f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing
them in quotes or by writing backslashes before the characters.
Eg:
\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[].
.PP
Characters which are significant both to the shell and in regular
expressions sometimes need to be double\-escaped.
\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[].
.SS More escaping
.PP
Characters significant both to the shell and in regular expressions may
need one extra level of escaping.
These include parentheses, the pipe symbol and the dollar sign.
Eg, to match the dollar symbol, bash users should do:
\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or
\f[C]hledger\ balance\ cur:\\\\$\f[].
.PP
When hledger is invoking an addon executable (like hledger\-ui), options
and arguments get de\-escaped once more, so you might need
\f[I]triple\f[]\-escaping.
Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or
\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] in bash.
\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[]
.PP
or:
.PP
\f[C]hledger\ balance\ cur:\\\\$\f[]
.SS Even more escaping
.PP
When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[],
hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options
and arguments once, so you might need to \f[I]triple\f[]\-escape.
Eg in bash, running the ui command and matching the dollar sign, it's:
.PP
\f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[]
.PP
or:
.PP
\f[C]hledger\ ui\ cur:\\\\\\\\$\f[]
.PP
If you asked why \f[I]four\f[] slashes above, this may help:
.PP
.TS
tab(@);
l l.
T{
unescaped:
T}@T{
\f[C]$\f[]
T}
T{
escaped:
T}@T{
\f[C]\\$\f[]
T}
T{
double\-escaped:
T}@T{
\f[C]\\\\$\f[]
T}
T{
triple\-escaped:
T}@T{
\f[C]\\\\\\\\$\f[]
T}
.TE
.PP
(The number of backslashes in fish shell is left as an exercise for the
reader.)
.PP
Inside a file used for argument expansion, one less level of escaping is
enough.
(And in this case, backslashes seem to work better than quotes.
Eg: \f[C]cur:\\$\f[]).
You can always avoid the extra escaping for addons by running the addon
directly:
.PP
\f[C]hledger\-ui\ cur:\\\\$\f[]
.SS Less escaping
.PP
Inside an argument file, or in the search field of hledger\-ui or
hledger\-web, or at a GHCI prompt, you need one less level of escaping
than at the command line.
And backslashes may work better than quotes.
Eg:
.PP
\f[C]ghci>\ :main\ balance\ cur:\\$\f[]
.SS Command line tips
.PP
If in doubt, keep things simple:
.IP \[bu] 2
run add\-on executables directly
write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[])
.IP \[bu] 2
write options after the command
run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[])
.IP \[bu] 2
enclose problematic args in single quotes
.IP \[bu] 2
if needed, also add a backslash to escape regexp metacharacters
.PP
If you're really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot.
To find out exactly how a command line is being parsed, add
\f[C]\-\-debug=2\f[] to troubleshoot.
.SS Unicode characters
.PP
hledger is expected to handle unicode (non\-ascii) characters, but this
requires a well\-configured environment.
.PP
To handle unicode characters in the command line or input data, a system
locale that can decode them must be configured (POSIX's default
\f[C]C\f[] locale will not work).
Eg in bash, you could do:
.IP
.nf
\f[C]
export\ LANG=en_US.UTF\-8
\f[]
.fi
.PP
See Troubleshooting for more about this.
.PP
Unicode characters should appear correctly in hledger's output.
For the hledger and hledger\-ui tools, this requires that
.IP \[bu] 2
your terminal supports unicode
.IP \[bu] 2
the terminal's font includes the required unicode glyphs
.IP \[bu] 2
the terminal is configured to display \[lq]wide\[rq] characters as
double width (otherwise report alignment will be off)
.SS Input files
.PP
hledger reads transactions from a data file (and the add command writes
@ -2900,7 +2979,7 @@ according to various schemes.
.SS irr
.PP
hledger\-irr calculates the internal rate of return of an investment
account.
account, but it's superseded now by the built\-in roi command.
.SS Experimental add\-ons
.PP
These are available in source form in the hledger repo's bin/ directory;

463
hledger/hledger.info
View File

@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.5 from stdin.

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
hledger(1) hledger 1.11.99
**************************
hledger(1) hledger 1.12
***********************
This is hledger's command-line interface (there are also curses and web
interfaces). Its basic function is to read a plain text file describing
@ -119,7 +119,9 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Command options::
* Command arguments::
* Argument files::
* Special characters::
* Special characters in arguments and queries::
* Command line tips::
* Unicode characters::
* Input files::
* Smart dates::
* Report start & end date::
@ -277,7 +279,7 @@ Most hledger commands accept arguments after the command name, which are
often a query, filtering the data in some way.

File: hledger.info, Node: Argument files, Next: Special characters, Prev: Command arguments, Up: OPTIONS
File: hledger.info, Node: Argument files, Next: Special characters in arguments and queries, Prev: Command arguments, Up: OPTIONS
2.4 Argument files
==================
@ -288,47 +290,132 @@ prevent this expansion of '@'-arguments, precede them with a '--'
argument. For more, see Save frequently used options.

File: hledger.info, Node: Special characters, Next: Input files, Prev: Argument files, Up: OPTIONS
File: hledger.info, Node: Special characters in arguments and queries, Next: Command line tips, Prev: Argument files, Up: OPTIONS
2.5 Special characters
======================
2.5 Special characters in arguments and queries
===============================================
Option and argument values which contain problematic characters should
be escaped with double quotes, backslashes, or (best) single quotes.
Problematic characters means spaces, and also characters which are
significant to your command shell, such as less-than/greater-than. Eg:
'hledger register -p 'last year' "accounts receivable
In shell command lines, option and argument values which contain
"problematic" characters, ie spaces, and also characters significant to
your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by
enclosing them in quotes or by writing backslashes before the
characters. Eg:
'hledger register -p 'last year' "accounts receivable
(receivable|payable)" amt:\>100'.
* Menu:
Characters which are significant both to the shell and in regular
expressions sometimes need to be double-escaped. These include
parentheses, the pipe symbol and the dollar sign. Eg, to match the
dollar symbol, bash users should do: 'hledger balance cur:'\$'' or
'hledger balance cur:\\$'.
* More escaping::
* Even more escaping::
* Less escaping::
When hledger is invoking an addon executable (like hledger-ui),
options and arguments get de-escaped once more, so you might need
_triple_-escaping. Eg: 'hledger ui cur:'\\$'' or 'hledger ui cur:\\\\$'
in bash. (The number of backslashes in fish shell is left as an
exercise for the reader.)

File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries
Inside a file used for argument expansion, one less level of escaping
is enough. (And in this case, backslashes seem to work better than
quotes. Eg: 'cur:\$').
2.5.1 More escaping
-------------------
If in doubt, keep things simple:
Characters significant both to the shell and in regular expressions may
need one extra level of escaping. These include parentheses, the pipe
symbol and the dollar sign. Eg, to match the dollar symbol, bash users
should do:
* run add-on executables directly
* write options after the command
'hledger balance cur:'\$''
or:
'hledger balance cur:\\$'

File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries
2.5.2 Even more escaping
------------------------
When hledger runs an addon executable (eg you type 'hledger ui', hledger
runs 'hledger-ui'), it de-escapes command-line options and arguments
once, so you might need to _triple_-escape. Eg in bash, running the ui
command and matching the dollar sign, it's:
'hledger ui cur:'\\$''
or:
'hledger ui cur:\\\\$'
If you asked why _four_ slashes above, this may help:
unescaped: '$'
escaped: '\$'
double-escaped: '\\$'
triple-escaped: '\\\\$'
(The number of backslashes in fish shell is left as an exercise for
the reader.)
You can always avoid the extra escaping for addons by running the
addon directly:
'hledger-ui cur:\\$'

File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries
2.5.3 Less escaping
-------------------
Inside an argument file, or in the search field of hledger-ui or
hledger-web, or at a GHCI prompt, you need one less level of escaping
than at the command line. And backslashes may work better than quotes.
Eg:
'ghci> :main balance cur:\$'

File: hledger.info, Node: Command line tips, Next: Unicode characters, Prev: Special characters in arguments and queries, Up: OPTIONS
2.6 Command line tips
=====================
If in doubt, keep things simple:
* write options after the command ('hledger CMD -OPTIONS ARGS')
* run add-on executables directly ('hledger-ui -OPTIONS ARGS')
* enclose problematic args in single quotes
* if needed, also add a backslash to escape regexp metacharacters
If you're really stumped, add '--debug=2' to troubleshoot.
To find out exactly how a command line is being parsed, add
'--debug=2' to troubleshoot.

File: hledger.info, Node: Input files, Next: Smart dates, Prev: Special characters, Up: OPTIONS
File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Command line tips, Up: OPTIONS
2.6 Input files
2.7 Unicode characters
======================
hledger is expected to handle unicode (non-ascii) characters, but this
requires a well-configured environment.
To handle unicode characters in the command line or input data, a
system locale that can decode them must be configured (POSIX's default
'C' locale will not work). Eg in bash, you could do:
export LANG=en_US.UTF-8
See Troubleshooting for more about this.
Unicode characters should appear correctly in hledger's output. For
the hledger and hledger-ui tools, this requires that
* your terminal supports unicode
* the terminal's font includes the required unicode glyphs
* the terminal is configured to display "wide" characters as double
width (otherwise report alignment will be off)

File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS
2.8 Input files
===============
hledger reads transactions from a data file (and the add command writes
@ -383,7 +470,7 @@ the files, eg: 'cat a.journal b.journal | hledger -f- CMD'.

File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS
2.7 Smart dates
2.9 Smart dates
===============
hledger's user interfaces accept a flexible "smart date" syntax (unlike
@ -416,8 +503,8 @@ results:

File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS
2.8 Report start & end date
===========================
2.10 Report start & end date
============================
Most hledger reports show the full span of time represented by the
journal data, by default. So, the effective report start and end dates
@ -445,8 +532,8 @@ need to write the date _after_ the last day you want to include.

File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS
2.9 Report intervals
====================
2.11 Report intervals
=====================
A report interval can be specified so that commands like register,
balance and activity will divide their reports into multiple subperiods.
@ -458,7 +545,7 @@ intervals can not be specified with a query, currently.

File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS
2.10 Period expressions
2.12 Period expressions
=======================
The '-p/--period' option accepts period expressions, a shorthand way of
@ -566,7 +653,7 @@ start date and exclusive end date):

File: hledger.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS
2.11 Depth limiting
2.13 Depth limiting
===================
With the '--depth N' option (short form: '-N'), commands like account,
@ -578,7 +665,7 @@ less detail. This flag has the same effect as a 'depth:' query argument

File: hledger.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS
2.12 Pivoting
2.14 Pivoting
=============
Normally hledger sums amounts, and organizes them in a hierarchy, based
@ -635,7 +722,7 @@ $ hledger balance --pivot member acct:.

File: hledger.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS
2.13 Cost
2.15 Cost
=========
The '-B/--cost' flag converts amounts to their cost at transaction time,
@ -644,7 +731,7 @@ if they have a transaction price specified.

File: hledger.info, Node: Market value, Next: Combining -B and -V, Prev: Cost, Up: OPTIONS
2.14 Market value
2.16 Market value
=================
The '-V/--value' flag converts reported amounts to their current market
@ -696,7 +783,7 @@ of the prices on each column's end date.)

File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS
2.15 Combining -B and -V
2.17 Combining -B and -V
========================
Using -B/-cost and -V/-value together is currently allowed, but the
@ -706,7 +793,7 @@ this.

File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS
2.16 Output destination
2.18 Output destination
=======================
Some commands (print, register, stats, the balance commands) can write
@ -719,7 +806,7 @@ $ hledger balance -o FILE # write to FILE

File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS
2.17 Output format
2.19 Output format
==================
Some commands can write their output in other formats. Eg print and
@ -733,7 +820,7 @@ $ hledger balance -o FILE.csv # write CSV to FILE.csv

File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS
2.18 Regular expressions
2.20 Regular expressions
========================
hledger uses regular expressions in a number of places:
@ -2419,7 +2506,7 @@ File: hledger.info, Node: irr, Prev: interest, Up: Third party add-ons
---------
hledger-irr calculates the internal rate of return of an investment
account.
account, but it's superseded now by the built-in roi command.

File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS
@ -2467,142 +2554,152 @@ hledger-check.hs checks more powerful account balance assertions.

Tag Table:
Node: Top68
Node: EXAMPLES1890
Ref: #examples1990
Node: OPTIONS3636
Ref: #options3738
Node: General options4103
Ref: #general-options4228
Node: Command options6910
Ref: #command-options7061
Node: Command arguments7459
Ref: #command-arguments7613
Node: Argument files7734
Ref: #argument-files7885
Node: Special characters8151
Ref: #special-characters8304
Node: Input files9723
Ref: #input-files9859
Node: Smart dates11829
Ref: #smart-dates11970
Node: Report start & end date13376
Ref: #report-start-end-date13546
Node: Report intervals14611
Ref: #report-intervals14774
Node: Period expressions15175
Ref: #period-expressions15335
Node: Depth limiting19292
Ref: #depth-limiting19436
Node: Pivoting19778
Ref: #pivoting19896
Node: Cost21572
Ref: #cost21680
Node: Market value21798
Ref: #market-value21933
Node: Combining -B and -V23299
Ref: #combining--b-and--v23462
Node: Output destination23609
Ref: #output-destination23771
Node: Output format24054
Ref: #output-format24206
Node: Regular expressions24591
Ref: #regular-expressions24728
Node: QUERIES26089
Ref: #queries26191
Node: COMMANDS30153
Ref: #commands30265
Node: accounts31265
Ref: #accounts31363
Node: activity32609
Ref: #activity32719
Node: add33079
Ref: #add33178
Node: balance35839
Ref: #balance35950
Node: Classic balance report39033
Ref: #classic-balance-report39206
Node: Customising the classic balance report40575
Ref: #customising-the-classic-balance-report40803
Node: Colour support42877
Ref: #colour-support43044
Node: Flat mode43217
Ref: #flat-mode43365
Node: Depth limited balance reports43778
Ref: #depth-limited-balance-reports43978
Node: Multicolumn balance report44434
Ref: #multicolumn-balance-report44632
Node: Budget report49812
Ref: #budget-report49955
Ref: #output-format-152989
Node: balancesheet53067
Ref: #balancesheet53203
Node: balancesheetequity55514
Ref: #balancesheetequity55663
Node: cashflow56200
Ref: #cashflow56328
Node: check-dates58451
Ref: #check-dates58578
Node: check-dupes58695
Ref: #check-dupes58819
Node: close58956
Ref: #close59064
Node: files59394
Ref: #files59495
Node: help59636
Ref: #help59736
Node: import60810
Ref: #import60924
Node: incomestatement61654
Ref: #incomestatement61788
Node: prices64192
Ref: #prices64307
Node: print64579
Ref: #print64689
Node: print-unique69583
Ref: #print-unique69709
Node: register69777
Ref: #register69904
Node: Custom register output74405
Ref: #custom-register-output74534
Node: register-match75764
Ref: #register-match75898
Node: rewrite76081
Ref: #rewrite76196
Node: roi76265
Ref: #roi76363
Node: stats76479
Ref: #stats76578
Node: tags77448
Ref: #tags77546
Node: test77782
Ref: #test77866
Node: ADD-ON COMMANDS78574
Ref: #add-on-commands78684
Node: Official add-ons79971
Ref: #official-add-ons80111
Node: api80198
Ref: #api80287
Node: ui80339
Ref: #ui80438
Node: web80496
Ref: #web80585
Node: Third party add-ons80631
Ref: #third-party-add-ons80806
Node: diff80941
Ref: #diff81038
Node: iadd81137
Ref: #iadd81251
Node: interest81334
Ref: #interest81455
Node: irr81550
Ref: #irr81648
Node: Experimental add-ons81726
Ref: #experimental-add-ons81878
Node: autosync82158
Ref: #autosync82269
Node: chart82508
Ref: #chart82627
Node: check82698
Ref: #check82800
Node: EXAMPLES1884
Ref: #examples1984
Node: OPTIONS3630
Ref: #options3732
Node: General options4167
Ref: #general-options4292
Node: Command options6974
Ref: #command-options7125
Node: Command arguments7523
Ref: #command-arguments7677
Node: Argument files7798
Ref: #argument-files7974
Node: Special characters in arguments and queries8240
Ref: #special-characters-in-arguments-and-queries8474
Node: More escaping8924
Ref: #more-escaping9086
Node: Even more escaping9382
Ref: #even-more-escaping9576
Node: Less escaping10247
Ref: #less-escaping10409
Node: Command line tips10654
Ref: #command-line-tips10840
Node: Unicode characters11217
Ref: #unicode-characters11373
Node: Input files12098
Ref: #input-files12234
Node: Smart dates14204
Ref: #smart-dates14345
Node: Report start & end date15751
Ref: #report-start-end-date15923
Node: Report intervals16988
Ref: #report-intervals17153
Node: Period expressions17554
Ref: #period-expressions17714
Node: Depth limiting21671
Ref: #depth-limiting21815
Node: Pivoting22157
Ref: #pivoting22275
Node: Cost23951
Ref: #cost24059
Node: Market value24177
Ref: #market-value24312
Node: Combining -B and -V25678
Ref: #combining--b-and--v25841
Node: Output destination25988
Ref: #output-destination26150
Node: Output format26433
Ref: #output-format26585
Node: Regular expressions26970
Ref: #regular-expressions27107
Node: QUERIES28468
Ref: #queries28570
Node: COMMANDS32532
Ref: #commands32644
Node: accounts33644
Ref: #accounts33742
Node: activity34988
Ref: #activity35098
Node: add35458
Ref: #add35557
Node: balance38218
Ref: #balance38329
Node: Classic balance report41412
Ref: #classic-balance-report41585
Node: Customising the classic balance report42954
Ref: #customising-the-classic-balance-report43182
Node: Colour support45256
Ref: #colour-support45423
Node: Flat mode45596
Ref: #flat-mode45744
Node: Depth limited balance reports46157
Ref: #depth-limited-balance-reports46357
Node: Multicolumn balance report46813
Ref: #multicolumn-balance-report47011
Node: Budget report52191
Ref: #budget-report52334
Ref: #output-format-155368
Node: balancesheet55446
Ref: #balancesheet55582
Node: balancesheetequity57893
Ref: #balancesheetequity58042
Node: cashflow58579
Ref: #cashflow58707
Node: check-dates60830
Ref: #check-dates60957
Node: check-dupes61074
Ref: #check-dupes61198
Node: close61335
Ref: #close61443
Node: files61773
Ref: #files61874
Node: help62015
Ref: #help62115
Node: import63189
Ref: #import63303
Node: incomestatement64033
Ref: #incomestatement64167
Node: prices66571
Ref: #prices66686
Node: print66958
Ref: #print67068
Node: print-unique71962
Ref: #print-unique72088
Node: register72156
Ref: #register72283
Node: Custom register output76784
Ref: #custom-register-output76913
Node: register-match78143
Ref: #register-match78277
Node: rewrite78460
Ref: #rewrite78575
Node: roi78644
Ref: #roi78742
Node: stats78858
Ref: #stats78957
Node: tags79827
Ref: #tags79925
Node: test80161
Ref: #test80245
Node: ADD-ON COMMANDS80953
Ref: #add-on-commands81063
Node: Official add-ons82350
Ref: #official-add-ons82490
Node: api82577
Ref: #api82666
Node: ui82718
Ref: #ui82817
Node: web82875
Ref: #web82964
Node: Third party add-ons83010
Ref: #third-party-add-ons83185
Node: diff83320
Ref: #diff83417
Node: iadd83516
Ref: #iadd83630
Node: interest83713
Ref: #interest83834
Node: irr83929
Ref: #irr84027
Node: Experimental add-ons84158
Ref: #experimental-add-ons84310
Node: autosync84590
Ref: #autosync84701
Node: chart84940
Ref: #chart85059
Node: check85130
Ref: #check85232

End Tag Table

104
hledger/hledger.txt
View File

@ -238,41 +238,98 @@ OPTIONS
prevent this expansion of @-arguments, precede them with a -- argument.
For more, see Save frequently used options.
Special characters
Option and argument values which contain problematic characters should
be escaped with double quotes, backslashes, or (best) single quotes.
Problematic characters means spaces, and also characters which are sig-
nificant to your command shell, such as less-than/greater-than. Eg:
Special characters in arguments and queries
In shell command lines, option and argument values which contain "prob-
lematic" characters, ie spaces, and also characters significant to your
shell such as <, >, (, ), | and $, should be escaped by enclosing them
in quotes or by writing backslashes before the characters. Eg:
hledger register -p 'last year' "accounts receivable (receiv-
able|payable)" amt:\>100.
Characters which are significant both to the shell and in regular
expressions sometimes need to be double-escaped. These include paren-
theses, the pipe symbol and the dollar sign. Eg, to match the dollar
symbol, bash users should do: hledger balance cur:'\$' or hledger bal-
ance cur:\\$.
More escaping
Characters significant both to the shell and in regular expressions may
need one extra level of escaping. These include parentheses, the pipe
symbol and the dollar sign. Eg, to match the dollar symbol, bash users
should do:
When hledger is invoking an addon executable (like hledger-ui), options
and arguments get de-escaped once more, so you might need triple-escap-
ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The
number of backslashes in fish shell is left as an exercise for the
hledger balance cur:'\$'
or:
hledger balance cur:\\$
Even more escaping
When hledger runs an addon executable (eg you type hledger ui, hledger
runs hledger-ui), it de-escapes command-line options and arguments
once, so you might need to triple-escape. Eg in bash, running the ui
command and matching the dollar sign, it's:
hledger ui cur:'\\$'
or:
hledger ui cur:\\\\$
If you asked why four slashes above, this may help:
unescaped: $
escaped: \$
double-escaped: \\$
triple-escaped: \\\\$
(The number of backslashes in fish shell is left as an exercise for the
reader.)
Inside a file used for argument expansion, one less level of escaping
is enough. (And in this case, backslashes seem to work better than
quotes. Eg: cur:\$).
You can always avoid the extra escaping for addons by running the addon
directly:
hledger-ui cur:\\$
Less escaping
Inside an argument file, or in the search field of hledger-ui or
hledger-web, or at a GHCI prompt, you need one less level of escaping
than at the command line. And backslashes may work better than quotes.
Eg:
ghci> :main balance cur:\$
Command line tips
If in doubt, keep things simple:
o run add-on executables directly
o write options after the command (hledger CMD -OPTIONS ARGS)
o write options after the command
o run add-on executables directly (hledger-ui -OPTIONS ARGS)
o enclose problematic args in single quotes
o if needed, also add a backslash to escape regexp metacharacters
If you're really stumped, add --debug=2 to troubleshoot.
To find out exactly how a command line is being parsed, add --debug=2
to troubleshoot.
Unicode characters
hledger is expected to handle unicode (non-ascii) characters, but this
requires a well-configured environment.
To handle unicode characters in the command line or input data, a sys-
tem locale that can decode them must be configured (POSIX's default C
locale will not work). Eg in bash, you could do:
export LANG=en_US.UTF-8
See Troubleshooting for more about this.
Unicode characters should appear correctly in hledger's output. For
the hledger and hledger-ui tools, this requires that
o your terminal supports unicode
o the terminal's font includes the required unicode glyphs
o the terminal is configured to display "wide" characters as double
width (otherwise report alignment will be off)
Input files
hledger reads transactions from a data file (and the add command writes
@ -340,6 +397,7 @@ OPTIONS
4+ digits, month is 1-12,
day is 1-31
2004 start of year
2004/10 start of month
10/1 month and day in current
year
@ -397,7 +455,6 @@ OPTIONS
rent month
-p thismonth all transactions in the
current month
date:2016/3/17- the above written as
queries instead
date:-12/1
@ -531,7 +588,6 @@ OPTIONS
-p "every 2nd Monday" - period bound-
aries will be on second Monday of each
month
-p "every 11/05" - yearly periods with
boundaries on 5th of Nov
-p "every 5th Nov" - same
@ -2094,7 +2150,7 @@ ADD-ON COMMANDS
irr
hledger-irr calculates the internal rate of return of an investment
account.
account, but it's superseded now by the built-in roi command.
Experimental add-ons
These are available in source form in the hledger repo's bin/ direc-
@ -2230,4 +2286,4 @@ SEE ALSO
hledger 1.11.99 September 2018 hledger(1)
hledger 1.12 December 2018 hledger(1)