slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages 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) 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 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 web apps operating on hledger data. It comes with a series of simple
@ -80,7 +80,7 @@ options as shown above.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS1666 Node: OPTIONS1660
Ref: #options1751 Ref: #options1745
 
End Tag Table 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) 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 hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a 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: Tag Table:
Node: Top72 Node: Top72
Node: CSV RULES2169 Node: CSV RULES2163
Ref: #csv-rules2277 Ref: #csv-rules2271
Node: skip2539 Node: skip2533
Ref: #skip2633 Ref: #skip2627
Node: date-format2805 Node: date-format2799
Ref: #date-format2932 Ref: #date-format2926
Node: field list3438 Node: field list3432
Ref: #field-list3575 Ref: #field-list3569
Node: field assignment4280 Node: field assignment4274
Ref: #field-assignment4435 Ref: #field-assignment4429
Node: conditional block4939 Node: conditional block4933
Ref: #conditional-block5093 Ref: #conditional-block5087
Node: include5989 Node: include5983
Ref: #include6119 Ref: #include6113
Node: newest-first6350 Node: newest-first6344
Ref: #newest-first6464 Ref: #newest-first6458
Node: CSV TIPS6875 Node: CSV TIPS6869
Ref: #csv-tips6969 Ref: #csv-tips6963
Node: CSV ordering7087 Node: CSV ordering7081
Ref: #csv-ordering7205 Ref: #csv-ordering7199
Node: CSV accounts7386 Node: CSV accounts7380
Ref: #csv-accounts7524 Ref: #csv-accounts7518
Node: CSV amounts7778 Node: CSV amounts7772
Ref: #csv-amounts7924 Ref: #csv-amounts7918
Node: CSV balance assertions8699 Node: CSV balance assertions8693
Ref: #csv-balance-assertions8881 Ref: #csv-balance-assertions8875
Node: Reading multiple CSV files9086 Node: Reading multiple CSV files9080
Ref: #reading-multiple-csv-files9256 Ref: #reading-multiple-csv-files9250
 
End Tag Table 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 .\"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 The asserted balance must be a simple single\-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi\-commodity) account balance. (possibly multi\-commodity) account balance.
We could call this a partial balance assertion. .PD 0
This is compatible with Ledger, and makes it possible to make assertions .P
about accounts containing multiple commodities. .PD
This is how assertions work in Ledger also.
We could call this a \[lq]partial\[rq] balance assertion.
.PP .PP
To assert each commodity's balance in such a multi\-commodity account, To assert the balance of more than one commodity in an account, you can
you can add multiple postings (with amount 0 if necessary). write multiple postings, each asserting one commodity's balance.
But note that no matter how many assertions you add, you can't be sure .PP
the account does not contain some unexpected commodity. You can make a stronger kind of balance assertion, by writing a double
(We'll add support for this kind of total balance assertion if there's equals sign (\f[C]==EXPECTEDBALANCE\f[]).
demand.) 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 .SS Assertions and subaccounts
.PP .PP
Balance assertions do not count the balance from subaccounts; they check Balance assertions do not count the balance from subaccounts; they check
@ -853,10 +894,9 @@ T}@T{
T}@T{ T}@T{
any text any text
T}@T{ T}@T{
declare an account name & optional account code document account names, declare account types & display order
T}@T{ T}@T{
account code: balance reports (except \f[C]balance\f[] single\-column all entries in all files, before or after
mode)
T} T}
T{ T{
\f[C]alias\f[] \f[C]alias\f[]
@ -951,13 +991,8 @@ lw(8.9n) lw(61.1n).
T{ T{
subdirective subdirective
T}@T{ T}@T{
optional indented directive or unparsed text lines immediately following optional indented directive line immediately following a parent
a parent directive directive
T}
T{
account code
T}@T{
numeric code influencing account display order in most balance reports
T} T}
T{ T{
number notation 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. to another commodity using these prices.
.SS Declaring accounts .SS Declaring accounts
.PP .PP
The \f[C]account\f[] directive predeclares account names. \f[C]account\f[] directives can be used to pre\-declare some or all
The simplest form is \f[C]account\ ACCTNAME\f[], eg: accounts.
.IP Though not required, they can provide several benefits:
.nf .IP \[bu] 2
\f[C] They can document your intended chart of accounts, providing a
account\ assets:bank:checking reference.
\f[] .IP \[bu] 2
.fi 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 .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: Here is the full syntax:
.IP .IP
.nf .nf
\f[C] \f[C]
;\ account\ ACCTNAME account\ ACCTNAME\ \ [ACCTTYPE]
;\ \ \ [OPTIONALSUBDIRECTIVES] \ \ [COMMENTS]
account\ assets:bank:checking
\ \ a\ comment
\ \ some\-tag:12345
\f[] \f[]
.fi .fi
.SS Account display order
.PP .PP
Account directives have another purpose: they set the order in which The simplest form just declares a hledger\-style account name, eg:
accounts are displayed, in hledger reports, hledger\-ui accounts screen,
hledger\-web sidebar etc.
For example, say you have these top\-level accounts:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ accounts\ \-1 account\ assets:bank:checking
assets \f[]
equity .fi
expenses .SS Account types
liabilities .PP
misc hledger recognises five types of account: asset, liability, equity,
other revenue, expense.
revenues 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[] \f[]
.fi .fi
.PP .PP
By default, they are displayed in alphabetical order. Note: if you ever override the types of those auto\-detected english
But if you add the following account directives to the journal: 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 .IP
.nf .nf
\f[C] \f[C]
@ -1206,27 +1291,25 @@ account\ expenses
\f[] \f[]
.fi .fi
.PP .PP
the display order changes to: you'll see those accounts listed in declaration order, not
alphabetically:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ accounts\ \-1 $\ hledger\ accounts\ \-1
assets assets
liabilities liabilities
equity equity
revenues revenues
expenses expenses
misc
other
\f[] \f[]
.fi .fi
.PP .PP
Ie, declared accounts first, in the order they were declared, followed Undeclared accounts, if any, are displayed last, in alphabetical order.
by any undeclared accounts in alphabetic order.
.PP .PP
Note that sorting is done at each level of the account tree (within each Note that sorting is done at each level of the account tree (within each
group of sibling accounts under the same parent). group of sibling accounts under the same parent).
This directive: And currently, this directive:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1237,6 +1320,10 @@ account\ other:zoo
would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s 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 subaccounts, but not the position of \f[C]other\f[] among the top\-level
accounts. 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 .SS Rewriting accounts
.PP .PP
You can define account alias rules which rewrite your account names, or 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 Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
\f[C]monthly\ from\ 2018/1/15\f[] is not. \f[C]monthly\ from\ 2018/1/15\f[] is not.
.PP .PP
If you write a transaction description or same\-line comment, it must be Partial or relative dates (M/D, D, tomorrow, last week) in the period
separated from the period expression by \f[B]two or more spaces\f[]. expression can work (useful or not).
Eg: 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 .IP
.nf .nf
\f[C] \f[C]
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces ;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || ;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv ;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
~\ every\ 2\ weeks\ from\ 2018/6\ to\ 2018/9\ \ paycheck ~\ every\ 2\ weeks\ from\ 2018/6/4\ to\ 2018/9\ \ paycheck
\ \ \ \ assets:bank:checking\ \ \ $1500 \ \ \ \ assets:bank:checking\ \ \ $1500
\ \ \ \ income:acme\ inc \ \ \ \ income:acme\ inc
\f[] \f[]
@ -1495,50 +1591,81 @@ Currently, this means adding extra postings (also known as
\[lq]automated postings\[rq]). \[lq]automated postings\[rq]).
Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag.
.PP .PP
A transaction modifier rule looks a bit like a normal journal entry, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equal sign (\f[C]=\f[]) followed by a query except the first line is an equals sign followed by a query that matches
(mnemonic: \f[C]=\f[] suggests matching something.): certain postings (mnemonic: \f[C]=\f[] suggests matching).
And each \[lq]posting\[rq] is actually a posting\-generating rule:
.IP .IP
.nf .nf
\f[C] \f[C]
=\ expenses:gifts =\ QUERY
\ \ \ \ budget:gifts\ \ *\-1 \ \ \ \ ACCT\ \ AMT
\ \ \ \ assets:budget\ \ *1 \ \ \ \ ACCT\ \ [AMT]
\ \ \ \ ...
\f[] \f[]
.fi .fi
.PP .PP
The posting amounts can be of the form \f[C]*N\f[], which means \[lq]the The posting rules look just like normal postings, except the amount can
amount of the matched transaction's first posting, multiplied by N\[rq]. be:
They can also be ordinary fixed amounts. .IP \[bu] 2
Fixed amounts with no commodity symbol will be given the same commodity a normal amount with a commodity symbol, eg \f[C]$2\f[].
as the matched transaction's first posting. 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 .PP
This example adds a corresponding (unbalanced) budget posting to every Some examples:
transaction involving the \f[C]expenses:gifts\f[] account:
.IP .IP
.nf .nf
\f[C] \f[C]
=\ expenses:gifts ;\ every\ time\ I\ buy\ food,\ schedule\ a\ dollar\ donation
\ \ \ \ (budget:gifts)\ \ *\-1 =\ expenses:food
\ \ \ \ (liabilities:charity)\ \ \ $\-1
2017\-12\-14 ;\ when\ I\ buy\ a\ gift,\ also\ deduct\ that\ amount\ from\ a\ budget\ envelope\ subaccount
\ \ expenses:gifts\ \ $20 =\ expenses:gifts
\ \ assets \ \ \ \ assets:checking:gifts\ \ *\-1
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ *1
2017/12/1
\ \ expenses:food\ \ \ \ $10
\ \ assets:checking
2017/12/14
\ \ expenses:gifts\ \ \ $20
\ \ assets:checking
\f[] \f[]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ print\ \-\-auto $\ hledger\ print\ \-\-auto
2017/12/01
\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ $10
\ \ \ \ assets:checking
\ \ \ \ (liabilities:charity)\ \ \ \ \ \ $\-1
2017/12/14 2017/12/14
\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20 \ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
\ \ \ \ (budget:gifts)\ \ \ \ \ \ \ \ \ \ \ \ $\-20 \ \ \ \ assets:checking
\ \ \ \ assets \ \ \ \ assets:checking:gifts\ \ \ \ \ \-$20
\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20
\f[] \f[]
.fi .fi
.PP .PP
Like postings recorded by hand, automated postings participate in Postings added by transaction modifiers participate in transaction
transaction balancing, missing amount inference and balance assertions. balancing, missing amount inference and balance assertions, like regular
postings.
.SH EDITOR SUPPORT .SH EDITOR SUPPORT
.PP .PP
Add\-on modes exist for various text editors, to make working with 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) 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 hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard 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 The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a (possibly multi-commodity) account balance.
partial balance assertion. This is compatible with Ledger, and makes it This is how assertions work in Ledger also. We could call this a
possible to make assertions about accounts containing multiple "partial" balance assertion.
commodities.
To assert each commodity's balance in such a multi-commodity account, To assert the balance of more than one commodity in an account, you
you can add multiple postings (with amount 0 if necessary). But note can write multiple postings, each asserting one commodity's balance.
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 You can make a stronger kind of balance assertion, by writing a
for this kind of total balance assertion if there's demand.) 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 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 directiveend subdirectivespurpose can affect (as of
directive 2018/06) directive 2018/06)
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
'account' any declare an account name & account code: 'account' any document account names, all entries in
text optional account code balance reports text declare account types & all files, before
(except 'balance' display order or after
single-column
mode)
'alias' 'end rewrite account names following 'alias' 'end rewrite account names following
aliases' inline/included aliases' inline/included
entries until end entries until end
@ -821,10 +849,8 @@ account' apply account names inline/included
And some definitions: And some definitions:
subdirectiveoptional indented directive or unparsed text lines subdirectiveoptional indented directive line immediately following a
immediately following a parent directive parent directive
account numeric code influencing account display order in most
code balance reports
number how to interpret numbers when parsing journal entries (the number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same each commodity can have its own notation, even in the same
@ -853,7 +879,6 @@ times though.
* Default commodity:: * Default commodity::
* Market prices:: * Market prices::
* Declaring accounts:: * Declaring accounts::
* Account display order::
* Rewriting accounts:: * Rewriting accounts::
* Default parent account:: * Default parent account::
@ -1003,52 +1028,106 @@ P 2010/1/1 € $1.40
another commodity using these prices. 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 1.14.7 Declaring accounts
------------------------- -------------------------
The 'account' directive predeclares account names. The simplest form is 'account' directives can be used to pre-declare some or all accounts.
'account ACCTNAME', eg: 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 account assets:bank:checking
Currently this mainly helps with account name autocompletion in eg * Menu:
hledger add, hledger-iadd, hledger-web, and ledger-mode.
In future it will also help detect misspelled accounts.
An account directive can also have indented subdirectives following * Account types::
it, which are currently ignored. Here is the full syntax: * Account comments::
* Account display order::
; account ACCTNAME
; [OPTIONALSUBDIRECTIVES]
account assets:bank:checking
a comment
some-tag:12345
 
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 hledger recognises five types of account: asset, liability, equity,
accounts are displayed, in hledger reports, hledger-ui accounts screen, revenue, expense. This is useful for certain accounting-aware reports,
hledger-web sidebar etc. For example, say you have these top-level in particular balancesheet, incomestatement and cashflow.
accounts:
$ accounts -1 If you name your top-level accounts with some variation of 'assets',
assets 'liabilities'/'debts', 'equity', 'revenues'/'income', or 'expenses',
equity their types are detected automatically.
expenses
liabilities
misc
other
revenues
By default, they are displayed in alphabetical order. But if you add More generally, you can declare an account's type by adding one of
the following account directives to the journal: 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 assets
account liabilities account liabilities
@ -1056,32 +1135,36 @@ account equity
account revenues account revenues
account expenses account expenses
the display order changes to: you'll see those accounts listed in declaration order, not
alphabetically:
$ accounts -1 $ hledger accounts -1
assets assets
liabilities liabilities
equity equity
revenues revenues
expenses expenses
misc
other
Ie, declared accounts first, in the order they were declared, Undeclared accounts, if any, are displayed last, in alphabetical
followed by any undeclared accounts in alphabetic order. order.
Note that sorting is done at each level of the account tree (within 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 account other:zoo
would influence the position of 'zoo' among 'other''s subaccounts, 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 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 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. 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 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, 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 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 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 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 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 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 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 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 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. 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 Partial or relative dates (M/D, D, tomorrow, last week) in the period
be separated from the period expression by *two or more spaces*. Eg: 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 Period expressions must be terminated by *two or more spaces* if
; || followed by additional fields. For example, the periodic transaction
; vv given below includes a transaction description "paycheck", which is
~ every 2 weeks from 2018/6 to 2018/9 paycheck 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 assets:bank:checking $1500
income:acme inc income:acme inc
@ -1330,38 +1422,64 @@ automatically to certain transactions. Currently, this means adding
extra postings (also known as "automated postings"). Transaction extra postings (also known as "automated postings"). Transaction
modifiers are enabled by the '--auto' flag. modifiers are enabled by the '--auto' flag.
A transaction modifier rule looks a bit like a normal journal entry, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equal sign ('=') followed by a query except the first line is an equals sign followed by a query that matches
(mnemonic: '=' suggests matching something.): 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 = expenses:gifts
budget:gifts *-1 assets:checking:gifts *-1
assets:budget *1 assets:checking *1
The posting amounts can be of the form '*N', which means "the amount 2017/12/1
of the matched transaction's first posting, multiplied by N". They can expenses:food $10
also be ordinary fixed amounts. Fixed amounts with no commodity symbol assets:checking
will be given the same commodity as the matched transaction's first
posting.
This example adds a corresponding (unbalanced) budget posting to 2017/12/14
every transaction involving the 'expenses:gifts' account: expenses:gifts $20
assets:checking
= expenses:gifts
(budget:gifts) *-1
2017-12-14
expenses:gifts $20
assets
$ hledger print --auto $ hledger print --auto
2017/12/01
expenses:food $10
assets:checking
(liabilities:charity) $-1
2017/12/14 2017/12/14
expenses:gifts $20 expenses:gifts $20
(budget:gifts) $-20 assets:checking
assets assets:checking:gifts -$20
assets:checking $20
Like postings recorded by hand, automated postings participate in Postings added by transaction modifiers participate in transaction
transaction balancing, missing amount inference and balance assertions. balancing, missing amount inference and balance assertions, like regular
postings.
 
File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -1393,93 +1511,97 @@ Code
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT2378 Node: FILE FORMAT2372
Ref: #file-format2502 Ref: #file-format2496
Node: Transactions2789 Node: Transactions2783
Ref: #transactions2910 Ref: #transactions2904
Node: Postings3594 Node: Postings3588
Ref: #postings3721 Ref: #postings3715
Node: Dates4716 Node: Dates4710
Ref: #dates4831 Ref: #dates4825
Node: Simple dates4896 Node: Simple dates4890
Ref: #simple-dates5022 Ref: #simple-dates5016
Node: Secondary dates5388 Node: Secondary dates5382
Ref: #secondary-dates5542 Ref: #secondary-dates5536
Node: Posting dates7105 Node: Posting dates7099
Ref: #posting-dates7234 Ref: #posting-dates7228
Node: Status8608 Node: Status8602
Ref: #status8728 Ref: #status8722
Node: Description10436 Node: Description10430
Ref: #description10574 Ref: #description10568
Node: Payee and note10893 Node: Payee and note10887
Ref: #payee-and-note11007 Ref: #payee-and-note11001
Node: Account names11249 Node: Account names11243
Ref: #account-names11392 Ref: #account-names11386
Node: Amounts11879 Node: Amounts11873
Ref: #amounts12015 Ref: #amounts12009
Node: Virtual Postings15032 Node: Virtual Postings15026
Ref: #virtual-postings15191 Ref: #virtual-postings15185
Node: Balance Assertions16411 Node: Balance Assertions16405
Ref: #balance-assertions16586 Ref: #balance-assertions16580
Node: Assertions and ordering17482 Node: Assertions and ordering17476
Ref: #assertions-and-ordering17668 Ref: #assertions-and-ordering17662
Node: Assertions and included files18368 Node: Assertions and included files18362
Ref: #assertions-and-included-files18609 Ref: #assertions-and-included-files18603
Node: Assertions and multiple -f options18942 Node: Assertions and multiple -f options18936
Ref: #assertions-and-multiple--f-options19196 Ref: #assertions-and-multiple--f-options19190
Node: Assertions and commodities19328 Node: Assertions and commodities19322
Ref: #assertions-and-commodities19563 Ref: #assertions-and-commodities19557
Node: Assertions and subaccounts20259 Node: Assertions and subaccounts20745
Ref: #assertions-and-subaccounts20491 Ref: #assertions-and-subaccounts20977
Node: Assertions and virtual postings21012 Node: Assertions and virtual postings21498
Ref: #assertions-and-virtual-postings21219 Ref: #assertions-and-virtual-postings21705
Node: Balance Assignments21361 Node: Balance Assignments21847
Ref: #balance-assignments21542 Ref: #balance-assignments22028
Node: Transaction prices22662 Node: Transaction prices23148
Ref: #transaction-prices22831 Ref: #transaction-prices23317
Node: Comments25099 Node: Comments25585
Ref: #comments25233 Ref: #comments25719
Node: Tags26403 Node: Tags26889
Ref: #tags26521 Ref: #tags27007
Node: Directives27923 Node: Directives28409
Ref: #directives28066 Ref: #directives28552
Node: Comment blocks33948 Node: Comment blocks34159
Ref: #comment-blocks34093 Ref: #comment-blocks34304
Node: Including other files34269 Node: Including other files34480
Ref: #including-other-files34449 Ref: #including-other-files34660
Node: Default year34857 Node: Default year35068
Ref: #default-year35026 Ref: #default-year35237
Node: Declaring commodities35449 Node: Declaring commodities35660
Ref: #declaring-commodities35632 Ref: #declaring-commodities35843
Node: Default commodity36859 Node: Default commodity37070
Ref: #default-commodity37035 Ref: #default-commodity37246
Node: Market prices37671 Node: Market prices37882
Ref: #market-prices37836 Ref: #market-prices38047
Node: Declaring accounts38677 Node: Declaring accounts38888
Ref: #declaring-accounts38856 Ref: #declaring-accounts39064
Node: Account display order39406 Node: Account types40021
Ref: #account-display-order39596 Ref: #account-types40170
Node: Rewriting accounts40617 Node: Account comments41244
Ref: #rewriting-accounts40805 Ref: #account-comments41429
Node: Basic aliases41539 Node: Account display order41750
Ref: #basic-aliases41685 Ref: #account-display-order41923
Node: Regex aliases42389 Node: Rewriting accounts43045
Ref: #regex-aliases42560 Ref: #rewriting-accounts43230
Node: Multiple aliases43278 Node: Basic aliases43964
Ref: #multiple-aliases43453 Ref: #basic-aliases44110
Node: end aliases43951 Node: Regex aliases44814
Ref: #end-aliases44098 Ref: #regex-aliases44985
Node: Default parent account44199 Node: Multiple aliases45703
Ref: #default-parent-account44367 Ref: #multiple-aliases45878
Node: Periodic transactions45251 Node: end aliases46376
Ref: #periodic-transactions45433 Ref: #end-aliases46523
Node: Forecasting with periodic transactions46644 Node: Default parent account46624
Ref: #forecasting-with-periodic-transactions46887 Ref: #default-parent-account46790
Node: Budgeting with periodic transactions48574 Node: Periodic transactions47674
Ref: #budgeting-with-periodic-transactions48813 Ref: #periodic-transactions47856
Node: Transaction Modifiers49272 Node: Forecasting with periodic transactions49559
Ref: #transaction-modifiers49435 Ref: #forecasting-with-periodic-transactions49802
Node: EDITOR SUPPORT50691 Node: Budgeting with periodic transactions51489
Ref: #editor-support50809 Ref: #budgeting-with-periodic-transactions51728
Node: Transaction Modifiers52187
Ref: #transaction-modifiers52350
Node: EDITOR SUPPORT54331
Ref: #editor-support54449
 
End Tag Table End Tag Table

421
hledger-lib/hledger_journal.txt
View File

@ -405,16 +405,46 @@ FILE FORMAT
Assertions and commodities Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a par- (possibly multi-commodity) account balance.
tial balance assertion. This is compatible with Ledger, and makes it This is how assertions work in Ledger also. We could call this a "par-
possible to make assertions about accounts containing multiple commodi- tial" balance assertion.
ties.
To assert each commodity's balance in such a multi-commodity account, To assert the balance of more than one commodity in an account, you can
you can add multiple postings (with amount 0 if necessary). But note write multiple postings, each asserting one commodity's balance.
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 You can make a stronger kind of balance assertion, by writing a double
for this kind of total balance assertion if there's demand.) 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 Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they Balance assertions do not count the balance from subaccounts; they
@ -614,40 +644,51 @@ FILE FORMAT
tive directive rec- 2018/06) tive directive rec- 2018/06)
tives tives
------------------------------------------------------------------------------------------------- -------------------------------------------------------------------------------------------------
account any declare an account name & account code: bal- account any document account names, all entries in all
text optional account code ance reports text declare account types & dis- files, before or
(except balance play order after
single-column mode)
alias end aliases rewrite account names following alias end aliases rewrite account names following
inline/included inline/included
entries until end entries until end
of current file or of current file or
end directive 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 account names inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
comment end comment ignore part of journal following comment end comment ignore part of journal following
inline/included inline/included
entries until end entries until end
of current file or of current file or
end directive 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 number notation & display following entries
style in that commodity style in that commodity
in all files; dis- in all files; dis-
play style: amounts play style: amounts
of that commodity of that commodity
in reports in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries notation & display style for modityless entries
commodityless amounts in all files; num- commodityless amounts in all files; num-
ber notation: fol- ber notation: fol-
lowing commodity- lowing commodity-
less entries and less entries and
entries in that entries in that
commodity in all commodity in all
files; display files; display
style: amounts of style: amounts of
that commodity in that commodity in
@ -658,7 +699,7 @@ FILE FORMAT
commodity commodity in commodity commodity in
reports, when -V is reports, when -V is
used used
Y declare a year for yearless following Y declare a year for yearless following
dates inline/included dates inline/included
entries until end entries until end
of current file of current file
@ -666,16 +707,11 @@ FILE FORMAT
And some definitions: And some definitions:
subdirec- optional indented directive or unparsed text lines immedi- subdirec- optional indented directive line immediately following a par-
tive ately following a parent directive tive ent directive
account numeric code influencing account display order in most bal- number how to interpret numbers when parsing journal entries (the
code ance reports notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
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.) file.)
display how to display amounts of a commodity in reports (symbol side display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places) style and spacing, digit groups, decimal separator, decimal places)
@ -683,37 +719,37 @@ FILE FORMAT
scope are affected by a directive scope are affected by a directive
As you can see, directives vary in which journal entries and files they 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. (reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f 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 options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro- typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by 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. times though.
Comment blocks 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) and a line containing just end comment (or the end of the current file)
ends it. See also comments. ends it. See also comments.
Including other files 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: directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current 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. 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. include journal, timeclock or timedot files, but not CSV files.
Default year Default year
You can set a default year to be used for subsequent dates which don't 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. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -733,8 +769,8 @@ FILE FORMAT
assets assets
Declaring commodities Declaring commodities
The commodity directive declares commodities which may be used in the The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written journal (though currently we do not enforce this). It may be written
on a single line, like this: on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -744,8 +780,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places: places:
; commodity SYMBOL ; commodity SYMBOL
@ -757,19 +793,19 @@ FILE FORMAT
commodity INR commodity INR
format INR 9,99,99,999.00 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- display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable; mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by always be written with a decimal point (a period or comma, followed by
0 or more decimal digits). 0 or more decimal digits).
Default commodity 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 used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive. amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars # commodity-less amounts should be treated as dollars
@ -784,9 +820,9 @@ FILE FORMAT
a decimal point. a decimal point.
Market prices 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 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. cryptocurrency exchange, or the foreign exchange market.
Here is the format: Here is the format:
@ -797,55 +833,97 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced 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. 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: dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35 P 2009/1/1 $1.35
P 2010/1/1 $1.40 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. commodity using these prices.
Declaring accounts Declaring accounts
The account directive predeclares account names. The simplest form is account directives can be used to pre-declare some or all accounts.
account ACCTNAME, eg: 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 account assets:bank:checking
Currently this mainly helps with account name autocompletion in eg Account types
hledger add, hledger-iadd, hledger-web, and ledger-mode. hledger recognises five types of account: asset, liability, equity,
In future it will also help detect misspelled accounts. 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, If you name your top-level accounts with some variation of assets, lia-
which are currently ignored. Here is the full syntax: bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
; account ACCTNAME More generally, you can declare an account's type by adding one of the
; [OPTIONALSUBDIRECTIVES] 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 account assets:bank:checking
a comment ; acctno:12345
some-tag: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 display order
Account directives have another purpose: they set the order in which Account directives also set the order in which accounts are displayed
accounts are displayed, in hledger reports, hledger-ui accounts screen, in reports, the hledger-ui accounts screen, the hledger-web sidebar,
hledger-web sidebar etc. For example, say you have these top-level etc. Normally accounts are listed in alphabetical order, but if you
accounts: have eg these account directives in the journal:
$ 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 assets account assets
account liabilities account liabilities
@ -853,27 +931,30 @@ FILE FORMAT
account revenues account revenues
account expenses 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 assets
liabilities liabilities
equity equity
revenues revenues
expenses expenses
misc
other
Ie, declared accounts first, in the order they were declared, followed Undeclared accounts, if any, are displayed last, in alphabetical order.
by any undeclared accounts in alphabetic order.
Note that sorting is done at each level of the account tree (within 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 account other:zoo
would influence the position of zoo among other's subaccounts, but not 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 Rewriting accounts
You can define account alias rules which rewrite your account names, or 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 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. 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 Partial or relative dates (M/D, D, tomorrow, last week) in the period
separated from the period expression by two or more spaces. Eg: 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 Period expressions must be terminated by two or more spaces if followed
; || by additional fields. For example, the periodic transaction given
; vv below includes a transaction description "paycheck", which is separated
~ every 2 weeks from 2018/6 to 2018/9 paycheck 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 assets:bank:checking $1500
income:acme inc income:acme inc
Forecasting with periodic transactions 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 future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like 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 normal transactions, but with an extra tag named recur, whose value is
the generating period expression. the generating period expression.
Forecast transactions start on the first occurrence, and end on the Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The last occurrence, of their interval within the forecast period. The
forecast period: forecast period:
o begins on the later of o begins on the later of
o the report start date if specified with -b/-p/date: 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. 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. days from today.
where "today" means the current date at report time. The "later of" where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac- rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end. tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal means that forecasted transactions are automatically replaced by normal
transactions as you add those. transactions as you add those.
Forecasting can also help with data entry: describe most of your trans- 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. print --forecast to the journal.
You can generate one-time transactions too: just write a period expres- You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.) forecast transactions on previous dates.)
Budgeting with periodic transactions Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command, With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com- checking) every month. Goals and actual performance can then be com-
pared in budget reports. 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. and Forecasting.
Transaction Modifiers Transaction Modifiers
Transaction modifier rules describe changes that should be applied Transaction modifier rules describe changes that should be applied
automatically to certain transactions. Currently, this means adding automatically to certain transactions. Currently, this means adding
extra postings (also known as "automated postings"). Transaction modi- extra postings (also known as "automated postings"). Transaction modi-
fiers are enabled by the --auto flag. fiers are enabled by the --auto flag.
A transaction modifier rule looks a bit like a normal journal entry, A transaction modifier rule looks quite like a normal transaction,
except the first line is an equal sign (=) followed by a query except the first line is an equals sign followed by a query that
(mnemonic: = suggests matching something.): 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 = expenses:gifts
budget:gifts *-1 assets:checking:gifts *-1
assets:budget *1 assets:checking *1
The posting amounts can be of the form *N, which means "the amount of 2017/12/1
the matched transaction's first posting, multiplied by N". They can expenses:food $10
also be ordinary fixed amounts. Fixed amounts with no commodity symbol assets:checking
will be given the same commodity as the matched transaction's first
posting.
This example adds a corresponding (unbalanced) budget posting to every 2017/12/14
transaction involving the expenses:gifts account: expenses:gifts $20
assets:checking
= expenses:gifts
(budget:gifts) *-1
2017-12-14
expenses:gifts $20
assets
$ hledger print --auto $ hledger print --auto
2017/12/01
expenses:food $10
assets:checking
(liabilities:charity) $-1
2017/12/14 2017/12/14
expenses:gifts $20 expenses:gifts $20
(budget:gifts) $-20 assets:checking
assets assets:checking:gifts -$20
assets:checking $20
Like postings recorded by hand, automated postings participate in Postings added by transaction modifiers participate in transaction bal-
transaction balancing, missing amount inference and balance assertions. ancing, missing amount inference and balance assertions, like regular
postings.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- 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) 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 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 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) 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 Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. It is convenient for (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: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT813 Node: FILE FORMAT807
Ref: #file-format914 Ref: #file-format908
 
End Tag Table 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) 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 hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some full-window text UI for viewing accounts and transactions, and some
@ -396,19 +396,19 @@ to cancel the reload attempt.)
 
Tag Table: Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1090 Node: OPTIONS1084
Ref: #options1187 Ref: #options1181
Node: KEYS4606 Node: KEYS4600
Ref: #keys4701 Ref: #keys4695
Node: SCREENS7957 Node: SCREENS7951
Ref: #screens8042 Ref: #screens8036
Node: Accounts screen8132 Node: Accounts screen8126
Ref: #accounts-screen8260 Ref: #accounts-screen8254
Node: Register screen10476 Node: Register screen10470
Ref: #register-screen10631 Ref: #register-screen10625
Node: Transaction screen12628 Node: Transaction screen12622
Ref: #transaction-screen12786 Ref: #transaction-screen12780
Node: Error screen13656 Node: Error screen13650
Ref: #error-screen13778 Ref: #error-screen13772
 
End Tag Table 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) 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 hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens application for browsing and adding transactions, and optionally opens
@ -212,7 +212,7 @@ this, insert a '--' argument before.)
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS3160 Node: OPTIONS3154
Ref: #options3245 Ref: #options3239
 
End Tag Table 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 .\"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 To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a
\f[C]\-\-\f[] argument. \f[C]\-\-\f[] argument.
For more, see Save frequently used options. For more, see Save frequently used options.
.SS Special characters .SS Special characters in arguments and queries
.PP .PP
Option and argument values which contain problematic characters should In shell command lines, option and argument values which contain
be escaped with double quotes, backslashes, or (best) single quotes. \[lq]problematic\[rq] characters, ie spaces, and also characters
Problematic characters means spaces, and also characters which are significant to your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[],
significant to your command shell, such as less\-than/greater\-than. \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: Eg:
\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[].
.PP .PP
Characters which are significant both to the shell and in regular \f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[].
expressions sometimes need to be double\-escaped. .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. These include parentheses, the pipe symbol and the dollar sign.
Eg, to match the dollar symbol, bash users should do: 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 .PP
When hledger is invoking an addon executable (like hledger\-ui), options \f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[]
and arguments get de\-escaped once more, so you might need .PP
\f[I]triple\f[]\-escaping. or:
Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or .PP
\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] in bash. \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 (The number of backslashes in fish shell is left as an exercise for the
reader.) reader.)
.PP .PP
Inside a file used for argument expansion, one less level of escaping is You can always avoid the extra escaping for addons by running the addon
enough. directly:
(And in this case, backslashes seem to work better than quotes. .PP
Eg: \f[C]cur:\\$\f[]). \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 .PP
If in doubt, keep things simple: If in doubt, keep things simple:
.IP \[bu] 2 .IP \[bu] 2
run add\-on executables directly write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[])
.IP \[bu] 2 .IP \[bu] 2
write options after the command run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[])
.IP \[bu] 2 .IP \[bu] 2
enclose problematic args in single quotes enclose problematic args in single quotes
.IP \[bu] 2 .IP \[bu] 2
if needed, also add a backslash to escape regexp metacharacters if needed, also add a backslash to escape regexp metacharacters
.PP .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 .SS Input files
.PP .PP
hledger reads transactions from a data file (and the add command writes hledger reads transactions from a data file (and the add command writes
@ -2900,7 +2979,7 @@ according to various schemes.
.SS irr .SS irr
.PP .PP
hledger\-irr calculates the internal rate of return of an investment 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 .SS Experimental add\-ons
.PP .PP
These are available in source form in the hledger repo's bin/ directory; 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) 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 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 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 options::
* Command arguments:: * Command arguments::
* Argument files:: * Argument files::
* Special characters:: * Special characters in arguments and queries::
* Command line tips::
* Unicode characters::
* Input files:: * Input files::
* Smart dates:: * Smart dates::
* Report start & end date:: * 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. 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 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. 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 In shell command lines, option and argument values which contain
be escaped with double quotes, backslashes, or (best) single quotes. "problematic" characters, ie spaces, and also characters significant to
Problematic characters means spaces, and also characters which are your shell such as '<', '>', '(', ')', '|' and '$', should be escaped by
significant to your command shell, such as less-than/greater-than. Eg: enclosing them in quotes or by writing backslashes before the
'hledger register -p 'last year' "accounts receivable characters. Eg:
'hledger register -p 'last year' "accounts receivable
(receivable|payable)" amt:\>100'. (receivable|payable)" amt:\>100'.
* Menu:
Characters which are significant both to the shell and in regular * More escaping::
expressions sometimes need to be double-escaped. These include * Even more escaping::
parentheses, the pipe symbol and the dollar sign. Eg, to match the * Less escaping::
dollar symbol, bash users should do: 'hledger balance cur:'\$'' or
'hledger balance cur:\\$'.
When hledger is invoking an addon executable (like hledger-ui), 
options and arguments get de-escaped once more, so you might need File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries
_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.)
Inside a file used for argument expansion, one less level of escaping 2.5.1 More escaping
is enough. (And in this case, backslashes seem to work better than -------------------
quotes. Eg: 'cur:\$').
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 'hledger balance cur:'\$''
* write options after the command
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 * enclose problematic args in single quotes
* if needed, also add a backslash to escape regexp metacharacters * 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 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 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 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 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 Most hledger reports show the full span of time represented by the
journal data, by default. So, the effective report start and end dates 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 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, A report interval can be specified so that commands like register,
balance and activity will divide their reports into multiple subperiods. 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 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 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 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, 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 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 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 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, 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 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 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 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 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 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 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 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 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 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: 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 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 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: Tag Table:
Node: Top68 Node: Top68
Node: EXAMPLES1890 Node: EXAMPLES1884
Ref: #examples1990 Ref: #examples1984
Node: OPTIONS3636 Node: OPTIONS3630
Ref: #options3738 Ref: #options3732
Node: General options4103 Node: General options4167
Ref: #general-options4228 Ref: #general-options4292
Node: Command options6910 Node: Command options6974
Ref: #command-options7061 Ref: #command-options7125
Node: Command arguments7459 Node: Command arguments7523
Ref: #command-arguments7613 Ref: #command-arguments7677
Node: Argument files7734 Node: Argument files7798
Ref: #argument-files7885 Ref: #argument-files7974
Node: Special characters8151 Node: Special characters in arguments and queries8240
Ref: #special-characters8304 Ref: #special-characters-in-arguments-and-queries8474
Node: Input files9723 Node: More escaping8924
Ref: #input-files9859 Ref: #more-escaping9086
Node: Smart dates11829 Node: Even more escaping9382
Ref: #smart-dates11970 Ref: #even-more-escaping9576
Node: Report start & end date13376 Node: Less escaping10247
Ref: #report-start-end-date13546 Ref: #less-escaping10409
Node: Report intervals14611 Node: Command line tips10654
Ref: #report-intervals14774 Ref: #command-line-tips10840
Node: Period expressions15175 Node: Unicode characters11217
Ref: #period-expressions15335 Ref: #unicode-characters11373
Node: Depth limiting19292 Node: Input files12098
Ref: #depth-limiting19436 Ref: #input-files12234
Node: Pivoting19778 Node: Smart dates14204
Ref: #pivoting19896 Ref: #smart-dates14345
Node: Cost21572 Node: Report start & end date15751
Ref: #cost21680 Ref: #report-start-end-date15923
Node: Market value21798 Node: Report intervals16988
Ref: #market-value21933 Ref: #report-intervals17153
Node: Combining -B and -V23299 Node: Period expressions17554
Ref: #combining--b-and--v23462 Ref: #period-expressions17714
Node: Output destination23609 Node: Depth limiting21671
Ref: #output-destination23771 Ref: #depth-limiting21815
Node: Output format24054 Node: Pivoting22157
Ref: #output-format24206 Ref: #pivoting22275
Node: Regular expressions24591 Node: Cost23951
Ref: #regular-expressions24728 Ref: #cost24059
Node: QUERIES26089 Node: Market value24177
Ref: #queries26191 Ref: #market-value24312
Node: COMMANDS30153 Node: Combining -B and -V25678
Ref: #commands30265 Ref: #combining--b-and--v25841
Node: accounts31265 Node: Output destination25988
Ref: #accounts31363 Ref: #output-destination26150
Node: activity32609 Node: Output format26433
Ref: #activity32719 Ref: #output-format26585
Node: add33079 Node: Regular expressions26970
Ref: #add33178 Ref: #regular-expressions27107
Node: balance35839 Node: QUERIES28468
Ref: #balance35950 Ref: #queries28570
Node: Classic balance report39033 Node: COMMANDS32532
Ref: #classic-balance-report39206 Ref: #commands32644
Node: Customising the classic balance report40575 Node: accounts33644
Ref: #customising-the-classic-balance-report40803 Ref: #accounts33742
Node: Colour support42877 Node: activity34988
Ref: #colour-support43044 Ref: #activity35098
Node: Flat mode43217 Node: add35458
Ref: #flat-mode43365 Ref: #add35557
Node: Depth limited balance reports43778 Node: balance38218
Ref: #depth-limited-balance-reports43978 Ref: #balance38329
Node: Multicolumn balance report44434 Node: Classic balance report41412
Ref: #multicolumn-balance-report44632 Ref: #classic-balance-report41585
Node: Budget report49812 Node: Customising the classic balance report42954
Ref: #budget-report49955 Ref: #customising-the-classic-balance-report43182
Ref: #output-format-152989 Node: Colour support45256
Node: balancesheet53067 Ref: #colour-support45423
Ref: #balancesheet53203 Node: Flat mode45596
Node: balancesheetequity55514 Ref: #flat-mode45744
Ref: #balancesheetequity55663 Node: Depth limited balance reports46157
Node: cashflow56200 Ref: #depth-limited-balance-reports46357
Ref: #cashflow56328 Node: Multicolumn balance report46813
Node: check-dates58451 Ref: #multicolumn-balance-report47011
Ref: #check-dates58578 Node: Budget report52191
Node: check-dupes58695 Ref: #budget-report52334
Ref: #check-dupes58819 Ref: #output-format-155368
Node: close58956 Node: balancesheet55446
Ref: #close59064 Ref: #balancesheet55582
Node: files59394 Node: balancesheetequity57893
Ref: #files59495 Ref: #balancesheetequity58042
Node: help59636 Node: cashflow58579
Ref: #help59736 Ref: #cashflow58707
Node: import60810 Node: check-dates60830
Ref: #import60924 Ref: #check-dates60957
Node: incomestatement61654 Node: check-dupes61074
Ref: #incomestatement61788 Ref: #check-dupes61198
Node: prices64192 Node: close61335
Ref: #prices64307 Ref: #close61443
Node: print64579 Node: files61773
Ref: #print64689 Ref: #files61874
Node: print-unique69583 Node: help62015
Ref: #print-unique69709 Ref: #help62115
Node: register69777 Node: import63189
Ref: #register69904 Ref: #import63303
Node: Custom register output74405 Node: incomestatement64033
Ref: #custom-register-output74534 Ref: #incomestatement64167
Node: register-match75764 Node: prices66571
Ref: #register-match75898 Ref: #prices66686
Node: rewrite76081 Node: print66958
Ref: #rewrite76196 Ref: #print67068
Node: roi76265 Node: print-unique71962
Ref: #roi76363 Ref: #print-unique72088
Node: stats76479 Node: register72156
Ref: #stats76578 Ref: #register72283
Node: tags77448 Node: Custom register output76784
Ref: #tags77546 Ref: #custom-register-output76913
Node: test77782 Node: register-match78143
Ref: #test77866 Ref: #register-match78277
Node: ADD-ON COMMANDS78574 Node: rewrite78460
Ref: #add-on-commands78684 Ref: #rewrite78575
Node: Official add-ons79971 Node: roi78644
Ref: #official-add-ons80111 Ref: #roi78742
Node: api80198 Node: stats78858
Ref: #api80287 Ref: #stats78957
Node: ui80339 Node: tags79827
Ref: #ui80438 Ref: #tags79925
Node: web80496 Node: test80161
Ref: #web80585 Ref: #test80245
Node: Third party add-ons80631 Node: ADD-ON COMMANDS80953
Ref: #third-party-add-ons80806 Ref: #add-on-commands81063
Node: diff80941 Node: Official add-ons82350
Ref: #diff81038 Ref: #official-add-ons82490
Node: iadd81137 Node: api82577
Ref: #iadd81251 Ref: #api82666
Node: interest81334 Node: ui82718
Ref: #interest81455 Ref: #ui82817
Node: irr81550 Node: web82875
Ref: #irr81648 Ref: #web82964
Node: Experimental add-ons81726 Node: Third party add-ons83010
Ref: #experimental-add-ons81878 Ref: #third-party-add-ons83185
Node: autosync82158 Node: diff83320
Ref: #autosync82269 Ref: #diff83417
Node: chart82508 Node: iadd83516
Ref: #chart82627 Ref: #iadd83630
Node: check82698 Node: interest83713
Ref: #check82800 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 End Tag Table

104
hledger/hledger.txt
View File

@ -238,41 +238,98 @@ OPTIONS
prevent this expansion of @-arguments, precede them with a -- argument. prevent this expansion of @-arguments, precede them with a -- argument.
For more, see Save frequently used options. For more, see Save frequently used options.
Special characters Special characters in arguments and queries
Option and argument values which contain problematic characters should In shell command lines, option and argument values which contain "prob-
be escaped with double quotes, backslashes, or (best) single quotes. lematic" characters, ie spaces, and also characters significant to your
Problematic characters means spaces, and also characters which are sig- shell such as <, >, (, ), | and $, should be escaped by enclosing them
nificant to your command shell, such as less-than/greater-than. Eg: in quotes or by writing backslashes before the characters. Eg:
hledger register -p 'last year' "accounts receivable (receiv- hledger register -p 'last year' "accounts receivable (receiv-
able|payable)" amt:\>100. able|payable)" amt:\>100.
Characters which are significant both to the shell and in regular More escaping
expressions sometimes need to be double-escaped. These include paren- Characters significant both to the shell and in regular expressions may
theses, the pipe symbol and the dollar sign. Eg, to match the dollar need one extra level of escaping. These include parentheses, the pipe
symbol, bash users should do: hledger balance cur:'\$' or hledger bal- symbol and the dollar sign. Eg, to match the dollar symbol, bash users
ance cur:\\$. should do:
When hledger is invoking an addon executable (like hledger-ui), options hledger balance cur:'\$'
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 or:
number of backslashes in fish shell is left as an exercise for the
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.) reader.)
Inside a file used for argument expansion, one less level of escaping You can always avoid the extra escaping for addons by running the addon
is enough. (And in this case, backslashes seem to work better than directly:
quotes. Eg: cur:\$).
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: 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 enclose problematic args in single quotes
o if needed, also add a backslash to escape regexp metacharacters 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 Input files
hledger reads transactions from a data file (and the add command writes hledger reads transactions from a data file (and the add command writes
@ -340,6 +397,7 @@ OPTIONS
4+ digits, month is 1-12, 4+ digits, month is 1-12,
day is 1-31 day is 1-31
2004 start of year 2004 start of year
2004/10 start of month 2004/10 start of month
10/1 month and day in current 10/1 month and day in current
year year
@ -397,7 +455,6 @@ OPTIONS
rent month rent month
-p thismonth all transactions in the -p thismonth all transactions in the
current month current month
date:2016/3/17- the above written as date:2016/3/17- the above written as
queries instead queries instead
date:-12/1 date:-12/1
@ -531,7 +588,6 @@ OPTIONS
-p "every 2nd Monday" - period bound- -p "every 2nd Monday" - period bound-
aries will be on second Monday of each aries will be on second Monday of each
month month
-p "every 11/05" - yearly periods with -p "every 11/05" - yearly periods with
boundaries on 5th of Nov boundaries on 5th of Nov
-p "every 5th Nov" - same -p "every 5th Nov" - same
@ -2094,7 +2150,7 @@ ADD-ON COMMANDS
irr irr
hledger-irr calculates the internal rate of return of an investment 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 Experimental add-ons
These are available in source form in the hledger repo's bin/ direc- 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)