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
.PP
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
.PP
\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.
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.
.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"

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)
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
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
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
@ -248,6 +251,7 @@ File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
* CSV amounts::
* CSV balance assertions/assignments::
* Reading multiple CSV files::
* Valid CSV::

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)

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
==============================
@ -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
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:
Node: Top72
Node: CSV RULES2167
Ref: #csv-rules2275
Node: skip2538
Ref: #skip2632
Node: date-format2804
Ref: #date-format2931
Node: field list3481
Ref: #field-list3618
Node: field assignment4348
Ref: #field-assignment4503
Node: conditional block5007
Ref: #conditional-block5161
Node: include6057
Ref: #include6187
Node: newest-first6418
Ref: #newest-first6532
Node: CSV TIPS6943
Ref: #csv-tips7037
Node: CSV ordering7167
Ref: #csv-ordering7285
Node: CSV accounts7466
Ref: #csv-accounts7604
Node: CSV amounts7858
Ref: #csv-amounts8016
Node: CSV balance assertions/assignments9096
Ref: #csv-balance-assertionsassignments9314
Node: Reading multiple CSV files9635
Ref: #reading-multiple-csv-files9817
Node: CSV RULES2161
Ref: #csv-rules2269
Node: skip2532
Ref: #skip2626
Node: date-format2798
Ref: #date-format2925
Node: field list3475
Ref: #field-list3612
Node: field assignment4342
Ref: #field-assignment4497
Node: conditional block5121
Ref: #conditional-block5275
Node: include6171
Ref: #include6301
Node: newest-first6532
Ref: #newest-first6646
Node: CSV TIPS7057
Ref: #csv-tips7151
Node: CSV ordering7295
Ref: #csv-ordering7413
Node: CSV accounts7594
Ref: #csv-accounts7732
Node: CSV amounts7986
Ref: #csv-amounts8144
Node: CSV balance assertions/assignments9224
Ref: #csv-balance-assertionsassignments9442
Node: Reading multiple CSV files9763
Ref: #reading-multiple-csv-files9963
Node: Valid CSV10237
Ref: #valid-csv10360

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
list.
Note, interpolation strips any outer whitespace, so a CSV value like "
1 " becomes 1 when interpolated (#1051).
conditional block
if PATTERN
FIELDASSIGNMENTS...
@ -143,12 +146,12 @@ CSV RULES
PATTERN...
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-
ular expressions which match anywhere within the whole CSV record (it's
not yet possible to match within a specific field). When there are
multiple patterns they can be written on separate lines, unindented.
The field assignments are on separate lines indented by at least one
not yet possible to match within a specific field). When there are
multiple patterns they can be written on separate lines, unindented.
The field assignments are on separate lines indented by at least one
space. Examples:
# if the CSV record contains "groceries", set account2 to "expenses:groceries"
@ -175,33 +178,33 @@ CSV RULES
newest-first
newest-first
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
chronological order (newest first), and you care about preserving the
order of same-day transactions. It usually isn't needed, because
hledger autodetects the CSV order, but when all CSV records have the
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
chronological order (newest first), and you care about preserving the
order of same-day transactions. It usually isn't needed, because
hledger autodetects the CSV order, but when all CSV records have the
same date it will assume they are oldest first.
CSV TIPS
CSV ordering
The generated journal entries will be sorted by date. The order of
same-day entries will be preserved (except in the special case where
The generated journal entries will be sorted by date. The order of
same-day entries will be preserved (except in the special case where
you might need newest-first, see above).
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
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.
CSV amounts
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
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-
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:
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.
o If an amount value begins with a double minus sign, those will cancel
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
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:
fields date,description,currency,amount
amount %amount %currency
CSV balance assertions/assignments
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-
ate a balance assertion (or if the amount is left empty, a balance
assignment), on the first or second posting, whenever the running bal-
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-
ate a balance assertion (or if the amount is left empty, a balance
assignment), on the first or second posting, whenever the running bal-
ance field is non-empty. (TODO: #1000)
Reading multiple CSV files
You can read multiple CSV files at once using multiple -f arguments on
the command line, and hledger will look for a correspondingly-named
You can read multiple CSV files at once using multiple -f arguments on
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 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
@ -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
.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.
.SS Payee and note
.PP
You can optionally include a \f[C]|\f[R] (pipe) character in a
description to subdivide it into a payee/payer name on the left and
additional notes on the right.
You can optionally include a \f[C]|\f[R] (pipe) character in
descriptions to subdivide the description into separate fields for
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
pivoting by payee.
pivoting by payee or by note.
.SS Account names
.PP
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]
2009/1/1
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]
.fi
.RE
@ -752,8 +753,8 @@ hledger infer the price that balances the transaction:
.nf
\f[C]
2009/1/1
assets:euros \[Eu]100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
assets:euros \[Eu]100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
\f[R]
.fi
.RE
@ -786,8 +787,8 @@ equivalent, -B shows something different:
.nf
\f[C]
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros \[Eu]100 ; for 100 euros
assets:dollars $-135 ; 135 dollars sold
assets:euros \[Eu]100 ; for 100 euros
\f[R]
.fi
.IP
@ -870,7 +871,7 @@ comma separated:
.IP
.nf
\f[C]
assets:checking ; a comment containing tag1:, tag2: some value ...
assets:checking ; a comment containing tag1:, tag2: some value ...
\f[R]
.fi
.PP
@ -1118,7 +1119,8 @@ Y2010 ; change default year to 2010
.SS Declaring commodities
.PP
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:
.IP
.nf
@ -1149,14 +1151,20 @@ commodity INR
\f[R]
.fi
.PP
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity.
Declaring commodites may be useful as documentation, but currently we do
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
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).
.PP
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
.SS Default commodity
.PP
The \f[C]D\f[R] directive sets a default commodity (and display format),
@ -1334,11 +1342,11 @@ Eg:
.nf
\f[C]
; 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,
; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities
account - ; type:L
account - ; type:L
\f[R]
.fi
.SS Account display order
@ -1474,20 +1482,39 @@ alias /\[ha](.+):bank:([\[ha]:]+)(.*)/ = \[rs]1:\[rs]2 \[rs]3
.PP
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.
.SS Multiple aliases
.SS Combining aliases
.PP
You can define as many aliases as you like using directives or
command-line options.
Aliases are recursive - each alias sees the result of applying previous
ones.
(This is different from Ledger, where aliases are non-recursive by
default).
Aliases are applied in the following order:
You can define as many aliases as you like, using journal directives
and/or command line options.
.PP
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed.
Each alias sees the effect of previously applied aliases.
.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
alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
\f[C]alias\f[R] directives preceding the journal entry, most recently
parsed first (ie, reading upward from the journal entry, bottom to top)
.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]
.PP
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
generates future transactions recurring at the specified interval.
These are not saved in the journal, but appear in all reports.
They will look like normal transactions, but with an extra tag named
\f[C]recur\f[R], whose value is the generating period expression.
They will look like normal transactions, but with an extra tag:
.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
Forecast transactions start on the first occurrence, and end on the last
occurrence, of their interval within the forecast period.
@ -1654,16 +1691,16 @@ and Forecasting.
.PP
.SS Auto postings / transaction modifiers
.PP
Transaction modifier rules describe changes to be applied automatically
to certain matched transactions.
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions.
Currently just one kind of change is possible - adding extra postings,
which we call \[dq]automated postings\[dq] or just \[dq]auto
postings\[dq].
These rules become active when you use the \f[C]--auto\f[R] flag.
.PP
A transaction modifier, AKA auto posting rule, looks much like a normal
transaction except the first line is an equals sign followed by a query
that matches certain postings (mnemonic: \f[C]=\f[R] suggests matching).
A transaction modifier rule looks much like a normal transaction except
the first line is an equals sign followed by a query that matches
certain postings (mnemonic: \f[C]=\f[R] suggests matching).
And each \[dq]posting\[dq] is actually a posting-generating rule:
.IP
.nf
@ -1736,6 +1773,11 @@ $ hledger print --auto
assets:checking $20
\f[R]
.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
.PP
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
after auto postings are added.
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
.PP
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)
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
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:
2015/5/30
expenses:food $10 ; food purchased on saturday 5/30
assets:checking ; bank cleared it on monday, date:6/1
expenses:food $10 ; food purchased on saturday 5/30
assets:checking ; bank cleared it on monday, date:6/1
$ hledger -f t.j register food
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
--------------------
You can optionally include a '|' (pipe) character in a description to
subdivide it into a payee/payer name on the left and additional notes on
the right. This may be worthwhile if you need to do more precise
querying and pivoting by payee.
You can optionally include a '|' (pipe) character in descriptions to
subdivide the description into separate fields for payee/payer name on
the left (up to the first '|') and an additional note field on the right
(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
@ -734,8 +735,8 @@ last amount. So if example 3's postings are reversed, while the
transaction is equivalent, -B shows something different:
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros €100 ; for 100 euros
assets:dollars $-135 ; 135 dollars sold
assets:euros €100 ; for 100 euros
$ hledger bal -N --flat -B
€-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
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
newlines. Ending at commas means you can write multiple short tags on
one line, comma separated:
assets:checking ; a comment containing tag1:, tag2: some value ...
assets:checking ; a comment containing tag1:, tag2: some value ...
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.
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
assets
Y2010 ; change default year to 2010
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
1/31 ; equivalent to 2010/1/31
expenses 1
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
journal (though currently we do not enforce this). It may be written on
a single line, like this:
journal, and their display format.
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -1014,13 +1016,19 @@ places:
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display
format is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0
or more decimal digits).
Declaring commodites may be useful as documentation, but currently we
do not enforce that only declared commodities may be used. This
directive is mainly useful for customising the preferred display format
for a commodity.
Normally the display format is inferred from journal entries, but
this can be unpredictable; declaring it with a commodity directive
overrides this and removes ambiguity. Towards this end, amounts in
commodity directives must always be written with a decimal point (a
period or comma, followed by 0 or more decimal digits).
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
@ -1039,7 +1047,7 @@ amounts, or until the next 'D' directive.
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
a 5 ; <- commodity-less amount, becomes $1
b
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:
; 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,
; 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
@ -1257,7 +1265,7 @@ hledger-web.
* Basic aliases::
* Regex aliases::
* Multiple aliases::
* Combining 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"

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
......................
@ -1309,23 +1317,44 @@ command line, to end of option argument), so it can contain trailing
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
command-line options. Aliases are recursive - each alias sees the
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
You can define as many aliases as you like, using journal directives
and/or command line options.
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
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'
......................
@ -1437,8 +1466,18 @@ File: hledger_journal.info, Node: Forecasting with periodic transactions, Next
With the '--forecast' flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named 'recur', whose value is
the generating period expression.
normal transactions, but with an extra tag:
* '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
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
==========================================
Transaction modifier rules describe changes to be applied automatically
to certain matched transactions. Currently just one kind of change is
possible - adding extra postings, which we call "automated postings" or
just "auto postings". These rules become active when you use the
'--auto' flag.
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
active when you use the '--auto' flag.
A transaction modifier, AKA auto posting rule, looks much like a
normal transaction except the first line is an equals sign followed by a
query that matches certain postings (mnemonic: '=' suggests matching).
And each "posting" is actually a posting-generating rule:
A transaction modifier rule looks much like a normal transaction
except the first line is an equals sign followed by a query that matches
certain postings (mnemonic: '=' suggests matching). And each "posting"
is actually a posting-generating rule:
= QUERY
ACCT AMT
@ -1560,12 +1599,24 @@ $ hledger print --auto
* Menu:
* Auto postings and dates::
* 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
@ -1579,6 +1630,28 @@ postings are added:
after auto postings are added. This changed in hledger 1.12+; see #893
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
@ -1595,109 +1668,113 @@ See the [[Cookbook]] at hledger.org for the latest information.

Tag Table:
Node: Top76
Node: FILE FORMAT2378
Ref: #file-format2502
Node: Transactions2805
Ref: #transactions2926
Node: Postings3610
Ref: #postings3737
Node: Dates4732
Ref: #dates4847
Node: Simple dates4912
Ref: #simple-dates5038
Node: Secondary dates5404
Ref: #secondary-dates5558
Node: Posting dates7121
Ref: #posting-dates7250
Node: Status8624
Ref: #status8744
Node: Description10452
Ref: #description10590
Node: Payee and note10910
Ref: #payee-and-note11024
Node: Account names11266
Ref: #account-names11409
Node: Amounts11896
Ref: #amounts12032
Node: Virtual Postings15049
Ref: #virtual-postings15208
Node: Balance Assertions16428
Ref: #balance-assertions16603
Node: Assertions and ordering17562
Ref: #assertions-and-ordering17748
Node: Assertions and included files18448
Ref: #assertions-and-included-files18689
Node: Assertions and multiple -f options19022
Ref: #assertions-and-multiple--f-options19276
Node: Assertions and commodities19408
Ref: #assertions-and-commodities19638
Node: Assertions and prices20794
Ref: #assertions-and-prices21006
Node: Assertions and subaccounts21446
Ref: #assertions-and-subaccounts21673
Node: Assertions and virtual postings21997
Ref: #assertions-and-virtual-postings22237
Node: Assertions and precision22379
Ref: #assertions-and-precision22570
Node: Balance Assignments22837
Ref: #balance-assignments23018
Node: Balance assignments and prices24183
Ref: #balance-assignments-and-prices24355
Node: Transaction prices24579
Ref: #transaction-prices24748
Node: Comments27016
Ref: #comments27150
Node: Tags28320
Ref: #tags28438
Node: Directives29840
Ref: #directives29983
Node: Comment blocks35591
Ref: #comment-blocks35736
Node: Including other files35912
Ref: #including-other-files36092
Node: Default year36500
Ref: #default-year36669
Node: Declaring commodities37092
Ref: #declaring-commodities37275
Node: Default commodity38502
Ref: #default-commodity38678
Node: Market prices39314
Ref: #market-prices39479
Node: Declaring accounts40320
Ref: #declaring-accounts40496
Node: Account comments41421
Ref: #account-comments41584
Node: Account subdirectives41979
Ref: #account-subdirectives42174
Node: Account types42487
Ref: #account-types42671
Node: Account display order44315
Ref: #account-display-order44485
Node: Rewriting accounts45614
Ref: #rewriting-accounts45799
Node: Basic aliases46534
Ref: #basic-aliases46680
Node: Regex aliases47384
Ref: #regex-aliases47555
Node: Multiple aliases48273
Ref: #multiple-aliases48448
Node: end aliases48946
Ref: #end-aliases49093
Node: Default parent account49194
Ref: #default-parent-account49360
Node: Periodic transactions50244
Ref: #periodic-transactions50442
Node: Two spaces after the period expression51568
Ref: #two-spaces-after-the-period-expression51813
Node: Forecasting with periodic transactions52298
Ref: #forecasting-with-periodic-transactions52588
Node: Budgeting with periodic transactions54275
Ref: #budgeting-with-periodic-transactions54514
Node: Auto postings / transaction modifiers54973
Ref: #auto-postings-transaction-modifiers55184
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57356
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57673
Node: EDITOR SUPPORT58051
Ref: #editor-support58169
Node: FILE FORMAT2352
Ref: #file-format2476
Node: Transactions2779
Ref: #transactions2900
Node: Postings3584
Ref: #postings3711
Node: Dates4706
Ref: #dates4821
Node: Simple dates4886
Ref: #simple-dates5012
Node: Secondary dates5378
Ref: #secondary-dates5532
Node: Posting dates7095
Ref: #posting-dates7224
Node: Status8596
Ref: #status8716
Node: Description10424
Ref: #description10562
Node: Payee and note10882
Ref: #payee-and-note10996
Node: Account names11331
Ref: #account-names11474
Node: Amounts11961
Ref: #amounts12097
Node: Virtual Postings15114
Ref: #virtual-postings15273
Node: Balance Assertions16493
Ref: #balance-assertions16668
Node: Assertions and ordering17627
Ref: #assertions-and-ordering17813
Node: Assertions and included files18513
Ref: #assertions-and-included-files18754
Node: Assertions and multiple -f options19087
Ref: #assertions-and-multiple--f-options19341
Node: Assertions and commodities19473
Ref: #assertions-and-commodities19703
Node: Assertions and prices20859
Ref: #assertions-and-prices21071
Node: Assertions and subaccounts21511
Ref: #assertions-and-subaccounts21738
Node: Assertions and virtual postings22062
Ref: #assertions-and-virtual-postings22302
Node: Assertions and precision22444
Ref: #assertions-and-precision22635
Node: Balance Assignments22902
Ref: #balance-assignments23083
Node: Balance assignments and prices24248
Ref: #balance-assignments-and-prices24420
Node: Transaction prices24644
Ref: #transaction-prices24813
Node: Comments27079
Ref: #comments27213
Node: Tags28383
Ref: #tags28501
Node: Directives29894
Ref: #directives30037
Node: Comment blocks35645
Ref: #comment-blocks35790
Node: Including other files35966
Ref: #including-other-files36146
Node: Default year36554
Ref: #default-year36723
Node: Declaring commodities37130
Ref: #declaring-commodities37313
Node: Default commodity38742
Ref: #default-commodity38918
Node: Market prices39552
Ref: #market-prices39717
Node: Declaring accounts40558
Ref: #declaring-accounts40734
Node: Account comments41659
Ref: #account-comments41822
Node: Account subdirectives42217
Ref: #account-subdirectives42412
Node: Account types42725
Ref: #account-types42909
Node: Account display order44551
Ref: #account-display-order44721
Node: Rewriting accounts45850
Ref: #rewriting-accounts46035
Node: Basic aliases46771
Ref: #basic-aliases46917
Node: Regex aliases47621
Ref: #regex-aliases47793
Node: Combining aliases48511
Ref: #combining-aliases48689
Node: end aliases49965
Ref: #end-aliases50113
Node: Default parent account50214
Ref: #default-parent-account50380
Node: Periodic transactions51264
Ref: #periodic-transactions51462
Node: Two spaces after the period expression52588
Ref: #two-spaces-after-the-period-expression52833
Node: Forecasting with periodic transactions53318
Ref: #forecasting-with-periodic-transactions53608
Node: Budgeting with periodic transactions55634
Ref: #budgeting-with-periodic-transactions55873
Node: Auto postings / transaction modifiers56332
Ref: #auto-postings-transaction-modifiers56543
Node: Auto postings and dates58772
Ref: #auto-postings-and-dates59029
Node: Auto postings and transaction balancing / inferred amounts / balance assertions59204
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

427
hledger-lib/hledger_journal.txt
View File

@ -229,19 +229,20 @@ FILE FORMAT
comments.
Payee and note
You can optionally include a | (pipe) character in a description to
subdivide it into a payee/payer name on the left and additional notes
on the right. This may be worthwhile if you need to do more precise
querying and pivoting by payee.
You can optionally include a | (pipe) character in descriptions to sub-
divide the description into separate fields for payee/payer name on the
left (up to the first |) and an additional note field on the right
(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 typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five top-
Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five top-
level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
spaces (or newline).
Account names can be aliased.
@ -250,7 +251,7 @@ FILE FORMAT
After the account name, there is usually an amount. Important: between
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:
2.00001
@ -266,35 +267,35 @@ FILE FORMAT
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").
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-
bers, spaces or non-word punctuation it must be enclosed in double
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-
bers, spaces or non-word punctuation it must be enclosed in double
quotes.
o negative amounts with a commodity on the left can have the minus sign
before or after it
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
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
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
o scientific E-notation is allowed. Be careful not to use a digit
group separator character in scientific notation, as it's not sup-
o scientific E-notation is allowed. Be careful not to use a digit
group separator character in scientific notation, as it's not sup-
ported and it might get mistaken for a decimal point. (Declaring the
digit group separator character explicitly with a commodity directive
will prevent this.)
You can use any of these variations when recording data. However,
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
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
You can use any of these variations when recording data. However,
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
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
will help to resolve that ambiguity differently:
commodity $1,000.00
@ -303,38 +304,38 @@ FILE FORMAT
expenses:gifts $1,000
assets
Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
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
that commodity in the journal, and the precision (number of decimal
o otherwise the format is inferred from the first posting amount in
that commodity in the journal, and the precision (number of decimal
places) will be the maximum from all posting amounts in that commmod-
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).
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount,
Price amounts and amounts in D directives usually don't affect amount
format inference, but in some situations they can do so indirectly.
(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
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.
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:
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.
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:
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-
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-
ings (but separately from them). Balanced virtual postings are also
tual postings in a transaction must balance to 0, like the real post-
ings (but separately from them). Balanced virtual postings are also
excluded by --real/-R or real:1.
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
@ -353,13 +354,13 @@ FILE FORMAT
[assets:checking:budget:food] $-10
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.
Balance Assertions
hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a
hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a
and b after each posting:
2013/1/1
@ -371,31 +372,31 @@ FILE FORMAT
b $-1 =$-2
After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
-I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files.
Assertions and ordering
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-
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-
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.)
So, hledger balance assertions keep working if you reorder differently-
dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating.
dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating.
This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert intra-
day balances.
Assertions and included files
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
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
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
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
day, you'll have to put the assertion in the right file.
Assertions and multiple -f options
@ -403,8 +404,8 @@ FILE FORMAT
-f options. Use include or concatenate the files instead.
Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance.
This is how assertions work in Ledger also. We could call this a "par-
tial" balance assertion.
@ -412,7 +413,7 @@ FILE FORMAT
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance.
You can make a stronger "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
unasserted commodities in the account (or, that their balance is 0).
@ -432,7 +433,7 @@ FILE FORMAT
a 0 == $1
It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity
has multiple commodities. One workaround is to isolate each commodity
into its own subaccount:
2013/1/1
@ -446,21 +447,21 @@ FILE FORMAT
a:euro 0 == 1EUR
Assertions and prices
Balance assertions ignore transaction prices, and should normally be
Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ EUR1 = $1
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.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
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.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
ments do use them (see below).
Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can
The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg:
2019/1/1
@ -474,16 +475,16 @@ FILE FORMAT
tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision
Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser-
Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts.
Balance Assignments
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when
setting opening balances:
; starting a new journal, set asset account balances
@ -501,14 +502,14 @@ FILE FORMAT
expenses:misc
The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it.
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:
2019/1/1
@ -520,9 +521,9 @@ FILE FORMAT
Transaction prices
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
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
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
record purchases of a foreign currency. Note transaction prices are
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-
tain date.
@ -533,7 +534,7 @@ FILE FORMAT
2009/1/1
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:
@ -546,12 +547,12 @@ FILE FORMAT
2009/1/1
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-
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).
Eg here is how -B affects the balance report for the example above:
@ -562,13 +563,13 @@ FILE FORMAT
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
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
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
amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different:
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:dollars $-135 ; 135 dollars sold
assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B
@ -577,14 +578,14 @@ FILE FORMAT
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;).
Some examples:
@ -608,28 +609,28 @@ FILE FORMAT
; another comment line for posting 2
; 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.
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.
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:
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:
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
line, comma separated:
assets:checking ; a comment containing tag1:, tag2: some value ...
assets:checking ; a comment containing tag1:, tag2: some value ...
Here,
@ -639,70 +640,69 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-
tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(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.
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
based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions).
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.
direc- end subdi- purpose can affect (as of
direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06)
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
alias end rewrite account names following
aliases inline/included
entries until end
of current file or
of current file or
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
entries until end
of current file or
of current file or
end directive
comment end com- ignore part of journal following
ment inline/included
entries until end
of current file or
of current file or
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
style in that commodity
in all files; dis-
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
less entries and
entries in that
commodity in all
commodity in all
files; display
style: amounts of
that commodity in
@ -713,7 +713,7 @@ FILE FORMAT
commodity commodity in
reports, when -V is
used
Y declare a year for yearless following
Y declare a year for yearless following
dates inline/included
entries until end
of current file
@ -723,9 +723,9 @@ FILE FORMAT
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@ -733,59 +733,60 @@ FILE FORMAT
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
writing file options in a different order. It can be surprising at
times though.
Comment blocks
A line containing just comment starts a commented region of the file,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
Y2009 ; set default year to 2009
12/15 ; equivalent to 2009/12/15
12/15 ; equivalent to 2009/12/15
expenses 1
assets
Y2010 ; change default year to 2010
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
1/31 ; equivalent to 2010/1/31
expenses 1
assets
Declaring commodities
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
The commodity directive declares commodities which may be used in the
journal, and their display format.
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -807,13 +808,19 @@ FILE FORMAT
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Declaring commodites may be useful as documentation, but currently we
do not enforce that only declared commodities may be used. This direc-
tive is mainly useful for customising the preferred display format for
a commodity.
Normally the display format is inferred from journal entries, but this
can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity. Towards this end, amounts in commodity
directives must always be written with a decimal point (a period or
comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
Default commodity
The D directive sets a default commodity (and display format), to be
@ -827,7 +834,7 @@ FILE FORMAT
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
a 5 ; <- commodity-less amount, becomes $1
b
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:
; 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,
; otherwise balancesheet would still show "liabilities" under Liabilities
account - ; type:L
account - ; type:L
Account display order
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-
space.
Multiple aliases
You can define as many aliases as you like using directives or command-
line options. Aliases are recursive - each alias sees the result of
applying previous ones. (This is different from Ledger, where aliases
are non-recursive by default). Aliases are applied in the following
order:
Combining aliases
You can define as many aliases as you like, using journal directives
and/or command line options.
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
Recursive aliases - where an account name is rewritten by one alias,
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
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
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
the generating period expression.
normal transactions, but with an extra tag:
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
last occurrence, of their interval within the forecast period. The
@ -1189,16 +1227,16 @@ FILE FORMAT
Auto postings / transaction modifiers
Transaction modifier rules describe changes to be applied automatically
to certain matched transactions. Currently just one kind of change is
possible - adding extra postings, which we call "automated postings" or
just "auto postings". These rules become active when you use the
--auto flag.
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
active when you use the --auto flag.
A transaction modifier, AKA auto posting rule, looks much like a normal
transaction except the first line is an equals sign followed by a query
that matches certain postings (mnemonic: = suggests matching). And
each "posting" is actually a posting-generating rule:
A transaction modifier rule looks much like a normal transaction except
the first line is an equals sign followed by a query that matches cer-
tain postings (mnemonic: = suggests matching). And each "posting" is
actually a posting-generating rule:
= QUERY
ACCT AMT
@ -1257,6 +1295,11 @@ FILE FORMAT
assets:checking:gifts -$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-
tions
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
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
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
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa-
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa-
tion.
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)
@ -1296,7 +1357,7 @@ COPYRIGHT
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-
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)
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
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)
hledger_timedot(5) hledger 1.14.99
**********************************
hledger_timedot(5) hledger 1.15
*******************************
Timedot is a plain text format for logging dated, categorised quantities
(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:
Node: Top76
Node: FILE FORMAT814
Ref: #file-format915
Node: FILE FORMAT808
Ref: #file-format909

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
.B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
period expressions syntax
.TP
.B \f[C]--date2\f[R]
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
subsiding, and possibly a small but persistent build-up of CPU usage
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"

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)
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
full-window text UI for viewing accounts and transactions, and some
@ -117,7 +117,7 @@ the data.
'-p --period=PERIODEXP'
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'
match the secondary date instead (see command help for other
@ -399,19 +399,19 @@ to cancel the reload attempt.)

Tag Table:
Node: Top71
Node: OPTIONS1107
Ref: #options1204
Node: KEYS4623
Ref: #keys4718
Node: SCREENS7974
Ref: #screens8059
Node: Accounts screen8149
Ref: #accounts-screen8277
Node: Register screen10493
Ref: #register-screen10648
Node: Transaction screen12644
Ref: #transaction-screen12802
Node: Error screen13672
Ref: #error-screen13794
Node: OPTIONS1101
Ref: #options1198
Node: KEYS4589
Ref: #keys4684
Node: SCREENS7940
Ref: #screens8025
Node: Accounts screen8115
Ref: #accounts-screen8243
Node: Register screen10459
Ref: #register-screen10614
Node: Transaction screen12610
Ref: #transaction-screen12768
Node: Error screen13638
Ref: #error-screen13760

End Tag Table

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

@ -114,7 +114,7 @@ OPTIONS
-p --period=PERIODEXP
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
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
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
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)
@ -398,7 +401,7 @@ COPYRIGHT
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-
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]
serve and log requests, don\[aq]t browse or auto-exit
.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]
listen on this IP address (default: 127.0.0.1)
.TP
@ -128,7 +132,7 @@ multiperiod/multicolumn report by year
.TP
.B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
period expressions syntax
.TP
.B \f[C]--date2\f[R]
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).
With \f[C]--serve\f[R], it just runs the web app without exiting, and
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
By default the server listens on IP address 127.0.0.1, accessible only
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.
If a change makes a file unparseable, hledger-web will display an error
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
.PP
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
\f[R]
.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
.PP
\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)
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
application for browsing and adding transactions, and optionally opens
@ -50,6 +50,10 @@ before options, as shown in the synopsis above.
'--serve'
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'
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'
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'
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
window, and will exit after two minutes of inactivity (no requests and
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
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 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
@ -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
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:
Node: Top72
Node: OPTIONS1361
Ref: #options1466
Node: PERMISSIONS6556
Ref: #permissions6695
Node: EDITING UPLOADING DOWNLOADING7907
Ref: #editing-uploading-downloading8088
Node: RELOADING8922
Ref: #reloading9056
Node: JSON API9366
Ref: #json-api9460
Node: OPTIONS1355
Ref: #options1460
Node: PERMISSIONS6739
Ref: #permissions6878
Node: EDITING UPLOADING DOWNLOADING8090
Ref: #editing-uploading-downloading8271
Node: RELOADING9105
Ref: #reloading9239
Node: JSON API9672
Ref: #json-api9766

End Tag Table

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

@ -46,6 +46,10 @@ OPTIONS
--serve
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
listen on this IP address (default: 127.0.0.1)
@ -53,22 +57,22 @@ OPTIONS
listen on this TCP port (default: 5000)
--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
a larger website.
--file-url=URL
set the static files url (default: BASEURL/static). hledger-web
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url
with this.
--capabilities=CAP[,CAP..]
enable the view, add, and/or manage capabilities (default:
enable the view, add, and/or manage capabilities (default:
view,add)
--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)
hledger input options:
@ -78,7 +82,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE
Conversion rules file to use when reading CSV (default:
Conversion rules file to use when reading CSV (default:
FILE.rules)
--separator=CHAR
@ -119,11 +123,11 @@ OPTIONS
multiperiod/multicolumn report by year
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above)
set start date, end date, and/or reporting interval all at once
using period expressions syntax
--date2
match the secondary date instead (see command help for other
match the secondary date instead (see command help for other
effects)
-U --unmarked
@ -142,21 +146,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep
-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)
-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)
-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)
--auto apply automated posting rules to modify transactions.
--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.
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)
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.)
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
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
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console.
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
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
to local requests. You can use --host to change this, eg --host
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
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.
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
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).
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.
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.
You can restrict who can reach it by
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
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
machine.
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
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:
o view - allows viewing the journal file and all included files
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
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
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
let you edit, upload, or download the journal file or any files it
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
let you edit, upload, or download the journal file or any files it
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.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
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
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
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
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
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
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
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
makes a file unparseable, hledger-web will display an error message
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
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
@ -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
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
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.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
Accounts : 8 (depth 3)
Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format
selection.

218
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"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
.B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
period expressions syntax
.TP
.B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects)
@ -455,7 +455,7 @@ turn:
.PP
.TS
tab(@);
lw(10.3n) lw(33.5n) lw(26.2n).
lw(7.6n) lw(31.2n) lw(31.2n).
T{
Reader:
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
(described below).
All of these accept the smart date syntax.
One important thing to be aware of when specifying end dates: as in
Ledger, end dates are exclusive, so you need to write the date
.PP
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.
.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
Examples:
.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],
or \f[C]-Y/--yearly\f[R].
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
.PP
The \f[C]-p/--period\f[R] option accepts period expressions, a shorthand
@ -993,18 +1004,33 @@ $ hledger balance --pivot member acct:.
-2 EUR
\f[R]
.fi
.SS Cost
.SS Valuation
.SS -B: Cost
.PP
The \f[C]-B/--cost\f[R] flag converts amounts to their cost at
transaction time, if they have a transaction price specified.
.SS Market value
The \f[C]-B/--cost\f[R] flag converts amounts to their cost (or selling
price) at transaction time, if they have a transaction price specified.
This flag is equivalent to \f[C]--value=cost\f[R], described below.
.SS -V: Market value
.PP
The \f[C]-V/--market\f[R] flag converts reported amounts to their market
value in another commodity.
It uses the commodity referenced in the latest market price (P
directive) dated on or before the valuation date.
The default valuation date is today.
For example:
value in a default valuation commodity, using the historical market
prices in effect on a default valuation date.
.PP
For single period reports, the valuation date is today.
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
.nf
\f[C]
@ -1048,52 +1074,79 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros
\f[R]
.fi
.SS -X: Market value in specified commodity
.PP
Ledger users: Ledger\[aq]s -V also infers market prices from journal
entries, but we don\[aq]t do that.
hledger\[aq]s -V uses only market prices declared explicitly, with P
directives.
(Mnemonic: -B/--cost uses transaction prices, -V/--market uses market
prices.)
.SS More control over valuation
The \f[C]-X/--exchange\f[R] option is like \f[C]-V/--market\f[R] except
it takes a commodity symbol argument, so that you can select a different
target commodity.
It is similar to the same option in Ledger, with the same caveat
mentioned for \f[C]-V\f[R]/\f[C]--value\f[R] above.
It is equivalent to \f[C]--value=now,COMM\f[R] or
\f[C]--value=end,COMM\f[R]; for more details, read on.
.SS --value
.PP
\f[I](experimental, added 201905)\f[R]
.PP
You can control valuation more precisely with the \f[C]--value\f[R]
option.
\f[C]-B\f[R], \f[C]-V\f[R] and \f[C]-X\f[R] are special cases of the
more general \f[C]--value\f[R] option:
.IP
.nf
\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]
.fi
.SS Valuation type
.PP
The argument is one of the keywords shown, or their first letter, or a
custom date.
The precise effect of the keywords is command-specific, but here is
their general meaning:
TYPE is one of these keywords, or their first letter, or a date (which
must be 8 digits with \f[C]-\f[R] or \f[C]/\f[R] or \f[C].\f[R]
separators):
.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.
\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
.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
market prices on the last day of the report period (or of each subperiod
in a multiperiod report).
When no report period is specified, uses the journal\[aq]s last
transaction date.
.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
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
.B \f[C]--value=YYYY-MM-DD\f[R]
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]
or \f[C]/\f[R] or \f[C].\f[R] separators).
market prices on this date.
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
Here are the effects of \f[C]--value\f[R] as seen with \f[C]print\f[R]:
.IP
@ -1192,6 +1245,56 @@ $ hledger -f- print --value=2000-01-15
(a) 1 B
\f[R]
.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
.PP
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
T}
.TE
.SS Some useful value reports
.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
.SS Combining -B, -V, -X, --value
.PP
The rightmost of these flags wins.
.SS Output destination
@ -1708,6 +1780,10 @@ Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $
\f[R]
.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
.PP
balance, bal, b
@ -2497,6 +2573,10 @@ assertions will depend on these flags.
Likewise, if you run this command with --auto, the balance assertions
will probably always require --auto.
.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:
.PP
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
Accounts : 8 (depth 3)
Commodities : 1 ($)
Market prices : 12 ($)
\f[R]
.fi
.PP
@ -3272,6 +3353,7 @@ With a TAGREGEX argument, only tag names matching the regular expression
(case insensitive) are shown.
With QUERY arguments, only transactions matching the query are
considered.
With --values flag, the tags\[aq] unique values are listed instead.
.SS test
.PP
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)
hledger(1) hledger 1.14.99
**************************
hledger(1) hledger 1.15
***********************
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
@ -130,9 +130,7 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Period expressions::
* Depth limiting::
* Pivoting::
* Cost::
* Market value::
* Combining -B -V --value::
* Valuation::
* Output destination::
* Output format::
* Regular expressions::
@ -209,7 +207,7 @@ by most hledger commands, run 'hledger -h'.
'-p --period=PERIODEXP'
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'
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
recognised, by trying each built-in "reader" in turn:
Reader: Reads: Used for file extensions:
----------------------------------------------------------------------------
'journal' hledger's journal format, also '.journal' '.j'
some Ledger journals '.hledger' '.ledger'
'timeclock' timeclock files (precise time '.timeclock'
logging)
'timedot' timedot files (approximate time '.timedot'
logging)
'csv' comma-separated values (data '.csv'
interchange)
Reader: Reads: Used for file extensions:
---------------------------------------------------------------------------
'journal'hledger's journal format, also '.journal' '.j' '.hledger'
some Ledger journals '.ledger'
'timeclock'timeclock files (precise time '.timeclock'
logging)
'timedot'timedot files (approximate '.timedot'
time logging)
'csv' comma-separated values (data '.csv'
interchange)
If needed (eg to ensure correct error messages when a file has the
"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
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
these accept the smart date syntax. One important thing to be aware of
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.
these accept the smart date syntax.
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:
@ -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',
'-W/--weekly', '-M/--monthly', '-Q/--quarterly', or '-Y/--yearly'. More
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
@ -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).

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
=============
@ -736,24 +743,54 @@ $ hledger balance --pivot member acct:.
-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,
if they have a transaction price specified.
* Menu:
* -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
in another commodity. It uses the commodity referenced in the latest
market price (P directive) dated on or before the valuation date. The
default valuation date is today. For example:
in a default valuation commodity, using the historical market prices in
effect on a default valuation date.
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
P 2016/11/01 € $1.10
@ -782,55 +819,101 @@ specified, defaults to today)
$ hledger -f t.j bal -N euros -V
$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
declared explicitly, with P directives. (Mnemonic: -B/-cost uses
transaction prices, -V/-market uses market prices.)

File: hledger.info, Node: -X Market value in specified commodity, Next: --value, Prev: -V Market value, Up: Valuation
* Menu:
2.15.3 -X: Market value in specified commodity
----------------------------------------------
* More control over valuation::
* Effect of --value on reports::
* Some useful value reports::
The '-X/--exchange' option is like '-V/--market' except it takes a
commodity symbol argument, so that you can select a different target
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)_
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
a custom date. The precise effect of the keywords is command-specific,
but here is their general meaning:
* Menu:
'--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.
'-B'/'--cost' does this.
'--value=end' (or 'e')
'-B'/'--cost' is equivalent to this.
'--value=end'
Convert amounts to their value in default valuation commodity using
market prices on the last day of the report period (or of each
subperiod in a multiperiod report). When no report period is
specified, uses the journal's last transaction date.
'--value=now' (or 'n')
'--value=now'
Convert amounts to their value in default valuation commodity using
current market prices (as of when report is generated).
'-V'/'--market' does this.
'-V'/'--market' is equivalent to this.
'--value=YYYY-MM-DD'
Convert amounts to their value in default valuation commodity using
market prices on the given date (which must be 8 digits with '-' or
'/' or '.' separators). Eg '--value=2019-04-25'.
market prices on this date. 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-02-01 A 2 B
@ -905,11 +988,43 @@ $ hledger -f- print --value=2000-01-15
2000/03/01
(a) 1 B

File: hledger.info, Node: Effect of --value on reports, Next: Some useful value reports, Prev: More control over valuation, Up: Market value
You may need to explicitly set a commodity's display style, when
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.
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

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
--------------------------------
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
=============================
2.15.5 Combining -B, -V, -X, -value
-----------------------------------
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
@ -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
2.19 Output format
2.17 Output format
==================
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
2.20 Regular expressions
2.18 Regular expressions
========================
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)
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
@ -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
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:
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
Accounts : 8 (depth 3)
Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format
selection.
@ -2727,7 +2835,8 @@ tags
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) 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
@ -2931,168 +3040,176 @@ hledger-check.hs checks more powerful account balance assertions.

Tag Table:
Node: Top68
Node: EXAMPLES1891
Ref: #examples1991
Node: OPTIONS3637
Ref: #options3739
Node: General options4178
Ref: #general-options4303
Node: Command options6985
Ref: #command-options7136
Node: Command arguments7534
Ref: #command-arguments7688
Node: Argument files7809
Ref: #argument-files7985
Node: Special characters in arguments and queries8251
Ref: #special-characters-in-arguments-and-queries8485
Node: More escaping8936
Ref: #more-escaping9098
Node: Even more escaping9394
Ref: #even-more-escaping9588
Node: Less escaping10259
Ref: #less-escaping10421
Node: Command line tips10666
Ref: #command-line-tips10852
Node: Unicode characters11229
Ref: #unicode-characters11385
Node: Input files12797
Ref: #input-files12933
Node: Smart dates14903
Ref: #smart-dates15044
Node: Report start & end date16450
Ref: #report-start-end-date16622
Node: Report intervals17688
Ref: #report-intervals17853
Node: Period expressions18254
Ref: #period-expressions18414
Node: Depth limiting22371
Ref: #depth-limiting22515
Node: Pivoting22857
Ref: #pivoting22975
Node: Cost24651
Ref: #cost24759
Node: Market value24877
Ref: #market-value25016
Node: More control over valuation26257
Ref: #more-control-over-valuation26442
Node: Effect of --value on reports28897
Ref: #effect-of---value-on-reports29116
Node: Some useful value reports31807
Ref: #some-useful-value-reports31986
Node: Combining -B -V --value32484
Ref: #combining--b--v---value32661
Node: Output destination32697
Ref: #output-destination32863
Node: Output format33146
Ref: #output-format33298
Node: Regular expressions33683
Ref: #regular-expressions33820
Node: QUERIES35181
Ref: #queries35283
Node: COMMANDS39245
Ref: #commands39357
Node: accounts40358
Ref: #accounts40456
Node: activity41155
Ref: #activity41265
Node: add41648
Ref: #add41747
Node: balance44334
Ref: #balance44445
Node: Classic balance report45887
Ref: #classic-balance-report46060
Node: Customising the classic balance report47429
Ref: #customising-the-classic-balance-report47657
Node: Colour support49733
Ref: #colour-support49900
Node: Flat mode50073
Ref: #flat-mode50221
Node: Depth limited balance reports50634
Ref: #depth-limited-balance-reports50834
Node: Multicolumn balance report51290
Ref: #multicolumn-balance-report51488
Node: Budget report56802
Ref: #budget-report56945
Node: Nested budgets62147
Ref: #nested-budgets62259
Ref: #output-format-165739
Node: balancesheet65817
Ref: #balancesheet65953
Node: balancesheetequity67268
Ref: #balancesheetequity67417
Node: cashflow67978
Ref: #cashflow68106
Node: check-dates69134
Ref: #check-dates69261
Node: check-dupes69540
Ref: #check-dupes69664
Node: close69957
Ref: #close70065
Node: files73479
Ref: #files73580
Node: help73727
Ref: #help73827
Node: import74920
Ref: #import75034
Node: Importing balance assignments75822
Ref: #importing-balance-assignments75970
Node: incomestatement76619
Ref: #incomestatement76753
Node: prices78089
Ref: #prices78204
Node: print78483
Ref: #print78593
Node: print-unique83086
Ref: #print-unique83212
Node: register83497
Ref: #register83624
Node: Custom register output87796
Ref: #custom-register-output87925
Node: register-match89187
Ref: #register-match89321
Node: rewrite89672
Ref: #rewrite89787
Node: Re-write rules in a file91642
Ref: #re-write-rules-in-a-file91776
Node: Diff output format92986
Ref: #diff-output-format93155
Node: rewrite vs print --auto94247
Ref: #rewrite-vs.-print---auto94426
Node: roi94982
Ref: #roi95080
Node: stats96092
Ref: #stats96191
Node: tags96945
Ref: #tags97043
Node: test97273
Ref: #test97357
Node: ADD-ON COMMANDS98118
Ref: #add-on-commands98228
Node: Official add-ons99516
Ref: #official-add-ons99656
Node: api99744
Ref: #api99833
Node: ui99885
Ref: #ui99984
Node: web100042
Ref: #web100131
Node: Third party add-ons100177
Ref: #third-party-add-ons100352
Node: diff100488
Ref: #diff100585
Node: iadd100684
Ref: #iadd100798
Node: interest100881
Ref: #interest101002
Node: irr101097
Ref: #irr101195
Node: Experimental add-ons101326
Ref: #experimental-add-ons101478
Node: autosync101759
Ref: #autosync101870
Node: chart102109
Ref: #chart102228
Node: check102299
Ref: #check102401
Node: EXAMPLES1885
Ref: #examples1985
Node: OPTIONS3631
Ref: #options3733
Node: General options4132
Ref: #general-options4257
Node: Command options6911
Ref: #command-options7062
Node: Command arguments7460
Ref: #command-arguments7614
Node: Argument files7735
Ref: #argument-files7911
Node: Special characters in arguments and queries8177
Ref: #special-characters-in-arguments-and-queries8411
Node: More escaping8862
Ref: #more-escaping9024
Node: Even more escaping9320
Ref: #even-more-escaping9514
Node: Less escaping10185
Ref: #less-escaping10347
Node: Command line tips10592
Ref: #command-line-tips10778
Node: Unicode characters11155
Ref: #unicode-characters11311
Node: Input files12723
Ref: #input-files12859
Node: Smart dates14788
Ref: #smart-dates14929
Node: Report start & end date16335
Ref: #report-start-end-date16507
Node: Report intervals17931
Ref: #report-intervals18096
Node: Period expressions18486
Ref: #period-expressions18646
Node: Depth limiting22603
Ref: #depth-limiting22747
Node: Pivoting23089
Ref: #pivoting23212
Node: Valuation24888
Ref: #valuation25017
Node: -B Cost25145
Ref: #b-cost25256
Node: -V Market value25454
Ref: #v-market-value25628
Node: -X Market value in specified commodity27034
Ref: #x-market-value-in-specified-commodity27254
Node: --value27594
Ref: #value27759
Node: Valuation type28560
Ref: #valuation-type28696
Node: Valuation commodity29581
Ref: #valuation-commodity29752
Node: --value examples30452
Ref: #value-examples30629
Node: Effect of --value on reports32612
Ref: #effect-of---value-on-reports32785
Node: Combining -B -V -X --value35476
Ref: #combining--b--v--x---value35638
Node: Output destination35674
Ref: #output-destination35826
Node: Output format36109
Ref: #output-format36261
Node: Regular expressions36646
Ref: #regular-expressions36783
Node: QUERIES38144
Ref: #queries38246
Node: COMMANDS42208
Ref: #commands42320
Node: accounts43321
Ref: #accounts43419
Node: activity44118
Ref: #activity44228
Node: add44611
Ref: #add44710
Node: balance47455
Ref: #balance47566
Node: Classic balance report49008
Ref: #classic-balance-report49181
Node: Customising the classic balance report50550
Ref: #customising-the-classic-balance-report50778
Node: Colour support52854
Ref: #colour-support53021
Node: Flat mode53194
Ref: #flat-mode53342
Node: Depth limited balance reports53755
Ref: #depth-limited-balance-reports53955
Node: Multicolumn balance report54411
Ref: #multicolumn-balance-report54609
Node: Budget report59923
Ref: #budget-report60066
Node: Nested budgets65268
Ref: #nested-budgets65380
Ref: #output-format-168860
Node: balancesheet68938
Ref: #balancesheet69074
Node: balancesheetequity70389
Ref: #balancesheetequity70538
Node: cashflow71099
Ref: #cashflow71227
Node: check-dates72255
Ref: #check-dates72382
Node: check-dupes72661
Ref: #check-dupes72785
Node: close73078
Ref: #close73186
Node: files76773
Ref: #files76874
Node: help77021
Ref: #help77121
Node: import78214
Ref: #import78328
Node: Importing balance assignments79116
Ref: #importing-balance-assignments79264
Node: incomestatement79913
Ref: #incomestatement80047
Node: prices81383
Ref: #prices81498
Node: print81777
Ref: #print81887
Node: print-unique86380
Ref: #print-unique86506
Node: register86791
Ref: #register86918
Node: Custom register output91090
Ref: #custom-register-output91219
Node: register-match92481
Ref: #register-match92615
Node: rewrite92966
Ref: #rewrite93081
Node: Re-write rules in a file94936
Ref: #re-write-rules-in-a-file95070
Node: Diff output format96280
Ref: #diff-output-format96449
Node: rewrite vs print --auto97541
Ref: #rewrite-vs.-print---auto97720
Node: roi98276
Ref: #roi98374
Node: stats99386
Ref: #stats99485
Node: tags100273
Ref: #tags100371
Node: test100665
Ref: #test100749
Node: ADD-ON COMMANDS101510
Ref: #add-on-commands101620
Node: Official add-ons102908
Ref: #official-add-ons103048
Node: api103136
Ref: #api103225
Node: ui103277
Ref: #ui103376
Node: web103434
Ref: #web103523
Node: Third party add-ons103569
Ref: #third-party-add-ons103744
Node: diff103880
Ref: #diff103977
Node: iadd104076
Ref: #iadd104190
Node: interest104273
Ref: #interest104394
Node: irr104489
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

925
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff