slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: regen man pages

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-08-31 21:02:00 -07:00
parent 29f7654c3a
commit b1859769ac
22 changed files with 1840 additions and 1265 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
hledger-lib/hledger_csv.5
View File

@ -1,5 +1,5 @@
.TH "hledger_csv" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger_csv" "5" "August 2019" "hledger 1.15" "hledger User Manuals"
@ -186,6 +186,9 @@ comment note: %somefield - %anotherfield, date: %1
.fi .fi
.PP .PP
Field assignments can be used instead of or in addition to a field list. Field assignments can be used instead of or in addition to a field list.
.PP
Note, interpolation strips any outer whitespace, so a CSV value like
\f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated (#1051).
.SS conditional block .SS conditional block
.PP .PP
\f[C]if\f[R] \f[I]\f[CI]PATTERN\f[I]\f[R] \f[C]if\f[R] \f[I]\f[CI]PATTERN\f[I]\f[R]
@ -332,6 +335,18 @@ arguments on the command line, and hledger will look for a
correspondingly-named rules file for each. correspondingly-named rules file for each.
Note if you use the \f[C]--rules-file\f[R] option, this one rules file Note if you use the \f[C]--rules-file\f[R] option, this one rules file
will be used for all the CSV files being read. will be used for all the CSV files being read.
.SS Valid CSV
.PP
hledger follows RFC 4180, with the addition of a customisable separator
character.
.PP
Some things to note:
.PP
When quoting fields,
.IP \[bu] 2
you must use double quotes, not single quotes
.IP \[bu] 2
spaces outside the quotes are not allowed.
.SH "REPORTING BUGS" .SH "REPORTING BUGS"

84
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.14.99 hledger_csv(5) hledger 1.15
****************************** ***************************
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
@ -171,6 +171,9 @@ comment note: %somefield - %anotherfield, date: %1
Field assignments can be used instead of or in addition to a field Field assignments can be used instead of or in addition to a field
list. list.
Note, interpolation strips any outer whitespace, so a CSV value like
'" 1 "' becomes '1' when interpolated (#1051).
 
File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES
@ -248,6 +251,7 @@ File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
* CSV amounts:: * CSV amounts::
* CSV balance assertions/assignments:: * CSV balance assertions/assignments::
* Reading multiple CSV files:: * Reading multiple CSV files::
* Valid CSV::
 
File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS
@ -317,7 +321,7 @@ assignment), on the first or second posting, whenever the running
balance field is non-empty. (TODO: #1000) balance field is non-empty. (TODO: #1000)
 
File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions/assignments, Up: CSV TIPS File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid CSV, Prev: CSV balance assertions/assignments, Up: CSV TIPS
2.5 Reading multiple CSV files 2.5 Reading multiple CSV files
============================== ==============================
@ -327,36 +331,54 @@ the command line, and hledger will look for a correspondingly-named
rules file for each. Note if you use the '--rules-file' option, this rules file for each. Note if you use the '--rules-file' option, this
one rules file will be used for all the CSV files being read. one rules file will be used for all the CSV files being read.

File: hledger_csv.info, Node: Valid CSV, Prev: Reading multiple CSV files, Up: CSV TIPS
2.6 Valid CSV
=============
hledger follows RFC 4180, with the addition of a customisable separator
character.
Some things to note:
When quoting fields,
* you must use double quotes, not single quotes
* spaces outside the quotes are not allowed.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: CSV RULES2167 Node: CSV RULES2161
Ref: #csv-rules2275 Ref: #csv-rules2269
Node: skip2538 Node: skip2532
Ref: #skip2632 Ref: #skip2626
Node: date-format2804 Node: date-format2798
Ref: #date-format2931 Ref: #date-format2925
Node: field list3481 Node: field list3475
Ref: #field-list3618 Ref: #field-list3612
Node: field assignment4348 Node: field assignment4342
Ref: #field-assignment4503 Ref: #field-assignment4497
Node: conditional block5007 Node: conditional block5121
Ref: #conditional-block5161 Ref: #conditional-block5275
Node: include6057 Node: include6171
Ref: #include6187 Ref: #include6301
Node: newest-first6418 Node: newest-first6532
Ref: #newest-first6532 Ref: #newest-first6646
Node: CSV TIPS6943 Node: CSV TIPS7057
Ref: #csv-tips7037 Ref: #csv-tips7151
Node: CSV ordering7167 Node: CSV ordering7295
Ref: #csv-ordering7285 Ref: #csv-ordering7413
Node: CSV accounts7466 Node: CSV accounts7594
Ref: #csv-accounts7604 Ref: #csv-accounts7732
Node: CSV amounts7858 Node: CSV amounts7986
Ref: #csv-amounts8016 Ref: #csv-amounts8144
Node: CSV balance assertions/assignments9096 Node: CSV balance assertions/assignments9224
Ref: #csv-balance-assertionsassignments9314 Ref: #csv-balance-assertionsassignments9442
Node: Reading multiple CSV files9635 Node: Reading multiple CSV files9763
Ref: #reading-multiple-csv-files9817 Ref: #reading-multiple-csv-files9963
Node: Valid CSV10237
Ref: #valid-csv10360
 
End Tag Table End Tag Table

65
hledger-lib/hledger_csv.txt
View File

@ -134,6 +134,9 @@ CSV RULES
Field assignments can be used instead of or in addition to a field Field assignments can be used instead of or in addition to a field
list. list.
Note, interpolation strips any outer whitespace, so a CSV value like "
1 " becomes 1 when interpolated (#1051).
conditional block conditional block
if PATTERN if PATTERN
FIELDASSIGNMENTS... FIELDASSIGNMENTS...
@ -143,12 +146,12 @@ CSV RULES
PATTERN... PATTERN...
FIELDASSIGNMENTS... FIELDASSIGNMENTS...
This applies one or more field assignments, only to those CSV records This applies one or more field assignments, only to those CSV records
matched by one of the PATTERNs. The patterns are case-insensitive reg- matched by one of the PATTERNs. The patterns are case-insensitive reg-
ular expressions which match anywhere within the whole CSV record (it's ular expressions which match anywhere within the whole CSV record (it's
not yet possible to match within a specific field). When there are not yet possible to match within a specific field). When there are
multiple patterns they can be written on separate lines, unindented. multiple patterns they can be written on separate lines, unindented.
The field assignments are on separate lines indented by at least one The field assignments are on separate lines indented by at least one
space. Examples: space. Examples:
# if the CSV record contains "groceries", set account2 to "expenses:groceries" # if the CSV record contains "groceries", set account2 to "expenses:groceries"
@ -175,33 +178,33 @@ CSV RULES
newest-first newest-first
newest-first newest-first
Consider adding this rule if all of the following are true: you might Consider adding this rule if all of the following are true: you might
be processing just one day of data, your CSV records are in reverse be processing just one day of data, your CSV records are in reverse
chronological order (newest first), and you care about preserving the chronological order (newest first), and you care about preserving the
order of same-day transactions. It usually isn't needed, because order of same-day transactions. It usually isn't needed, because
hledger autodetects the CSV order, but when all CSV records have the hledger autodetects the CSV order, but when all CSV records have the
same date it will assume they are oldest first. same date it will assume they are oldest first.
CSV TIPS CSV TIPS
CSV ordering CSV ordering
The generated journal entries will be sorted by date. The order of The generated journal entries will be sorted by date. The order of
same-day entries will be preserved (except in the special case where same-day entries will be preserved (except in the special case where
you might need newest-first, see above). you might need newest-first, see above).
CSV accounts CSV accounts
Each journal entry will have two postings, to account1 and account2 Each journal entry will have two postings, to account1 and account2
respectively. It's not yet possible to generate entries with more than respectively. It's not yet possible to generate entries with more than
two postings. It's conventional and recommended to use account1 for two postings. It's conventional and recommended to use account1 for
the account whose CSV we are reading. the account whose CSV we are reading.
CSV amounts CSV amounts
A transaction amount must be set, in one of these ways: A transaction amount must be set, in one of these ways:
o with an amount field assignment, which sets the first posting's o with an amount field assignment, which sets the first posting's
amount amount
o (When the CSV has debit and credit amounts in separate fields:) o (When the CSV has debit and credit amounts in separate fields:)
with field assignments for the amount-in and amount-out pseudo fields with field assignments for the amount-in and amount-out pseudo fields
(both of them). Whichever one has a value will be used, with appropri- (both of them). Whichever one has a value will be used, with appropri-
ate sign. If both contain a value, it might not work so well. ate sign. If both contain a value, it might not work so well.
@ -209,33 +212,45 @@ CSV TIPS
There is some special handling for sign in amounts: There is some special handling for sign in amounts:
o If an amount value is parenthesised, it will be de-parenthesised and o If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped. sign-flipped.
o If an amount value begins with a double minus sign, those will cancel o If an amount value begins with a double minus sign, those will cancel
out and be removed. out and be removed.
If the currency/commodity symbol is provided as a separate CSV field, If the currency/commodity symbol is provided as a separate CSV field,
assign it to the currency pseudo field; the symbol will be prepended to assign it to the currency pseudo field; the symbol will be prepended to
the amount (TODO: when there is an amount). Or, you can use an amount the amount (TODO: when there is an amount). Or, you can use an amount
field assignment for more control, eg: field assignment for more control, eg:
fields date,description,currency,amount fields date,description,currency,amount
amount %amount %currency amount %amount %currency
CSV balance assertions/assignments CSV balance assertions/assignments
If the CSV includes a running balance, you can assign that to one of If the CSV includes a running balance, you can assign that to one of
the pseudo fields balance (or balance1) or balance2. This will gener- the pseudo fields balance (or balance1) or balance2. This will gener-
ate a balance assertion (or if the amount is left empty, a balance ate a balance assertion (or if the amount is left empty, a balance
assignment), on the first or second posting, whenever the running bal- assignment), on the first or second posting, whenever the running bal-
ance field is non-empty. (TODO: #1000) ance field is non-empty. (TODO: #1000)
Reading multiple CSV files Reading multiple CSV files
You can read multiple CSV files at once using multiple -f arguments on You can read multiple CSV files at once using multiple -f arguments on
the command line, and hledger will look for a correspondingly-named the command line, and hledger will look for a correspondingly-named
rules file for each. Note if you use the --rules-file option, this one rules file for each. Note if you use the --rules-file option, this one
rules file will be used for all the CSV files being read. rules file will be used for all the CSV files being read.
Valid CSV
hledger follows RFC 4180, with the addition of a customisable separator
character.
Some things to note:
When quoting fields,
o you must use double quotes, not single quotes
o spaces outside the quotes are not allowed.
REPORTING BUGS REPORTING BUGS
@ -261,4 +276,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger_csv(5) hledger 1.15 August 2019 hledger_csv(5)

129
hledger-lib/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "hledger_journal" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger_journal" "5" "August 2019" "hledger 1.15" "hledger User Manuals"
@ -314,11 +314,12 @@ can be used for whatever you wish, or left blank.
Transaction descriptions can be queried, unlike comments. Transaction descriptions can be queried, unlike comments.
.SS Payee and note .SS Payee and note
.PP .PP
You can optionally include a \f[C]|\f[R] (pipe) character in a You can optionally include a \f[C]|\f[R] (pipe) character in
description to subdivide it into a payee/payer name on the left and descriptions to subdivide the description into separate fields for
additional notes on the right. payee/payer name on the left (up to the first \f[C]|\f[R]) and an
additional note field on the right (after the first \f[C]|\f[R]).
This may be worthwhile if you need to do more precise querying and This may be worthwhile if you need to do more precise querying and
pivoting by payee. pivoting by payee or by note.
.SS Account names .SS Account names
.PP .PP
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
@ -727,7 +728,7 @@ Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount:
\f[C] \f[C]
2009/1/1 2009/1/1
assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00 assets:dollars ; balancing amount is -$135.00
\f[R] \f[R]
.fi .fi
.RE .RE
@ -752,8 +753,8 @@ hledger infer the price that balances the transaction:
.nf .nf
\f[C] \f[C]
2009/1/1 2009/1/1
assets:euros \[Eu]100 ; one hundred euros purchased assets:euros \[Eu]100 ; one hundred euros purchased
assets:dollars $-135 ; for $135 assets:dollars $-135 ; for $135
\f[R] \f[R]
.fi .fi
.RE .RE
@ -786,8 +787,8 @@ equivalent, -B shows something different:
.nf .nf
\f[C] \f[C]
2009/1/1 2009/1/1
assets:dollars $-135 ; 135 dollars sold assets:dollars $-135 ; 135 dollars sold
assets:euros \[Eu]100 ; for 100 euros assets:euros \[Eu]100 ; for 100 euros
\f[R] \f[R]
.fi .fi
.IP .IP
@ -870,7 +871,7 @@ comma separated:
.IP .IP
.nf .nf
\f[C] \f[C]
assets:checking ; a comment containing tag1:, tag2: some value ... assets:checking ; a comment containing tag1:, tag2: some value ...
\f[R] \f[R]
.fi .fi
.PP .PP
@ -1118,7 +1119,8 @@ Y2010 ; change default year to 2010
.SS Declaring commodities .SS Declaring commodities
.PP .PP
The \f[C]commodity\f[R] directive declares commodities which may be used The \f[C]commodity\f[R] directive declares commodities which may be used
in the journal (though currently we do not enforce this). in the journal, and their display format.
.PP
It may be written on a single line, like this: It may be written on a single line, like this:
.IP .IP
.nf .nf
@ -1149,14 +1151,20 @@ commodity INR
\f[R] \f[R]
.fi .fi
.PP .PP
Commodity directives have a second purpose: they define the standard Declaring commodites may be useful as documentation, but currently we do
display format for amounts in the commodity. not enforce that only declared commodities may be used.
This directive is mainly useful for customising the preferred display
format for a commodity.
.PP
Normally the display format is inferred from journal entries, but this Normally the display format is inferred from journal entries, but this
can be unpredictable; declaring it with a commodity directive overrides can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity. this and removes ambiguity.
Towards this end, amounts in commodity directives must always be written Towards this end, amounts in commodity directives must always be written
with a decimal point (a period or comma, followed by 0 or more decimal with a decimal point (a period or comma, followed by 0 or more decimal
digits). digits).
.PP
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
.SS Default commodity .SS Default commodity
.PP .PP
The \f[C]D\f[R] directive sets a default commodity (and display format), The \f[C]D\f[R] directive sets a default commodity (and display format),
@ -1334,11 +1342,11 @@ Eg:
.nf .nf
\f[C] \f[C]
; make \[dq]liabilities\[dq] not have the liability type - who knows why ; make \[dq]liabilities\[dq] not have the liability type - who knows why
account liabilities ; type:E account liabilities ; type:E
; we need to ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities ; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities
account - ; type:L account - ; type:L
\f[R] \f[R]
.fi .fi
.SS Account display order .SS Account display order
@ -1474,20 +1482,39 @@ alias /\[ha](.+):bank:([\[ha]:]+)(.*)/ = \[rs]1:\[rs]2 \[rs]3
.PP .PP
Also note that REPLACEMENT continues to the end of line (or on command Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing whitespace. line, to end of option argument), so it can contain trailing whitespace.
.SS Multiple aliases .SS Combining aliases
.PP .PP
You can define as many aliases as you like using directives or You can define as many aliases as you like, using journal directives
command-line options. and/or command line options.
Aliases are recursive - each alias sees the result of applying previous .PP
ones. Recursive aliases - where an account name is rewritten by one alias,
(This is different from Ledger, where aliases are non-recursive by then by another alias, and so on - are allowed.
default). Each alias sees the effect of previously applied aliases.
Aliases are applied in the following order: .PP
In such cases it can be important to understand which aliases will be
applied and in which order.
For (each account name in) each journal entry, we apply:
.IP "1." 3 .IP "1." 3
alias directives, most recently seen first (recent directives take \f[C]alias\f[R] directives preceding the journal entry, most recently
precedence over earlier ones; directives not yet seen are ignored) parsed first (ie, reading upward from the journal entry, bottom to top)
.IP "2." 3 .IP "2." 3
alias options, in the order they appear on the command line \f[C]--alias\f[R] options, in the order they appeared on the command
line (left to right).
.PP
In other words, for (an account name in) a given journal entry:
.IP \[bu] 2
the nearest alias declaration before/above the entry is applied first
.IP \[bu] 2
the next alias before/above that will be be applied next, and so on
.IP \[bu] 2
aliases defined after/below the entry do not affect it.
.PP
This gives nearby aliases precedence over distant ones, and helps
provide semantic stability - aliases will keep working the same way
independent of which files are being read and in which order.
.PP
In case of trouble, adding \f[C]--debug=6\f[R] to the command line will
show which aliases are being applied when.
.SS \f[C]end aliases\f[R] .SS \f[C]end aliases\f[R]
.PP .PP
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases with the
@ -1603,8 +1630,18 @@ example:
With the \f[C]--forecast\f[R] flag, each periodic transaction rule With the \f[C]--forecast\f[R] flag, each periodic transaction rule
generates future transactions recurring at the specified interval. generates future transactions recurring at the specified interval.
These are not saved in the journal, but appear in all reports. These are not saved in the journal, but appear in all reports.
They will look like normal transactions, but with an extra tag named They will look like normal transactions, but with an extra tag:
\f[C]recur\f[R], whose value is the generating period expression. .IP \[bu] 2
\f[C]generated-transaction:\[ti] PERIODICEXPR\f[R] - shows that this was
generated by a periodic transaction rule, and the period
.PP
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger\[aq]s output:
.IP \[bu] 2
\f[C]_generated-transaction:\[ti] PERIODICEXPR\f[R]
.PP
This can be used to match transactions generated \[dq]just now\[dq],
rather than generated in the past and saved to the journal.
.PP .PP
Forecast transactions start on the first occurrence, and end on the last Forecast transactions start on the first occurrence, and end on the last
occurrence, of their interval within the forecast period. occurrence, of their interval within the forecast period.
@ -1654,16 +1691,16 @@ and Forecasting.
.PP .PP
.SS Auto postings / transaction modifiers .SS Auto postings / transaction modifiers
.PP .PP
Transaction modifier rules describe changes to be applied automatically Transaction modifier rules, AKA auto posting rules, describe changes to
to certain matched transactions. be applied automatically to certain matched transactions.
Currently just one kind of change is possible - adding extra postings, Currently just one kind of change is possible - adding extra postings,
which we call \[dq]automated postings\[dq] or just \[dq]auto which we call \[dq]automated postings\[dq] or just \[dq]auto
postings\[dq]. postings\[dq].
These rules become active when you use the \f[C]--auto\f[R] flag. These rules become active when you use the \f[C]--auto\f[R] flag.
.PP .PP
A transaction modifier, AKA auto posting rule, looks much like a normal A transaction modifier rule looks much like a normal transaction except
transaction except the first line is an equals sign followed by a query the first line is an equals sign followed by a query that matches
that matches certain postings (mnemonic: \f[C]=\f[R] suggests matching). certain postings (mnemonic: \f[C]=\f[R] suggests matching).
And each \[dq]posting\[dq] is actually a posting-generating rule: And each \[dq]posting\[dq] is actually a posting-generating rule:
.IP .IP
.nf .nf
@ -1736,6 +1773,11 @@ $ hledger print --auto
assets:checking $20 assets:checking $20
\f[R] \f[R]
.fi .fi
.SS Auto postings and dates
.PP
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also be
used in the generated posting.
.SS Auto postings and transaction balancing / inferred amounts / balance assertions .SS Auto postings and transaction balancing / inferred amounts / balance assertions
.PP .PP
Currently, transaction modifiers are applied / auto postings are added: Currently, transaction modifiers are applied / auto postings are added:
@ -1748,6 +1790,25 @@ but before balance assertions are checked.
Note this means that journal entries must be balanced both before and Note this means that journal entries must be balanced both before and
after auto postings are added. after auto postings are added.
This changed in hledger 1.12+; see #893 for background. This changed in hledger 1.12+; see #893 for background.
.SS Auto posting tags
.PP
Postings added by transaction modifiers will have some extra tags:
.IP \[bu] 2
\f[C]generated-posting:= QUERY\f[R] - shows this was generated by an
auto posting rule, and the query
.IP \[bu] 2
\f[C]_generated-posting:= QUERY\f[R] - a hidden tag, which does not
appear in hledger\[aq]s output.
This can be used to match postings generated \[dq]just now\[dq], rather
than generated in the past and saved to the journal.
.PP
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
.IP \[bu] 2
\f[C]modified:\f[R] - this transaction was modified
.IP \[bu] 2
\f[C]_modified:\f[R] - a hidden tag not appearing in the comment; this
transaction was modified \[dq]just now\[dq].
.SH EDITOR SUPPORT .SH EDITOR SUPPORT
.PP .PP
Helper modes exist for popular text editors, which make working with Helper modes exist for popular text editors, which make working with

395
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.14.99 hledger_journal(5) hledger 1.15
********************************** *******************************
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
@ -214,8 +214,8 @@ reports, and the deduction from checking should be reported on 6/1 for
easy bank reconciliation: easy bank reconciliation:
2015/5/30 2015/5/30
expenses:food $10 ; food purchased on saturday 5/30 expenses:food $10 ; food purchased on saturday 5/30
assets:checking ; bank cleared it on monday, date:6/1 assets:checking ; bank cleared it on monday, date:6/1
$ hledger -f t.j register food $ hledger -f t.j register food
2015/05/30 expenses:food $10 $10 2015/05/30 expenses:food $10 $10
@ -307,10 +307,11 @@ File: hledger_journal.info, Node: Payee and note, Up: Description
1.5.1 Payee and note 1.5.1 Payee and note
-------------------- --------------------
You can optionally include a '|' (pipe) character in a description to You can optionally include a '|' (pipe) character in descriptions to
subdivide it into a payee/payer name on the left and additional notes on subdivide the description into separate fields for payee/payer name on
the right. This may be worthwhile if you need to do more precise the left (up to the first '|') and an additional note field on the right
querying and pivoting by payee. (after the first '|'). This may be worthwhile if you need to do more
precise querying and pivoting by payee or by note.
 
File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT
@ -734,8 +735,8 @@ last amount. So if example 3's postings are reversed, while the
transaction is equivalent, -B shows something different: transaction is equivalent, -B shows something different:
2009/1/1 2009/1/1
assets:dollars $-135 ; 135 dollars sold assets:dollars $-135 ; 135 dollars sold
assets:euros €100 ; for 100 euros assets:euros €100 ; for 100 euros
$ hledger bal -N --flat -B $ hledger bal -N --flat -B
€-100 assets:dollars # <- the dollars' selling price €-100 assets:dollars # <- the dollars' selling price
@ -799,13 +800,13 @@ colon, written inside a transaction or posting comment line:
Tags can have a value, which is the text after the colon, up to the Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed: next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or Note this means hledger's tag values can not contain commas or
newlines. Ending at commas means you can write multiple short tags on newlines. Ending at commas means you can write multiple short tags on
one line, comma separated: one line, comma separated:
assets:checking ; a comment containing tag1:, tag2: some value ... assets:checking ; a comment containing tag1:, tag2: some value ...
Here, Here,
@ -968,19 +969,19 @@ 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
12/15 ; equivalent to 2009/12/15 12/15 ; equivalent to 2009/12/15
expenses 1 expenses 1
assets assets
Y2010 ; change default year to 2010 Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected 2009/1/30 ; specifies the year, not affected
expenses 1 expenses 1
assets assets
1/31 ; equivalent to 2010/1/31 1/31 ; equivalent to 2010/1/31
expenses 1 expenses 1
assets assets
@ -991,8 +992,9 @@ File: hledger_journal.info, Node: Declaring commodities, Next: Default commodi
---------------------------- ----------------------------
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 on journal, and their display format.
a single line, like this:
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -1014,13 +1016,19 @@ places:
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 Declaring commodites may be useful as documentation, but currently we
display format for amounts in the commodity. Normally the display do not enforce that only declared commodities may be used. This
format is inferred from journal entries, but this can be unpredictable; directive is mainly useful for customising the preferred display format
declaring it with a commodity directive overrides this and removes for a commodity.
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0 Normally the display format is inferred from journal entries, but
or more decimal digits). this can be unpredictable; declaring it with a commodity directive
overrides this and removes ambiguity. Towards this end, amounts in
commodity directives must always be written with a decimal point (a
period or comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
 
File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
@ -1039,7 +1047,7 @@ amounts, or until the next 'D' directive.
D $1,000.00 D $1,000.00
1/1 1/1
a 5 ; <- commodity-less amount, becomes $1 a 5 ; <- commodity-less amount, becomes $1
b b
As with the 'commodity' directive, the amount must always be written As with the 'commodity' directive, the amount must always be written
@ -1182,11 +1190,11 @@ those auto-detected english account names mentioned above, you might
need to help the reports a bit. Eg: need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
account liabilities ; type:E account liabilities ; type:E
; we need to ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities ; otherwise balancesheet would still show "liabilities" under Liabilities
account - ; type:L account - ; type:L
 
File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts
@ -1257,7 +1265,7 @@ hledger-web.
* Basic aliases:: * Basic aliases::
* Regex aliases:: * Regex aliases::
* Multiple aliases:: * Combining aliases::
* end aliases:: * end aliases::
 
@ -1284,7 +1292,7 @@ alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
 
File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.8.2 Regex aliases 1.14.8.2 Regex aliases
...................... ......................
@ -1309,23 +1317,44 @@ command line, to end of option argument), so it can contain trailing
whitespace. whitespace.
 
File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Combining aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.8.3 Multiple aliases 1.14.8.3 Combining aliases
......................... ..........................
You can define as many aliases as you like using directives or You can define as many aliases as you like, using journal directives
command-line options. Aliases are recursive - each alias sees the and/or command line options.
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
1. alias directives, most recently seen first (recent directives take Recursive aliases - where an account name is rewritten by one alias,
precedence over earlier ones; directives not yet seen are ignored) then by another alias, and so on - are allowed. Each alias sees the
2. alias options, in the order they appear on the command line effect of previously applied aliases.
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. 'alias' directives preceding the journal entry, most recently
parsed first (ie, reading upward from the journal entry, bottom to
top)
2. '--alias' options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
* the nearest alias declaration before/above the entry is applied
first
* the next alias before/above that will be be applied next, and so on
* aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps
provide semantic stability - aliases will keep working the same way
independent of which files are being read and in which order.
In case of trouble, adding '--debug=6' to the command line will show
which aliases are being applied when.
 
File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts File: hledger_journal.info, Node: end aliases, Prev: Combining aliases, Up: Rewriting accounts
1.14.8.4 'end aliases' 1.14.8.4 'end aliases'
...................... ......................
@ -1437,8 +1466,18 @@ File: hledger_journal.info, Node: Forecasting with periodic transactions, Next
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:
the generating period expression.
* 'generated-transaction:~ PERIODICEXPR' - shows that this was
generated by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
* '_generated-transaction:~ PERIODICEXPR'
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
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
@ -1493,16 +1532,16 @@ File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev:
1.16 Auto postings / transaction modifiers 1.16 Auto postings / transaction modifiers
========================================== ==========================================
Transaction modifier rules describe changes to be applied automatically Transaction modifier rules, AKA auto posting rules, describe changes to
to certain matched transactions. Currently just one kind of change is be applied automatically to certain matched transactions. Currently
possible - adding extra postings, which we call "automated postings" or just one kind of change is possible - adding extra postings, which we
just "auto postings". These rules become active when you use the call "automated postings" or just "auto postings". These rules become
'--auto' flag. active when you use the '--auto' flag.
A transaction modifier, AKA auto posting rule, looks much like a A transaction modifier rule looks much like a normal transaction
normal transaction except the first line is an equals sign followed by a except the first line is an equals sign followed by a query that matches
query that matches certain postings (mnemonic: '=' suggests matching). certain postings (mnemonic: '=' suggests matching). And each "posting"
And each "posting" is actually a posting-generating rule: is actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCT AMT
@ -1560,12 +1599,24 @@ $ hledger print --auto
* Menu: * Menu:
* Auto postings and dates::
* Auto postings and transaction balancing / inferred amounts / balance assertions:: * Auto postings and transaction balancing / inferred amounts / balance assertions::
* Auto posting tags::
 
File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
1.16.1 Auto postings and transaction balancing / inferred amounts / 1.16.1 Auto postings and dates
------------------------------
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also be
used in the generated posting.

File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings / transaction modifiers
1.16.2 Auto postings and transaction balancing / inferred amounts /
------------------------------------------------------------------- -------------------------------------------------------------------
balance assertions Currently, transaction modifiers are applied / auto balance assertions Currently, transaction modifiers are applied / auto
@ -1579,6 +1630,28 @@ postings are added:
after auto postings are added. This changed in hledger 1.12+; see #893 after auto postings are added. This changed in hledger 1.12+; see #893
for background. for background.

File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
1.16.3 Auto posting tags
------------------------
Postings added by transaction modifiers will have some extra tags:
* 'generated-posting:= QUERY' - shows this was generated by an auto
posting rule, and the query
* '_generated-posting:= QUERY' - a hidden tag, which does not appear
in hledger's output. This can be used to match postings generated
"just now", rather than generated in the past and saved to the
journal.
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
* 'modified:' - this transaction was modified
* '_modified:' - a hidden tag not appearing in the comment; this
transaction was modified "just now".
 
File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -1595,109 +1668,113 @@ See the [[Cookbook]] at hledger.org for the latest information.
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT2378 Node: FILE FORMAT2352
Ref: #file-format2502 Ref: #file-format2476
Node: Transactions2805 Node: Transactions2779
Ref: #transactions2926 Ref: #transactions2900
Node: Postings3610 Node: Postings3584
Ref: #postings3737 Ref: #postings3711
Node: Dates4732 Node: Dates4706
Ref: #dates4847 Ref: #dates4821
Node: Simple dates4912 Node: Simple dates4886
Ref: #simple-dates5038 Ref: #simple-dates5012
Node: Secondary dates5404 Node: Secondary dates5378
Ref: #secondary-dates5558 Ref: #secondary-dates5532
Node: Posting dates7121 Node: Posting dates7095
Ref: #posting-dates7250 Ref: #posting-dates7224
Node: Status8624 Node: Status8596
Ref: #status8744 Ref: #status8716
Node: Description10452 Node: Description10424
Ref: #description10590 Ref: #description10562
Node: Payee and note10910 Node: Payee and note10882
Ref: #payee-and-note11024 Ref: #payee-and-note10996
Node: Account names11266 Node: Account names11331
Ref: #account-names11409 Ref: #account-names11474
Node: Amounts11896 Node: Amounts11961
Ref: #amounts12032 Ref: #amounts12097
Node: Virtual Postings15049 Node: Virtual Postings15114
Ref: #virtual-postings15208 Ref: #virtual-postings15273
Node: Balance Assertions16428 Node: Balance Assertions16493
Ref: #balance-assertions16603 Ref: #balance-assertions16668
Node: Assertions and ordering17562 Node: Assertions and ordering17627
Ref: #assertions-and-ordering17748 Ref: #assertions-and-ordering17813
Node: Assertions and included files18448 Node: Assertions and included files18513
Ref: #assertions-and-included-files18689 Ref: #assertions-and-included-files18754
Node: Assertions and multiple -f options19022 Node: Assertions and multiple -f options19087
Ref: #assertions-and-multiple--f-options19276 Ref: #assertions-and-multiple--f-options19341
Node: Assertions and commodities19408 Node: Assertions and commodities19473
Ref: #assertions-and-commodities19638 Ref: #assertions-and-commodities19703
Node: Assertions and prices20794 Node: Assertions and prices20859
Ref: #assertions-and-prices21006 Ref: #assertions-and-prices21071
Node: Assertions and subaccounts21446 Node: Assertions and subaccounts21511
Ref: #assertions-and-subaccounts21673 Ref: #assertions-and-subaccounts21738
Node: Assertions and virtual postings21997 Node: Assertions and virtual postings22062
Ref: #assertions-and-virtual-postings22237 Ref: #assertions-and-virtual-postings22302
Node: Assertions and precision22379 Node: Assertions and precision22444
Ref: #assertions-and-precision22570 Ref: #assertions-and-precision22635
Node: Balance Assignments22837 Node: Balance Assignments22902
Ref: #balance-assignments23018 Ref: #balance-assignments23083
Node: Balance assignments and prices24183 Node: Balance assignments and prices24248
Ref: #balance-assignments-and-prices24355 Ref: #balance-assignments-and-prices24420
Node: Transaction prices24579 Node: Transaction prices24644
Ref: #transaction-prices24748 Ref: #transaction-prices24813
Node: Comments27016 Node: Comments27079
Ref: #comments27150 Ref: #comments27213
Node: Tags28320 Node: Tags28383
Ref: #tags28438 Ref: #tags28501
Node: Directives29840 Node: Directives29894
Ref: #directives29983 Ref: #directives30037
Node: Comment blocks35591 Node: Comment blocks35645
Ref: #comment-blocks35736 Ref: #comment-blocks35790
Node: Including other files35912 Node: Including other files35966
Ref: #including-other-files36092 Ref: #including-other-files36146
Node: Default year36500 Node: Default year36554
Ref: #default-year36669 Ref: #default-year36723
Node: Declaring commodities37092 Node: Declaring commodities37130
Ref: #declaring-commodities37275 Ref: #declaring-commodities37313
Node: Default commodity38502 Node: Default commodity38742
Ref: #default-commodity38678 Ref: #default-commodity38918
Node: Market prices39314 Node: Market prices39552
Ref: #market-prices39479 Ref: #market-prices39717
Node: Declaring accounts40320 Node: Declaring accounts40558
Ref: #declaring-accounts40496 Ref: #declaring-accounts40734
Node: Account comments41421 Node: Account comments41659
Ref: #account-comments41584 Ref: #account-comments41822
Node: Account subdirectives41979 Node: Account subdirectives42217
Ref: #account-subdirectives42174 Ref: #account-subdirectives42412
Node: Account types42487 Node: Account types42725
Ref: #account-types42671 Ref: #account-types42909
Node: Account display order44315 Node: Account display order44551
Ref: #account-display-order44485 Ref: #account-display-order44721
Node: Rewriting accounts45614 Node: Rewriting accounts45850
Ref: #rewriting-accounts45799 Ref: #rewriting-accounts46035
Node: Basic aliases46534 Node: Basic aliases46771
Ref: #basic-aliases46680 Ref: #basic-aliases46917
Node: Regex aliases47384 Node: Regex aliases47621
Ref: #regex-aliases47555 Ref: #regex-aliases47793
Node: Multiple aliases48273 Node: Combining aliases48511
Ref: #multiple-aliases48448 Ref: #combining-aliases48689
Node: end aliases48946 Node: end aliases49965
Ref: #end-aliases49093 Ref: #end-aliases50113
Node: Default parent account49194 Node: Default parent account50214
Ref: #default-parent-account49360 Ref: #default-parent-account50380
Node: Periodic transactions50244 Node: Periodic transactions51264
Ref: #periodic-transactions50442 Ref: #periodic-transactions51462
Node: Two spaces after the period expression51568 Node: Two spaces after the period expression52588
Ref: #two-spaces-after-the-period-expression51813 Ref: #two-spaces-after-the-period-expression52833
Node: Forecasting with periodic transactions52298 Node: Forecasting with periodic transactions53318
Ref: #forecasting-with-periodic-transactions52588 Ref: #forecasting-with-periodic-transactions53608
Node: Budgeting with periodic transactions54275 Node: Budgeting with periodic transactions55634
Ref: #budgeting-with-periodic-transactions54514 Ref: #budgeting-with-periodic-transactions55873
Node: Auto postings / transaction modifiers54973 Node: Auto postings / transaction modifiers56332
Ref: #auto-postings-transaction-modifiers55184 Ref: #auto-postings-transaction-modifiers56543
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57356 Node: Auto postings and dates58772
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57673 Ref: #auto-postings-and-dates59029
Node: EDITOR SUPPORT58051 Node: Auto postings and transaction balancing / inferred amounts / balance assertions59204
Ref: #editor-support58169 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions59579
Node: Auto posting tags59957
Ref: #auto-posting-tags60196
Node: EDITOR SUPPORT60861
Ref: #editor-support60979
 
End Tag Table End Tag Table

427
hledger-lib/hledger_journal.txt
View File

@ -229,19 +229,20 @@ FILE FORMAT
comments. comments.
Payee and note Payee and note
You can optionally include a | (pipe) character in a description to You can optionally include a | (pipe) character in descriptions to sub-
subdivide it into a payee/payer name on the left and additional notes divide the description into separate fields for payee/payer name on the
on the right. This may be worthwhile if you need to do more precise left (up to the first |) and an additional note field on the right
querying and pivoting by payee. (after the first |). This may be worthwhile if you need to do more
precise querying and pivoting by payee or by note.
Account names Account names
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five top- be anything you like, but in finance there are traditionally five top-
level accounts: assets, liabilities, income, expenses, and equity. level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv- Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more able. Because of this, they must always be followed by two or more
spaces (or newline). spaces (or newline).
Account names can be aliased. Account names can be aliased.
@ -250,7 +251,7 @@ FILE FORMAT
After the account name, there is usually an amount. Important: between After the account name, there is usually an amount. Important: between
account name and amount, there must be two or more spaces. account name and amount, there must be two or more spaces.
Amounts consist of a number and (usually) a currency symbol or commod- Amounts consist of a number and (usually) a currency symbol or commod-
ity name. Some examples: ity name. Some examples:
2.00001 2.00001
@ -266,35 +267,35 @@ FILE FORMAT
As you can see, the amount format is somewhat flexible: As you can see, the amount format is somewhat flexible:
o amounts are a number (the "quantity") and optionally a currency sym- o amounts are a number (the "quantity") and optionally a currency sym-
bol/commodity name (the "commodity"). bol/commodity name (the "commodity").
o the commodity is a symbol, word, or phrase, on the left or right, o the commodity is a symbol, word, or phrase, on the left or right,
with or without a separating space. If the commodity contains num- with or without a separating space. If the commodity contains num-
bers, spaces or non-word punctuation it must be enclosed in double bers, spaces or non-word punctuation it must be enclosed in double
quotes. quotes.
o negative amounts with a commodity on the left can have the minus sign o negative amounts with a commodity on the left can have the minus sign
before or after it before or after it
o digit groups (thousands, or any other grouping) can be separated by o digit groups (thousands, or any other grouping) can be separated by
space or comma or period and should be used as separator between all space or comma or period and should be used as separator between all
groups groups
o decimal part can be separated by comma or period and should be dif- o decimal part can be separated by comma or period and should be dif-
ferent from digit groups separator ferent from digit groups separator
o scientific E-notation is allowed. Be careful not to use a digit o scientific E-notation is allowed. Be careful not to use a digit
group separator character in scientific notation, as it's not sup- group separator character in scientific notation, as it's not sup-
ported and it might get mistaken for a decimal point. (Declaring the ported and it might get mistaken for a decimal point. (Declaring the
digit group separator character explicitly with a commodity directive digit group separator character explicitly with a commodity directive
will prevent this.) will prevent this.)
You can use any of these variations when recording data. However, You can use any of these variations when recording data. However,
there is some ambiguous way of representing numbers like $1.000 and there is some ambiguous way of representing numbers like $1.000 and
$1,000 both may mean either one thousand or one dollar. By default $1,000 both may mean either one thousand or one dollar. By default
hledger will assume that this is sole delimiter is used only for deci- hledger will assume that this is sole delimiter is used only for deci-
mals. On the other hand commodity format declared prior to that line mals. On the other hand commodity format declared prior to that line
will help to resolve that ambiguity differently: will help to resolve that ambiguity differently:
commodity $1,000.00 commodity $1,000.00
@ -303,38 +304,38 @@ FILE FORMAT
expenses:gifts $1,000 expenses:gifts $1,000
assets assets
Though journal may contain mixed styles to represent amount, when Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows: written). The display format is chosen as follows:
o if there is a commodity directive specifying the format, that is used o if there is a commodity directive specifying the format, that is used
o otherwise the format is inferred from the first posting amount in o otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of decimal that commodity in the journal, and the precision (number of decimal
places) will be the maximum from all posting amounts in that commmod- places) will be the maximum from all posting amounts in that commmod-
ity ity
o or if there are no such amounts in the journal, a default format is o or if there are no such amounts in the journal, a default format is
used (like $1000.00). used (like $1000.00).
Price amounts and amounts in D directives usually don't affect amount Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly. format inference, but in some situations they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount, (Eg when D's default commodity is applied to a commodity-less amount,
or when an amountless posting is balanced using a price's commodity, or or when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, set the desired when -V is used.) If you find this causing problems, set the desired
format with a commodity directive. format with a commodity directive.
Virtual Postings Virtual Postings
When you parenthesise the account name in a posting, we call that a When you parenthesise the account name in a posting, we call that a
virtual posting, which means: virtual posting, which means:
o it is ignored when checking that the transaction is balanced o it is ignored when checking that the transaction is balanced
o it is excluded from reports when the --real/-R flag is used, or the o it is excluded from reports when the --real/-R flag is used, or the
real:1 query. real:1 query.
You could use this, eg, to set an account's opening balance without You could use this, eg, to set an account's opening balance without
needing to use the equity:opening balances account: needing to use the equity:opening balances account:
1/1 special unbalanced posting to set initial balance 1/1 special unbalanced posting to set initial balance
@ -342,8 +343,8 @@ FILE FORMAT
When the account name is bracketed, we call it a balanced virtual post- When the account name is bracketed, we call it a balanced virtual post-
ing. This is like an ordinary virtual posting except the balanced vir- ing. This is like an ordinary virtual posting except the balanced vir-
tual postings in a transaction must balance to 0, like the real post- tual postings in a transaction must balance to 0, like the real post-
ings (but separately from them). Balanced virtual postings are also ings (but separately from them). Balanced virtual postings are also
excluded by --real/-R or real:1. excluded by --real/-R or real:1.
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere 1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
@ -353,13 +354,13 @@ FILE FORMAT
[assets:checking:budget:food] $-10 [assets:checking:budget:food] $-10
Virtual postings have some legitimate uses, but those are few. You can Virtual postings have some legitimate uses, but those are few. You can
usually find an equivalent journal entry using real postings, which is usually find an equivalent journal entry using real postings, which is
more correct and provides better error checking. more correct and provides better error checking.
Balance Assertions Balance Assertions
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a amount. Eg here we assert the expected dollar balance in accounts a
and b after each posting: and b after each posting:
2013/1/1 2013/1/1
@ -371,31 +372,31 @@ FILE FORMAT
b $-1 =$-2 b $-1 =$-2
After reading a journal file, hledger will check all balance assertions After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro- and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the cleaning up old entries. You can disable them temporarily with the
-I/--ignore-assertions flag, which can be useful for troubleshooting or -I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files. for reading Ledger files.
Assertions and ordering Assertions and ordering
hledger sorts an account's postings and assertions first by date and hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif- then (for postings on the same day) by parse order. Note this is dif-
ferent from Ledger, which sorts assertions only by parse order. (Also, ferent from Ledger, which sorts assertions only by parse order. (Also,
Ledger assertions do not see the accumulated effect of repeated post- Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.) ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differently- So, hledger balance assertions keep working if you reorder differently-
dated transactions within the journal. But if you reorder same-dated dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating. transactions or postings, assertions might break and require updating.
This order dependence does bring an advantage: precise control over the This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert intra- order of postings and assertions within a day, so you can assert intra-
day balances. day balances.
Assertions and included files Assertions and included files
With included files, things are a little more complicated. Including With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi- preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same files, and you also want to assert the account's balance on the same
day, you'll have to put the assertion in the right file. day, you'll have to put the assertion in the right file.
Assertions and multiple -f options Assertions and multiple -f options
@ -403,8 +404,8 @@ FILE FORMAT
-f options. Use include or concatenate the files instead. -f options. Use include or concatenate the files instead.
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. (possibly multi-commodity) account balance.
This is how assertions work in Ledger also. We could call this a "par- This is how assertions work in Ledger also. We could call this a "par-
tial" balance assertion. tial" balance assertion.
@ -412,7 +413,7 @@ FILE FORMAT
To assert the balance of more than one commodity in an account, you can To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance. write multiple postings, each asserting one commodity's balance.
You can make a stronger "total" balance assertion by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (== EXPECTEDBALANCE). This asserts that there are no other equals sign (== EXPECTEDBALANCE). This asserts that there are no other
unasserted commodities in the account (or, that their balance is 0). unasserted commodities in the account (or, that their balance is 0).
@ -432,7 +433,7 @@ FILE FORMAT
a 0 == $1 a 0 == $1
It's not yet possible to make a complete assertion about a balance that It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity has multiple commodities. One workaround is to isolate each commodity
into its own subaccount: into its own subaccount:
2013/1/1 2013/1/1
@ -446,21 +447,21 @@ FILE FORMAT
a:euro 0 == 1EUR a:euro 0 == 1EUR
Assertions and prices Assertions and prices
Balance assertions ignore transaction prices, and should normally be Balance assertions ignore transaction prices, and should normally be
written without one: written without one:
2019/1/1 2019/1/1
(a) $1 @ EUR1 = $1 (a) $1 @ EUR1 = $1
We do allow prices to be written there, however, and print shows them, We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails. even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign- generate balance assertions with prices), and because balance assign-
ments do use them (see below). ments do use them (see below).
Assertions and subaccounts Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg: assert the balance including subaccounts by writing =* or ==*, eg:
2019/1/1 2019/1/1
@ -474,16 +475,16 @@ FILE FORMAT
tual. They are not affected by the --real/-R flag or real: query. tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision Assertions and precision
Balance assertions compare the exactly calculated amounts, which are Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser- limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts. tions. Balance assertion failure messages show exact amounts.
Balance Assignments Balance Assignments
Ledger-style balance assignments are also supported. These are like Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when the assertion. This can be a convenience during data entry, eg when
setting opening balances: setting opening balances:
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
@ -501,14 +502,14 @@ FILE FORMAT
expenses:misc expenses:misc
The calculated amount depends on the account's balance in the commodity The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign- commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it. or do the calculations yourself, instead of just reading it.
Balance assignments and prices Balance assignments and prices
A transaction price in a balance assignment will cause the calculated A transaction price in a balance assignment will cause the calculated
amount to have that price attached: amount to have that price attached:
2019/1/1 2019/1/1
@ -520,9 +521,9 @@ FILE FORMAT
Transaction prices Transaction prices
Within a transaction, you can note an amount's price in another commod- Within a transaction, you can note an amount's price in another commod-
ity. This can be used to document the cost (in a purchase) or selling ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer- also market prices, which represent prevailing exchange rates on a cer-
tain date. tain date.
@ -533,7 +534,7 @@ FILE FORMAT
2009/1/1 2009/1/1
assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00 assets:dollars ; balancing amount is -$135.00
2. Write the total price, as @@ TOTALPRICE after the amount: 2. Write the total price, as @@ TOTALPRICE after the amount:
@ -546,12 +547,12 @@ FILE FORMAT
2009/1/1 2009/1/1
assets:euros EUR100 ; one hundred euros purchased assets:euros EUR100 ; one hundred euros purchased
assets:dollars $-135 ; for $135 assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores). PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price's Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above: Eg here is how -B affects the balance report for the example above:
@ -562,13 +563,13 @@ FILE FORMAT
$-135 assets:dollars $-135 assets:dollars
$135 assets:euros # <- the euros' cost $135 assets:euros # <- the euros' cost
Note -B is sensitive to the order of postings when a transaction price Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last is inferred: the inferred price will be in the commodity of the last
amount. So if example 3's postings are reversed, while the transaction amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different: is equivalent, -B shows something different:
2009/1/1 2009/1/1
assets:dollars $-135 ; 135 dollars sold assets:dollars $-135 ; 135 dollars sold
assets:euros EUR100 ; for 100 euros assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B $ hledger bal -N --flat -B
@ -577,14 +578,14 @@ FILE FORMAT
Comments Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) are comments, and will be ignored. (Star comments cause org-mode (*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.) journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post- description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines. writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;). Transaction and posting comments must begin with a semicolon (;).
Some examples: Some examples:
@ -608,28 +609,28 @@ FILE FORMAT
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; a file comment (because not indented)
You can also comment larger regions of a file using comment and end You can also comment larger regions of a file using comment and end
comment directives. comment directives.
Tags Tags
Tags are a way to add extra labels or labelled data to postings and Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on. transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line: colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag: 2017/1/16 bought groceries ; sometag:
Tags can have a value, which is the text after the colon, up to the Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed: next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new- Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one lines. Ending at commas means you can write multiple short tags on one
line, comma separated: line, comma separated:
assets:checking ; a comment containing tag1:, tag2: some value ... assets:checking ; a comment containing tag1:, tag2: some value ...
Here, Here,
@ -639,70 +640,69 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..." o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting. postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third- For example, the following transaction has three tags (A, TAG2, third-
tag) and the posting has four (those plus posting-tag): tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2: 1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value ; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag: (a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings. are simple strings.
Directives Directives
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions). some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with here is a table summarising the directives and their effects, with
links to more detailed docs. links to more detailed docs.
direc- end subdi- purpose can affect (as of direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06) tive directive rec- 2018/06)
tives tives
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
account any document account names, all entries in all
text declare account types & dis- files, before or
account any document account names, all entries in all
text declare account types & dis- files, before or
play order after play order after
alias end rewrite account names following alias end rewrite account names following
aliases inline/included aliases inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
apply end apply prepend a common parent to following apply end apply prepend a common parent to following
account account account names inline/included account account account names inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
comment end com- ignore part of journal following comment end com- ignore part of journal following
ment inline/included ment inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
commod- format declare a commodity and its number notation: commod- format declare a commodity and its number notation:
ity number notation & display following entries ity 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
@ -713,7 +713,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
@ -723,9 +723,9 @@ FILE FORMAT
subdirec- optional indented directive line immediately following a par- subdirec- optional indented directive line immediately following a par-
tive ent directive tive ent directive
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
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)
@ -733,59 +733,60 @@ 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
12/15 ; equivalent to 2009/12/15 12/15 ; equivalent to 2009/12/15
expenses 1 expenses 1
assets assets
Y2010 ; change default year to 2010 Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected 2009/1/30 ; specifies the year, not affected
expenses 1 expenses 1
assets assets
1/31 ; equivalent to 2010/1/31 1/31 ; equivalent to 2010/1/31
expenses 1 expenses 1
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, and their display format.
on a single line, like this:
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -807,13 +808,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 Declaring commodites may be useful as documentation, but currently we
display format for amounts in the commodity. Normally the display for- do not enforce that only declared commodities may be used. This direc-
mat is inferred from journal entries, but this can be unpredictable; tive is mainly useful for customising the preferred display format for
declaring it with a commodity directive overrides this and removes a commodity.
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by Normally the display format is inferred from journal entries, but this
0 or more decimal digits). can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity. Towards this end, amounts in commodity
directives must always be written with a decimal point (a period or
comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
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
@ -827,7 +834,7 @@ FILE FORMAT
D $1,000.00 D $1,000.00
1/1 1/1
a 5 ; <- commodity-less amount, becomes $1 a 5 ; <- commodity-less amount, becomes $1
b b
As with the commodity directive, the amount must always be written with As with the commodity directive, the amount must always be written with
@ -947,11 +954,11 @@ FILE FORMAT
names mentioned above, you might need to help the reports a bit. Eg: names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
account liabilities ; type:E account liabilities ; type:E
; we need to ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities ; otherwise balancesheet would still show "liabilities" under Liabilities
account - ; type:L account - ; type:L
Account display order Account display order
Account directives also set the order in which accounts are displayed, Account directives also set the order in which accounts are displayed,
@ -1047,17 +1054,38 @@ FILE FORMAT
line, to end of option argument), so it can contain trailing white- line, to end of option argument), so it can contain trailing white-
space. space.
Multiple aliases Combining aliases
You can define as many aliases as you like using directives or command- You can define as many aliases as you like, using journal directives
line options. Aliases are recursive - each alias sees the result of and/or command line options.
applying previous ones. (This is different from Ledger, where aliases
are non-recursive by default). Aliases are applied in the following
order:
1. alias directives, most recently seen first (recent directives take Recursive aliases - where an account name is rewritten by one alias,
precedence over earlier ones; directives not yet seen are ignored) then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases.
2. alias options, in the order they appear on the command line In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. alias directives preceding the journal entry, most recently parsed
first (ie, reading upward from the journal entry, bottom to top)
2. --alias options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
o the nearest alias declaration before/above the entry is applied first
o the next alias before/above that will be be applied next, and so on
o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order.
In case of trouble, adding --debug=6 to the command line will show
which aliases are being applied when.
end aliases end aliases
You can clear (forget) all currently defined aliases with the end You can clear (forget) all currently defined aliases with the end
@ -1141,8 +1169,18 @@ FILE FORMAT
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:
the generating period expression.
o generated-transaction:~ PERIODICEXPR - shows that this was generated
by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
o _generated-transaction:~ PERIODICEXPR
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
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
@ -1189,16 +1227,16 @@ FILE FORMAT
Auto postings / transaction modifiers Auto postings / transaction modifiers
Transaction modifier rules describe changes to be applied automatically Transaction modifier rules, AKA auto posting rules, describe changes to
to certain matched transactions. Currently just one kind of change is be applied automatically to certain matched transactions. Currently
possible - adding extra postings, which we call "automated postings" or just one kind of change is possible - adding extra postings, which we
just "auto postings". These rules become active when you use the call "automated postings" or just "auto postings". These rules become
--auto flag. active when you use the --auto flag.
A transaction modifier, AKA auto posting rule, looks much like a normal A transaction modifier rule looks much like a normal transaction except
transaction except the first line is an equals sign followed by a query the first line is an equals sign followed by a query that matches cer-
that matches certain postings (mnemonic: = suggests matching). And tain postings (mnemonic: = suggests matching). And each "posting" is
each "posting" is actually a posting-generating rule: actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCT AMT
@ -1257,6 +1295,11 @@ FILE FORMAT
assets:checking:gifts -$20 assets:checking:gifts -$20
assets:checking $20 assets:checking $20
Auto postings and dates
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also
be used in the generated posting.
Auto postings and transaction balancing / inferred amounts / balance asser- Auto postings and transaction balancing / inferred amounts / balance asser-
tions tions
Currently, transaction modifiers are applied / auto postings are added: Currently, transaction modifiers are applied / auto postings are added:
@ -1270,19 +1313,37 @@ FILE FORMAT
after auto postings are added. This changed in hledger 1.12+; see #893 after auto postings are added. This changed in hledger 1.12+; see #893
for background. for background.
Auto posting tags
Postings added by transaction modifiers will have some extra tags:
o generated-posting:= QUERY - shows this was generated by an auto post-
ing rule, and the query
o _generated-posting:= QUERY - a hidden tag, which does not appear in
hledger's output. This can be used to match postings generated "just
now", rather than generated in the past and saved to the journal.
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
o modified: - this transaction was modified
o _modified: - a hidden tag not appearing in the comment; this transac-
tion was modified "just now".
EDITOR SUPPORT EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa- others. See the [[Cookbook]] at hledger.org for the latest informa-
tion. tion.
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -1296,7 +1357,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)
@ -1304,4 +1365,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger_journal(5) hledger 1.15 August 2019 hledger_journal(5)

2
hledger-lib/hledger_timeclock.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger_timeclock" "5" "August 2019" "hledger 1.15" "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.14.99 hledger_timeclock(5) hledger 1.15
************************************ *********************************
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

@ -78,4 +78,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger_timeclock(5) hledger 1.15 August 2019 hledger_timeclock(5)

2
hledger-lib/hledger_timedot.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger_timedot" "5" "August 2019" "hledger 1.15" "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.14.99 hledger_timedot(5) hledger 1.15
********************************** *******************************
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
@ -111,7 +111,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT814 Node: FILE FORMAT808
Ref: #file-format915 Ref: #file-format909
 
End Tag Table End Tag Table

2
hledger-lib/hledger_timedot.txt
View File

@ -124,4 +124,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger_timedot(5) hledger 1.15 August 2019 hledger_timedot(5)

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

@ -1,5 +1,5 @@
.TH "hledger-ui" "1" "March 2019" "hledger-ui 1.14.99" "hledger User Manuals" .TH "hledger-ui" "1" "August 2019" "hledger-ui 1.15" "hledger User Manuals"
@ -118,7 +118,7 @@ multiperiod/multicolumn report by year
.TP .TP
.B \f[C]-p --period=PERIODEXP\f[R] .B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above) period expressions syntax
.TP .TP
.B \f[C]--date2\f[R] .B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects) match the secondary date instead (see command help for other effects)
@ -426,6 +426,9 @@ Symptoms include: unresponsive UI, periodic resetting of the cursor
position, momentary display of parse errors, high CPU usage eventually position, momentary display of parse errors, high CPU usage eventually
subsiding, and possibly a small but persistent build-up of CPU usage subsiding, and possibly a small but persistent build-up of CPU usage
until the program is restarted. until the program is restarted.
.PP
Also, if you are viewing files mounted from another machine,
\f[C]--watch\f[R] requires that both machine clocks are roughly in step.
.SH "REPORTING BUGS" .SH "REPORTING BUGS"

34
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.14.99 hledger-ui(1) hledger-ui 1.15
******************************** *****************************
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
@ -117,7 +117,7 @@ the data.
'-p --period=PERIODEXP' '-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
'--date2' '--date2'
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -399,19 +399,19 @@ to cancel the reload attempt.)
 
Tag Table: Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1107 Node: OPTIONS1101
Ref: #options1204 Ref: #options1198
Node: KEYS4623 Node: KEYS4589
Ref: #keys4718 Ref: #keys4684
Node: SCREENS7974 Node: SCREENS7940
Ref: #screens8059 Ref: #screens8025
Node: Accounts screen8149 Node: Accounts screen8115
Ref: #accounts-screen8277 Ref: #accounts-screen8243
Node: Register screen10493 Node: Register screen10459
Ref: #register-screen10648 Ref: #register-screen10614
Node: Transaction screen12644 Node: Transaction screen12610
Ref: #transaction-screen12802 Ref: #transaction-screen12768
Node: Error screen13672 Node: Error screen13638
Ref: #error-screen13794 Ref: #error-screen13760
 
End Tag Table End Tag Table

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

@ -114,7 +114,7 @@ OPTIONS
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
--date2 --date2
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -381,10 +381,13 @@ BUGS
siding, and possibly a small but persistent build-up of CPU usage until siding, and possibly a small but persistent build-up of CPU usage until
the program is restarted. the program is restarted.
Also, if you are viewing files mounted from another machine, --watch
requires that both machine clocks are roughly in step.
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -398,7 +401,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)
@ -406,4 +409,4 @@ SEE ALSO
hledger-ui 1.14.99 March 2019 hledger-ui(1) hledger-ui 1.15 August 2019 hledger-ui(1)

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

@ -1,5 +1,5 @@
.TH "hledger-web" "1" "March 2019" "hledger-web 1.14.99" "hledger User Manuals" .TH "hledger-web" "1" "August 2019" "hledger-web 1.15" "hledger User Manuals"
@ -54,6 +54,10 @@ Note: if invoking hledger-web as a hledger subcommand, write
.B \f[C]--serve\f[R] .B \f[C]--serve\f[R]
serve and log requests, don\[aq]t browse or auto-exit serve and log requests, don\[aq]t browse or auto-exit
.TP .TP
.B \f[C]--serve-api\f[R]
like --serve, but serve only the JSON web API, without the server-side
web UI
.TP
.B \f[C]--host=IPADDR\f[R] .B \f[C]--host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1) listen on this IP address (default: 127.0.0.1)
.TP .TP
@ -128,7 +132,7 @@ multiperiod/multicolumn report by year
.TP .TP
.B \f[C]-p --period=PERIODEXP\f[R] .B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above) period expressions syntax
.TP .TP
.B \f[C]--date2\f[R] .B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects) match the secondary date instead (see command help for other effects)
@ -194,6 +198,8 @@ open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it). (no requests and no browser windows viewing it).
With \f[C]--serve\f[R], it just runs the web app without exiting, and With \f[C]--serve\f[R], it just runs the web app without exiting, and
logs requests to the console. logs requests to the console.
With \f[C]--serve-api\f[R], only the JSON web api (see below) is served,
with the usual HTML server-side web UI disabled.
.PP .PP
By default the server listens on IP address 127.0.0.1, accessible only By default the server listens on IP address 127.0.0.1, accessible only
to local requests. to local requests.
@ -276,6 +282,9 @@ edit it directly, outside of hledger-web), and it will show the new data
when you reload the page or navigate to a new page. when you reload the page or navigate to a new page.
If a change makes a file unparseable, hledger-web will display an error If a change makes a file unparseable, hledger-web will display an error
message until the file has been fixed. message until the file has been fixed.
.PP
(Note: if you are viewing files mounted from another machine, make sure
that both machine clocks are roughly in step.)
.SH JSON API .SH JSON API
.PP .PP
In addition to the web UI, hledger-web provides some API routes that In addition to the web UI, hledger-web provides some API routes that
@ -329,6 +338,10 @@ And here\[aq]s how to test adding that with curl:
$ curl -s http://127.0.0.1:5000/add -X PUT -H \[aq]Content-Type: application/json\[aq] --data-binary \[at]txn.pretty.json; echo $ curl -s http://127.0.0.1:5000/add -X PUT -H \[aq]Content-Type: application/json\[aq] --data-binary \[at]txn.pretty.json; echo
\f[R] \f[R]
.fi .fi
.PP
By default, both the server-side HTML UI and the JSON API are served.
Running with \f[C]--serve-api\f[R] disables the former, useful if you
only want to serve the API.
.SH ENVIRONMENT .SH ENVIRONMENT
.PP .PP
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with \f[B]LEDGER_FILE\f[R] The journal file path when not specified with

41
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.14.99 hledger-web(1) hledger-web 1.15
********************************** *******************************
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
@ -50,6 +50,10 @@ before options, as shown in the synopsis above.
'--serve' '--serve'
serve and log requests, don't browse or auto-exit serve and log requests, don't browse or auto-exit
'--serve-api'
like -serve, but serve only the JSON web API, without the
server-side web UI
'--host=IPADDR' '--host=IPADDR'
listen on this IP address (default: 127.0.0.1) listen on this IP address (default: 127.0.0.1)
@ -127,7 +131,7 @@ before options, as shown in the synopsis above.
'-p --period=PERIODEXP' '-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
'--date2' '--date2'
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -193,7 +197,9 @@ also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console. app without exiting, and logs requests to the console. With
'--serve-api', only the JSON web api (see below) is served, with the
usual HTML server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host only to local requests. You can use '--host' to change this, eg '--host
@ -282,6 +288,9 @@ when you reload the page or navigate to a new page. If a change makes a
file unparseable, hledger-web will display an error message until the file unparseable, hledger-web will display an error message until the
file has been fixed. file has been fixed.
(Note: if you are viewing files mounted from another machine, make
sure that both machine clocks are roughly in step.)
 
File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top
@ -325,18 +334,22 @@ $ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readabl
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served.
Running with '--serve-api' disables the former, useful if you only want
to serve the API.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS1361 Node: OPTIONS1355
Ref: #options1466 Ref: #options1460
Node: PERMISSIONS6556 Node: PERMISSIONS6739
Ref: #permissions6695 Ref: #permissions6878
Node: EDITING UPLOADING DOWNLOADING7907 Node: EDITING UPLOADING DOWNLOADING8090
Ref: #editing-uploading-downloading8088 Ref: #editing-uploading-downloading8271
Node: RELOADING8922 Node: RELOADING9105
Ref: #reloading9056 Ref: #reloading9239
Node: JSON API9366 Node: JSON API9672
Ref: #json-api9460 Ref: #json-api9766
 
End Tag Table End Tag Table

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

@ -46,6 +46,10 @@ OPTIONS
--serve --serve
serve and log requests, don't browse or auto-exit serve and log requests, don't browse or auto-exit
--serve-api
like --serve, but serve only the JSON web API, without the
server-side web UI
--host=IPADDR --host=IPADDR
listen on this IP address (default: 127.0.0.1) listen on this IP address (default: 127.0.0.1)
@ -53,22 +57,22 @@ OPTIONS
listen on this TCP port (default: 5000) listen on this TCP port (default: 5000)
--base-url=URL --base-url=URL
set the base url (default: http://IPADDR:PORT). You would set the base url (default: http://IPADDR:PORT). You would
change this when sharing over the network, or integrating within change this when sharing over the network, or integrating within
a larger website. a larger website.
--file-url=URL --file-url=URL
set the static files url (default: BASEURL/static). hledger-web set the static files url (default: BASEURL/static). hledger-web
normally serves static files itself, but if you wanted to serve normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url them from another server for efficiency, you would set the url
with this. with this.
--capabilities=CAP[,CAP..] --capabilities=CAP[,CAP..]
enable the view, add, and/or manage capabilities (default: enable the view, add, and/or manage capabilities (default:
view,add) view,add)
--capabilities-header=HTTPHEADER --capabilities-header=HTTPHEADER
read capabilities to enable from a HTTP header, like X-Sand- read capabilities to enable from a HTTP header, like X-Sand-
storm-Permissions (default: disabled) storm-Permissions (default: disabled)
hledger input options: hledger input options:
@ -78,7 +82,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal) $LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE --rules-file=RULESFILE
Conversion rules file to use when reading CSV (default: Conversion rules file to use when reading CSV (default:
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
@ -119,11 +123,11 @@ OPTIONS
multiperiod/multicolumn report by year multiperiod/multicolumn report by year
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
--date2 --date2
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
effects) effects)
-U --unmarked -U --unmarked
@ -142,21 +146,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep hide/aggregate accounts or postings more than NUM levels deep
-E --empty -E --empty
show items with zero amount, normally hidden (and vice-versa in show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost at transaction time (using the convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
-V --value -V --value
convert amounts to their market value on the report end date convert amounts to their market value on the report end date
(using the most recent applicable market price, if any) (using the most recent applicable market price, if any)
--auto apply automated posting rules to modify transactions. --auto apply automated posting rules to modify transactions.
--forecast --forecast
apply periodic transaction rules to generate future transac- apply periodic transaction rules to generate future transac-
tions, to 6 months from now or report end date. tions, to 6 months from now or report end date.
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
@ -176,39 +180,41 @@ OPTIONS
show debug output (levels 1-9, default: 1) show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this, contain one command line option/argument per line. (To prevent this,
insert a -- argument before.) insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win- app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML
server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host to local requests. You can use --host to change this, eg --host
0.0.0.0 to listen on all configured addresses. 0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances. running multiple hledger-web instances.
You can use --base-url to change the protocol, hostname, port and path You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80). configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites. for better caching or cookie-less serving on high performance websites.
PERMISSIONS PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data. journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local it listens on 127.0.0.1, accessible to all users on the local
machine. machine.
o putting it behind an authenticating proxy, using eg apache or nginx o putting it behind an authenticating proxy, using eg apache or nginx
@ -218,47 +224,50 @@ PERMISSIONS
You can restrict what the users who reach it can do, by You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is one or more of the following capabilities. The default value is
view,add: view,add:
o view - allows viewing the journal file and all included files o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or o manage - allows editing, uploading or downloading the main or
included files included files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default. with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will "spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it let you edit, upload, or download the journal file or any files it
includes. includes.
Note, unlike any other hledger command, in this mode you (or any visi- Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files. tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur- full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr). yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This (eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.) needs re-testing.)
RELOADING RELOADING
hledger-web detects changes made to the files by other means (eg if you hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message makes a file unparseable, hledger-web will display an error message
until the file has been fixed. until the file has been fixed.
(Note: if you are viewing files mounted from another machine, make sure
that both machine clocks are roughly in step.)
JSON API JSON API
In addition to the web UI, hledger-web provides some API routes that In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. Currently these are same ones serve JSON in response to GET requests. Currently these are same ones
@ -297,6 +306,10 @@ JSON API
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
to serve the API.
ENVIRONMENT ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default: LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
@ -345,4 +358,4 @@ SEE ALSO
hledger-web 1.14.99 March 2019 hledger-web(1) hledger-web 1.15 August 2019 hledger-web(1)

1
hledger/Hledger/Cli/Commands/Stats.txt
View File

@ -20,6 +20,7 @@ Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 5 Payees/descriptions : 5
Accounts : 8 (depth 3) Accounts : 8 (depth 3)
Commodities : 1 ($) Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.

218
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "hledger" "1" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger" "1" "August 2019" "hledger 1.15" "hledger User Manuals"
@ -218,7 +218,7 @@ multiperiod/multicolumn report by year
.TP .TP
.B \f[C]-p --period=PERIODEXP\f[R] .B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above) period expressions syntax
.TP .TP
.B \f[C]--date2\f[R] .B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects) match the secondary date instead (see command help for other effects)
@ -455,7 +455,7 @@ turn:
.PP .PP
.TS .TS
tab(@); tab(@);
lw(10.3n) lw(33.5n) lw(26.2n). lw(7.6n) lw(31.2n) lw(31.2n).
T{ T{
Reader: Reader:
T}@T{ T}@T{
@ -622,9 +622,20 @@ You can specify a start and/or end date using \f[C]-b/--begin\f[R],
\f[C]-e/--end\f[R], \f[C]-p/--period\f[R] or a \f[C]date:\f[R] query \f[C]-e/--end\f[R], \f[C]-p/--period\f[R] or a \f[C]date:\f[R] query
(described below). (described below).
All of these accept the smart date syntax. All of these accept the smart date syntax.
One important thing to be aware of when specifying end dates: as in .PP
Ledger, end dates are exclusive, so you need to write the date Some notes:
.IP \[bu] 2
As in Ledger, end dates are exclusive, so you need to write the date
\f[I]after\f[R] the last day you want to include. \f[I]after\f[R] the last day you want to include.
.IP \[bu] 2
As noted in reporting options: among start/end dates specified with
\f[I]options\f[R], the last (i.e.
right-most) option takes precedence.
.IP \[bu] 2
The effective report start and end dates are the intersection of the
start/end dates from options and that from \f[C]date:\f[R] queries.
That is, \f[C]date:2019-01 date:2019 -p\[aq]2000 to 2030\[aq]\f[R]
yields January 2019, the smallest common time span.
.PP .PP
Examples: Examples:
.PP .PP
@ -679,7 +690,7 @@ The basic intervals can be selected with one of \f[C]-D/--daily\f[R],
\f[C]-W/--weekly\f[R], \f[C]-M/--monthly\f[R], \f[C]-Q/--quarterly\f[R], \f[C]-W/--weekly\f[R], \f[C]-M/--monthly\f[R], \f[C]-Q/--quarterly\f[R],
or \f[C]-Y/--yearly\f[R]. or \f[C]-Y/--yearly\f[R].
More complex intervals may be specified with a period expression. More complex intervals may be specified with a period expression.
Report intervals can not be specified with a query, currently. Report intervals can not be specified with a query.
.SS Period expressions .SS Period expressions
.PP .PP
The \f[C]-p/--period\f[R] option accepts period expressions, a shorthand The \f[C]-p/--period\f[R] option accepts period expressions, a shorthand
@ -993,18 +1004,33 @@ $ hledger balance --pivot member acct:.
-2 EUR -2 EUR
\f[R] \f[R]
.fi .fi
.SS Cost .SS Valuation
.SS -B: Cost
.PP .PP
The \f[C]-B/--cost\f[R] flag converts amounts to their cost at The \f[C]-B/--cost\f[R] flag converts amounts to their cost (or selling
transaction time, if they have a transaction price specified. price) at transaction time, if they have a transaction price specified.
.SS Market value This flag is equivalent to \f[C]--value=cost\f[R], described below.
.SS -V: Market value
.PP .PP
The \f[C]-V/--market\f[R] flag converts reported amounts to their market The \f[C]-V/--market\f[R] flag converts reported amounts to their market
value in another commodity. value in a default valuation commodity, using the historical market
It uses the commodity referenced in the latest market price (P prices in effect on a default valuation date.
directive) dated on or before the valuation date. .PP
The default valuation date is today. For single period reports, the valuation date is today.
For example: For multiperiod reports, it is the last day of each subperiod.
.PP
The valuation commodity will be the one referenced in the latest
applicable market price dated on or before the valuation date.
If most of your P declarations lead to a single home currency, this will
usually be what you want.
.PP
Unlike the similar flag in Ledger, it does not infer market prices from
transaction prices.
In hledger, -B uses transaction prices, -V and -X use market prices.
.PP
It is equivalent to \f[C]--value=now\f[R] or \f[C]--value=end\f[R].
.PP
Here\[aq]s a quick example:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1048,52 +1074,79 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
\f[R] \f[R]
.fi .fi
.SS -X: Market value in specified commodity
.PP .PP
Ledger users: Ledger\[aq]s -V also infers market prices from journal The \f[C]-X/--exchange\f[R] option is like \f[C]-V/--market\f[R] except
entries, but we don\[aq]t do that. it takes a commodity symbol argument, so that you can select a different
hledger\[aq]s -V uses only market prices declared explicitly, with P target commodity.
directives. It is similar to the same option in Ledger, with the same caveat
(Mnemonic: -B/--cost uses transaction prices, -V/--market uses market mentioned for \f[C]-V\f[R]/\f[C]--value\f[R] above.
prices.) It is equivalent to \f[C]--value=now,COMM\f[R] or
.SS More control over valuation \f[C]--value=end,COMM\f[R]; for more details, read on.
.SS --value
.PP .PP
\f[I](experimental, added 201905)\f[R] \f[I](experimental, added 201905)\f[R]
.PP .PP
You can control valuation more precisely with the \f[C]--value\f[R] \f[C]-B\f[R], \f[C]-V\f[R] and \f[C]-X\f[R] are special cases of the
option. more general \f[C]--value\f[R] option:
.IP .IP
.nf .nf
\f[C] \f[C]
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD --value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
\f[R] \f[R]
.fi .fi
.SS Valuation type
.PP .PP
The argument is one of the keywords shown, or their first letter, or a TYPE is one of these keywords, or their first letter, or a date (which
custom date. must be 8 digits with \f[C]-\f[R] or \f[C]/\f[R] or \f[C].\f[R]
The precise effect of the keywords is command-specific, but here is separators):
their general meaning:
.TP .TP
.B \f[C]--value=cost\f[R] (or \f[C]c\f[R]) .B \f[C]--value=cost\f[R]
Convert amounts to cost, using the prices recorded in transactions. Convert amounts to cost, using the prices recorded in transactions.
\f[C]-B\f[R]/\f[C]--cost\f[R] does this. \f[C]-B\f[R]/\f[C]--cost\f[R] is equivalent to this.
.TP .TP
.B \f[C]--value=end\f[R] (or \f[C]e\f[R]) .B \f[C]--value=end\f[R]
Convert amounts to their value in default valuation commodity using Convert amounts to their value in default valuation commodity using
market prices on the last day of the report period (or of each subperiod market prices on the last day of the report period (or of each subperiod
in a multiperiod report). in a multiperiod report).
When no report period is specified, uses the journal\[aq]s last When no report period is specified, uses the journal\[aq]s last
transaction date. transaction date.
.TP .TP
.B \f[C]--value=now\f[R] (or \f[C]n\f[R]) .B \f[C]--value=now\f[R]
Convert amounts to their value in default valuation commodity using Convert amounts to their value in default valuation commodity using
current market prices (as of when report is generated). current market prices (as of when report is generated).
\f[C]-V\f[R]/\f[C]--market\f[R] does this. \f[C]-V\f[R]/\f[C]--market\f[R] is equivalent to this.
.TP .TP
.B \f[C]--value=YYYY-MM-DD\f[R] .B \f[C]--value=YYYY-MM-DD\f[R]
Convert amounts to their value in default valuation commodity using Convert amounts to their value in default valuation commodity using
market prices on the given date (which must be 8 digits with \f[C]-\f[R] market prices on this date.
or \f[C]/\f[R] or \f[C].\f[R] separators).
Eg \f[C]--value=2019-04-25\f[R]. Eg \f[C]--value=2019-04-25\f[R].
.SS Valuation commodity
.PP
The default valuation commodity is the commodity mentioned in the most
recent applicable market price declaration.
When all your price declarations lead to a single home currency, this
will usually do what you want.
.PP
To select a different valuation commodity: write the commodity symbol
after the valuation type, separated by a comma (eg:
\f[B]\f[CB]--value=now,EUR\f[B]\f[R]).
This will use, in this preferred order:
.IP \[bu] 2
declared prices (from source commodity to valuation commodity)
.IP \[bu] 2
reverse prices (declared prices from valuation to source commodity,
inverted)
.IP \[bu] 2
indirect prices (prices calculated from the shortest chain of declared
or reverse prices from source to valuation commodity).
.SS --value examples
.PP .PP
Here are the effects of \f[C]--value\f[R] as seen with \f[C]print\f[R]: Here are the effects of \f[C]--value\f[R] as seen with \f[C]print\f[R]:
.IP .IP
@ -1192,6 +1245,56 @@ $ hledger -f- print --value=2000-01-15
(a) 1 B (a) 1 B
\f[R] \f[R]
.fi .fi
.PP
You may need to explicitly set a commodity\[aq]s display style, when
reverse prices are used.
Eg this output might be surprising:
.IP
.nf
\f[C]
P 2000-01-01 A 2B
2000-01-01
a 1B
b
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print -x -X A
2000/01/01
a 0
b 0
\f[R]
.fi
.PP
Explanation: because there\[aq]s no amount or commodity directive
specifying a display style for A, 0.5A gets the default style, which
shows no decimal digits.
Because the displayed amount looks like zero, the commodity symbol and
minus sign are not displayed either.
Adding a commodity directive sets a more useful display style for A:
.IP
.nf
\f[C]
P 2000-01-01 A 2B
commodity 0.00A
2000-01-01
a 1B
b
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print -X A
2000/01/01
a 0.50A
b -0.50A
\f[R]
.fi
.SS Effect of --value on reports .SS Effect of --value on reports
.PP .PP
Below is how \f[C]--value\f[R] affects each of hledger\[aq]s reports, Below is how \f[C]--value\f[R] affects each of hledger\[aq]s reports,
@ -1333,38 +1436,7 @@ T}@T{
market value at DATE of sum/average of postings market value at DATE of sum/average of postings
T} T}
.TE .TE
.SS Some useful value reports .SS Combining -B, -V, -X, --value
.PP
Here are some probably useful reports - please send suggestions if you
find out more:
.PP
.TS
tab(@);
lw(15.9n) lw(27.6n) lw(26.5n).
T{
Command:
T}@T{
Description of report:
T}@T{
Could answer:
T}
_
T{
\f[C]hledger bs -M --value=p\f[R]
T}@T{
Monthly historical value of assets/liabilities
T}@T{
How are my investments performing ?
T}
T{
\f[C]hledger is -M --value=t\f[R]
T}@T{
Monthly contemporaneous value of revenues/expenses
T}@T{
How much foreign currency have I been spending ?
T}
.TE
.SS Combining -B, -V, --value
.PP .PP
The rightmost of these flags wins. The rightmost of these flags wins.
.SS Output destination .SS Output destination
@ -1708,6 +1780,10 @@ Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $ Date [2015/05/22]: <CTRL-D> $
\f[R] \f[R]
.fi .fi
.PP
On Microsoft Windows, the add command makes sure that no part of the
file path ends with a period, as it can cause data loss on that platform
(cf #1056).
.SS balance .SS balance
.PP .PP
balance, bal, b balance, bal, b
@ -2497,6 +2573,10 @@ assertions will depend on these flags.
Likewise, if you run this command with --auto, the balance assertions Likewise, if you run this command with --auto, the balance assertions
will probably always require --auto. will probably always require --auto.
.PP .PP
When account balances have cost information (transaction prices), the
closing/opening transactions will preserve it, so that eg balance -B
reports will not be affected.
.PP
Examples: Examples:
.PP .PP
Carrying asset/liability balances into a new file for 2019, all from Carrying asset/liability balances into a new file for 2019, all from
@ -3256,6 +3336,7 @@ Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 5 Payees/descriptions : 5
Accounts : 8 (depth 3) Accounts : 8 (depth 3)
Commodities : 1 ($) Commodities : 1 ($)
Market prices : 12 ($)
\f[R] \f[R]
.fi .fi
.PP .PP
@ -3272,6 +3353,7 @@ With a TAGREGEX argument, only tag names matching the regular expression
(case insensitive) are shown. (case insensitive) are shown.
With QUERY arguments, only transactions matching the query are With QUERY arguments, only transactions matching the query are
considered. considered.
With --values flag, the tags\[aq] unique values are listed instead.
.SS test .SS test
.PP .PP
test test

611
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.14.99 hledger(1) hledger 1.15
************************** ***********************
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
@ -130,9 +130,7 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Period expressions:: * Period expressions::
* Depth limiting:: * Depth limiting::
* Pivoting:: * Pivoting::
* Cost:: * Valuation::
* Market value::
* Combining -B -V --value::
* Output destination:: * Output destination::
* Output format:: * Output format::
* Regular expressions:: * Regular expressions::
@ -209,7 +207,7 @@ by most hledger commands, run 'hledger -h'.
'-p --period=PERIODEXP' '-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
'--date2' '--date2'
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -455,16 +453,16 @@ be one of several other formats, listed below. hledger detects the
format automatically based on the file extension, or if that is not format automatically based on the file extension, or if that is not
recognised, by trying each built-in "reader" in turn: recognised, by trying each built-in "reader" in turn:
Reader: Reads: Used for file extensions: Reader: Reads: Used for file extensions:
---------------------------------------------------------------------------- ---------------------------------------------------------------------------
'journal' hledger's journal format, also '.journal' '.j' 'journal'hledger's journal format, also '.journal' '.j' '.hledger'
some Ledger journals '.hledger' '.ledger' some Ledger journals '.ledger'
'timeclock' timeclock files (precise time '.timeclock' 'timeclock'timeclock files (precise time '.timeclock'
logging) logging)
'timedot' timedot files (approximate time '.timedot' 'timedot'timedot files (approximate '.timedot'
logging) time logging)
'csv' comma-separated values (data '.csv' 'csv' comma-separated values (data '.csv'
interchange) interchange)
If needed (eg to ensure correct error messages when a file has the If needed (eg to ensure correct error messages when a file has the
"wrong" extension), you can force a specific reader/format by prepending "wrong" extension), you can force a specific reader/format by prepending
@ -530,9 +528,18 @@ the journal.
Often you will want to see a shorter time span, such as the current Often you will want to see a shorter time span, such as the current
month. You can specify a start and/or end date using '-b/--begin', month. You can specify a start and/or end date using '-b/--begin',
'-e/--end', '-p/--period' or a 'date:' query (described below). All of '-e/--end', '-p/--period' or a 'date:' query (described below). All of
these accept the smart date syntax. One important thing to be aware of these accept the smart date syntax.
when specifying end dates: as in Ledger, end dates are exclusive, so you
need to write the date _after_ the last day you want to include. Some notes:
* As in Ledger, end dates are exclusive, so you need to write the
date _after_ the last day you want to include.
* As noted in reporting options: among start/end dates specified with
_options_, the last (i.e. right-most) option takes precedence.
* The effective report start and end dates are the intersection of
the start/end dates from options and that from 'date:' queries.
That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January
2019, the smallest common time span.
Examples: Examples:
@ -556,7 +563,7 @@ balance and activity will divide their reports into multiple subperiods.
The basic intervals can be selected with one of '-D/--daily', The basic intervals can be selected with one of '-D/--daily',
'-W/--weekly', '-M/--monthly', '-Q/--quarterly', or '-Y/--yearly'. More '-W/--weekly', '-M/--monthly', '-Q/--quarterly', or '-Y/--yearly'. More
complex intervals may be specified with a period expression. Report complex intervals may be specified with a period expression. Report
intervals can not be specified with a query, currently. intervals can not be specified with a query.
 
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
@ -679,7 +686,7 @@ less detail. This flag has the same effect as a 'depth:' query argument
(so '-2', '--depth=2' or 'depth:2' are basically equivalent). (so '-2', '--depth=2' or 'depth:2' are basically equivalent).
 
File: hledger.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS File: hledger.info, Node: Pivoting, Next: Valuation, Prev: Depth limiting, Up: OPTIONS
2.14 Pivoting 2.14 Pivoting
============= =============
@ -736,24 +743,54 @@ $ hledger balance --pivot member acct:.
-2 EUR -2 EUR
 
File: hledger.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS File: hledger.info, Node: Valuation, Next: Output destination, Prev: Pivoting, Up: OPTIONS
2.15 Cost 2.15 Valuation
========= ==============
The '-B/--cost' flag converts amounts to their cost at transaction time, * Menu:
if they have a transaction price specified.
* -B Cost::
* -V Market value::
* -X Market value in specified commodity::
* --value::
* Combining -B -V -X --value::
 
File: hledger.info, Node: Market value, Next: Combining -B -V --value, Prev: Cost, Up: OPTIONS File: hledger.info, Node: -B Cost, Next: -V Market value, Up: Valuation
2.16 Market value 2.15.1 -B: Cost
================= ---------------
The '-B/--cost' flag converts amounts to their cost (or selling price)
at transaction time, if they have a transaction price specified. This
flag is equivalent to '--value=cost', described below.

File: hledger.info, Node: -V Market value, Next: -X Market value in specified commodity, Prev: -B Cost, Up: Valuation
2.15.2 -V: Market value
-----------------------
The '-V/--market' flag converts reported amounts to their market value The '-V/--market' flag converts reported amounts to their market value
in another commodity. It uses the commodity referenced in the latest in a default valuation commodity, using the historical market prices in
market price (P directive) dated on or before the valuation date. The effect on a default valuation date.
default valuation date is today. For example:
For single period reports, the valuation date is today. For
multiperiod reports, it is the last day of each subperiod.
The valuation commodity will be the one referenced in the latest
applicable market price dated on or before the valuation date. If most
of your P declarations lead to a single home currency, this will usually
be what you want.
Unlike the similar flag in Ledger, it does not infer market prices
from transaction prices. In hledger, -B uses transaction prices, -V and
-X use market prices.
It is equivalent to '--value=now' or '--value=end'.
Here's a quick example:
# one euro is worth this many dollars from nov 1 # one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10 P 2016/11/01 € $1.10
@ -782,55 +819,101 @@ specified, defaults to today)
$ hledger -f t.j bal -N euros -V $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
Ledger users: Ledger's -V also infers market prices from journal 
entries, but we don't do that. hledger's -V uses only market prices File: hledger.info, Node: -X Market value in specified commodity, Next: --value, Prev: -V Market value, Up: Valuation
declared explicitly, with P directives. (Mnemonic: -B/-cost uses
transaction prices, -V/-market uses market prices.)
* Menu: 2.15.3 -X: Market value in specified commodity
----------------------------------------------
* More control over valuation:: The '-X/--exchange' option is like '-V/--market' except it takes a
* Effect of --value on reports:: commodity symbol argument, so that you can select a different target
* Some useful value reports:: commodity. It is similar to the same option in Ledger, with the same
caveat mentioned for '-V'/'--value' above. It is equivalent to
'--value=now,COMM' or '--value=end,COMM'; for more details, read on.
 
File: hledger.info, Node: More control over valuation, Next: Effect of --value on reports, Up: Market value File: hledger.info, Node: --value, Next: Combining -B -V -X --value, Prev: -X Market value in specified commodity, Up: Valuation
2.16.1 More control over valuation 2.15.4 -value
---------------------------------- -------------
_(experimental, added 201905)_ _(experimental, added 201905)_
You can control valuation more precisely with the '--value' option. '-B', '-V' and '-X' are special cases of the more general '--value'
option:
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD --value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
The argument is one of the keywords shown, or their first letter, or * Menu:
a custom date. The precise effect of the keywords is command-specific,
but here is their general meaning:
'--value=cost' (or 'c') * Valuation type::
* Valuation commodity::
* --value examples::
* Effect of --value on reports::

File: hledger.info, Node: Valuation type, Next: Valuation commodity, Up: --value
2.15.4.1 Valuation type
.......................
TYPE is one of these keywords, or their first letter, or a date (which
must be 8 digits with '-' or '/' or '.' separators):
'--value=cost'
Convert amounts to cost, using the prices recorded in transactions. Convert amounts to cost, using the prices recorded in transactions.
'-B'/'--cost' does this. '-B'/'--cost' is equivalent to this.
'--value=end' (or 'e') '--value=end'
Convert amounts to their value in default valuation commodity using Convert amounts to their value in default valuation commodity using
market prices on the last day of the report period (or of each market prices on the last day of the report period (or of each
subperiod in a multiperiod report). When no report period is subperiod in a multiperiod report). When no report period is
specified, uses the journal's last transaction date. specified, uses the journal's last transaction date.
'--value=now' (or 'n') '--value=now'
Convert amounts to their value in default valuation commodity using Convert amounts to their value in default valuation commodity using
current market prices (as of when report is generated). current market prices (as of when report is generated).
'-V'/'--market' does this. '-V'/'--market' is equivalent to this.
'--value=YYYY-MM-DD' '--value=YYYY-MM-DD'
Convert amounts to their value in default valuation commodity using Convert amounts to their value in default valuation commodity using
market prices on the given date (which must be 8 digits with '-' or market prices on this date. Eg '--value=2019-04-25'.
'/' or '.' separators). Eg '--value=2019-04-25'.
Here are the effects of '--value' as seen with 'print': 
File: hledger.info, Node: Valuation commodity, Next: --value examples, Prev: Valuation type, Up: --value
2.15.4.2 Valuation commodity
............................
The default valuation commodity is the commodity mentioned in the most
recent applicable market price declaration. When all your price
declarations lead to a single home currency, this will usually do what
you want.
To select a different valuation commodity: write the commodity symbol
after the valuation type, separated by a comma (eg:
*'--value=now,EUR'*). This will use, in this preferred order:
* declared prices (from source commodity to valuation commodity)
* reverse prices (declared prices from valuation to source commodity,
inverted)
* indirect prices (prices calculated from the shortest chain of
declared or reverse prices from source to valuation commodity).

File: hledger.info, Node: --value examples, Next: Effect of --value on reports, Prev: Valuation commodity, Up: --value
2.15.4.3 -value examples
........................
Here are the effects of '--value' as seen with 'print':
P 2000-01-01 A 1 B P 2000-01-01 A 1 B
P 2000-02-01 A 2 B P 2000-02-01 A 2 B
@ -905,11 +988,43 @@ $ hledger -f- print --value=2000-01-15
2000/03/01 2000/03/01
(a) 1 B (a) 1 B
 You may need to explicitly set a commodity's display style, when
File: hledger.info, Node: Effect of --value on reports, Next: Some useful value reports, Prev: More control over valuation, Up: Market value reverse prices are used. Eg this output might be surprising:
2.16.2 Effect of -value on reports P 2000-01-01 A 2B
----------------------------------
2000-01-01
a 1B
b
$ hledger print -x -X A
2000/01/01
a 0
b 0
Explanation: because there's no amount or commodity directive
specifying a display style for A, 0.5A gets the default style, which
shows no decimal digits. Because the displayed amount looks like zero,
the commodity symbol and minus sign are not displayed either. Adding a
commodity directive sets a more useful display style for A:
P 2000-01-01 A 2B
commodity 0.00A
2000-01-01
a 1B
b
$ hledger print -X A
2000/01/01
a 0.50A
b -0.50A

File: hledger.info, Node: Effect of --value on reports, Prev: --value examples, Up: --value
2.15.4.4 Effect of -value on reports
....................................
Below is how '--value' affects each of hledger's reports, currently. Below is how '--value' affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a You're not expected to remember all this, but when troubleshooting a
@ -962,33 +1077,17 @@ totals/averagesof the end of sum/average of DATE of
values postings values postings
 
File: hledger.info, Node: Some useful value reports, Prev: Effect of --value on reports, Up: Market value File: hledger.info, Node: Combining -B -V -X --value, Prev: --value, Up: Valuation
2.16.3 Some useful value reports 2.15.5 Combining -B, -V, -X, -value
-------------------------------- -----------------------------------
Here are some probably useful reports - please send suggestions if you
find out more:
Command: Description of report: Could answer:
---------------------------------------------------------------------------
'hledger bs -M Monthly historical value How are my investments
--value=p' of assets/liabilities performing ?
'hledger is -M Monthly contemporaneous How much foreign currency
--value=t' value of revenues/expenses have I been spending ?

File: hledger.info, Node: Combining -B -V --value, Next: Output destination, Prev: Market value, Up: OPTIONS
2.17 Combining -B, -V, -value
=============================
The rightmost of these flags wins. The rightmost of these flags wins.
 
File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B -V --value, Up: OPTIONS File: hledger.info, Node: Output destination, Next: Output format, Prev: Valuation, Up: OPTIONS
2.18 Output destination 2.16 Output destination
======================= =======================
Some commands (print, register, stats, the balance commands) can write Some commands (print, register, stats, the balance commands) can write
@ -1001,7 +1100,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.19 Output format 2.17 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
@ -1015,7 +1114,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.20 Regular expressions 2.18 Regular expressions
======================== ========================
hledger uses regular expressions in a number of places: hledger uses regular expressions in a number of places:
@ -1328,6 +1427,10 @@ Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit) Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $ Date [2015/05/22]: <CTRL-D> $
On Microsoft Windows, the add command makes sure that no part of the
file path ends with a period, as it can cause data loss on that platform
(cf #1056).
 
File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS
@ -2055,6 +2158,10 @@ balance assertions will depend on these flags. Likewise, if you run
this command with -auto, the balance assertions will probably always this command with -auto, the balance assertions will probably always
require -auto. require -auto.
When account balances have cost information (transaction prices), the
closing/opening transactions will preserve it, so that eg balance -B
reports will not be affected.
Examples: Examples:
Carrying asset/liability balances into a new file for 2019, all from Carrying asset/liability balances into a new file for 2019, all from
@ -2713,6 +2820,7 @@ Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 5 Payees/descriptions : 5
Accounts : 8 (depth 3) Accounts : 8 (depth 3)
Commodities : 1 ($) Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.
@ -2727,7 +2835,8 @@ tags
List all the tag names used in the journal. With a TAGREGEX argument, List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are shown. With QUERY arguments, only transactions matching the query are
considered. considered. With -values flag, the tags' unique values are listed
instead.
 
File: hledger.info, Node: test, Prev: tags, Up: COMMANDS File: hledger.info, Node: test, Prev: tags, Up: COMMANDS
@ -2931,168 +3040,176 @@ hledger-check.hs checks more powerful account balance assertions.
 
Tag Table: Tag Table:
Node: Top68 Node: Top68
Node: EXAMPLES1891 Node: EXAMPLES1885
Ref: #examples1991 Ref: #examples1985
Node: OPTIONS3637 Node: OPTIONS3631
Ref: #options3739 Ref: #options3733
Node: General options4178 Node: General options4132
Ref: #general-options4303 Ref: #general-options4257
Node: Command options6985 Node: Command options6911
Ref: #command-options7136 Ref: #command-options7062
Node: Command arguments7534 Node: Command arguments7460
Ref: #command-arguments7688 Ref: #command-arguments7614
Node: Argument files7809 Node: Argument files7735
Ref: #argument-files7985 Ref: #argument-files7911
Node: Special characters in arguments and queries8251 Node: Special characters in arguments and queries8177
Ref: #special-characters-in-arguments-and-queries8485 Ref: #special-characters-in-arguments-and-queries8411
Node: More escaping8936 Node: More escaping8862
Ref: #more-escaping9098 Ref: #more-escaping9024
Node: Even more escaping9394 Node: Even more escaping9320
Ref: #even-more-escaping9588 Ref: #even-more-escaping9514
Node: Less escaping10259 Node: Less escaping10185
Ref: #less-escaping10421 Ref: #less-escaping10347
Node: Command line tips10666 Node: Command line tips10592
Ref: #command-line-tips10852 Ref: #command-line-tips10778
Node: Unicode characters11229 Node: Unicode characters11155
Ref: #unicode-characters11385 Ref: #unicode-characters11311
Node: Input files12797 Node: Input files12723
Ref: #input-files12933 Ref: #input-files12859
Node: Smart dates14903 Node: Smart dates14788
Ref: #smart-dates15044 Ref: #smart-dates14929
Node: Report start & end date16450 Node: Report start & end date16335
Ref: #report-start-end-date16622 Ref: #report-start-end-date16507
Node: Report intervals17688 Node: Report intervals17931
Ref: #report-intervals17853 Ref: #report-intervals18096
Node: Period expressions18254 Node: Period expressions18486
Ref: #period-expressions18414 Ref: #period-expressions18646
Node: Depth limiting22371 Node: Depth limiting22603
Ref: #depth-limiting22515 Ref: #depth-limiting22747
Node: Pivoting22857 Node: Pivoting23089
Ref: #pivoting22975 Ref: #pivoting23212
Node: Cost24651 Node: Valuation24888
Ref: #cost24759 Ref: #valuation25017
Node: Market value24877 Node: -B Cost25145
Ref: #market-value25016 Ref: #b-cost25256
Node: More control over valuation26257 Node: -V Market value25454
Ref: #more-control-over-valuation26442 Ref: #v-market-value25628
Node: Effect of --value on reports28897 Node: -X Market value in specified commodity27034
Ref: #effect-of---value-on-reports29116 Ref: #x-market-value-in-specified-commodity27254
Node: Some useful value reports31807 Node: --value27594
Ref: #some-useful-value-reports31986 Ref: #value27759
Node: Combining -B -V --value32484 Node: Valuation type28560
Ref: #combining--b--v---value32661 Ref: #valuation-type28696
Node: Output destination32697 Node: Valuation commodity29581
Ref: #output-destination32863 Ref: #valuation-commodity29752
Node: Output format33146 Node: --value examples30452
Ref: #output-format33298 Ref: #value-examples30629
Node: Regular expressions33683 Node: Effect of --value on reports32612
Ref: #regular-expressions33820 Ref: #effect-of---value-on-reports32785
Node: QUERIES35181 Node: Combining -B -V -X --value35476
Ref: #queries35283 Ref: #combining--b--v--x---value35638
Node: COMMANDS39245 Node: Output destination35674
Ref: #commands39357 Ref: #output-destination35826
Node: accounts40358 Node: Output format36109
Ref: #accounts40456 Ref: #output-format36261
Node: activity41155 Node: Regular expressions36646
Ref: #activity41265 Ref: #regular-expressions36783
Node: add41648 Node: QUERIES38144
Ref: #add41747 Ref: #queries38246
Node: balance44334 Node: COMMANDS42208
Ref: #balance44445 Ref: #commands42320
Node: Classic balance report45887 Node: accounts43321
Ref: #classic-balance-report46060 Ref: #accounts43419
Node: Customising the classic balance report47429 Node: activity44118
Ref: #customising-the-classic-balance-report47657 Ref: #activity44228
Node: Colour support49733 Node: add44611
Ref: #colour-support49900 Ref: #add44710
Node: Flat mode50073 Node: balance47455
Ref: #flat-mode50221 Ref: #balance47566
Node: Depth limited balance reports50634 Node: Classic balance report49008
Ref: #depth-limited-balance-reports50834 Ref: #classic-balance-report49181
Node: Multicolumn balance report51290 Node: Customising the classic balance report50550
Ref: #multicolumn-balance-report51488 Ref: #customising-the-classic-balance-report50778
Node: Budget report56802 Node: Colour support52854
Ref: #budget-report56945 Ref: #colour-support53021
Node: Nested budgets62147 Node: Flat mode53194
Ref: #nested-budgets62259 Ref: #flat-mode53342
Ref: #output-format-165739 Node: Depth limited balance reports53755
Node: balancesheet65817 Ref: #depth-limited-balance-reports53955
Ref: #balancesheet65953 Node: Multicolumn balance report54411
Node: balancesheetequity67268 Ref: #multicolumn-balance-report54609
Ref: #balancesheetequity67417 Node: Budget report59923
Node: cashflow67978 Ref: #budget-report60066
Ref: #cashflow68106 Node: Nested budgets65268
Node: check-dates69134 Ref: #nested-budgets65380
Ref: #check-dates69261 Ref: #output-format-168860
Node: check-dupes69540 Node: balancesheet68938
Ref: #check-dupes69664 Ref: #balancesheet69074
Node: close69957 Node: balancesheetequity70389
Ref: #close70065 Ref: #balancesheetequity70538
Node: files73479 Node: cashflow71099
Ref: #files73580 Ref: #cashflow71227
Node: help73727 Node: check-dates72255
Ref: #help73827 Ref: #check-dates72382
Node: import74920 Node: check-dupes72661
Ref: #import75034 Ref: #check-dupes72785
Node: Importing balance assignments75822 Node: close73078
Ref: #importing-balance-assignments75970 Ref: #close73186
Node: incomestatement76619 Node: files76773
Ref: #incomestatement76753 Ref: #files76874
Node: prices78089 Node: help77021
Ref: #prices78204 Ref: #help77121
Node: print78483 Node: import78214
Ref: #print78593 Ref: #import78328
Node: print-unique83086 Node: Importing balance assignments79116
Ref: #print-unique83212 Ref: #importing-balance-assignments79264
Node: register83497 Node: incomestatement79913
Ref: #register83624 Ref: #incomestatement80047
Node: Custom register output87796 Node: prices81383
Ref: #custom-register-output87925 Ref: #prices81498
Node: register-match89187 Node: print81777
Ref: #register-match89321 Ref: #print81887
Node: rewrite89672 Node: print-unique86380
Ref: #rewrite89787 Ref: #print-unique86506
Node: Re-write rules in a file91642 Node: register86791
Ref: #re-write-rules-in-a-file91776 Ref: #register86918
Node: Diff output format92986 Node: Custom register output91090
Ref: #diff-output-format93155 Ref: #custom-register-output91219
Node: rewrite vs print --auto94247 Node: register-match92481
Ref: #rewrite-vs.-print---auto94426 Ref: #register-match92615
Node: roi94982 Node: rewrite92966
Ref: #roi95080 Ref: #rewrite93081
Node: stats96092 Node: Re-write rules in a file94936
Ref: #stats96191 Ref: #re-write-rules-in-a-file95070
Node: tags96945 Node: Diff output format96280
Ref: #tags97043 Ref: #diff-output-format96449
Node: test97273 Node: rewrite vs print --auto97541
Ref: #test97357 Ref: #rewrite-vs.-print---auto97720
Node: ADD-ON COMMANDS98118 Node: roi98276
Ref: #add-on-commands98228 Ref: #roi98374
Node: Official add-ons99516 Node: stats99386
Ref: #official-add-ons99656 Ref: #stats99485
Node: api99744 Node: tags100273
Ref: #api99833 Ref: #tags100371
Node: ui99885 Node: test100665
Ref: #ui99984 Ref: #test100749
Node: web100042 Node: ADD-ON COMMANDS101510
Ref: #web100131 Ref: #add-on-commands101620
Node: Third party add-ons100177 Node: Official add-ons102908
Ref: #third-party-add-ons100352 Ref: #official-add-ons103048
Node: diff100488 Node: api103136
Ref: #diff100585 Ref: #api103225
Node: iadd100684 Node: ui103277
Ref: #iadd100798 Ref: #ui103376
Node: interest100881 Node: web103434
Ref: #interest101002 Ref: #web103523
Node: irr101097 Node: Third party add-ons103569
Ref: #irr101195 Ref: #third-party-add-ons103744
Node: Experimental add-ons101326 Node: diff103880
Ref: #experimental-add-ons101478 Ref: #diff103977
Node: autosync101759 Node: iadd104076
Ref: #autosync101870 Ref: #iadd104190
Node: chart102109 Node: interest104273
Ref: #chart102228 Ref: #interest104394
Node: check102299 Node: irr104489
Ref: #check102401 Ref: #irr104587
Node: Experimental add-ons104718
Ref: #experimental-add-ons104870
Node: autosync105151
Ref: #autosync105262
Node: chart105501
Ref: #chart105620
Node: check105691
Ref: #check105793
 
End Tag Table End Tag Table

925
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff