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 assign a value to one hledger field, with interpolation
T} T}
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] \f[B]\f[CB]if\f[B]\f[R]
T}@T{ T}@T{
apply some rules to matched CSV records 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 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). \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. 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] .SS \f[C]if\f[R]
.IP .IP
.nf .nf
@ -791,29 +819,6 @@ When CSV values are enclosed in quotes, note:
they must be double quotes (not single quotes) they must be double quotes (not single quotes)
.IP \[bu] 2 .IP \[bu] 2
spaces outside the quotes are not allowed 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 .SS Reading multiple CSV files
.PP .PP
If you use multiple \f[C]-f\f[R] options to read multiple CSV files at 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 *'fields'* name CSV fields, assign them to hledger fields
*field assign a value to one hledger field, with interpolation *field assign a value to one hledger field, with interpolation
assignment* assignment*
*'separator'* a custom field separator
*'if'* apply some rules to matched CSV records *'if'* apply some rules to matched CSV records
*'end'* skip the remaining CSV records *'end'* skip the remaining CSV records
*'date-format'* describe the format of CSV dates *'date-format'* describe the format of CSV dates
@ -371,6 +372,7 @@ Blank lines and lines beginning with '#' or ';' are ignored.
* skip:: * skip::
* fields:: * fields::
* field assignment:: * field assignment::
* separator::
* if:: * if::
* end:: * end::
* date-format:: * date-format::
@ -479,7 +481,7 @@ also contain tags, as usual.
See TIPS below for more about setting amounts and currency. 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 2.3 field assignment
==================== ====================
@ -504,9 +506,27 @@ becomes '1' when interpolated) (#1051). See TIPS below for more about
referencing other fields. 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 if PATTERN
@ -565,7 +585,7 @@ banking thru software
 
File: hledger_csv.info, Node: end, Next: date-format, Prev: if, Up: CSV RULES 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 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 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 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 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 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 File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES
2.8 'include' 2.9 'include'
============= =============
include RULESFILE include RULESFILE
@ -655,8 +675,8 @@ include categorisation.rules
 
File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV 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 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
@ -685,7 +705,6 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top
* Rapid feedback:: * Rapid feedback::
* Valid CSV:: * Valid CSV::
* Other separator characters::
* Reading multiple CSV files:: * Reading multiple CSV files::
* Valid transactions:: * Valid transactions::
* Deduplicating importing:: * Deduplicating importing::
@ -712,7 +731,7 @@ a separator each time the command re-runs, making it easier to read the
output. 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 3.2 Valid CSV
============= =============
@ -724,29 +743,9 @@ enclosed in quotes, note:
* spaces outside the quotes are not allowed * 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 3.3 Reading multiple CSV files
==============================
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
============================== ==============================
If you use multiple '-f' options to read multiple CSV files at once, 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 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 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 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 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 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: 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 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 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 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 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 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 Here's how to think of CSV rules being evaluated (if you really need
to). First, to). First,
@ -940,62 +939,62 @@ command the user specified.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: EXAMPLES1835 Node: EXAMPLES1879
Ref: #examples1941 Ref: #examples1985
Node: Basic2149 Node: Basic2193
Ref: #basic2249 Ref: #basic2293
Node: Bank of Ireland2791 Node: Bank of Ireland2835
Ref: #bank-of-ireland2926 Ref: #bank-of-ireland2970
Node: Amazon4389 Node: Amazon4433
Ref: #amazon4507 Ref: #amazon4551
Node: Paypal6440 Node: Paypal6484
Ref: #paypal6534 Ref: #paypal6578
Node: CSV RULES14417 Node: CSV RULES14461
Ref: #csv-rules14526 Ref: #csv-rules14570
Node: skip14788 Node: skip14846
Ref: #skip14881 Ref: #skip14939
Node: fields15256 Node: fields15314
Ref: #fields15378 Ref: #fields15436
Node: Transaction field names16543 Node: Transaction field names16601
Ref: #transaction-field-names16703 Ref: #transaction-field-names16761
Node: Posting field names16814 Node: Posting field names16872
Ref: #posting-field-names16966 Ref: #posting-field-names17024
Node: field assignment18257 Node: field assignment18315
Ref: #field-assignment18393 Ref: #field-assignment18458
Node: if19211 Node: separator19276
Ref: #if19320 Ref: #separator19405
Node: end21036 Node: if19786
Ref: #end21142 Ref: #if19888
Node: date-format21366 Node: end21604
Ref: #date-format21498 Ref: #end21710
Node: newest-first22247 Node: date-format21934
Ref: #newest-first22385 Ref: #date-format22066
Node: include23068 Node: newest-first22815
Ref: #include23197 Ref: #newest-first22953
Node: balance-type23641 Node: include23636
Ref: #balance-type23759 Ref: #include23765
Node: TIPS24459 Node: balance-type24209
Ref: #tips24541 Ref: #balance-type24329
Node: Rapid feedback24809 Node: TIPS25029
Ref: #rapid-feedback24926 Ref: #tips25111
Node: Valid CSV25386 Node: Rapid feedback25348
Ref: #valid-csv25528 Ref: #rapid-feedback25465
Node: Other separator characters25720 Node: Valid CSV25925
Ref: #other-separator-characters25908 Ref: #valid-csv26067
Node: Reading multiple CSV files26347 Node: Reading multiple CSV files26259
Ref: #reading-multiple-csv-files26544 Ref: #reading-multiple-csv-files26439
Node: Valid transactions26785 Node: Valid transactions26680
Ref: #valid-transactions26963 Ref: #valid-transactions26858
Node: Deduplicating importing27591 Node: Deduplicating importing27486
Ref: #deduplicating-importing27770 Ref: #deduplicating-importing27665
Node: Setting amounts28803 Node: Setting amounts28698
Ref: #setting-amounts28972 Ref: #setting-amounts28867
Node: Setting currency/commodity29958 Node: Setting currency/commodity29853
Ref: #setting-currencycommodity30150 Ref: #setting-currencycommodity30045
Node: Referencing other fields30953 Node: Referencing other fields30848
Ref: #referencing-other-fields31153 Ref: #referencing-other-fields31048
Node: How CSV rules are evaluated32050 Node: How CSV rules are evaluated31945
Ref: #how-csv-rules-are-evaluated32223 Ref: #how-csv-rules-are-evaluated32116
 
End Tag Table End Tag Table

178
hledger-lib/hledger_csv.txt
View File

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

10
hledger-lib/hledger_journal.5
View File

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

334
hledger-lib/hledger_journal.txt
View File

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