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

;doc: regen some manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-01-07 16:24:51 -08:00
parent 41f00e42f9
commit 65efdea4c0
6 changed files with 450 additions and 447 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
hledger-lib/hledger_csv.5
View File

@ -52,6 +52,11 @@ T}@T{
assign a value to one hledger field, with interpolation
T}
T{
\f[B]\f[CB]separator\f[B]\f[R]
T}@T{
a custom field separator
T}
T{
\f[B]\f[CB]if\f[B]\f[R]
T}@T{
apply some rules to matched CSV records
@ -547,6 +552,29 @@ comment note: %somefield - %anotherfield, date: %1
Interpolation strips outer whitespace (so a CSV value like
\f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated) (#1051).
See TIPS below for more about referencing other fields.
.SS \f[C]separator\f[R]
.PP
You can use the \f[C]separator\f[R] directive to read other kinds of
character-separated data.
Eg to read SSV (Semicolon Separated Values), use:
.IP
.nf
\f[C]
separator ;
\f[R]
.fi
.PP
The separator directive accepts exactly one single byte character as a
separator.
To specify whitespace characters, you may use the special words
\f[C]TAB\f[R] or \f[C]SPACE\f[R].
Eg to read TSV (Tab Separated Values), use:
.IP
.nf
\f[C]
separator TAB
\f[R]
.fi
.SS \f[C]if\f[R]
.IP
.nf
@ -791,29 +819,6 @@ When CSV values are enclosed in quotes, note:
they must be double quotes (not single quotes)
.IP \[bu] 2
spaces outside the quotes are not allowed
.SS Other separator characters
.PP
You can use the \f[C]--separator \[aq]CHAR\[aq]\f[R] command line option
(experimental) to read other kinds of character-separated data.
Eg to read SSV (Semicolon Separated Values), use:
.IP
.nf
\f[C]
$ hledger -f foo.tsv --separator \[aq];\[aq] print
\f[R]
.fi
.PP
Note the semicolon is quoted because it\[aq]s a special shell character.
.PP
To read TSV (Tab Separated Values), use:
.IP
.nf
\f[C]
$ hledger -f foo.tsv --separator \[aq] \[aq] print
\f[R]
.fi
.PP
Note, that\[aq]s a real tab character in quotes, not \f[C]\[rs]t\f[R].
.SS Reading multiple CSV files
.PP
If you use multiple \f[C]-f\f[R] options to read multiple CSV files at

191
hledger-lib/hledger_csv.info
View File

@ -30,6 +30,7 @@ after the examples:
*'fields'* name CSV fields, assign them to hledger fields
*field assign a value to one hledger field, with interpolation
assignment*
*'separator'* a custom field separator
*'if'* apply some rules to matched CSV records
*'end'* skip the remaining CSV records
*'date-format'* describe the format of CSV dates
@ -371,6 +372,7 @@ Blank lines and lines beginning with '#' or ';' are ignored.
* skip::
* fields::
* field assignment::
* separator::
* if::
* end::
* date-format::
@ -479,7 +481,7 @@ also contain tags, as usual.
See TIPS below for more about setting amounts and currency.

File: hledger_csv.info, Node: field assignment, Next: if, Prev: fields, Up: CSV RULES
File: hledger_csv.info, Node: field assignment, Next: separator, Prev: fields, Up: CSV RULES
2.3 field assignment
====================
@ -504,9 +506,27 @@ becomes '1' when interpolated) (#1051). See TIPS below for more about
referencing other fields.

File: hledger_csv.info, Node: if, Next: end, Prev: field assignment, Up: CSV RULES
File: hledger_csv.info, Node: separator, Next: if, Prev: field assignment, Up: CSV RULES
2.4 'if'
2.4 'separator'
===============
You can use the 'separator' directive to read other kinds of
character-separated data. Eg to read SSV (Semicolon Separated Values),
use:
separator ;
The separator directive accepts exactly one single byte character as
a separator. To specify whitespace characters, you may use the special
words 'TAB' or 'SPACE'. Eg to read TSV (Tab Separated Values), use:
separator TAB

File: hledger_csv.info, Node: if, Next: end, Prev: separator, Up: CSV RULES
2.5 'if'
========
if PATTERN
@ -565,7 +585,7 @@ banking thru software

File: hledger_csv.info, Node: end, Next: date-format, Prev: if, Up: CSV RULES
2.5 'end'
2.6 'end'
=========
This rule can be used inside if blocks (only), to make hledger stop
@ -579,7 +599,7 @@ if ,,,,

File: hledger_csv.info, Node: date-format, Next: newest-first, Prev: end, Up: CSV RULES
2.6 'date-format'
2.7 'date-format'
=================
date-format DATEFMT
@ -610,7 +630,7 @@ https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime

File: hledger_csv.info, Node: newest-first, Next: include, Prev: date-format, Up: CSV RULES
2.7 'newest-first'
2.8 'newest-first'
==================
hledger always sorts the generated transactions by date. Transactions
@ -632,7 +652,7 @@ newest-first

File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES
2.8 'include'
2.9 'include'
=============
include RULESFILE
@ -655,8 +675,8 @@ include categorisation.rules

File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV RULES
2.9 'balance-type'
==================
2.10 'balance-type'
===================
Balance assertions generated by assigning to balanceN are of the simple
'=' type by default, which is a single-commodity, subaccount-excluding
@ -685,7 +705,6 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top
* Rapid feedback::
* Valid CSV::
* Other separator characters::
* Reading multiple CSV files::
* Valid transactions::
* Deduplicating importing::
@ -712,7 +731,7 @@ a separator each time the command re-runs, making it easier to read the
output.

File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Prev: Rapid feedback, Up: TIPS
File: hledger_csv.info, Node: Valid CSV, Next: Reading multiple CSV files, Prev: Rapid feedback, Up: TIPS
3.2 Valid CSV
=============
@ -724,29 +743,9 @@ enclosed in quotes, note:
* spaces outside the quotes are not allowed

File: hledger_csv.info, Node: Other separator characters, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS
File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Valid CSV, Up: TIPS
3.3 Other separator characters
==============================
You can use the '--separator 'CHAR'' command line option (experimental)
to read other kinds of character-separated data. Eg to read SSV
(Semicolon Separated Values), use:
$ hledger -f foo.tsv --separator ';' print
Note the semicolon is quoted because it's a special shell character.
To read TSV (Tab Separated Values), use:
$ hledger -f foo.tsv --separator ' ' print
Note, that's a real tab character in quotes, not '\t'.

File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Other separator characters, Up: TIPS
3.4 Reading multiple CSV files
3.3 Reading multiple CSV files
==============================
If you use multiple '-f' options to read multiple CSV files at once,
@ -757,7 +756,7 @@ used for all the CSV files.

File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS
3.5 Valid transactions
3.4 Valid transactions
======================
After reading a CSV file, hledger post-processes and validates the
@ -776,7 +775,7 @@ $ hledger -f file.csv print | hledger -f- print

File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS
3.6 Deduplicating, importing
3.5 Deduplicating, importing
============================
When you download a CSV file periodically, eg to get your latest bank
@ -806,7 +805,7 @@ CSV data. See:

File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS
3.7 Setting amounts
3.6 Setting amounts
===================
A posting amount can be set in one of these ways:
@ -835,7 +834,7 @@ A posting amount can be set in one of these ways:

File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS
3.8 Setting currency/commodity
3.7 Setting currency/commodity
==============================
If the currency/commodity symbol is included in the CSV's amount
@ -862,7 +861,7 @@ field(s), you don't have to do anything special.

File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS
3.9 Referencing other fields
3.8 Referencing other fields
============================
In field assignments, you can interpolate only CSV fields, not hledger
@ -899,8 +898,8 @@ if something

File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS
3.10 How CSV rules are evaluated
================================
3.9 How CSV rules are evaluated
===============================
Here's how to think of CSV rules being evaluated (if you really need
to). First,
@ -940,62 +939,62 @@ command the user specified.

Tag Table:
Node: Top72
Node: EXAMPLES1835
Ref: #examples1941
Node: Basic2149
Ref: #basic2249
Node: Bank of Ireland2791
Ref: #bank-of-ireland2926
Node: Amazon4389
Ref: #amazon4507
Node: Paypal6440
Ref: #paypal6534
Node: CSV RULES14417
Ref: #csv-rules14526
Node: skip14788
Ref: #skip14881
Node: fields15256
Ref: #fields15378
Node: Transaction field names16543
Ref: #transaction-field-names16703
Node: Posting field names16814
Ref: #posting-field-names16966
Node: field assignment18257
Ref: #field-assignment18393
Node: if19211
Ref: #if19320
Node: end21036
Ref: #end21142
Node: date-format21366
Ref: #date-format21498
Node: newest-first22247
Ref: #newest-first22385
Node: include23068
Ref: #include23197
Node: balance-type23641
Ref: #balance-type23759
Node: TIPS24459
Ref: #tips24541
Node: Rapid feedback24809
Ref: #rapid-feedback24926
Node: Valid CSV25386
Ref: #valid-csv25528
Node: Other separator characters25720
Ref: #other-separator-characters25908
Node: Reading multiple CSV files26347
Ref: #reading-multiple-csv-files26544
Node: Valid transactions26785
Ref: #valid-transactions26963
Node: Deduplicating importing27591
Ref: #deduplicating-importing27770
Node: Setting amounts28803
Ref: #setting-amounts28972
Node: Setting currency/commodity29958
Ref: #setting-currencycommodity30150
Node: Referencing other fields30953
Ref: #referencing-other-fields31153
Node: How CSV rules are evaluated32050
Ref: #how-csv-rules-are-evaluated32223
Node: EXAMPLES1879
Ref: #examples1985
Node: Basic2193
Ref: #basic2293
Node: Bank of Ireland2835
Ref: #bank-of-ireland2970
Node: Amazon4433
Ref: #amazon4551
Node: Paypal6484
Ref: #paypal6578
Node: CSV RULES14461
Ref: #csv-rules14570
Node: skip14846
Ref: #skip14939
Node: fields15314
Ref: #fields15436
Node: Transaction field names16601
Ref: #transaction-field-names16761
Node: Posting field names16872
Ref: #posting-field-names17024
Node: field assignment18315
Ref: #field-assignment18458
Node: separator19276
Ref: #separator19405
Node: if19786
Ref: #if19888
Node: end21604
Ref: #end21710
Node: date-format21934
Ref: #date-format22066
Node: newest-first22815
Ref: #newest-first22953
Node: include23636
Ref: #include23765
Node: balance-type24209
Ref: #balance-type24329
Node: TIPS25029
Ref: #tips25111
Node: Rapid feedback25348
Ref: #rapid-feedback25465
Node: Valid CSV25925
Ref: #valid-csv26067
Node: Reading multiple CSV files26259
Ref: #reading-multiple-csv-files26439
Node: Valid transactions26680
Ref: #valid-transactions26858
Node: Deduplicating importing27486
Ref: #deduplicating-importing27665
Node: Setting amounts28698
Ref: #setting-amounts28867
Node: Setting currency/commodity29853
Ref: #setting-currencycommodity30045
Node: Referencing other fields30848
Ref: #referencing-other-fields31048
Node: How CSV rules are evaluated31945
Ref: #how-csv-rules-are-evaluated32116

End Tag Table

178
hledger-lib/hledger_csv.txt
View File

@ -34,6 +34,7 @@ DESCRIPTION
field assignment assign a value to one
hledger field, with inter-
polation
separator a custom field separator
if apply some rules to
matched CSV records
end skip the remaining CSV
@ -427,6 +428,18 @@ CSV RULES
comes 1 when interpolated) (#1051). See TIPS below for more about ref-
erencing other fields.
separator
You can use the separator directive to read other kinds of character-
separated data. Eg to read SSV (Semicolon Separated Values), use:
separator ;
The separator directive accepts exactly one single byte character as a
separator. To specify whitespace characters, you may use the special
words TAB or SPACE. Eg to read TSV (Tab Separated Values), use:
separator TAB
if
if PATTERN
RULE
@ -438,28 +451,28 @@ CSV RULES
RULE
RULE
Conditional blocks ("if blocks") are a block of rules that are applied
only to CSV records which match certain patterns. They are often used
Conditional blocks ("if blocks") are a block of rules that are applied
only to CSV records which match certain patterns. They are often used
for customising account names based on transaction descriptions.
A single pattern can be written on the same line as the "if"; or multi-
ple patterns can be written on the following lines, non-indented. Mul-
tiple patterns are OR'd (any one of them can match). Patterns are
tiple patterns are OR'd (any one of them can match). Patterns are
case-insensitive regular expressions which try to match anywhere within
the whole CSV record (POSIX extended regular expressions with some ad-
the whole CSV record (POSIX extended regular expressions with some ad-
ditions, see https://hledger.org/hledger.html#regular-expressions).
Note the CSV record they see is close to, but not identical to, the one
in the CSV file; enclosing double quotes will be removed, and the sepa-
rator character is always comma.
It's not yet easy to match within a specific field. If the data does
It's not yet easy to match within a specific field. If the data does
not contain commas, you can hack it with a regular expression like:
# match "foo" in the fourth field
if ^([^,]*,){3}foo
After the patterns there should be one or more rules to apply, all in-
dented by at least one space. Three kinds of rule are allowed in con-
After the patterns there should be one or more rules to apply, all in-
dented by at least one space. Three kinds of rule are allowed in con-
ditional blocks:
o field assignments (to set a hledger field)
@ -483,7 +496,7 @@ CSV RULES
comment XXX deductible ? check it
end
This rule can be used inside if blocks (only), to make hledger stop
This rule can be used inside if blocks (only), to make hledger stop
reading this CSV file and move on to the next input file, or to command
execution. Eg:
@ -494,10 +507,10 @@ CSV RULES
date-format
date-format DATEFMT
This is a helper for the date (and date2) fields. If your CSV dates
are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
need to add a date-format rule describing them with a strptime date
parsing pattern, which must parse the CSV date value completely. Some
This is a helper for the date (and date2) fields. If your CSV dates
are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
need to add a date-format rule describing them with a strptime date
parsing pattern, which must parse the CSV date value completely. Some
examples:
# MM/DD/YY
@ -519,15 +532,15 @@ CSV RULES
mat.html#v:formatTime
newest-first
hledger always sorts the generated transactions by date. Transactions
on the same date should appear in the same order as their CSV records,
as hledger can usually auto-detect whether the CSV's normal order is
hledger always sorts the generated transactions by date. Transactions
on the same date should appear in the same order as their CSV records,
as hledger can usually auto-detect whether the CSV's normal order is
oldest first or newest first. But if all of the following are true:
o the CSV might sometimes contain just one day of data (all records
o the CSV might sometimes contain just one day of data (all records
having the same date)
o the CSV records are normally in reverse chronological order (newest
o the CSV records are normally in reverse chronological order (newest
at the top)
o and you care about preserving the order of same-day transactions
@ -540,9 +553,9 @@ CSV RULES
include
include RULESFILE
This includes the contents of another CSV rules file at this point.
RULESFILE is an absolute file path or a path relative to the current
file's directory. This can be useful for sharing common rules between
This includes the contents of another CSV rules file at this point.
RULESFILE is an absolute file path or a path relative to the current
file's directory. This can be useful for sharing common rules between
several rules files, eg:
# someaccount.csv.rules
@ -557,10 +570,10 @@ CSV RULES
balance-type
Balance assertions generated by assigning to balanceN are of the simple
= type by default, which is a single-commodity, subaccount-excluding
= type by default, which is a single-commodity, subaccount-excluding
assertion. You may find the subaccount-including variants more useful,
eg if you have created some virtual subaccounts of checking to help
with budgeting. You can select a different type of assertion with the
eg if you have created some virtual subaccounts of checking to help
with budgeting. You can select a different type of assertion with the
balance-type rule:
# balance assertions will consider all commodities and all subaccounts
@ -575,79 +588,64 @@ CSV RULES
TIPS
Rapid feedback
It's a good idea to get rapid feedback while creating/troubleshooting
It's a good idea to get rapid feedback while creating/troubleshooting
CSV rules. Here's a good way, using entr from http://eradman.com/entr-
project :
$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
A desc: query (eg) is used to select just one, or a few, transactions
of interest. "bash -c" is used to run multiple commands, so we can
echo a separator each time the command re-runs, making it easier to
A desc: query (eg) is used to select just one, or a few, transactions
of interest. "bash -c" is used to run multiple commands, so we can
echo a separator each time the command re-runs, making it easier to
read the output.
Valid CSV
hledger accepts CSV conforming to RFC 4180. When CSV values are en-
hledger accepts CSV conforming to RFC 4180. When CSV values are en-
closed in quotes, note:
o they must be double quotes (not single quotes)
o spaces outside the quotes are not allowed
Other separator characters
You can use the --separator 'CHAR' command line option (experimental)
to read other kinds of character-separated data. Eg to read SSV (Semi-
colon Separated Values), use:
$ hledger -f foo.tsv --separator ';' print
Note the semicolon is quoted because it's a special shell character.
To read TSV (Tab Separated Values), use:
$ hledger -f foo.tsv --separator ' ' print
Note, that's a real tab character in quotes, not \t.
Reading multiple CSV files
If you use multiple -f options to read multiple CSV files at once,
hledger will look for a correspondingly-named rules file for each CSV
file. But if you use the --rules-file option, that rules file will be
If you use multiple -f options to read multiple CSV files at once,
hledger will look for a correspondingly-named rules file for each CSV
file. But if you use the --rules-file option, that rules file will be
used for all the CSV files.
Valid transactions
After reading a CSV file, hledger post-processes and validates the gen-
erated journal entries as it would for a journal file - balancing them,
applying balance assignments, and canonicalising amount styles. Any
errors at this stage will be reported in the usual way, displaying the
applying balance assignments, and canonicalising amount styles. Any
errors at this stage will be reported in the usual way, displaying the
problem entry.
There is one exception: balance assertions, if you have generated them,
will not be checked, since normally these will work only when the CSV
data is part of the main journal. If you do need to check balance as-
will not be checked, since normally these will work only when the CSV
data is part of the main journal. If you do need to check balance as-
sertions generated from CSV right away, pipe into another hledger:
$ hledger -f file.csv print | hledger -f- print
Deduplicating, importing
When you download a CSV file periodically, eg to get your latest bank
transactions, the new file may overlap with the old one, containing
When you download a CSV file periodically, eg to get your latest bank
transactions, the new file may overlap with the old one, containing
some of the same records.
The import command will (a) detect the new transactions, and (b) append
just those transactions to your main journal. It is idempotent, so you
don't have to remember how many times you ran it or with which version
of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
don't have to remember how many times you ran it or with which version
of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
is the easiest way to import CSV data. Eg:
# download the latest CSV files, then run this command.
# Note, no -f flags needed here.
$ hledger import *.csv [--dry]
This method works for most CSV files. (Where records have a stable
This method works for most CSV files. (Where records have a stable
chronological order, and new records appear only at the new end.)
A number of other tools and workflows, hledger-specific and otherwise,
A number of other tools and workflows, hledger-specific and otherwise,
exist for converting, deduplicating, classifying and managing CSV data.
See:
@ -658,43 +656,43 @@ TIPS
Setting amounts
A posting amount can be set in one of these ways:
o by assigning (with a fields list or field assigment) to amountN
o by assigning (with a fields list or field assigment) to amountN
(posting N's amount) or amount (posting 1's amount)
o by assigning to amountN-in and amountN-out (or amount-in and amount-
out). For each CSV record, whichever of these has a non-zero value
will be used, with appropriate sign. If both contain a non-zero
o by assigning to amountN-in and amountN-out (or amount-in and amount-
out). For each CSV record, whichever of these has a non-zero value
will be used, with appropriate sign. If both contain a non-zero
value, this may not work.
o by assigning to balanceN (or balance) instead of the above, setting
the amount indirectly via a balance assignment. If you do this the
o by assigning to balanceN (or balance) instead of the above, setting
the amount indirectly via a balance assignment. If you do this the
default account name may be wrong, so you should set that explicitly.
There is some special handling for an amount's sign:
o If an amount value is parenthesised, it will be de-parenthesised and
o If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped.
o If an amount value begins with a double minus sign, those cancel out
o If an amount value begins with a double minus sign, those cancel out
and are removed.
o If an amount value begins with a plus sign, that will be removed
Setting currency/commodity
If the currency/commodity symbol is included in the CSV's amount
If the currency/commodity symbol is included in the CSV's amount
field(s), you don't have to do anything special.
If the currency is provided as a separate CSV field, you can either:
o assign that to currency, which adds it to all posting amounts. The
symbol will prepended to the amount quantity (on the left side). If
you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
o assign that to currency, which adds it to all posting amounts. The
symbol will prepended to the amount quantity (on the left side). If
you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
stripping).
o or assign it to currencyN which adds it to posting N's amount only.
o or for more control, construct the amount from symbol and quantity
o or for more control, construct the amount from symbol and quantity
using field assignment, eg:
fields date,description,currency,quantity
@ -702,9 +700,9 @@ TIPS
amount %quantity %currency
Referencing other fields
In field assignments, you can interpolate only CSV fields, not hledger
fields. In the example below, there's both a CSV field and a hledger
field named amount1, but %amount1 always means the CSV field, not the
In field assignments, you can interpolate only CSV fields, not hledger
fields. In the example below, there's both a CSV field and a hledger
field named amount1, but %amount1 always means the CSV field, not the
hledger field:
# Name the third CSV field "amount1"
@ -716,7 +714,7 @@ TIPS
# Set comment to the CSV amount1 (not the amount1 assigned above)
comment %amount1
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
eral "amount1":
fields date,description,csvamount
@ -724,7 +722,7 @@ TIPS
# Can't interpolate amount1 here
comment %amount1
When there are multiple field assignments to the same hledger field,
When there are multiple field assignments to the same hledger field,
only the last one takes effect. Here, comment's value will be be B, or
C if "something" is matched, but never A:
@ -734,14 +732,14 @@ TIPS
comment C
How CSV rules are evaluated
Here's how to think of CSV rules being evaluated (if you really need
Here's how to think of CSV rules being evaluated (if you really need
to). First,
o include - all includes are inlined, from top to bottom, depth first.
(At each include point the file is inlined and scanned for further
o include - all includes are inlined, from top to bottom, depth first.
(At each include point the file is inlined and scanned for further
includes, recursively, before proceeding.)
Then "global" rules are evaluated, top to bottom. If a rule is re-
Then "global" rules are evaluated, top to bottom. If a rule is re-
peated, the last one wins:
o skip (at top level)
@ -755,30 +753,30 @@ TIPS
Then for each CSV record in turn:
o test all if blocks. If any of them contain a end rule, skip all re-
maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip
o test all if blocks. If any of them contain a end rule, skip all re-
maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip
rules, the first one wins.
o collect all field assignments at top level and in matched if blocks.
When there are multiple assignments for a field, keep only the last
o collect all field assignments at top level and in matched if blocks.
When there are multiple assignments for a field, keep only the last
one.
o compute a value for each hledger field - either the one that was as-
o compute a value for each hledger field - either the one that was as-
signed to it (and interpolate the %CSVFIELDNAME references), or a de-
fault
o generate a synthetic hledger transaction from these values.
This is all part of the CSV reader, one of several readers hledger can
use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the
This is all part of the CSV reader, one of several readers hledger can
use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the
user specified.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -792,7 +790,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

10
hledger-lib/hledger_journal.5
View File

@ -1002,12 +1002,12 @@ T{
T}@T{
T}@T{
T}@T{
declare a commodity, number notation & display style for commodityless
amounts
declare a commodity to be used for commodityless amounts, and its number
notation & display style
T}@T{
commodity: all commodityless entries in all files; number notation:
following commodityless entries and entries in that commodity in all
files; display style: amounts of that commodity in reports
default commodity: following commodityless entries until end of current
file; number notation: following entries in that commodity until end of
current file; display style: amounts of that commodity in reports
T}
T{
\f[C]include\f[R]

133
hledger-lib/hledger_journal.info
View File

@ -903,19 +903,20 @@ account' apply account names inline/included
amounts of that
commodity in
reports
'D' declare a commodity, number commodity: all
'D' declare a commodity to be default
used for commodityless commodity:
amounts, and its number following
notation & display style commodityless
for commodityless amounts entries in all
files; number
notation:
following
commodityless
entries and
entries in that
commodity in all
files; display
style: amounts of
that commodity in
entries until end
of current file;
number notation:
following entries
in that commodity
until end of
current file;
display style:
amounts of that
commodity in
reports
'include' include entries/directives what the included
from another file directives affect
@ -1808,60 +1809,60 @@ Node: Tags28648
Ref: #tags28766
Node: Directives30159
Ref: #directives30302
Node: Comment blocks35910
Ref: #comment-blocks36055
Node: Including other files36231
Ref: #including-other-files36411
Node: Default year36819
Ref: #default-year36988
Node: Declaring commodities37395
Ref: #declaring-commodities37578
Node: Default commodity39239
Ref: #default-commodity39415
Node: Market prices40049
Ref: #market-prices40214
Node: Declaring accounts41055
Ref: #declaring-accounts41231
Node: Account comments42156
Ref: #account-comments42319
Node: Account subdirectives42714
Ref: #account-subdirectives42909
Node: Account types43222
Ref: #account-types43406
Node: Account display order45048
Ref: #account-display-order45218
Node: Rewriting accounts46347
Ref: #rewriting-accounts46532
Node: Basic aliases47258
Ref: #basic-aliases47404
Node: Regex aliases48108
Ref: #regex-aliases48280
Node: Combining aliases48998
Ref: #combining-aliases49176
Node: end aliases50452
Ref: #end-aliases50600
Node: Default parent account50701
Ref: #default-parent-account50867
Node: Periodic transactions51751
Ref: #periodic-transactions51949
Node: Periodic rule syntax53821
Ref: #periodic-rule-syntax54027
Node: Two spaces between period expression and description!54731
Ref: #two-spaces-between-period-expression-and-description55050
Node: Forecasting with periodic transactions55734
Ref: #forecasting-with-periodic-transactions56039
Node: Budgeting with periodic transactions58065
Ref: #budgeting-with-periodic-transactions58304
Node: Auto postings / transaction modifiers58753
Ref: #auto-postings-transaction-modifiers58964
Node: Auto postings and dates61193
Ref: #auto-postings-and-dates61450
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61625
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62000
Node: Auto posting tags62378
Ref: #auto-posting-tags62617
Node: EDITOR SUPPORT63282
Ref: #editor-support63400
Node: Comment blocks35981
Ref: #comment-blocks36126
Node: Including other files36302
Ref: #including-other-files36482
Node: Default year36890
Ref: #default-year37059
Node: Declaring commodities37466
Ref: #declaring-commodities37649
Node: Default commodity39310
Ref: #default-commodity39486
Node: Market prices40120
Ref: #market-prices40285
Node: Declaring accounts41126
Ref: #declaring-accounts41302
Node: Account comments42227
Ref: #account-comments42390
Node: Account subdirectives42785
Ref: #account-subdirectives42980
Node: Account types43293
Ref: #account-types43477
Node: Account display order45119
Ref: #account-display-order45289
Node: Rewriting accounts46418
Ref: #rewriting-accounts46603
Node: Basic aliases47329
Ref: #basic-aliases47475
Node: Regex aliases48179
Ref: #regex-aliases48351
Node: Combining aliases49069
Ref: #combining-aliases49247
Node: end aliases50523
Ref: #end-aliases50671
Node: Default parent account50772
Ref: #default-parent-account50938
Node: Periodic transactions51822
Ref: #periodic-transactions52020
Node: Periodic rule syntax53892
Ref: #periodic-rule-syntax54098
Node: Two spaces between period expression and description!54802
Ref: #two-spaces-between-period-expression-and-description55121
Node: Forecasting with periodic transactions55805
Ref: #forecasting-with-periodic-transactions56110
Node: Budgeting with periodic transactions58136
Ref: #budgeting-with-periodic-transactions58375
Node: Auto postings / transaction modifiers58824
Ref: #auto-postings-transaction-modifiers59035
Node: Auto postings and dates61264
Ref: #auto-postings-and-dates61521
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61696
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62071
Node: Auto posting tags62449
Ref: #auto-posting-tags62688
Node: EDITOR SUPPORT63353
Ref: #editor-support63471

End Tag Table

334
hledger-lib/hledger_journal.txt
View File

@ -700,36 +700,36 @@ FILE FORMAT
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
entries in that
commodity in all
files; display
style: amounts of
that commodity in
reports
D declare a commodity to be default commodity:
used for commodityless following commod-
amounts, and its number no- ityless entries un-
tation & display style til end of current
file; number nota-
tion: following en-
tries in that com-
modity until end of
current file; dis-
play style: amounts
of that commodity
in reports
include include entries/directives what the included
from another file directives affect
P declare a market price for a amounts of that
commodity commodity in re-
ports, when -V is
commodity commodity in re-
ports, when -V is
used
Y declare a year for yearless following in-
Y declare a year for yearless following in-
dates line/included en-
tries until end of
tries until end of
current file
And some definitions:
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@ -740,34 +740,34 @@ FILE FORMAT
affect, and whether they are focussed on input (parsing) or output (re-
ports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
writing file options in a different order. It can be surprising at
times though.
Comment blocks
A line containing just comment starts a commented region of the file,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can in-
The include directive can only be used in journal files. It can in-
clude journal, timeclock or timedot files, but not CSV files.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -789,18 +789,18 @@ FILE FORMAT
Declaring commodities
The commodity directive has several functions:
1. It declares commodities which may be used in the journal. This is
1. It declares commodities which may be used in the journal. This is
currently not enforced, but can serve as documentation.
2. It declares what decimal mark character to expect when parsing input
- useful to disambiguate international number formats in your data.
- useful to disambiguate international number formats in your data.
(Without this, hledger will parse both 1,000 and 1.000 as 1).
3. It declares the amount display format to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them
You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them
to declare your commodities.
A commodity directive is just the word commodity followed by an amount.
@ -813,8 +813,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both
or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both
places.):
; commodity SYMBOL
@ -827,14 +827,14 @@ FILE FORMAT
format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi-
cant. The number must include a decimal mark: either a period or a
cant. The number must include a decimal mark: either a period or a
comma, followed by 0 or more decimal digits.
Default commodity
The D directive sets a default commodity (and display format), to be
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
; commodity-less amounts should be treated as dollars
@ -849,9 +849,9 @@ FILE FORMAT
a decimal point.
Market prices
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@ -862,16 +862,16 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, giving the price in commodity B of one unit of commodity A.
These two market price directives say that one euro was worth 1.35 US
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40
The -V/--value flag can be used to convert reported amounts to another
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
@ -881,20 +881,20 @@ FILE FORMAT
o They can document your intended chart of accounts, providing a refer-
ence.
o They can store extra information about accounts (account numbers,
o They can store extra information about accounts (account numbers,
notes, etc.)
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
o They control account display order in reports, allowing non-alpha-
o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command, hledger-
o They help with account name completion in the add command, hledger-
iadd, hledger-web, ledger-mode etc.
The simplest form is just the word account followed by a hledger-style
The simplest form is just the word account followed by a hledger-style
account name, eg:
account assets:bank:checking
@ -912,7 +912,7 @@ FILE FORMAT
the next line instead.
Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just
We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
@ -925,18 +925,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are
bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
Account types declared with tags
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@ -947,8 +947,8 @@ FILE FORMAT
account expenses ; type:Expenses
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A
@ -958,7 +958,7 @@ FILE FORMAT
account expenses X
Overriding auto-detected types
If you ever override the types of those auto-detected english account
If you ever override the types of those auto-detected english account
names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why
@ -969,8 +969,8 @@ FILE FORMAT
account - ; type:L
Account display order
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal:
@ -992,16 +992,16 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
@ -1020,14 +1020,14 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or hledger-
do not affect account names being entered via hledger add or hledger-
web.
See also Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -1035,49 +1035,49 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
OLD and NEW are case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
counts are also affected. Eg:
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"
Regex aliases
There is also a more powerful variant that uses a regular expression,
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
space.
Combining aliases
You can define as many aliases as you like, using journal directives
You can define as many aliases as you like, using journal directives
and/or command line options.
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
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
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
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
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:
@ -1088,22 +1088,22 @@ FILE FORMAT
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-
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
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
You can clear (forget) all currently defined aliases with the end
aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
apply account directives like so:
apply account home
@ -1120,7 +1120,7 @@ FILE FORMAT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -1129,50 +1129,50 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
account.
Periodic transactions
Periodic transaction rules describe transactions that recur. They al-
low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal,
and it's easy to try out different forecasts. Secondly, they are also
Periodic transaction rules describe transactions that recur. They al-
low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal,
and it's easy to try out different forecasts. Secondly, they are also
used to define the budgets shown in budget reports.
Periodic transactions can be a little tricky, so before you use them,
Periodic transactions can be a little tricky, so before you use them,
read this whole section - or at least these tips:
1. Two spaces accidentally added or omitted will cause you trouble -
1. Two spaces accidentally added or omitted will cause you trouble -
read about this below.
2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast
2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast
tag:generated.
3. Forecasted transactions will begin only after the last non-fore-
3. Forecasted transactions will begin only after the last non-fore-
casted transaction's date.
4. Forecasted transactions will end 6 months from today, by default.
4. Forecasted transactions will end 6 months from today, by default.
See below for the exact start/end rules.
5. period expressions can be tricky. Their documentation needs im-
5. period expressions can be tricky. Their documentation needs im-
provement, but is worth studying.
6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
error.
7. Other period expressions with an interval are automatically expanded
to cover a whole number of that interval. (This is done to improve
to cover a whole number of that interval. (This is done to improve
reports, but it also affects periodic transactions. Yes, it's a bit
inconsistent with the above.) Eg: ~ every 10th day of month from
2020/01, which is equivalent to ~ every 10th day of month from
inconsistent with the above.) Eg: ~ every 10th day of month from
2020/01, which is equivalent to ~ every 10th day of month from
2020/01/01, will be adjusted to start on 2019/12/10.
Periodic rule syntax
@ -1184,17 +1184,17 @@ FILE FORMAT
expenses:rent $2000
assets:bank:checking
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg monthly from
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg monthly from
2018/1/1 is valid, but monthly from 2018/1/15 is not.
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
Two spaces between period expression and description!
If the period expression is followed by a transaction description,
If the period expression is followed by a transaction description,
these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example:
@ -1208,82 +1208,82 @@ FILE FORMAT
So,
o Do write two spaces between your period expression and your transac-
o Do write two spaces between your period expression and your transac-
tion description, if any.
o Don't accidentally write two spaces in the middle of your period ex-
o Don't accidentally write two spaces in the middle of your period ex-
pression.
Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates fu-
ture transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
With the --forecast flag, each periodic transaction rule generates fu-
ture 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:
o generated-transaction:~ PERIODICEXPR - shows that this was generated
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
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
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
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
forecast period:
o begins on the later of
o the report start date if specified with -b/-p/date:
o the day after the latest normal (non-periodic) transaction in the
o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
o ends on the report end date if specified with -e/-p/date:, or 180
o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
actions with periodic rules, and every so often copy the output of
actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
For more details, see: balance: Budget report and Budgeting and Fore-
For more details, see: balance: Budget report and Budgeting and Fore-
casting.
Auto postings / transaction modifiers
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
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 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
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
@ -1291,20 +1291,20 @@ FILE FORMAT
ACCT [AMT]
...
These posting-generating rules look like normal postings, except the
These posting-generating rules look like normal postings, except the
amount can be:
o a normal amount with a commodity symbol, eg $2. This will be used
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
o a numeric multiplier, eg *2 (a star followed by a number N). The
o a numeric multiplier, eg *2 (a star followed by a number N). The
matched posting's amount (and total price, if any) will be multiplied
by N.
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
@ -1344,20 +1344,20 @@ FILE FORMAT
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
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:
o after missing amounts are inferred, and transactions are checked for
o after missing amounts are inferred, and transactions are checked for
balancedness,
o but before balance assertions are checked.
Note this means that journal entries must be balanced both before and
Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893
for background.
@ -1367,11 +1367,11 @@ FILE FORMAT
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
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
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
o modified: - this transaction was modified
@ -1380,18 +1380,18 @@ FILE FORMAT
tion was modified "just now".
EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with
Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the Editor configuration at hledger.org for the latest in-
formation.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -1405,7 +1405,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)