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

;doc: regen man pages

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

17
hledger-lib/hledger_csv.5
View File

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

84
hledger-lib/hledger_csv.info
View File

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

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

17
hledger-lib/hledger_csv.txt
View File

@ -134,6 +134,9 @@ CSV RULES
Field assignments can be used instead of or in addition to a field Field assignments can be used instead of or in addition to a field
list. list.
Note, interpolation strips any outer whitespace, so a CSV value like "
1 " becomes 1 when interpolated (#1051).
conditional block conditional block
if PATTERN if PATTERN
FIELDASSIGNMENTS... FIELDASSIGNMENTS...
@ -236,6 +239,18 @@ CSV TIPS
rules file for each. Note if you use the --rules-file option, this one rules file for each. Note if you use the --rules-file option, this one
rules file will be used for all the CSV files being read. rules file will be used for all the CSV files being read.
Valid CSV
hledger follows RFC 4180, with the addition of a customisable separator
character.
Some things to note:
When quoting fields,
o you must use double quotes, not single quotes
o spaces outside the quotes are not allowed.
REPORTING BUGS REPORTING BUGS
@ -261,4 +276,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger_csv(5) hledger 1.15 August 2019 hledger_csv(5)

113
hledger-lib/hledger_journal.5
View File

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

369
hledger-lib/hledger_journal.info
View File

@ -4,8 +4,8 @@ stdin.
 
File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_journal(5) hledger 1.14.99 hledger_journal(5) hledger 1.15
********************************** *******************************
hledger's usual data source is a plain text file containing journal hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard entries in hledger journal format. This file represents a standard
@ -307,10 +307,11 @@ File: hledger_journal.info, Node: Payee and note, Up: Description
1.5.1 Payee and note 1.5.1 Payee and note
-------------------- --------------------
You can optionally include a '|' (pipe) character in a description to You can optionally include a '|' (pipe) character in descriptions to
subdivide it into a payee/payer name on the left and additional notes on subdivide the description into separate fields for payee/payer name on
the right. This may be worthwhile if you need to do more precise the left (up to the first '|') and an additional note field on the right
querying and pivoting by payee. (after the first '|'). This may be worthwhile if you need to do more
precise querying and pivoting by payee or by note.
 
File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT
@ -991,8 +992,9 @@ File: hledger_journal.info, Node: Declaring commodities, Next: Default commodi
---------------------------- ----------------------------
The 'commodity' directive declares commodities which may be used in the The 'commodity' directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written on journal, and their display format.
a single line, like this:
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -1014,13 +1016,19 @@ places:
commodity INR commodity INR
format INR 9,99,99,999.00 format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard Declaring commodites may be useful as documentation, but currently we
display format for amounts in the commodity. Normally the display do not enforce that only declared commodities may be used. This
format is inferred from journal entries, but this can be unpredictable; directive is mainly useful for customising the preferred display format
declaring it with a commodity directive overrides this and removes for a commodity.
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0 Normally the display format is inferred from journal entries, but
or more decimal digits). this can be unpredictable; declaring it with a commodity directive
overrides this and removes ambiguity. Towards this end, amounts in
commodity directives must always be written with a decimal point (a
period or comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
 
File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
@ -1257,7 +1265,7 @@ hledger-web.
* Basic aliases:: * Basic aliases::
* Regex aliases:: * Regex aliases::
* Multiple aliases:: * Combining aliases::
* end aliases:: * end aliases::
 
@ -1284,7 +1292,7 @@ alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
 
File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.8.2 Regex aliases 1.14.8.2 Regex aliases
...................... ......................
@ -1309,23 +1317,44 @@ command line, to end of option argument), so it can contain trailing
whitespace. whitespace.
 
File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Combining aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.8.3 Multiple aliases 1.14.8.3 Combining aliases
......................... ..........................
You can define as many aliases as you like using directives or You can define as many aliases as you like, using journal directives
command-line options. Aliases are recursive - each alias sees the and/or command line options.
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
1. alias directives, most recently seen first (recent directives take Recursive aliases - where an account name is rewritten by one alias,
precedence over earlier ones; directives not yet seen are ignored) then by another alias, and so on - are allowed. Each alias sees the
2. alias options, in the order they appear on the command line effect of previously applied aliases.
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. 'alias' directives preceding the journal entry, most recently
parsed first (ie, reading upward from the journal entry, bottom to
top)
2. '--alias' options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
* the nearest alias declaration before/above the entry is applied
first
* the next alias before/above that will be be applied next, and so on
* aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps
provide semantic stability - aliases will keep working the same way
independent of which files are being read and in which order.
In case of trouble, adding '--debug=6' to the command line will show
which aliases are being applied when.
 
File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts File: hledger_journal.info, Node: end aliases, Prev: Combining aliases, Up: Rewriting accounts
1.14.8.4 'end aliases' 1.14.8.4 'end aliases'
...................... ......................
@ -1437,8 +1466,18 @@ File: hledger_journal.info, Node: Forecasting with periodic transactions, Next
With the '--forecast' flag, each periodic transaction rule generates With the '--forecast' flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named 'recur', whose value is normal transactions, but with an extra tag:
the generating period expression.
* 'generated-transaction:~ PERIODICEXPR' - shows that this was
generated by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
* '_generated-transaction:~ PERIODICEXPR'
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
Forecast transactions start on the first occurrence, and end on the Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The last occurrence, of their interval within the forecast period. The
@ -1493,16 +1532,16 @@ File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev:
1.16 Auto postings / transaction modifiers 1.16 Auto postings / transaction modifiers
========================================== ==========================================
Transaction modifier rules describe changes to be applied automatically Transaction modifier rules, AKA auto posting rules, describe changes to
to certain matched transactions. Currently just one kind of change is be applied automatically to certain matched transactions. Currently
possible - adding extra postings, which we call "automated postings" or just one kind of change is possible - adding extra postings, which we
just "auto postings". These rules become active when you use the call "automated postings" or just "auto postings". These rules become
'--auto' flag. active when you use the '--auto' flag.
A transaction modifier, AKA auto posting rule, looks much like a A transaction modifier rule looks much like a normal transaction
normal transaction except the first line is an equals sign followed by a except the first line is an equals sign followed by a query that matches
query that matches certain postings (mnemonic: '=' suggests matching). certain postings (mnemonic: '=' suggests matching). And each "posting"
And each "posting" is actually a posting-generating rule: is actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCT AMT
@ -1560,12 +1599,24 @@ $ hledger print --auto
* Menu: * Menu:
* Auto postings and dates::
* Auto postings and transaction balancing / inferred amounts / balance assertions:: * Auto postings and transaction balancing / inferred amounts / balance assertions::
* Auto posting tags::
 
File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
1.16.1 Auto postings and transaction balancing / inferred amounts / 1.16.1 Auto postings and dates
------------------------------
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also be
used in the generated posting.

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

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

137
hledger-lib/hledger_journal.txt
View File

@ -229,10 +229,11 @@ FILE FORMAT
comments. comments.
Payee and note Payee and note
You can optionally include a | (pipe) character in a description to You can optionally include a | (pipe) character in descriptions to sub-
subdivide it into a payee/payer name on the left and additional notes divide the description into separate fields for payee/payer name on the
on the right. This may be worthwhile if you need to do more precise left (up to the first |) and an additional note field on the right
querying and pivoting by payee. (after the first |). This may be worthwhile if you need to do more
precise querying and pivoting by payee or by note.
Account names Account names
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
@ -666,13 +667,12 @@ FILE FORMAT
tive directive rec- 2018/06) tive directive rec- 2018/06)
tives tives
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
account any document account names, all entries in all account any document account names, all entries in all
text declare account types & dis- files, before or text declare account types & dis- files, before or
play order after play order after
alias end rewrite account names following alias end rewrite account names following
aliases inline/included aliases inline/included
entries until end entries until end
@ -784,8 +784,9 @@ FILE FORMAT
Declaring commodities Declaring commodities
The commodity directive declares commodities which may be used in the The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written journal, and their display format.
on a single line, like this:
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -807,13 +808,19 @@ FILE FORMAT
commodity INR commodity INR
format INR 9,99,99,999.00 format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard Declaring commodites may be useful as documentation, but currently we
display format for amounts in the commodity. Normally the display for- do not enforce that only declared commodities may be used. This direc-
mat is inferred from journal entries, but this can be unpredictable; tive is mainly useful for customising the preferred display format for
declaring it with a commodity directive overrides this and removes a commodity.
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by Normally the display format is inferred from journal entries, but this
0 or more decimal digits). can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity. Towards this end, amounts in commodity
directives must always be written with a decimal point (a period or
comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.
Default commodity Default commodity
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity (and display format), to be
@ -1047,17 +1054,38 @@ FILE FORMAT
line, to end of option argument), so it can contain trailing white- line, to end of option argument), so it can contain trailing white-
space. space.
Multiple aliases Combining aliases
You can define as many aliases as you like using directives or command- You can define as many aliases as you like, using journal directives
line options. Aliases are recursive - each alias sees the result of and/or command line options.
applying previous ones. (This is different from Ledger, where aliases
are non-recursive by default). Aliases are applied in the following
order:
1. alias directives, most recently seen first (recent directives take Recursive aliases - where an account name is rewritten by one alias,
precedence over earlier ones; directives not yet seen are ignored) then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases.
2. alias options, in the order they appear on the command line In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. alias directives preceding the journal entry, most recently parsed
first (ie, reading upward from the journal entry, bottom to top)
2. --alias options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
o the nearest alias declaration before/above the entry is applied first
o the next alias before/above that will be be applied next, and so on
o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order.
In case of trouble, adding --debug=6 to the command line will show
which aliases are being applied when.
end aliases end aliases
You can clear (forget) all currently defined aliases with the end You can clear (forget) all currently defined aliases with the end
@ -1141,8 +1169,18 @@ FILE FORMAT
With the --forecast flag, each periodic transaction rule generates With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is normal transactions, but with an extra tag:
the generating period expression.
o generated-transaction:~ PERIODICEXPR - shows that this was generated
by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
o _generated-transaction:~ PERIODICEXPR
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
Forecast transactions start on the first occurrence, and end on the Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The last occurrence, of their interval within the forecast period. The
@ -1189,16 +1227,16 @@ FILE FORMAT
Auto postings / transaction modifiers Auto postings / transaction modifiers
Transaction modifier rules describe changes to be applied automatically Transaction modifier rules, AKA auto posting rules, describe changes to
to certain matched transactions. Currently just one kind of change is be applied automatically to certain matched transactions. Currently
possible - adding extra postings, which we call "automated postings" or just one kind of change is possible - adding extra postings, which we
just "auto postings". These rules become active when you use the call "automated postings" or just "auto postings". These rules become
--auto flag. active when you use the --auto flag.
A transaction modifier, AKA auto posting rule, looks much like a normal A transaction modifier rule looks much like a normal transaction except
transaction except the first line is an equals sign followed by a query the first line is an equals sign followed by a query that matches cer-
that matches certain postings (mnemonic: = suggests matching). And tain postings (mnemonic: = suggests matching). And each "posting" is
each "posting" is actually a posting-generating rule: actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCT AMT
@ -1257,6 +1295,11 @@ FILE FORMAT
assets:checking:gifts -$20 assets:checking:gifts -$20
assets:checking $20 assets:checking $20
Auto postings and dates
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also
be used in the generated posting.
Auto postings and transaction balancing / inferred amounts / balance asser- Auto postings and transaction balancing / inferred amounts / balance asser-
tions tions
Currently, transaction modifiers are applied / auto postings are added: Currently, transaction modifiers are applied / auto postings are added:
@ -1270,6 +1313,24 @@ FILE FORMAT
after auto postings are added. This changed in hledger 1.12+; see #893 after auto postings are added. This changed in hledger 1.12+; see #893
for background. for background.
Auto posting tags
Postings added by transaction modifiers will have some extra tags:
o generated-posting:= QUERY - shows this was generated by an auto post-
ing rule, and the query
o _generated-posting:= QUERY - a hidden tag, which does not appear in
hledger's output. This can be used to match postings generated "just
now", rather than generated in the past and saved to the journal.
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
o modified: - this transaction was modified
o _modified: - a hidden tag not appearing in the comment; this transac-
tion was modified "just now".
EDITOR SUPPORT EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and journal files easier. They add colour, formatting, tab completion, and
@ -1304,4 +1365,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger_journal(5) hledger 1.15 August 2019 hledger_journal(5)

2
hledger-lib/hledger_timeclock.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger_timeclock" "5" "August 2019" "hledger 1.15" "hledger User Manuals"

4
hledger-lib/hledger_timeclock.info
View File

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

2
hledger-lib/hledger_timeclock.txt
View File

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

2
hledger-lib/hledger_timedot.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals" .TH "hledger_timedot" "5" "August 2019" "hledger 1.15" "hledger User Manuals"

8
hledger-lib/hledger_timedot.info
View File

@ -4,8 +4,8 @@ stdin.
 
File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir) File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_timedot(5) hledger 1.14.99 hledger_timedot(5) hledger 1.15
********************************** *******************************
Timedot is a plain text format for logging dated, categorised quantities Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. It is convenient for (of time, usually), supported by hledger. It is convenient for
@ -111,7 +111,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT814 Node: FILE FORMAT808
Ref: #file-format915 Ref: #file-format909
 
End Tag Table End Tag Table

2
hledger-lib/hledger_timedot.txt
View File

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

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

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

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

@ -3,8 +3,8 @@ This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.
 
File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-ui(1) hledger-ui 1.14.99 hledger-ui(1) hledger-ui 1.15
******************************** *****************************
hledger-ui is hledger's curses-style interface, providing an efficient hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some full-window text UI for viewing accounts and transactions, and some
@ -117,7 +117,7 @@ the data.
'-p --period=PERIODEXP' '-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
'--date2' '--date2'
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -399,19 +399,19 @@ to cancel the reload attempt.)
 
Tag Table: Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1107 Node: OPTIONS1101
Ref: #options1204 Ref: #options1198
Node: KEYS4623 Node: KEYS4589
Ref: #keys4718 Ref: #keys4684
Node: SCREENS7974 Node: SCREENS7940
Ref: #screens8059 Ref: #screens8025
Node: Accounts screen8149 Node: Accounts screen8115
Ref: #accounts-screen8277 Ref: #accounts-screen8243
Node: Register screen10493 Node: Register screen10459
Ref: #register-screen10648 Ref: #register-screen10614
Node: Transaction screen12644 Node: Transaction screen12610
Ref: #transaction-screen12802 Ref: #transaction-screen12768
Node: Error screen13672 Node: Error screen13638
Ref: #error-screen13794 Ref: #error-screen13760
 
End Tag Table End Tag Table

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

@ -114,7 +114,7 @@ OPTIONS
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
--date2 --date2
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -381,6 +381,9 @@ BUGS
siding, and possibly a small but persistent build-up of CPU usage until siding, and possibly a small but persistent build-up of CPU usage until
the program is restarted. the program is restarted.
Also, if you are viewing files mounted from another machine, --watch
requires that both machine clocks are roughly in step.
REPORTING BUGS REPORTING BUGS
@ -406,4 +409,4 @@ SEE ALSO
hledger-ui 1.14.99 March 2019 hledger-ui(1) hledger-ui 1.15 August 2019 hledger-ui(1)

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

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

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

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

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

@ -46,6 +46,10 @@ OPTIONS
--serve --serve
serve and log requests, don't browse or auto-exit serve and log requests, don't browse or auto-exit
--serve-api
like --serve, but serve only the JSON web API, without the
server-side web UI
--host=IPADDR --host=IPADDR
listen on this IP address (default: 127.0.0.1) listen on this IP address (default: 127.0.0.1)
@ -120,7 +124,7 @@ OPTIONS
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
--date2 --date2
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -184,7 +188,9 @@ OPTIONS
app will keep running for as long as you have it open in a browser win- app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML
server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host to local requests. You can use --host to change this, eg --host
@ -259,6 +265,9 @@ RELOADING
makes a file unparseable, hledger-web will display an error message makes a file unparseable, hledger-web will display an error message
until the file has been fixed. until the file has been fixed.
(Note: if you are viewing files mounted from another machine, make sure
that both machine clocks are roughly in step.)
JSON API JSON API
In addition to the web UI, hledger-web provides some API routes that In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. Currently these are same ones serve JSON in response to GET requests. Currently these are same ones
@ -297,6 +306,10 @@ JSON API
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
to serve the API.
ENVIRONMENT ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default: LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
@ -345,4 +358,4 @@ SEE ALSO
hledger-web 1.14.99 March 2019 hledger-web(1) hledger-web 1.15 August 2019 hledger-web(1)

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

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

218
hledger/hledger.1
View File

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

603
hledger/hledger.info
View File

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

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

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

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

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

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

191
hledger/hledger.txt
View File

@ -173,7 +173,7 @@ OPTIONS
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above) using period expressions syntax
--date2 --date2
match the secondary date instead (see command help for other match the secondary date instead (see command help for other
@ -368,10 +368,10 @@ OPTIONS
Reader: Reads: Used for file extensions: Reader: Reads: Used for file extensions:
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
journal hledger's journal format, also .journal .j .hledger journal hledger's journal format, also .journal .j .hledger .ledger
some Ledger journals .ledger some Ledger journals
timeclock timeclock files (precise time .timeclock time- timeclock files (precise time .timeclock
logging) clock logging)
timedot timedot files (approximate time .timedot timedot timedot files (approximate time .timedot
logging) logging)
csv comma-separated values (data .csv csv comma-separated values (data .csv
@ -449,9 +449,20 @@ OPTIONS
Often you will want to see a shorter time span, such as the current Often you will want to see a shorter time span, such as the current
month. You can specify a start and/or end date using -b/--begin, month. You can specify a start and/or end date using -b/--begin,
-e/--end, -p/--period or a date: query (described below). All of these -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 accept the smart date syntax.
specifying end dates: as in Ledger, end dates are exclusive, so you
need to write the date after the last day you want to include. Some notes:
o As in Ledger, end dates are exclusive, so you need to write the date
after the last day you want to include.
o As noted in reporting options: among start/end dates specified with
options, the last (i.e. right-most) option takes precedence.
o The effective report start and end dates are the intersection of the
start/end dates from options and that from date: queries. That is,
date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
smallest common time span.
Examples: Examples:
@ -462,9 +473,6 @@ OPTIONS
ber 1st of the current ber 1st of the current
year (11/30 will be the year (11/30 will be the
last date included) last date included)
-b thismonth all transactions on or -b thismonth all transactions on or
after the 1st of the cur- after the 1st of the cur-
rent month rent month
@ -482,7 +490,7 @@ OPTIONS
The basic intervals can be selected with one of -D/--daily, The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
plex intervals may be specified with a period expression. Report plex 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.
Period expressions Period expressions
The -p/--period option accepts period expressions, a shorthand way of The -p/--period option accepts period expressions, a shorthand way of
@ -531,7 +539,6 @@ OPTIONS
-p "2009/1" the month of jan; equiva- -p "2009/1" the month of jan; equiva-
lent to "2009/1/1 to lent to "2009/1/1 to
2009/2/1" 2009/2/1"
-p "2009/1/1" just that day; equivalent -p "2009/1/1" just that day; equivalent
to "2009/1/1 to 2009/1/2" to "2009/1/1 to 2009/1/2"
@ -598,7 +605,6 @@ OPTIONS
-p "every 2nd day of week" -- periods -p "every 2nd day of week" -- periods
will go from Tue to Tue will go from Tue to Tue
-p "every Tue" -- same -p "every Tue" -- same
-p "every 15th day" -- period bound- -p "every 15th day" -- period bound-
aries will be on 15th of each month aries will be on 15th of each month
-p "every 2nd Monday" -- period bound- -p "every 2nd Monday" -- period bound-
@ -678,15 +684,32 @@ OPTIONS
-------------------- --------------------
-2 EUR -2 EUR
Cost Valuation
The -B/--cost flag converts amounts to their cost at transaction time, -B: Cost
if they have a transaction price specified. 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.
Market value -V: Market value
The -V/--market flag converts reported amounts to their market value in The -V/--market flag converts reported amounts to their market value in
another commodity. It uses the commodity referenced in the latest mar- a default valuation commodity, using the historical market prices in
ket price (P directive) dated on or before the valuation date. The effect on a default valuation date.
default valuation date is today. For example:
For single period reports, the valuation date is today. For multi-
period reports, it is the last day of each subperiod.
The valuation commodity will be the one referenced in the latest appli-
cable market price dated on or before the valuation date. If most of
your P declarations lead to a single home currency, this will usually
be what you want.
Unlike the similar flag in Ledger, it does not infer market prices from
transaction prices. In hledger, -B uses transaction prices, -V and -X
use market prices.
It is equivalent to --value=now or --value=end.
Here's a quick example:
# one euro is worth this many dollars from nov 1 # one euro is worth this many dollars from nov 1
P 2016/11/01 EUR $1.10 P 2016/11/01 EUR $1.10
@ -715,42 +738,68 @@ OPTIONS
$ hledger -f t.j bal -N euros -V $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
Ledger users: Ledger's -V also infers market prices from journal -X: Market value in specified commodity
entries, but we don't do that. hledger's -V uses only market prices The -X/--exchange option is like -V/--market except it takes a commod-
declared explicitly, with P directives. (Mnemonic: -B/--cost uses ity symbol argument, so that you can select a different target commod-
transaction prices, -V/--market uses market prices.) ity. 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.
More control over valuation --value
(experimental, added 201905) (experimental, added 201905)
You can control valuation more precisely with the --value option. -B, -V and -X are special cases of the more general --value option:
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD --value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
The argument is one of the keywords shown, or their first letter, or a Valuation type
custom date. The precise effect of the keywords is command-specific, TYPE is one of these keywords, or their first letter, or a date (which
but here is their general meaning: must be 8 digits with - or / or . separators):
--value=cost (or c) --value=cost
Convert amounts to cost, using the prices recorded in transac- Convert amounts to cost, using the prices recorded in transac-
tions. -B/--cost does this. tions. -B/--cost is equivalent to this.
--value=end (or e) --value=end
Convert amounts to their value in default valuation commodity Convert amounts to their value in default valuation commodity
using market prices on the last day of the report period (or of using market prices on the last day of the report period (or of
each subperiod in a multiperiod report). When no report period each subperiod in a multiperiod report). When no report period
is specified, uses the journal's last transaction date. is specified, uses the journal's last transaction date.
--value=now (or n) --value=now
Convert amounts to their value in default valuation commodity Convert amounts to their value in default valuation commodity
using current market prices (as of when report is generated). using current market prices (as of when report is generated).
-V/--market does this. -V/--market is equivalent to this.
--value=YYYY-MM-DD --value=YYYY-MM-DD
Convert amounts to their value in default valuation commodity Convert amounts to their value in default valuation commodity
using market prices on the given date (which must be 8 digits using market prices on this date. Eg --value=2019-04-25.
with - or / or . separators). Eg --value=2019-04-25.
Valuation commodity
The default valuation commodity is the commodity mentioned in the most
recent applicable market price declaration. When all your price decla-
rations 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:
o declared prices (from source commodity to valuation commodity)
o reverse prices (declared prices from valuation to source commodity,
inverted)
o indirect prices (prices calculated from the shortest chain of
declared or reverse prices from source to valuation commodity).
--value examples
Here are the effects of --value as seen with print: Here are the effects of --value as seen with print:
P 2000-01-01 A 1 B P 2000-01-01 A 1 B
@ -825,6 +874,38 @@ OPTIONS
2000/03/01 2000/03/01
(a) 1 B (a) 1 B
You may need to explicitly set a commodity's display style, when
reverse prices are used. Eg this output might be surprising:
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 specify-
ing a display style for A, 0.5A gets the default style, which shows no
decimal digits. Because the displayed amount looks like zero, the com-
modity symbol and minus sign are not displayed either. Adding a com-
modity 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
Effect of --value on reports Effect of --value on reports
Below is how --value affects each of hledger's reports, currently. Below is how --value affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a You're not expected to remember all this, but when troubleshooting a
@ -856,6 +937,9 @@ OPTIONS
values values
balance (bs, balance (bs,
cf, is..) cf, is..)
starting bal- costs of market value at day market value at starting bal- costs of market value at day market value at
ances with -H starting bal- before report start of DATE of sum of ances with -H starting bal- before report start of DATE of sum of
ances sum of previous postings previous postings ances sum of previous postings previous postings
@ -868,27 +952,12 @@ OPTIONS
budget costs of bud- budget-setting periodic budget-setting budget costs of bud- budget-setting periodic budget-setting
amounts with get amounts txns are valued at period periodic txns are amounts with get amounts txns are valued at period periodic txns are
--budget end valued at DATE --budget end valued at DATE
col- sum/average of market value at period market value at col- sum/average of market value at period market value at
umn/row/grand the displayed end of sum/average of DATE of sum/aver- umn/row/grand the displayed end of sum/average of DATE of sum/aver-
totals/aver- values postings age of postings totals/aver- values postings age of postings
ages ages
Some useful value reports Combining -B, -V, -X, --value
Here are some probably useful reports - please send suggestions if you
find out more:
Command: Description of report: Could answer:
-----------------------------------------------------------------------------
hledger bs -M Monthly historical value of How are my investments
--value=p assets/liabilities performing ?
hledger is -M Monthly contemporaneous How much foreign currency
--value=t value of revenues/expenses have I been spending ?
Combining -B, -V, --value
The rightmost of these flags wins. The rightmost of these flags wins.
Output destination Output destination
@ -1185,6 +1254,10 @@ COMMANDS
Starting the next transaction (. or ctrl-D/ctrl-C to quit) Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $ Date [2015/05/22]: <CTRL-D> $
On Microsoft Windows, the add command makes sure that no part of the
file path ends with a period, as it can cause data loss on that plat-
form (cf #1056).
balance balance
balance, bal, b balance, bal, b
Show accounts and their balances. Show accounts and their balances.
@ -1826,6 +1899,10 @@ COMMANDS
run this command with --auto, the balance assertions will probably run this command with --auto, the balance assertions will probably
always require --auto. 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: Examples:
Carrying asset/liability balances into a new file for 2019, all from Carrying asset/liability balances into a new file for 2019, all from
@ -2384,6 +2461,7 @@ COMMANDS
Payees/descriptions : 5 Payees/descriptions : 5
Accounts : 8 (depth 3) Accounts : 8 (depth 3)
Commodities : 1 ($) Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format selec- This command also supports output destination and output format selec-
tion. tion.
@ -2393,7 +2471,8 @@ COMMANDS
List all the tag names used in the journal. With a TAGREGEX argument, List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are shown. With QUERY arguments, only transactions matching the query are
considered. considered. With --values flag, the tags' unique values are listed
instead.
test test
test test
@ -2612,4 +2691,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger(1) hledger 1.15 August 2019 hledger(1)