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

;doc: regen man pages

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

17
hledger-lib/hledger_csv.5
View File

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

84
hledger-lib/hledger_csv.info
View File

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

File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)
hledger_csv(5) hledger 1.14.99
******************************
hledger_csv(5) hledger 1.15
***************************
hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a
@ -171,6 +171,9 @@ comment note: %somefield - %anotherfield, date: %1
Field assignments can be used instead of or in addition to a field
list.
Note, interpolation strips any outer whitespace, so a CSV value like
'" 1 "' becomes '1' when interpolated (#1051).

File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES
@ -248,6 +251,7 @@ File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
* CSV amounts::
* CSV balance assertions/assignments::
* Reading multiple CSV files::
* Valid CSV::

File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS
@ -317,7 +321,7 @@ assignment), on the first or second posting, whenever the running
balance field is non-empty. (TODO: #1000)

File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions/assignments, Up: CSV TIPS
File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid CSV, Prev: CSV balance assertions/assignments, Up: CSV TIPS
2.5 Reading multiple CSV files
==============================
@ -327,36 +331,54 @@ the command line, and hledger will look for a correspondingly-named
rules file for each. Note if you use the '--rules-file' option, this
one rules file will be used for all the CSV files being read.

File: hledger_csv.info, Node: Valid CSV, Prev: Reading multiple CSV files, Up: CSV TIPS
2.6 Valid CSV
=============
hledger follows RFC 4180, with the addition of a customisable separator
character.
Some things to note:
When quoting fields,
* you must use double quotes, not single quotes
* spaces outside the quotes are not allowed.

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

End Tag Table

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

113
hledger-lib/hledger_journal.5
View File

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

369
hledger-lib/hledger_journal.info
View File

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

File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_journal(5) hledger 1.14.99
**********************************
hledger_journal(5) hledger 1.15
*******************************
hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard
@ -307,10 +307,11 @@ File: hledger_journal.info, Node: Payee and note, Up: Description
1.5.1 Payee and note
--------------------
You can optionally include a '|' (pipe) character in a description to
subdivide it into a payee/payer name on the left and additional notes on
the right. This may be worthwhile if you need to do more precise
querying and pivoting by payee.
You can optionally include a '|' (pipe) character in descriptions to
subdivide the description into separate fields for payee/payer name on
the left (up to the first '|') and an additional note field on the right
(after the first '|'). This may be worthwhile if you need to do more
precise querying and pivoting by payee or by note.

File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT
@ -991,8 +992,9 @@ File: hledger_journal.info, Node: Declaring commodities, Next: Default commodi
----------------------------
The 'commodity' directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written on
a single line, like this:
journal, and their display format.
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -1014,13 +1016,19 @@ places:
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display
format is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0
or more decimal digits).
Declaring commodites may be useful as documentation, but currently we
do not enforce that only declared commodities may be used. This
directive is mainly useful for customising the preferred display format
for a commodity.
Normally the display format is inferred from journal entries, but
this can be unpredictable; declaring it with a commodity directive
overrides this and removes ambiguity. Towards this end, amounts in
commodity directives must always be written with a decimal point (a
period or comma, followed by 0 or more decimal digits).
Commodity directives do not affect how amounts are parsed; the parser
will read multiple formats.

File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
@ -1257,7 +1265,7 @@ hledger-web.
* Basic aliases::
* Regex aliases::
* Multiple aliases::
* Combining aliases::
* end aliases::

@ -1284,7 +1292,7 @@ alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts
File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.8.2 Regex aliases
......................
@ -1309,23 +1317,44 @@ command line, to end of option argument), so it can contain trailing
whitespace.

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
File: hledger_journal.info, Node: Combining aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.8.3 Multiple aliases
.........................
1.14.8.3 Combining aliases
..........................
You can define as many aliases as you like using directives or
command-line options. Aliases are recursive - each alias sees the
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
You can define as many aliases as you like, using journal directives
and/or command line options.
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases.
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. 'alias' directives preceding the journal entry, most recently
parsed first (ie, reading upward from the journal entry, bottom to
top)
2. '--alias' options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
* the nearest alias declaration before/above the entry is applied
first
* the next alias before/above that will be be applied next, and so on
* aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps
provide semantic stability - aliases will keep working the same way
independent of which files are being read and in which order.
In case of trouble, adding '--debug=6' to the command line will show
which aliases are being applied when.

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts
File: hledger_journal.info, Node: end aliases, Prev: Combining aliases, Up: Rewriting accounts
1.14.8.4 'end aliases'
......................
@ -1437,8 +1466,18 @@ File: hledger_journal.info, Node: Forecasting with periodic transactions, Next
With the '--forecast' flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named 'recur', whose value is
the generating period expression.
normal transactions, but with an extra tag:
* 'generated-transaction:~ PERIODICEXPR' - shows that this was
generated by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
* '_generated-transaction:~ PERIODICEXPR'
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
@ -1493,16 +1532,16 @@ File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev:
1.16 Auto postings / transaction modifiers
==========================================
Transaction modifier rules describe changes to be applied automatically
to certain matched transactions. Currently just one kind of change is
possible - adding extra postings, which we call "automated postings" or
just "auto postings". These rules become active when you use the
'--auto' flag.
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
active when you use the '--auto' flag.
A transaction modifier, AKA auto posting rule, looks much like a
normal transaction except the first line is an equals sign followed by a
query that matches certain postings (mnemonic: '=' suggests matching).
And each "posting" is actually a posting-generating rule:
A transaction modifier rule looks much like a normal transaction
except the first line is an equals sign followed by a query that matches
certain postings (mnemonic: '=' suggests matching). And each "posting"
is actually a posting-generating rule:
= QUERY
ACCT AMT
@ -1560,12 +1599,24 @@ $ hledger print --auto
* Menu:
* Auto postings and dates::
* Auto postings and transaction balancing / inferred amounts / balance assertions::
* Auto posting tags::

File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
1.16.1 Auto postings and transaction balancing / inferred amounts /
1.16.1 Auto postings and dates
------------------------------
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also be
used in the generated posting.

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

File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
1.16.3 Auto posting tags
------------------------
Postings added by transaction modifiers will have some extra tags:
* 'generated-posting:= QUERY' - shows this was generated by an auto
posting rule, and the query
* '_generated-posting:= QUERY' - a hidden tag, which does not appear
in hledger's output. This can be used to match postings generated
"just now", rather than generated in the past and saved to the
journal.
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
* 'modified:' - this transaction was modified
* '_modified:' - a hidden tag not appearing in the comment; this
transaction was modified "just now".

File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
@ -1595,109 +1668,113 @@ See the [[Cookbook]] at hledger.org for the latest information.

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

End Tag Table

137
hledger-lib/hledger_journal.txt
View File

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

2
hledger-lib/hledger_timeclock.txt
View File

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

2
hledger-lib/hledger_timedot.5
View File

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

8
hledger-lib/hledger_timedot.info
View File

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

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

Tag Table:
Node: Top76
Node: FILE FORMAT814
Ref: #file-format915
Node: FILE FORMAT808
Ref: #file-format909

End Tag Table

2
hledger-lib/hledger_timedot.txt
View File

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

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

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

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

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

File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-ui(1) hledger-ui 1.14.99
********************************
hledger-ui(1) hledger-ui 1.15
*****************************
hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some
@ -117,7 +117,7 @@ the data.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above)
using period expressions syntax
'--date2'
match the secondary date instead (see command help for other
@ -399,19 +399,19 @@ to cancel the reload attempt.)

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

End Tag Table

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

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

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

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

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

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

File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-web(1) hledger-web 1.14.99
**********************************
hledger-web(1) hledger-web 1.15
*******************************
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens
@ -50,6 +50,10 @@ before options, as shown in the synopsis above.
'--serve'
serve and log requests, don't browse or auto-exit
'--serve-api'
like -serve, but serve only the JSON web API, without the
server-side web UI
'--host=IPADDR'
listen on this IP address (default: 127.0.0.1)
@ -127,7 +131,7 @@ before options, as shown in the synopsis above.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above)
using period expressions syntax
'--date2'
match the secondary date instead (see command help for other
@ -193,7 +197,9 @@ also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console.
app without exiting, and logs requests to the console. With
'--serve-api', only the JSON web api (see below) is served, with the
usual HTML server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
@ -282,6 +288,9 @@ when you reload the page or navigate to a new page. If a change makes a
file unparseable, hledger-web will display an error message until the
file has been fixed.
(Note: if you are viewing files mounted from another machine, make
sure that both machine clocks are roughly in step.)

File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top
@ -325,18 +334,22 @@ $ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readabl
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served.
Running with '--serve-api' disables the former, useful if you only want
to serve the API.

Tag Table:
Node: Top72
Node: OPTIONS1361
Ref: #options1466
Node: PERMISSIONS6556
Ref: #permissions6695
Node: EDITING UPLOADING DOWNLOADING7907
Ref: #editing-uploading-downloading8088
Node: RELOADING8922
Ref: #reloading9056
Node: JSON API9366
Ref: #json-api9460
Node: OPTIONS1355
Ref: #options1460
Node: PERMISSIONS6739
Ref: #permissions6878
Node: EDITING UPLOADING DOWNLOADING8090
Ref: #editing-uploading-downloading8271
Node: RELOADING9105
Ref: #reloading9239
Node: JSON API9672
Ref: #json-api9766

End Tag Table

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

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

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

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

218
hledger/hledger.1
View File

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

599
hledger/hledger.info
View File

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

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
hledger(1) hledger 1.14.99
**************************
hledger(1) hledger 1.15
***********************
This is hledger's command-line interface (there are also curses and web
interfaces). Its basic function is to read a plain text file describing
@ -130,9 +130,7 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Period expressions::
* Depth limiting::
* Pivoting::
* Cost::
* Market value::
* Combining -B -V --value::
* Valuation::
* Output destination::
* Output format::
* Regular expressions::
@ -209,7 +207,7 @@ by most hledger commands, run 'hledger -h'.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above)
using period expressions syntax
'--date2'
match the secondary date instead (see command help for other
@ -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:
Reader: Reads: Used for file extensions:
----------------------------------------------------------------------------
'journal' hledger's journal format, also '.journal' '.j'
some Ledger journals '.hledger' '.ledger'
---------------------------------------------------------------------------
'journal'hledger's journal format, also '.journal' '.j' '.hledger'
some Ledger journals '.ledger'
'timeclock'timeclock files (precise time '.timeclock'
logging)
'timedot' timedot files (approximate time '.timedot'
logging)
'timedot'timedot files (approximate '.timedot'
time logging)
'csv' comma-separated values (data '.csv'
interchange)
@ -530,9 +528,18 @@ the journal.
Often you will want to see a shorter time span, such as the current
month. You can specify a start and/or end date using '-b/--begin',
'-e/--end', '-p/--period' or a 'date:' query (described below). All of
these accept the smart date syntax. One important thing to be aware of
when specifying end dates: as in Ledger, end dates are exclusive, so you
need to write the date _after_ the last day you want to include.
these accept the smart date syntax.
Some notes:
* As in Ledger, end dates are exclusive, so you need to write the
date _after_ the last day you want to include.
* As noted in reporting options: among start/end dates specified with
_options_, the last (i.e. right-most) option takes precedence.
* The effective report start and end dates are the intersection of
the start/end dates from options and that from 'date:' queries.
That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January
2019, the smallest common time span.
Examples:
@ -556,7 +563,7 @@ balance and activity will divide their reports into multiple subperiods.
The basic intervals can be selected with one of '-D/--daily',
'-W/--weekly', '-M/--monthly', '-Q/--quarterly', or '-Y/--yearly'. More
complex intervals may be specified with a period expression. Report
intervals can not be specified with a query, currently.
intervals can not be specified with a query.

File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS
@ -679,7 +686,7 @@ less detail. This flag has the same effect as a 'depth:' query argument
(so '-2', '--depth=2' or 'depth:2' are basically equivalent).

File: hledger.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS
File: hledger.info, Node: Pivoting, Next: Valuation, Prev: Depth limiting, Up: OPTIONS
2.14 Pivoting
=============
@ -736,24 +743,54 @@ $ hledger balance --pivot member acct:.
-2 EUR

File: hledger.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS
File: hledger.info, Node: Valuation, Next: Output destination, Prev: Pivoting, Up: OPTIONS
2.15 Cost
=========
2.15 Valuation
==============
The '-B/--cost' flag converts amounts to their cost at transaction time,
if they have a transaction price specified.
* Menu:
* -B Cost::
* -V Market value::
* -X Market value in specified commodity::
* --value::
* Combining -B -V -X --value::

File: hledger.info, Node: Market value, Next: Combining -B -V --value, Prev: Cost, Up: OPTIONS
File: hledger.info, Node: -B Cost, Next: -V Market value, Up: Valuation
2.16 Market value
=================
2.15.1 -B: Cost
---------------
The '-B/--cost' flag converts amounts to their cost (or selling price)
at transaction time, if they have a transaction price specified. This
flag is equivalent to '--value=cost', described below.

File: hledger.info, Node: -V Market value, Next: -X Market value in specified commodity, Prev: -B Cost, Up: Valuation
2.15.2 -V: Market value
-----------------------
The '-V/--market' flag converts reported amounts to their market value
in another commodity. It uses the commodity referenced in the latest
market price (P directive) dated on or before the valuation date. The
default valuation date is today. For example:
in a default valuation commodity, using the historical market prices in
effect on a default valuation date.
For single period reports, the valuation date is today. For
multiperiod reports, it is the last day of each subperiod.
The valuation commodity will be the one referenced in the latest
applicable market price dated on or before the valuation date. If most
of your P declarations lead to a single home currency, this will usually
be what you want.
Unlike the similar flag in Ledger, it does not infer market prices
from transaction prices. In hledger, -B uses transaction prices, -V and
-X use market prices.
It is equivalent to '--value=now' or '--value=end'.
Here's a quick example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
@ -782,53 +819,99 @@ specified, defaults to today)
$ hledger -f t.j bal -N euros -V
$103.00 assets:euros
Ledger users: Ledger's -V also infers market prices from journal
entries, but we don't do that. hledger's -V uses only market prices
declared explicitly, with P directives. (Mnemonic: -B/-cost uses
transaction prices, -V/-market uses market prices.)

File: hledger.info, Node: -X Market value in specified commodity, Next: --value, Prev: -V Market value, Up: Valuation
* Menu:
2.15.3 -X: Market value in specified commodity
----------------------------------------------
* More control over valuation::
* Effect of --value on reports::
* Some useful value reports::
The '-X/--exchange' option is like '-V/--market' except it takes a
commodity symbol argument, so that you can select a different target
commodity. It is similar to the same option in Ledger, with the same
caveat mentioned for '-V'/'--value' above. It is equivalent to
'--value=now,COMM' or '--value=end,COMM'; for more details, read on.

File: hledger.info, Node: More control over valuation, Next: Effect of --value on reports, Up: Market value
File: hledger.info, Node: --value, Next: Combining -B -V -X --value, Prev: -X Market value in specified commodity, Up: Valuation
2.16.1 More control over valuation
----------------------------------
2.15.4 -value
-------------
_(experimental, added 201905)_
You can control valuation more precisely with the '--value' option.
'-B', '-V' and '-X' are special cases of the more general '--value'
option:
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD
--value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
The argument is one of the keywords shown, or their first letter, or
a custom date. The precise effect of the keywords is command-specific,
but here is their general meaning:
* Menu:
'--value=cost' (or 'c')
* Valuation type::
* Valuation commodity::
* --value examples::
* Effect of --value on reports::

File: hledger.info, Node: Valuation type, Next: Valuation commodity, Up: --value
2.15.4.1 Valuation type
.......................
TYPE is one of these keywords, or their first letter, or a date (which
must be 8 digits with '-' or '/' or '.' separators):
'--value=cost'
Convert amounts to cost, using the prices recorded in transactions.
'-B'/'--cost' does this.
'--value=end' (or 'e')
'-B'/'--cost' is equivalent to this.
'--value=end'
Convert amounts to their value in default valuation commodity using
market prices on the last day of the report period (or of each
subperiod in a multiperiod report). When no report period is
specified, uses the journal's last transaction date.
'--value=now' (or 'n')
'--value=now'
Convert amounts to their value in default valuation commodity using
current market prices (as of when report is generated).
'-V'/'--market' does this.
'-V'/'--market' is equivalent to this.
'--value=YYYY-MM-DD'
Convert amounts to their value in default valuation commodity using
market prices on the given date (which must be 8 digits with '-' or
'/' or '.' separators). Eg '--value=2019-04-25'.
market prices on this date. Eg '--value=2019-04-25'.

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':
@ -905,11 +988,43 @@ $ hledger -f- print --value=2000-01-15
2000/03/01
(a) 1 B

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

File: hledger.info, Node: Effect of --value on reports, Prev: --value examples, Up: --value
2.15.4.4 Effect of -value on reports
....................................
Below is how '--value' affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a
@ -962,33 +1077,17 @@ totals/averagesof the end of sum/average of DATE of
values postings

File: hledger.info, Node: Some useful value reports, Prev: Effect of --value on reports, Up: Market value
File: hledger.info, Node: Combining -B -V -X --value, Prev: --value, Up: Valuation
2.16.3 Some useful value reports
--------------------------------
Here are some probably useful reports - please send suggestions if you
find out more:
Command: Description of report: Could answer:
---------------------------------------------------------------------------
'hledger bs -M Monthly historical value How are my investments
--value=p' of assets/liabilities performing ?
'hledger is -M Monthly contemporaneous How much foreign currency
--value=t' value of revenues/expenses have I been spending ?

File: hledger.info, Node: Combining -B -V --value, Next: Output destination, Prev: Market value, Up: OPTIONS
2.17 Combining -B, -V, -value
=============================
2.15.5 Combining -B, -V, -X, -value
-----------------------------------
The rightmost of these flags wins.

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

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

File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS
2.20 Regular expressions
2.18 Regular expressions
========================
hledger uses regular expressions in a number of places:
@ -1328,6 +1427,10 @@ Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $
On Microsoft Windows, the add command makes sure that no part of the
file path ends with a period, as it can cause data loss on that platform
(cf #1056).

File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS
@ -2055,6 +2158,10 @@ balance assertions will depend on these flags. Likewise, if you run
this command with -auto, the balance assertions will probably always
require -auto.
When account balances have cost information (transaction prices), the
closing/opening transactions will preserve it, so that eg balance -B
reports will not be affected.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
@ -2713,6 +2820,7 @@ Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 5
Accounts : 8 (depth 3)
Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format
selection.
@ -2727,7 +2835,8 @@ tags
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are
considered.
considered. With -values flag, the tags' unique values are listed
instead.

File: hledger.info, Node: test, Prev: tags, Up: COMMANDS
@ -2931,168 +3040,176 @@ hledger-check.hs checks more powerful account balance assertions.

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

End Tag Table

191
hledger/hledger.txt
View File

@ -173,7 +173,7 @@ OPTIONS
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above)
using period expressions syntax
--date2
match the secondary date instead (see command help for other
@ -368,10 +368,10 @@ OPTIONS
Reader: Reads: Used for file extensions:
-----------------------------------------------------------------------------
journal hledger's journal format, also .journal .j .hledger
some Ledger journals .ledger
timeclock timeclock files (precise time .timeclock
logging)
journal hledger's journal format, also .journal .j .hledger .ledger
some Ledger journals
time- timeclock files (precise time .timeclock
clock logging)
timedot timedot files (approximate time .timedot
logging)
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
month. You can specify a start and/or end date using -b/--begin,
-e/--end, -p/--period or a date: query (described below). All of these
accept the smart date syntax. One important thing to be aware of when
specifying end dates: as in Ledger, end dates are exclusive, so you
need to write the date after the last day you want to include.
accept the smart date syntax.
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:
@ -462,9 +473,6 @@ OPTIONS
ber 1st of the current
year (11/30 will be the
last date included)
-b thismonth all transactions on or
after the 1st of the cur-
rent month
@ -482,7 +490,7 @@ OPTIONS
The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
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
The -p/--period option accepts period expressions, a shorthand way of
@ -531,7 +539,6 @@ OPTIONS
-p "2009/1" the month of jan; equiva-
lent to "2009/1/1 to
2009/2/1"
-p "2009/1/1" just that day; equivalent
to "2009/1/1 to 2009/1/2"
@ -598,7 +605,6 @@ OPTIONS
-p "every 2nd day of week" -- periods
will go from Tue to Tue
-p "every Tue" -- same
-p "every 15th day" -- period bound-
aries will be on 15th of each month
-p "every 2nd Monday" -- period bound-
@ -678,15 +684,32 @@ OPTIONS
--------------------
-2 EUR
Cost
The -B/--cost flag converts amounts to their cost at transaction time,
if they have a transaction price specified.
Valuation
-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.
Market value
-V: Market value
The -V/--market flag converts reported amounts to their market value in
another commodity. It uses the commodity referenced in the latest mar-
ket price (P directive) dated on or before the valuation date. The
default valuation date is today. For example:
a default valuation commodity, using the historical market prices in
effect on a default valuation date.
For single period reports, the valuation date is today. For 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
P 2016/11/01 EUR $1.10
@ -715,42 +738,68 @@ OPTIONS
$ hledger -f t.j bal -N euros -V
$103.00 assets:euros
Ledger users: Ledger's -V also infers market prices from journal
entries, but we don't do that. hledger's -V uses only market prices
declared explicitly, with P directives. (Mnemonic: -B/--cost uses
transaction prices, -V/--market uses market prices.)
-X: Market value in specified commodity
The -X/--exchange option is like -V/--market except it takes a commod-
ity symbol argument, so that you can select a different target commod-
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)
You can control valuation more precisely with the --value option.
-B, -V and -X are special cases of the more general --value option:
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD
--value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
The argument is one of the keywords shown, or their first letter, or a
custom date. The precise effect of the keywords is command-specific,
but here is their general meaning:
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 (or c)
--value=cost
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
using market prices on the last day of the report period (or of
each subperiod in a multiperiod report). When no report period
is specified, uses the journal's last transaction date.
--value=now (or n)
--value=now
Convert amounts to their value in default valuation commodity
using current market prices (as of when report is generated).
-V/--market does this.
-V/--market is equivalent to this.
--value=YYYY-MM-DD
Convert amounts to their value in default valuation commodity
using market prices on the given date (which must be 8 digits
with - or / or . separators). Eg --value=2019-04-25.
using market prices on this date. 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:
P 2000-01-01 A 1 B
@ -825,6 +874,38 @@ OPTIONS
2000/03/01
(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
Below is how --value affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a
@ -856,6 +937,9 @@ OPTIONS
values
balance (bs,
cf, is..)
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 sum of previous postings previous postings
@ -868,27 +952,12 @@ OPTIONS
budget costs of bud- budget-setting periodic budget-setting
amounts with get amounts txns are valued at period periodic txns are
--budget end valued at DATE
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-
totals/aver- values postings age of postings
ages
Some useful value reports
Here are some probably useful reports - please send suggestions if you
find out more:
Command: Description of report: Could answer:
-----------------------------------------------------------------------------
hledger bs -M Monthly historical value 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
Combining -B, -V, -X, --value
The rightmost of these flags wins.
Output destination
@ -1185,6 +1254,10 @@ COMMANDS
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $
On Microsoft Windows, the add command makes sure that no part of the
file path ends with a period, as it can cause data loss on that plat-
form (cf #1056).
balance
balance, bal, b
Show accounts and their balances.
@ -1826,6 +1899,10 @@ COMMANDS
run this command with --auto, the balance assertions will probably
always require --auto.
When account balances have cost information (transaction prices), the
closing/opening transactions will preserve it, so that eg balance -B
reports will not be affected.
Examples:
Carrying asset/liability balances into a new file for 2019, all from
@ -2384,6 +2461,7 @@ COMMANDS
Payees/descriptions : 5
Accounts : 8 (depth 3)
Commodities : 1 ($)
Market prices : 12 ($)
This command also supports output destination and output format selec-
tion.
@ -2393,7 +2471,8 @@ COMMANDS
List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are
considered.
considered. With --values flag, the tags' unique values are listed
instead.
test
test
@ -2612,4 +2691,4 @@ SEE ALSO
hledger 1.14.99 March 2019 hledger(1)
hledger 1.15 August 2019 hledger(1)