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

;doc: regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-03-01 17:25:25 -08:00
parent ba44d00bed
commit 061bf73b61
28 changed files with 1364 additions and 1041 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
hledger-lib/hledger_csv.5
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "hledger_csv" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" .TH "hledger_csv" "5" "March 2020" "hledger 1.17" "hledger User Manuals"
@ -236,10 +236,7 @@ amount2 %amzamount
#include categorisation.rules #include categorisation.rules
# add a third posting for fees, but only if they are non-zero. # add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead. if %fees [1-9]
# (Regex translation: \[dq]a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields\[dq])
if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$
account3 expenses:fees account3 expenses:fees
amount3 %fees amount3 %fees
\f[R] \f[R]
@ -308,13 +305,11 @@ description %description_ %itemtitle
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
# convert to short currency symbols # convert to short currency symbols
# Note: in conditional block regexps, the line of csv being matched is if %currency USD
# a synthetic one: the unquoted field values, with commas between them.
if ,USD,
currency $ currency $
if ,EUR, if %currency EUR
currency E currency E
if ,GBP, if %currency GBP
currency P currency P
# generate postings # generate postings
@ -328,9 +323,8 @@ amount1 %netamount
# (account2 is set below) # (account2 is set below)
amount2 -%grossamount amount2 -%grossamount
# if there\[aq]s a fee (9th field), add a third posting for the money taken by paypal. # if there\[aq]s a fee, add a third posting for the money taken by paypal.
# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount) if %feeamount [1-9]
if \[ha]([\[ha],]+,){8}[\[ha]0]
account3 expenses:banking:paypal account3 expenses:banking:paypal
amount3 -%feeamount amount3 -%feeamount
comment3 business: comment3 business:
@ -338,11 +332,11 @@ if \[ha]([\[ha],]+,){8}[\[ha]0]
# choose an account for the second posting # choose an account for the second posting
# override the default account names: # override the default account names:
# if amount (8th field) is positive, it\[aq]s income (a debit) # if the amount is positive, it\[aq]s income (a debit)
if \[ha]([\[ha],]+,){7}[0-9] if %grossamount \[ha][\[ha]-]
account2 income:unknown account2 income:unknown
# if negative, it\[aq]s an expense (a credit) # if negative, it\[aq]s an expense (a credit)
if \[ha]([\[ha],]+,){7}- if %grossamount \[ha]-
account2 expenses:unknown account2 expenses:unknown
# apply common rules for setting account2 & other tweaks # apply common rules for setting account2 & other tweaks
@ -585,13 +579,13 @@ See also: File Extension.
.IP .IP
.nf .nf
\f[C] \f[C]
if PATTERN if MATCHER
RULE RULE
if if
PATTERN MATCHER
PATTERN MATCHER
PATTERN MATCHER
RULE RULE
RULE RULE
\f[R] \f[R]
@ -602,28 +596,40 @@ applied only to CSV records which match certain patterns.
They are often used for customising account names based on transaction They are often used for customising account names based on transaction
descriptions. descriptions.
.PP .PP
A single pattern can be written on the same line as the \[dq]if\[dq]; or Each MATCHER can be a record matcher, which looks like this:
multiple patterns can be written on the following lines, non-indented.
Multiple patterns are OR\[aq]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 additions, 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
separator character is always comma.
.PP
It\[aq]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:
.IP .IP
.nf .nf
\f[C] \f[C]
# match \[dq]foo\[dq] in the fourth field REGEX
if \[ha]([\[ha],]*,){3}foo
\f[R] \f[R]
.fi .fi
.PP .PP
REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record.
It is a POSIX extended regular expressions with some additions (see
Regular expressions in the hledger manual).
Note: the \[dq]CSV record\[dq] it is matched against is not the original
record, but a synthetic one, with enclosing double quotes or whitespace
removed, and always comma-separated.
(Eg, an SSV record \f[C]2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000\f[R]
appears to REGEX as \f[C]2020-01-01,Acme, Inc.,1,000\f[R]).
.PP
Or, MATCHER can be a field matcher, like this:
.IP
.nf
\f[C]
%CSVFIELD REGEX
\f[R]
.fi
.PP
which matches just the content of a particular CSV field.
CSVFIELD is a percent sign followed by the field\[aq]s name or column
number, like \f[C]%date\f[R] or \f[C]%1\f[R].
.PP
A single matcher can be written on the same line as the \[dq]if\[dq]; or
multiple matchers can be written on the following lines, non-indented.
Multiple matchers are OR\[aq]d (any one of them can match).
.PP
After the patterns there should be one or more rules to apply, all After the patterns there should be one or more rules to apply, all
indented by at least one space. indented by at least one space.
Three kinds of rule are allowed in conditional blocks: Three kinds of rule are allowed in conditional blocks:

187
hledger-lib/hledger_csv.info
View File

@ -3,8 +3,8 @@ This is hledger_csv.info, produced by makeinfo version 6.7 from stdin.
 
File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir)
hledger_csv(5) hledger 1.16.99 hledger_csv(5) hledger 1.17
****************************** ***************************
CSV - how hledger reads CSV data, and the CSV rules file format CSV - how hledger reads CSV data, and the CSV rules file format
@ -190,10 +190,7 @@ amount2 %amzamount
#include categorisation.rules #include categorisation.rules
# add a third posting for fees, but only if they are non-zero. # add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead. if %fees [1-9]
# (Regex translation: "a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields")
if ,\$[1-9][.0-9]+(,[^,]*){1}$
account3 expenses:fees account3 expenses:fees
amount3 %fees amount3 %fees
@ -255,13 +252,11 @@ description %description_ %itemtitle
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
# convert to short currency symbols # convert to short currency symbols
# Note: in conditional block regexps, the line of csv being matched is if %currency USD
# a synthetic one: the unquoted field values, with commas between them.
if ,USD,
currency $ currency $
if ,EUR, if %currency EUR
currency E currency E
if ,GBP, if %currency GBP
currency P currency P
# generate postings # generate postings
@ -275,9 +270,8 @@ amount1 %netamount
# (account2 is set below) # (account2 is set below)
amount2 -%grossamount amount2 -%grossamount
# if there's a fee (9th field), add a third posting for the money taken by paypal. # if there's a fee, add a third posting for the money taken by paypal.
# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount) if %feeamount [1-9]
if ^([^,]+,){8}[^0]
account3 expenses:banking:paypal account3 expenses:banking:paypal
amount3 -%feeamount amount3 -%feeamount
comment3 business: comment3 business:
@ -285,11 +279,11 @@ if ^([^,]+,){8}[^0]
# choose an account for the second posting # choose an account for the second posting
# override the default account names: # override the default account names:
# if amount (8th field) is positive, it's income (a debit) # if the amount is positive, it's income (a debit)
if ^([^,]+,){7}[0-9] if %grossamount ^[^-]
account2 income:unknown account2 income:unknown
# if negative, it's an expense (a credit) # if negative, it's an expense (a credit)
if ^([^,]+,){7}- if %grossamount ^-
account2 expenses:unknown account2 expenses:unknown
# apply common rules for setting account2 & other tweaks # apply common rules for setting account2 & other tweaks
@ -537,13 +531,13 @@ File: hledger_csv.info, Node: if, Next: end, Prev: separator, Up: CSV RULES
2.5 'if' 2.5 'if'
======== ========
if PATTERN if MATCHER
RULE RULE
if if
PATTERN MATCHER
PATTERN MATCHER
PATTERN MATCHER
RULE RULE
RULE RULE
@ -552,21 +546,30 @@ applied only to CSV records which match certain patterns. They are
often used for customising account names based on transaction often used for customising account names based on transaction
descriptions. descriptions.
A single pattern can be written on the same line as the "if"; or Each MATCHER can be a record matcher, which looks like this:
multiple patterns can be written on the following lines, non-indented.
Multiple 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
additions, 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
separator character is always comma.
It's not yet easy to match within a specific field. If the data does REGEX
not contain commas, you can hack it with a regular expression like:
# match "foo" in the fourth field REGEX is a case-insensitive regular expression which tries to match
if ^([^,]*,){3}foo anywhere within the CSV record. It is a POSIX extended regular
expressions with some additions (see Regular expressions in the hledger
manual). Note: the "CSV record" it is matched against is not the
original record, but a synthetic one, with enclosing double quotes or
whitespace removed, and always comma-separated. (Eg, an SSV record
'2020-01-01; "Acme, Inc."; 1,000' appears to REGEX as '2020-01-01,Acme,
Inc.,1,000').
Or, MATCHER can be a field matcher, like this:
%CSVFIELD REGEX
which matches just the content of a particular CSV field. CSVFIELD
is a percent sign followed by the field's name or column number, like
'%date' or '%1'.
A single matcher can be written on the same line as the "if"; or
multiple matchers can be written on the following lines, non-indented.
Multiple matchers are OR'd (any one of them can match).
After the patterns there should be one or more rules to apply, all After the patterns there should be one or more rules to apply, all
indented by at least one space. Three kinds of rule are allowed in indented by at least one space. Three kinds of rule are allowed in
@ -968,64 +971,64 @@ command the user specified.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: EXAMPLES2099 Node: EXAMPLES2093
Ref: #examples2205 Ref: #examples2199
Node: Basic2413 Node: Basic2407
Ref: #basic2513 Ref: #basic2507
Node: Bank of Ireland3055 Node: Bank of Ireland3049
Ref: #bank-of-ireland3190 Ref: #bank-of-ireland3184
Node: Amazon4652 Node: Amazon4646
Ref: #amazon4770 Ref: #amazon4764
Node: Paypal6702 Node: Paypal6483
Ref: #paypal6796 Ref: #paypal6577
Node: CSV RULES14675 Node: CSV RULES14221
Ref: #csv-rules14784 Ref: #csv-rules14330
Node: skip15060 Node: skip14606
Ref: #skip15153 Ref: #skip14699
Node: fields15528 Node: fields15074
Ref: #fields15650 Ref: #fields15196
Node: Transaction field names16815 Node: Transaction field names16361
Ref: #transaction-field-names16975 Ref: #transaction-field-names16521
Node: Posting field names17086 Node: Posting field names16632
Ref: #posting-field-names17238 Ref: #posting-field-names16784
Node: field assignment18529 Node: field assignment18075
Ref: #field-assignment18672 Ref: #field-assignment18218
Node: separator19490 Node: separator19036
Ref: #separator19619 Ref: #separator19165
Node: if20030 Node: if19576
Ref: #if20132 Ref: #if19678
Node: end21848 Node: end21597
Ref: #end21954 Ref: #end21703
Node: date-format22178 Node: date-format21927
Ref: #date-format22310 Ref: #date-format22059
Node: newest-first23059 Node: newest-first22808
Ref: #newest-first23197 Ref: #newest-first22946
Node: include23880 Node: include23629
Ref: #include24009 Ref: #include23758
Node: balance-type24453 Node: balance-type24202
Ref: #balance-type24573 Ref: #balance-type24322
Node: TIPS25273 Node: TIPS25022
Ref: #tips25355 Ref: #tips25104
Node: Rapid feedback25611 Node: Rapid feedback25360
Ref: #rapid-feedback25728 Ref: #rapid-feedback25477
Node: Valid CSV26188 Node: Valid CSV25937
Ref: #valid-csv26318 Ref: #valid-csv26067
Node: File Extension26510 Node: File Extension26259
Ref: #file-extension26662 Ref: #file-extension26411
Node: Reading multiple CSV files27072 Node: Reading multiple CSV files26821
Ref: #reading-multiple-csv-files27257 Ref: #reading-multiple-csv-files27006
Node: Valid transactions27498 Node: Valid transactions27247
Ref: #valid-transactions27676 Ref: #valid-transactions27425
Node: Deduplicating importing28304 Node: Deduplicating importing28053
Ref: #deduplicating-importing28483 Ref: #deduplicating-importing28232
Node: Setting amounts29516 Node: Setting amounts29265
Ref: #setting-amounts29685 Ref: #setting-amounts29434
Node: Setting currency/commodity30671 Node: Setting currency/commodity30420
Ref: #setting-currencycommodity30863 Ref: #setting-currencycommodity30612
Node: Referencing other fields31666 Node: Referencing other fields31415
Ref: #referencing-other-fields31866 Ref: #referencing-other-fields31615
Node: How CSV rules are evaluated32763 Node: How CSV rules are evaluated32512
Ref: #how-csv-rules-are-evaluated32936 Ref: #how-csv-rules-are-evaluated32685
 
End Tag Table End Tag Table

214
hledger-lib/hledger_csv.txt
View File

@ -163,10 +163,7 @@ EXAMPLES
#include categorisation.rules #include categorisation.rules
# add a third posting for fees, but only if they are non-zero. # add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead. if %fees [1-9]
# (Regex translation: "a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields")
if ,\$[1-9][.0-9]+(,[^,]*){1}$
account3 expenses:fees account3 expenses:fees
amount3 %fees amount3 %fees
@ -223,13 +220,11 @@ EXAMPLES
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
# convert to short currency symbols # convert to short currency symbols
# Note: in conditional block regexps, the line of csv being matched is if %currency USD
# a synthetic one: the unquoted field values, with commas between them.
if ,USD,
currency $ currency $
if ,EUR, if %currency EUR
currency E currency E
if ,GBP, if %currency GBP
currency P currency P
# generate postings # generate postings
@ -243,9 +238,8 @@ EXAMPLES
# (account2 is set below) # (account2 is set below)
amount2 -%grossamount amount2 -%grossamount
# if there's a fee (9th field), add a third posting for the money taken by paypal. # if there's a fee, add a third posting for the money taken by paypal.
# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount) if %feeamount [1-9]
if ^([^,]+,){8}[^0]
account3 expenses:banking:paypal account3 expenses:banking:paypal
amount3 -%feeamount amount3 -%feeamount
comment3 business: comment3 business:
@ -253,11 +247,11 @@ EXAMPLES
# choose an account for the second posting # choose an account for the second posting
# override the default account names: # override the default account names:
# if amount (8th field) is positive, it's income (a debit) # if the amount is positive, it's income (a debit)
if ^([^,]+,){7}[0-9] if %grossamount ^[^-]
account2 income:unknown account2 income:unknown
# if negative, it's an expense (a credit) # if negative, it's an expense (a credit)
if ^([^,]+,){7}- if %grossamount ^-
account2 expenses:unknown account2 expenses:unknown
# apply common rules for setting account2 & other tweaks # apply common rules for setting account2 & other tweaks
@ -446,13 +440,13 @@ CSV RULES
See also: File Extension. See also: File Extension.
if if
if PATTERN if MATCHER
RULE RULE
if if
PATTERN MATCHER
PATTERN MATCHER
PATTERN MATCHER
RULE RULE
RULE RULE
@ -460,24 +454,32 @@ CSV RULES
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- Each MATCHER can be a record matcher, which looks like this:
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
case-insensitive regular expressions which try to match anywhere within
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 REGEX
not contain commas, you can hack it with a regular expression like:
# match "foo" in the fourth field REGEX is a case-insensitive regular expression which tries to match
if ^([^,]*,){3}foo anywhere within the CSV record. It is a POSIX extended regular expres-
sions with some additions (see Regular expressions in the hledger man-
ual). Note: the "CSV record" it is matched against is not the original
record, but a synthetic one, with enclosing double quotes or whitespace
removed, and always comma-separated. (Eg, an SSV record 2020-01-01;
"Acme, Inc."; 1,000 appears to REGEX as 2020-01-01,Acme, Inc.,1,000).
After the patterns there should be one or more rules to apply, all in- Or, MATCHER can be a field matcher, like this:
dented by at least one space. Three kinds of rule are allowed in con-
%CSVFIELD REGEX
which matches just the content of a particular CSV field. CSVFIELD is
a percent sign followed by the field's name or column number, like
%date or %1.
A single matcher can be written on the same line as the "if"; or multi-
ple matchers can be written on the following lines, non-indented. Mul-
tiple matchers are OR'd (any one of them can match).
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: ditional blocks:
o field assignments (to set a hledger field) o field assignments (to set a hledger field)
@ -501,7 +503,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:
@ -512,10 +514,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
@ -537,15 +539,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
@ -558,9 +560,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
@ -575,10 +577,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
@ -593,19 +595,19 @@ 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)
@ -613,9 +615,9 @@ TIPS
o spaces outside the quotes are not allowed o spaces outside the quotes are not allowed
File Extension File Extension
CSV ("Character Separated Values") files should be named with one of CSV ("Character Separated Values") files should be named with one of
these filename extensions: .csv, .ssv, .tsv. Or, the file path should these filename extensions: .csv, .ssv, .tsv. Or, the file path should
be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify
the format and show the right error messages. For example: the format and show the right error messages. For example:
$ hledger -f foo.ssv print $ hledger -f foo.ssv print
@ -627,44 +629,44 @@ TIPS
More about this: Input files in the hledger manual. More about this: Input files in the hledger manual.
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:
@ -675,43 +677,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
@ -719,9 +721,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"
@ -733,7 +735,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
@ -741,7 +743,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:
@ -751,14 +753,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)
@ -772,30 +774,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)
@ -809,7 +811,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)
@ -817,4 +819,4 @@ SEE ALSO
hledger 1.16.99 February 2020 hledger_csv(5) hledger 1.17 March 2020 hledger_csv(5)

2
hledger-lib/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "hledger_journal" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" .TH "hledger_journal" "5" "March 2020" "hledger 1.17" "hledger User Manuals"

224
hledger-lib/hledger_journal.info
View File

@ -4,8 +4,8 @@ stdin.
 
File: hledger_journal.info, Node: Top, Up: (dir) File: hledger_journal.info, Node: Top, Up: (dir)
hledger_journal(5) hledger 1.16.99 hledger_journal(5) hledger 1.17
********************************** *******************************
Journal - hledger's default file format, representing a General Journal Journal - hledger's default file format, representing a General Journal
@ -1735,116 +1735,116 @@ rules will have these tags added:
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: Transactions1875 Node: Transactions1869
Ref: #transactions1967 Ref: #transactions1961
Node: Dates3156 Node: Dates3150
Ref: #dates3255 Ref: #dates3249
Node: Simple dates3320 Node: Simple dates3314
Ref: #simple-dates3446 Ref: #simple-dates3440
Node: Secondary dates3955 Node: Secondary dates3949
Ref: #secondary-dates4109 Ref: #secondary-dates4103
Node: Posting dates5445 Node: Posting dates5439
Ref: #posting-dates5574 Ref: #posting-dates5568
Node: Status6946 Node: Status6940
Ref: #status7067 Ref: #status7061
Node: Description8775 Node: Description8769
Ref: #description8909 Ref: #description8903
Node: Payee and note9229 Node: Payee and note9223
Ref: #payee-and-note9343 Ref: #payee-and-note9337
Node: Comments9678 Node: Comments9672
Ref: #comments9804 Ref: #comments9798
Node: Tags10998 Node: Tags10992
Ref: #tags11113 Ref: #tags11107
Node: Postings12506 Node: Postings12500
Ref: #postings12634 Ref: #postings12628
Node: Virtual Postings13660 Node: Virtual Postings13654
Ref: #virtual-postings13777 Ref: #virtual-postings13771
Node: Account names15082 Node: Account names15076
Ref: #account-names15223 Ref: #account-names15217
Node: Amounts15710 Node: Amounts15704
Ref: #amounts15849 Ref: #amounts15843
Node: Digit group marks16781 Node: Digit group marks16775
Ref: #digit-group-marks16929 Ref: #digit-group-marks16923
Node: Amount display style17867 Node: Amount display style17861
Ref: #amount-display-style18021 Ref: #amount-display-style18015
Node: Transaction prices19182 Node: Transaction prices19176
Ref: #transaction-prices19348 Ref: #transaction-prices19342
Node: Balance Assertions21614 Node: Balance Assertions21608
Ref: #balance-assertions21794 Ref: #balance-assertions21788
Node: Assertions and ordering22827 Node: Assertions and ordering22821
Ref: #assertions-and-ordering23015 Ref: #assertions-and-ordering23009
Node: Assertions and included files23715 Node: Assertions and included files23709
Ref: #assertions-and-included-files23958 Ref: #assertions-and-included-files23952
Node: Assertions and multiple -f options24291 Node: Assertions and multiple -f options24285
Ref: #assertions-and-multiple--f-options24547 Ref: #assertions-and-multiple--f-options24541
Node: Assertions and commodities24679 Node: Assertions and commodities24673
Ref: #assertions-and-commodities24911 Ref: #assertions-and-commodities24905
Node: Assertions and prices26068 Node: Assertions and prices26062
Ref: #assertions-and-prices26282 Ref: #assertions-and-prices26276
Node: Assertions and subaccounts26722 Node: Assertions and subaccounts26716
Ref: #assertions-and-subaccounts26951 Ref: #assertions-and-subaccounts26945
Node: Assertions and virtual postings27275 Node: Assertions and virtual postings27269
Ref: #assertions-and-virtual-postings27517 Ref: #assertions-and-virtual-postings27511
Node: Assertions and precision27659 Node: Assertions and precision27653
Ref: #assertions-and-precision27852 Ref: #assertions-and-precision27846
Node: Balance Assignments28119 Node: Balance Assignments28113
Ref: #balance-assignments28293 Ref: #balance-assignments28287
Node: Balance assignments and prices29457 Node: Balance assignments and prices29451
Ref: #balance-assignments-and-prices29629 Ref: #balance-assignments-and-prices29623
Node: Directives29853 Node: Directives29847
Ref: #directives30012 Ref: #directives30006
Node: Comment blocks35660 Node: Comment blocks35654
Ref: #comment-blocks35805 Ref: #comment-blocks35799
Node: Including other files35981 Node: Including other files35975
Ref: #including-other-files36161 Ref: #including-other-files36155
Node: Default year36569 Node: Default year36563
Ref: #default-year36738 Ref: #default-year36732
Node: Declaring commodities37145 Node: Declaring commodities37139
Ref: #declaring-commodities37328 Ref: #declaring-commodities37322
Node: Default commodity39001 Node: Default commodity38995
Ref: #default-commodity39177 Ref: #default-commodity39171
Node: Market prices40066 Node: Market prices40060
Ref: #market-prices40231 Ref: #market-prices40225
Node: Declaring accounts41072 Node: Declaring accounts41066
Ref: #declaring-accounts41248 Ref: #declaring-accounts41242
Node: Account comments42173 Node: Account comments42167
Ref: #account-comments42336 Ref: #account-comments42330
Node: Account subdirectives42760 Node: Account subdirectives42754
Ref: #account-subdirectives42955 Ref: #account-subdirectives42949
Node: Account types43268 Node: Account types43262
Ref: #account-types43452 Ref: #account-types43446
Node: Account display order45091 Node: Account display order45085
Ref: #account-display-order45261 Ref: #account-display-order45255
Node: Rewriting accounts46412 Node: Rewriting accounts46406
Ref: #rewriting-accounts46597 Ref: #rewriting-accounts46591
Node: Basic aliases47323 Node: Basic aliases47317
Ref: #basic-aliases47469 Ref: #basic-aliases47463
Node: Regex aliases48173 Node: Regex aliases48167
Ref: #regex-aliases48345 Ref: #regex-aliases48339
Node: Combining aliases49063 Node: Combining aliases49057
Ref: #combining-aliases49241 Ref: #combining-aliases49235
Node: end aliases50517 Node: end aliases50511
Ref: #end-aliases50665 Ref: #end-aliases50659
Node: Default parent account50766 Node: Default parent account50760
Ref: #default-parent-account50932 Ref: #default-parent-account50926
Node: Periodic transactions51816 Node: Periodic transactions51810
Ref: #periodic-transactions52015 Ref: #periodic-transactions52009
Node: Periodic rule syntax53887 Node: Periodic rule syntax53881
Ref: #periodic-rule-syntax54093 Ref: #periodic-rule-syntax54087
Node: Two spaces between period expression and description!54797 Node: Two spaces between period expression and description!54791
Ref: #two-spaces-between-period-expression-and-description55116 Ref: #two-spaces-between-period-expression-and-description55110
Node: Forecasting with periodic transactions55800 Node: Forecasting with periodic transactions55794
Ref: #forecasting-with-periodic-transactions56105 Ref: #forecasting-with-periodic-transactions56099
Node: Budgeting with periodic transactions58131 Node: Budgeting with periodic transactions58125
Ref: #budgeting-with-periodic-transactions58370 Ref: #budgeting-with-periodic-transactions58364
Node: Auto postings / transaction modifiers58819 Node: Auto postings / transaction modifiers58813
Ref: #auto-postings-transaction-modifiers59031 Ref: #auto-postings-transaction-modifiers59025
Node: Auto postings and dates61527 Node: Auto postings and dates61521
Ref: #auto-postings-and-dates61784 Ref: #auto-postings-and-dates61778
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959 Node: Auto postings and transaction balancing / inferred amounts / balance assertions61953
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62328
Node: Auto posting tags62712 Node: Auto posting tags62706
Ref: #auto-posting-tags62951 Ref: #auto-posting-tags62945
 
End Tag Table End Tag Table

2
hledger-lib/hledger_journal.txt
View File

@ -1415,4 +1415,4 @@ SEE ALSO
hledger 1.16.99 February 2020 hledger_journal(5) hledger 1.17 March 2020 hledger_journal(5)

2
hledger-lib/hledger_timeclock.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" .TH "hledger_timeclock" "5" "March 2020" "hledger 1.17" "hledger User Manuals"

4
hledger-lib/hledger_timeclock.info
View File

@ -4,8 +4,8 @@ stdin.
 
File: hledger_timeclock.info, Node: Top, Up: (dir) File: hledger_timeclock.info, Node: Top, Up: (dir)
hledger_timeclock(5) hledger 1.16.99 hledger_timeclock(5) hledger 1.17
************************************ *********************************
Timeclock - the time logging format of timeclock.el, as read by hledger Timeclock - the time logging format of timeclock.el, as read by hledger

2
hledger-lib/hledger_timeclock.txt
View File

@ -78,4 +78,4 @@ SEE ALSO
hledger 1.16.99 February 2020 hledger_timeclock(5) hledger 1.17 March 2020 hledger_timeclock(5)

74
hledger-lib/hledger_timedot.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" .TH "hledger_timedot" "5" "March 2020" "hledger 1.17" "hledger User Manuals"
@ -22,17 +22,21 @@ quantities other than time.
In the docs below we\[aq]ll assume it\[aq]s time. In the docs below we\[aq]ll assume it\[aq]s time.
.PP .PP
A timedot file contains a series of day entries. A timedot file contains a series of day entries.
A day entry begins with a date, and is followed by category/quantity A day entry begins with a non-indented hledger-style simple date (Y-M-D,
pairs, one per line. Y/M/D, Y.M.D..) Any additional text on the same line is used as a
Dates are hledger-style simple dates (see hledger_journal(5)). transaction description for this day.
Categories are hledger-style account names, optionally indented. .PP
As in a hledger journal, there must be at least two spaces between the This is followed by optionally-indented timelog items for that day, one
category (account name) and the quantity. per line.
Each timelog item is a note, usually a hledger:style:account:name
representing a time category, followed by two or more spaces, and a
quantity.
Each timelog item generates a hledger transaction.
.PP .PP
Quantities can be written as: Quantities can be written as:
.IP \[bu] 2 .IP \[bu] 2
a sequence of dots (.) representing quarter hours. dots: a sequence of dots (.) representing quarter hours.
Spaces may optionally be used for grouping and readability. Spaces may optionally be used for grouping.
Eg: .... Eg: ....
\&.. \&..
.IP \[bu] 2 .IP \[bu] 2
@ -47,8 +51,25 @@ Eg: 90m.
The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m,
1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
.PP .PP
Blank lines and lines beginning with #, ; or * are ignored. There is some flexibility allowing notes and todo lists to be kept right
An example: in the time log, if needed:
.IP \[bu] 2
Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are
ignored.
.IP \[bu] 2
Lines not ending with a double-space and quantity are parsed as items
taking no time, which will not appear in balance reports by default.
(Add -E to see them.)
.IP \[bu] 2
Org mode headlines (lines beginning with one or more \f[C]*\f[R]
followed by a space) can be used as date lines or timelog items (the
stars are ignored).
Also all org headlines before the first date line are ignored.
This means org users can manage their timelog as an org outline (eg
using org-mode/orgstruct-mode in Emacs), for organisation, faster
navigation, controlling visibility etc.
.PP
Examples:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -63,8 +84,6 @@ inc:client1 .... ....
biz:research . biz:research .
\f[R] \f[R]
.fi .fi
.PP
Or with numbers:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -74,6 +93,35 @@ fos:hledger 3
biz:research 1 biz:research 1
\f[R] \f[R]
.fi .fi
.IP
.nf
\f[C]
* Time log
** 2020-01-01
*** adm:time .
*** adm:finance .
\f[R]
.fi
.IP
.nf
\f[C]
* 2020 Work Diary
** Q1
*** 2020-02-29
**** DONE
0700 yoga
**** UNPLANNED
**** BEGUN
hom:chores
cleaning ...
water plants
outdoor - one full watering can
indoor - light watering
**** TODO
adm:planning: trip
*** LATER
\f[R]
.fi
.PP .PP
Reporting: Reporting:
.IP .IP

64
hledger-lib/hledger_timedot.info
View File

@ -4,8 +4,8 @@ stdin.
 
File: hledger_timedot.info, Node: Top, Up: (dir) File: hledger_timedot.info, Node: Top, Up: (dir)
hledger_timedot(5) hledger 1.16.99 hledger_timedot(5) hledger 1.17
********************************** *******************************
Timedot - hledger's human-friendly time logging format Timedot - hledger's human-friendly time logging format
@ -21,16 +21,20 @@ commodityless quantities, so it could be used to represent dated
quantities other than time. In the docs below we'll assume it's time. quantities other than time. In the docs below we'll assume it's time.
A timedot file contains a series of day entries. A day entry begins A timedot file contains a series of day entries. A day entry begins
with a date, and is followed by category/quantity pairs, one per line. with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..)
Dates are hledger-style simple dates (see hledger_journal(5)). Any additional text on the same line is used as a transaction
Categories are hledger-style account names, optionally indented. As in description for this day.
a hledger journal, there must be at least two spaces between the
category (account name) and the quantity. This is followed by optionally-indented timelog items for that day,
one per line. Each timelog item is a note, usually a
hledger:style:account:name representing a time category, followed by two
or more spaces, and a quantity. Each timelog item generates a hledger
transaction.
Quantities can be written as: Quantities can be written as:
* a sequence of dots (.) representing quarter hours. Spaces may * dots: a sequence of dots (.) representing quarter hours. Spaces
optionally be used for grouping and readability. Eg: .... .. may optionally be used for grouping. Eg: .... ..
* an integral or decimal number, representing hours. Eg: 1.5 * an integral or decimal number, representing hours. Eg: 1.5
@ -40,8 +44,23 @@ category (account name) and the quantity.
The following equivalencies are assumed, currently: 1m = 60s, 1h = The following equivalencies are assumed, currently: 1m = 60s, 1h =
60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
Blank lines and lines beginning with #, ; or * are ignored. An There is some flexibility allowing notes and todo lists to be kept
example: right in the time log, if needed:
* Blank lines and lines beginning with '#' or ';' are ignored.
* Lines not ending with a double-space and quantity are parsed as
items taking no time, which will not appear in balance reports by
default. (Add -E to see them.)
* Org mode headlines (lines beginning with one or more '*' followed
by a space) can be used as date lines or timelog items (the stars
are ignored). Also all org headlines before the first date line
are ignored. This means org users can manage their timelog as an
org outline (eg using org-mode/orgstruct-mode in Emacs), for
organisation, faster navigation, controlling visibility etc.
Examples:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1 2016/2/1
@ -53,13 +72,32 @@ biz:research .
inc:client1 .... .... inc:client1 .... ....
biz:research . biz:research .
Or with numbers:
2016/2/3 2016/2/3
inc:client1 4 inc:client1 4
fos:hledger 3 fos:hledger 3
biz:research 1 biz:research 1
* Time log
** 2020-01-01
*** adm:time .
*** adm:finance .
* 2020 Work Diary
** Q1
*** 2020-02-29
**** DONE
0700 yoga
**** UNPLANNED
**** BEGUN
hom:chores
cleaning ...
water plants
outdoor - one full watering can
indoor - light watering
**** TODO
adm:planning: trip
*** LATER
Reporting: Reporting:
$ hledger -f t.timedot print date:2016/2/2 $ hledger -f t.timedot print date:2016/2/2

68
hledger-lib/hledger_timedot.txt
View File

@ -19,16 +19,20 @@ DESCRIPTION
other than time. In the docs below we'll assume it's time. other than time. In the docs below we'll assume it's time.
A timedot file contains a series of day entries. A day entry begins A timedot file contains a series of day entries. A day entry begins
with a date, and is followed by category/quantity pairs, one per line. with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..)
Dates are hledger-style simple dates (see hledger_journal(5)). Cate- Any additional text on the same line is used as a transaction descrip-
gories are hledger-style account names, optionally indented. As in a tion for this day.
hledger journal, there must be at least two spaces between the category
(account name) and the quantity. This is followed by optionally-indented timelog items for that day, one
per line. Each timelog item is a note, usually a hledger:style:ac-
count:name representing a time category, followed by two or more spa-
ces, and a quantity. Each timelog item generates a hledger transac-
tion.
Quantities can be written as: Quantities can be written as:
o a sequence of dots (.) representing quarter hours. Spaces may op- o dots: a sequence of dots (.) representing quarter hours. Spaces may
tionally be used for grouping and readability. Eg: .... .. optionally be used for grouping. Eg: .... ..
o an integral or decimal number, representing hours. Eg: 1.5 o an integral or decimal number, representing hours. Eg: 1.5
@ -38,8 +42,23 @@ DESCRIPTION
lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w =
7d, 1mo = 30d, 1y=365d. 7d, 1mo = 30d, 1y=365d.
Blank lines and lines beginning with #, ; or * are ignored. An exam- There is some flexibility allowing notes and todo lists to be kept
ple: right in the time log, if needed:
o Blank lines and lines beginning with # or ; are ignored.
o Lines not ending with a double-space and quantity are parsed as items
taking no time, which will not appear in balance reports by default.
(Add -E to see them.)
o Org mode headlines (lines beginning with one or more * followed by a
space) can be used as date lines or timelog items (the stars are ig-
nored). Also all org headlines before the first date line are ig-
nored. This means org users can manage their timelog as an org out-
line (eg using org-mode/orgstruct-mode in Emacs), for organisation,
faster navigation, controlling visibility etc.
Examples:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1 2016/2/1
@ -51,13 +70,32 @@ DESCRIPTION
inc:client1 .... .... inc:client1 .... ....
biz:research . biz:research .
Or with numbers:
2016/2/3 2016/2/3
inc:client1 4 inc:client1 4
fos:hledger 3 fos:hledger 3
biz:research 1 biz:research 1
* Time log
** 2020-01-01
*** adm:time .
*** adm:finance .
* 2020 Work Diary
** Q1
*** 2020-02-29
**** DONE
0700 yoga
**** UNPLANNED
**** BEGUN
hom:chores
cleaning ...
water plants
outdoor - one full watering can
indoor - light watering
**** TODO
adm:planning: trip
*** LATER
Reporting: Reporting:
$ hledger -f t.timedot print date:2016/2/2 $ hledger -f t.timedot print date:2016/2/2
@ -82,7 +120,7 @@ DESCRIPTION
------------++---------------------------------------- ------------++----------------------------------------
|| 7.75 2.25 8.00 || 7.75 2.25 8.00
I prefer to use period for separating account components. We can make I prefer to use period for separating account components. We can make
this work with an account alias: this work with an account alias:
2016/2/4 2016/2/4
@ -101,7 +139,7 @@ DESCRIPTION
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)
@ -115,7 +153,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)
@ -123,4 +161,4 @@ SEE ALSO
hledger 1.16.99 February 2020 hledger_timedot(5) hledger 1.17 March 2020 hledger_timedot(5)

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

@ -1,5 +1,5 @@
.TH "hledger-ui" "1" "February 2020" "hledger-ui 1.16.99" "hledger User Manuals" .TH "hledger-ui" "1" "March 2020" "hledger-ui 1.17" "hledger User Manuals"

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

@ -3,8 +3,8 @@ This is hledger-ui.info, produced by makeinfo version 6.7 from stdin.
 
File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-ui(1) hledger-ui 1.16.99 hledger-ui(1) hledger-ui 1.17
******************************** *****************************
hledger-ui - terminal interface for the hledger accounting tool hledger-ui - terminal interface for the hledger accounting tool
@ -499,26 +499,26 @@ program is restarted.
 
Tag Table: Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1476 Node: OPTIONS1470
Ref: #options1573 Ref: #options1567
Node: KEYS5004 Node: KEYS4998
Ref: #keys5099 Ref: #keys5093
Node: SCREENS9375 Node: SCREENS9369
Ref: #screens9480 Ref: #screens9474
Node: Accounts screen9570 Node: Accounts screen9564
Ref: #accounts-screen9698 Ref: #accounts-screen9692
Node: Register screen11914 Node: Register screen11908
Ref: #register-screen12069 Ref: #register-screen12063
Node: Transaction screen14066 Node: Transaction screen14060
Ref: #transaction-screen14224 Ref: #transaction-screen14218
Node: Error screen15094 Node: Error screen15088
Ref: #error-screen15216 Ref: #error-screen15210
Node: ENVIRONMENT15460 Node: ENVIRONMENT15454
Ref: #environment15574 Ref: #environment15568
Node: FILES16381 Node: FILES16375
Ref: #files16480 Ref: #files16474
Node: BUGS16693 Node: BUGS16687
Ref: #bugs16770 Ref: #bugs16764
 
End Tag Table End Tag Table

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

@ -441,4 +441,4 @@ SEE ALSO
hledger-ui 1.16.99 February 2020 hledger-ui(1) hledger-ui 1.17 March 2020 hledger-ui(1)

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

@ -1,5 +1,5 @@
.TH "hledger-web" "1" "February 2020" "hledger-web 1.16.99" "hledger User Manuals" .TH "hledger-web" "1" "March 2020" "hledger-web 1.17" "hledger User Manuals"
@ -343,8 +343,8 @@ what you get from \f[C]/transactions\f[R] or
.PP .PP
Another way to generate test data is with the Another way to generate test data is with the
\f[C]readJsonFile\f[R]/\f[C]writeJsonFile\f[R] helpers in \f[C]readJsonFile\f[R]/\f[C]writeJsonFile\f[R] helpers in
Hledger.Web.Json, which read or write any of hledger\[aq]s JSON-capable Hledger.Web.Json, which can write or read most of hledger\[aq]s data
types from or to a file. types to or from a file.
Eg here we write the first transaction of a sample journal: Eg here we write the first transaction of a sample journal:
.IP .IP
.nf .nf

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

@ -3,8 +3,8 @@ This is hledger-web.info, produced by makeinfo version 6.7 from stdin.
 
File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-web(1) hledger-web 1.16.99 hledger-web(1) hledger-web 1.17
********************************** *******************************
hledger-web - web interface for the hledger accounting tool hledger-web - web interface for the hledger accounting tool
@ -350,8 +350,8 @@ form, hledger-web must be started with the 'add' capability for this
what you get from '/transactions' or '/accounttransactions'. what you get from '/transactions' or '/accounttransactions'.
Another way to generate test data is with the Another way to generate test data is with the
'readJsonFile'/'writeJsonFile' helpers in Hledger.Web.Json, which read 'readJsonFile'/'writeJsonFile' helpers in Hledger.Web.Json, which can
or write any of hledger's JSON-capable types from or to a file. Eg here write or read most of hledger's data types to or from a file. Eg here
we write the first transaction of a sample journal: we write the first transaction of a sample journal:
$ make ghci-web $ make ghci-web
@ -427,22 +427,22 @@ awkward.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS1752 Node: OPTIONS1746
Ref: #options1857 Ref: #options1851
Node: PERMISSIONS8201 Node: PERMISSIONS8195
Ref: #permissions8340 Ref: #permissions8334
Node: EDITING UPLOADING DOWNLOADING9552 Node: EDITING UPLOADING DOWNLOADING9546
Ref: #editing-uploading-downloading9733 Ref: #editing-uploading-downloading9727
Node: RELOADING10567 Node: RELOADING10561
Ref: #reloading10701 Ref: #reloading10695
Node: JSON API11134 Node: JSON API11128
Ref: #json-api11248 Ref: #json-api11242
Node: ENVIRONMENT12689 Node: ENVIRONMENT12680
Ref: #environment12805 Ref: #environment12796
Node: FILES13538 Node: FILES13529
Ref: #files13638 Ref: #files13629
Node: BUGS13851 Node: BUGS13842
Ref: #bugs13929 Ref: #bugs13920
 
End Tag Table End Tag Table

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

@ -309,8 +309,8 @@ JSON API
what you get from /transactions or /accounttransactions. what you get from /transactions or /accounttransactions.
Another way to generate test data is with the readJsonFile/writeJson- Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's File helpers in Hledger.Web.Json, which can write or read most of
JSON-capable types from or to a file. Eg here we write the first hledger's data types to or from a file. Eg here we write the first
transaction of a sample journal: transaction of a sample journal:
$ make ghci-web $ make ghci-web
@ -392,4 +392,4 @@ SEE ALSO
hledger-web 1.16.99 February 2020 hledger-web(1) hledger-web 1.17 March 2020 hledger-web(1)

5
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -499,5 +499,6 @@ Budget performance in 2019/01:
Output format Output format
The balance command supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are txt, csv, (multicolumn
non-budget reports only) html, and (experimental) json.

5
hledger/Hledger/Cli/Commands/Balancesheet.txt
View File

@ -39,5 +39,6 @@ for a balance sheet; note this means it ignores report begin dates (and
-T/--row-total, since summing end balances generally does not make -T/--row-total, since summing end balances generally does not make
sense). Instead of absolute values percentages can be displayed with -%. sense). Instead of absolute values percentages can be displayed with -%.
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are txt, csv, html, and
(experimental) json.

4
hledger/Hledger/Cli/Commands/Balancesheetequity.txt
View File

@ -29,3 +29,7 @@ Equity:
Total: Total:
-------------------- --------------------
0 0
This command also supports the output destination and output format
options The output formats supported are txt, csv, html, and
(experimental) json.

5
hledger/Hledger/Cli/Commands/Cashflow.txt
View File

@ -30,5 +30,6 @@ though as with multicolumn balance reports you can alter the report mode
with --change/--cumulative/--historical. Instead of absolute values with --change/--cumulative/--historical. Instead of absolute values
percentages can be displayed with -%. percentages can be displayed with -%.
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are txt, csv, html, and
(experimental) json.

5
hledger/Hledger/Cli/Commands/Incomestatement.txt
View File

@ -39,5 +39,6 @@ period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical. Instead of absolute report mode with --change/--cumulative/--historical. Instead of absolute
values percentages can be displayed with -%. values percentages can be displayed with -%.
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are txt, csv, html, and
(experimental) json.

7
hledger/Hledger/Cli/Commands/Print.txt
View File

@ -70,8 +70,11 @@ This assumes that transactions added to FILE always have same or
increasing dates, and that transactions on the same day do not get increasing dates, and that transactions on the same day do not get
reordered. See also the import command. reordered. See also the import command.
This command also supports output destination and output format This command also supports the output destination and output format
selection. Here's an example of print's CSV output: options The output formats supported are txt, csv, and (experimental)
json.
Here's an example of print's CSV output:
$ hledger print -Ocsv $ hledger print -Ocsv
"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"

5
hledger/Hledger/Cli/Commands/Register.txt
View File

@ -103,5 +103,6 @@ $ export COLUMNS=100; hledger reg # set till session end (or window resize)
$ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are txt, csv, and (experimental)
json.

123
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "hledger" "1" "February 2020" "hledger 1.16.99" "hledger User Manuals" .TH "hledger" "1" "March 2020" "hledger 1.17" "hledger User Manuals"
@ -1037,31 +1037,90 @@ If you need those, either use the include directive, or concatenate the
files, eg: \f[C]cat a.journal b.journal | hledger -f- CMD\f[R]. files, eg: \f[C]cat a.journal b.journal | hledger -f- CMD\f[R].
.SS Output destination .SS Output destination
.PP .PP
Some commands (print, register, stats, the balance commands) can write hledger commands send their output to the terminal by default.
their output to a destination other than the console. You can of course redirect this, eg into a file, using standard shell
This is controlled by the \f[C]-o/--output-file\f[R] option. syntax:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger balance -o - # write to stdout (the default) $ hledger print > foo.txt
$ hledger balance -o FILE # write to FILE \f[R]
.fi
.PP
Some commands (print, register, stats, the balance commands) also
provide the \f[C]-o/--output-file\f[R] option, which does the same thing
without needing the shell.
Eg:
.IP
.nf
\f[C]
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
\f[R] \f[R]
.fi .fi
.SS Output format .SS Output format
.PP .PP
Some commands can write their output in other formats. Some commands (print, register, the balance commands) offer a choice of
Eg print and register can output CSV, and the balance commands can output format.
output CSV or HTML. In addition to the usual plain text format (\f[C]txt\f[R]), there are
This is controlled by the \f[C]-O/--output-format\f[R] option, or by CSV (\f[C]csv\f[R]), HTML (\f[C]html\f[R]) and JSON (\f[C]json\f[R]).
specifying a \f[C].csv\f[R] or \f[C].html\f[R] file extension with This is controlled by the \f[C]-O/--output-format\f[R] option:
\f[C]-o/--output-file\f[R].
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger balance -O csv # write CSV to stdout $ hledger print -O csv
$ hledger balance -o FILE.csv # write CSV to FILE.csv
\f[R] \f[R]
.fi .fi
.PP
or, by a file extension specified with \f[C]-o/--output-file\f[R]:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.html # write HTML to foo.html
\f[R]
.fi
.PP
The \f[C]-O\f[R] option can be used to override the file extension if
needed:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt
\f[R]
.fi
.PP
Some notes about JSON output:
.IP \[bu] 2
This feature is marked experimental, and not yet much used; you should
expect our JSON to evolve.
Real-world feedback is welcome.
.IP \[bu] 2
Our JSON is rather large and verbose, as it is quite a faithful
representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are
mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
.IP \[bu] 2
The JSON output from hledger commands is essentially the same as the
JSON served by hledger-web\[aq]s JSON API, but pretty printed, using
line breaks and indentation.
Our pretty printer has the ability to elide data in certain cases -
rendering non-strings as if they were strings, or displaying
\[dq]FOO..\[dq] instead of FOO\[aq]s full details.
This should never happen in hledger\[aq]s JSON output; if you see
otherwise, please report as a bug.
.IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals.
Such numbers can arise in practice (from automatically-calculated
transaction prices), and would break most JSON consumers.
So in JSON, we show quantities as simple Numbers with at most 10 decimal
places.
We don\[aq]t limit the number of integer digits, but that part is under
your control.
We hope this approach will not cause problems in practice; if you find
otherwise, please let us know.
(Cf #1195)
.SS Regular expressions .SS Regular expressions
.PP .PP
hledger uses regular expressions in a number of places: hledger uses regular expressions in a number of places:
@ -2955,8 +3014,10 @@ Budget performance in 2019/01:
.fi .fi
.SS Output format .SS Output format
.PP .PP
The balance command supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
(multicolumn non-budget reports only) \f[C]html\f[R], and (experimental)
\f[C]json\f[R].
.SS balancesheet .SS balancesheet
.PP .PP
balancesheet, bs balancesheet, bs
@ -3010,8 +3071,9 @@ generally does not make sense).
Instead of absolute values percentages can be displayed with Instead of absolute values percentages can be displayed with
\f[C]-%\f[R]. \f[C]-%\f[R].
.PP .PP
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
\f[C]html\f[R], and (experimental) \f[C]json\f[R].
.SS balancesheetequity .SS balancesheetequity
.PP .PP
balancesheetequity, bse balancesheetequity, bse
@ -3050,6 +3112,10 @@ Total:
0 0
\f[R] \f[R]
.fi .fi
.PP
This command also supports the output destination and output format
options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
\f[C]html\f[R], and (experimental) \f[C]json\f[R].
.SS cashflow .SS cashflow
.PP .PP
cashflow, cf cashflow, cf
@ -3093,8 +3159,9 @@ multicolumn balance reports you can alter the report mode with
Instead of absolute values percentages can be displayed with Instead of absolute values percentages can be displayed with
\f[C]-%\f[R]. \f[C]-%\f[R].
.PP .PP
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
\f[C]html\f[R], and (experimental) \f[C]json\f[R].
.SS check-dates .SS check-dates
.PP .PP
check-dates check-dates
@ -3461,8 +3528,9 @@ with multicolumn balance reports you can alter the report mode with
Instead of absolute values percentages can be displayed with Instead of absolute values percentages can be displayed with
\f[C]-%\f[R]. \f[C]-%\f[R].
.PP .PP
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
\f[C]html\f[R], and (experimental) \f[C]json\f[R].
.SS notes .SS notes
.PP .PP
notes Show notes. notes Show notes.
@ -3602,8 +3670,10 @@ increasing dates, and that transactions on the same day do not get
reordered. reordered.
See also the import command. See also the import command.
.PP .PP
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
and (experimental) \f[C]json\f[R].
.PP
Here\[aq]s an example of print\[aq]s CSV output: Here\[aq]s an example of print\[aq]s CSV output:
.IP .IP
.nf .nf
@ -3812,8 +3882,9 @@ $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
\f[R] \f[R]
.fi .fi
.PP .PP
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R],
and (experimental) \f[C]json\f[R].
.SS register-match .SS register-match
.PP .PP
register-match register-match

463
hledger/hledger.info
View File

@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.7 from stdin.
 
File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir) File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir)
hledger(1) hledger 1.16.99 hledger(1) hledger 1.17
************************** ***********************
hledger - a command-line accounting tool hledger - a command-line accounting tool
@ -978,12 +978,17 @@ File: hledger.info, Node: Output destination, Next: Output format, Prev: Inpu
2.8 Output destination 2.8 Output destination
====================== ======================
Some commands (print, register, stats, the balance commands) can write hledger commands send their output to the terminal by default. You can
their output to a destination other than the console. This is of course redirect this, eg into a file, using standard shell syntax:
controlled by the '-o/--output-file' option.
$ hledger balance -o - # write to stdout (the default) $ hledger print > foo.txt
$ hledger balance -o FILE # write to FILE
Some commands (print, register, stats, the balance commands) also
provide the '-o/--output-file' option, which does the same thing without
needing the shell. Eg:
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
 
File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS
@ -991,13 +996,47 @@ File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Out
2.9 Output format 2.9 Output format
================= =================
Some commands can write their output in other formats. Eg print and Some commands (print, register, the balance commands) offer a choice of
register can output CSV, and the balance commands can output CSV or output format. In addition to the usual plain text format ('txt'),
HTML. This is controlled by the '-O/--output-format' option, or by there are CSV ('csv'), HTML ('html') and JSON ('json'). This is
specifying a '.csv' or '.html' file extension with '-o/--output-file'. controlled by the '-O/--output-format' option:
$ hledger balance -O csv # write CSV to stdout $ hledger print -O csv
$ hledger balance -o FILE.csv # write CSV to FILE.csv
or, by a file extension specified with '-o/--output-file':
$ hledger balancesheet -o foo.html # write HTML to foo.html
The '-O' option can be used to override the file extension if needed:
$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt
Some notes about JSON output:
* This feature is marked experimental, and not yet much used; you
should expect our JSON to evolve. Real-world feedback is welcome.
* Our JSON is rather large and verbose, as it is quite a faithful
representation of hledger's internal data types. To understand the
JSON, read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
* The JSON output from hledger commands is essentially the same as
the JSON served by hledger-web's JSON API, but pretty printed,
using line breaks and indentation. Our pretty printer has the
ability to elide data in certain cases - rendering non-strings as
if they were strings, or displaying "FOO.." instead of FOO's full
details. This should never happen in hledger's JSON output; if you
see otherwise, please report as a bug.
* hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
arise in practice (from automatically-calculated transaction
prices), and would break most JSON consumers. So in JSON, we show
quantities as simple Numbers with at most 10 decimal places. We
don't limit the number of integer digits, but that part is under
your control. We hope this approach will not cause problems in
practice; if you find otherwise, please let us know. (Cf #1195)
 
File: hledger.info, Node: Regular expressions, Next: Smart dates, Prev: Output format, Up: OPTIONS File: hledger.info, Node: Regular expressions, Next: Smart dates, Prev: Output format, Up: OPTIONS
@ -2437,8 +2476,9 @@ Budget performance in 2019/01:
3.4.9 Output format 3.4.9 Output format
------------------- -------------------
The balance command supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are 'txt', 'csv', (multicolumn
non-budget reports only) 'html', and (experimental) 'json'.
 
File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
@ -2486,8 +2526,9 @@ for a balance sheet; note this means it ignores report begin dates (and
sense). Instead of absolute values percentages can be displayed with sense). Instead of absolute values percentages can be displayed with
'-%'. '-%'.
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are 'txt', 'csv', 'html', and
(experimental) 'json'.
 
File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS
@ -2525,6 +2566,10 @@ Total:
-------------------- --------------------
0 0
This command also supports the output destination and output format
options The output formats supported are 'txt', 'csv', 'html', and
(experimental) 'json'.
 
File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS
@ -2561,8 +2606,9 @@ period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'. Instead of report mode with '--change'/'--cumulative'/'--historical'. Instead of
absolute values percentages can be displayed with '-%'. absolute values percentages can be displayed with '-%'.
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are 'txt', 'csv', 'html', and
(experimental) 'json'.
 
File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS
@ -2904,8 +2950,9 @@ per period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'. Instead of report mode with '--change'/'--cumulative'/'--historical'. Instead of
absolute values percentages can be displayed with '-%'. absolute values percentages can be displayed with '-%'.
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are 'txt', 'csv', 'html', and
(experimental) 'json'.
 
File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS
@ -3029,8 +3076,11 @@ $ hledger -f bank1.csv print --new
increasing dates, and that transactions on the same day do not get increasing dates, and that transactions on the same day do not get
reordered. See also the import command. reordered. See also the import command.
This command also supports output destination and output format This command also supports the output destination and output format
selection. Here's an example of print's CSV output: options The output formats supported are 'txt', 'csv', and
(experimental) 'json'.
Here's an example of print's CSV output:
$ hledger print -Ocsv $ hledger print -Ocsv
"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
@ -3198,8 +3248,9 @@ $ export COLUMNS=100; hledger reg # set till session end (or window resize)
$ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
This command also supports output destination and output format This command also supports the output destination and output format
selection. options The output formats supported are 'txt', 'csv', and
(experimental) 'json'.
 
File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
@ -3683,187 +3734,187 @@ $ LANG=fr_FR.utf8 hledger -f my.journal print
 
Tag Table: Tag Table:
Node: Top68 Node: Top68
Node: COMMON TASKS2321 Node: COMMON TASKS2315
Ref: #common-tasks2433 Ref: #common-tasks2427
Node: Getting help2840 Node: Getting help2834
Ref: #getting-help2972 Ref: #getting-help2966
Node: Constructing command lines3525 Node: Constructing command lines3519
Ref: #constructing-command-lines3717 Ref: #constructing-command-lines3711
Node: Starting a journal file4414 Node: Starting a journal file4408
Ref: #starting-a-journal-file4612 Ref: #starting-a-journal-file4606
Node: Setting opening balances5800 Node: Setting opening balances5794
Ref: #setting-opening-balances5996 Ref: #setting-opening-balances5990
Node: Recording transactions9137 Node: Recording transactions9131
Ref: #recording-transactions9317 Ref: #recording-transactions9311
Node: Reconciling9873 Node: Reconciling9867
Ref: #reconciling10016 Ref: #reconciling10010
Node: Reporting12273 Node: Reporting12267
Ref: #reporting12413 Ref: #reporting12407
Node: Migrating to a new file16412 Node: Migrating to a new file16406
Ref: #migrating-to-a-new-file16560 Ref: #migrating-to-a-new-file16554
Node: OPTIONS16859 Node: OPTIONS16853
Ref: #options16966 Ref: #options16960
Node: General options17336 Node: General options17330
Ref: #general-options17461 Ref: #general-options17455
Node: Command options20231 Node: Command options20225
Ref: #command-options20382 Ref: #command-options20376
Node: Command arguments20780 Node: Command arguments20774
Ref: #command-arguments20927 Ref: #command-arguments20921
Node: Queries21807 Node: Queries21801
Ref: #queries21962 Ref: #queries21956
Node: Special characters in arguments and queries25924 Node: Special characters in arguments and queries25918
Ref: #special-characters-in-arguments-and-queries26152 Ref: #special-characters-in-arguments-and-queries26146
Node: More escaping26603 Node: More escaping26597
Ref: #more-escaping26765 Ref: #more-escaping26759
Node: Even more escaping27061 Node: Even more escaping27055
Ref: #even-more-escaping27255 Ref: #even-more-escaping27249
Node: Less escaping27926 Node: Less escaping27920
Ref: #less-escaping28088 Ref: #less-escaping28082
Node: Unicode characters28333 Node: Unicode characters28327
Ref: #unicode-characters28515 Ref: #unicode-characters28509
Node: Input files29927 Node: Input files29921
Ref: #input-files30070 Ref: #input-files30064
Node: Output destination31999 Node: Output destination31993
Ref: #output-destination32151 Ref: #output-destination32145
Node: Output format32434 Node: Output format32570
Ref: #output-format32584 Ref: #output-format32720
Node: Regular expressions32969 Node: Regular expressions34768
Ref: #regular-expressions33126 Ref: #regular-expressions34925
Node: Smart dates34487 Node: Smart dates36286
Ref: #smart-dates34638 Ref: #smart-dates36437
Node: Report start & end date35999 Node: Report start & end date37798
Ref: #report-start-end-date36171 Ref: #report-start-end-date37970
Node: Report intervals37609 Node: Report intervals39408
Ref: #report-intervals37774 Ref: #report-intervals39573
Node: Period expressions38164 Node: Period expressions39963
Ref: #period-expressions38324 Ref: #period-expressions40123
Node: Depth limiting42450 Node: Depth limiting44249
Ref: #depth-limiting42594 Ref: #depth-limiting44393
Node: Pivoting42936 Node: Pivoting44735
Ref: #pivoting43059 Ref: #pivoting44858
Node: Valuation44735 Node: Valuation46534
Ref: #valuation44837 Ref: #valuation46636
Node: -B Cost45017 Node: -B Cost46816
Ref: #b-cost45128 Ref: #b-cost46927
Node: -V Market value45326 Node: -V Market value47125
Ref: #v-market-value45500 Ref: #v-market-value47299
Node: -X Market value in specified commodity46932 Node: -X Market value in specified commodity48731
Ref: #x-market-value-in-specified-commodity47171 Ref: #x-market-value-in-specified-commodity48970
Node: --value Flexible valuation47347 Node: --value Flexible valuation49146
Ref: #value-flexible-valuation47573 Ref: #value-flexible-valuation49372
Node: Effect of --value on reports52078 Node: Effect of --value on reports53877
Ref: #effect-of---value-on-reports52294 Ref: #effect-of---value-on-reports54093
Node: Combining -B -V -X --value57840 Node: Combining -B -V -X --value59639
Ref: #combining--b--v--x---value58023 Ref: #combining--b--v--x---value59822
Node: COMMANDS58059 Node: COMMANDS59858
Ref: #commands58167 Ref: #commands59966
Node: accounts59251 Node: accounts61050
Ref: #accounts59349 Ref: #accounts61148
Node: activity60048 Node: activity61847
Ref: #activity60158 Ref: #activity61957
Node: add60541 Node: add62340
Ref: #add60640 Ref: #add62439
Node: balance63379 Node: balance65178
Ref: #balance63490 Ref: #balance65289
Node: Classic balance report64948 Node: Classic balance report66747
Ref: #classic-balance-report65121 Ref: #classic-balance-report66920
Node: Customising the classic balance report66490 Node: Customising the classic balance report68289
Ref: #customising-the-classic-balance-report66718 Ref: #customising-the-classic-balance-report68517
Node: Colour support68794 Node: Colour support70593
Ref: #colour-support68961 Ref: #colour-support70760
Node: Flat mode69134 Node: Flat mode70933
Ref: #flat-mode69282 Ref: #flat-mode71081
Node: Depth limited balance reports69695 Node: Depth limited balance reports71494
Ref: #depth-limited-balance-reports69880 Ref: #depth-limited-balance-reports71679
Node: Percentages70336 Node: Percentages72135
Ref: #percentages70502 Ref: #percentages72301
Node: Multicolumn balance report71639 Node: Multicolumn balance report73438
Ref: #multicolumn-balance-report71819 Ref: #multicolumn-balance-report73618
Node: Budget report77081 Node: Budget report78880
Ref: #budget-report77224 Ref: #budget-report79023
Node: Nested budgets82426 Node: Nested budgets84225
Ref: #nested-budgets82538 Ref: #nested-budgets84337
Ref: #output-format-186019 Ref: #output-format-187818
Node: balancesheet86097 Node: balancesheet88015
Ref: #balancesheet86233 Ref: #balancesheet88151
Node: balancesheetequity87616 Node: balancesheetequity89617
Ref: #balancesheetequity87765 Ref: #balancesheetequity89766
Node: cashflow88326 Node: cashflow90489
Ref: #cashflow88454 Ref: #cashflow90617
Node: check-dates89550 Node: check-dates91796
Ref: #check-dates89677 Ref: #check-dates91923
Node: check-dupes89956 Node: check-dupes92202
Ref: #check-dupes90080 Ref: #check-dupes92326
Node: close90373 Node: close92619
Ref: #close90487 Ref: #close92733
Node: close usage92009 Node: close usage94255
Ref: #close-usage92102 Ref: #close-usage94348
Node: commodities94915 Node: commodities97161
Ref: #commodities95042 Ref: #commodities97288
Node: descriptions95124 Node: descriptions97370
Ref: #descriptions95252 Ref: #descriptions97498
Node: diff95433 Node: diff97679
Ref: #diff95539 Ref: #diff97785
Node: files96586 Node: files98832
Ref: #files96686 Ref: #files98932
Node: help96833 Node: help99079
Ref: #help96933 Ref: #help99179
Node: import98014 Node: import100260
Ref: #import98128 Ref: #import100374
Node: Importing balance assignments99021 Node: Importing balance assignments101267
Ref: #importing-balance-assignments99169 Ref: #importing-balance-assignments101415
Node: incomestatement99818 Node: incomestatement102064
Ref: #incomestatement99951 Ref: #incomestatement102197
Node: notes101355 Node: notes103684
Ref: #notes101468 Ref: #notes103797
Node: payees101594 Node: payees103923
Ref: #payees101700 Ref: #payees104029
Node: prices101858 Node: prices104187
Ref: #prices101964 Ref: #prices104293
Node: print102305 Node: print104634
Ref: #print102415 Ref: #print104744
Node: print-unique107123 Node: print-unique109530
Ref: #print-unique107249 Ref: #print-unique109656
Node: register107534 Node: register109941
Ref: #register107661 Ref: #register110068
Node: Custom register output111833 Node: Custom register output114240
Ref: #custom-register-output111962 Ref: #custom-register-output114369
Node: register-match113224 Node: register-match115706
Ref: #register-match113358 Ref: #register-match115840
Node: rewrite113709 Node: rewrite116191
Ref: #rewrite113824 Ref: #rewrite116306
Node: Re-write rules in a file115679 Node: Re-write rules in a file118161
Ref: #re-write-rules-in-a-file115813 Ref: #re-write-rules-in-a-file118295
Node: Diff output format117023 Node: Diff output format119505
Ref: #diff-output-format117192 Ref: #diff-output-format119674
Node: rewrite vs print --auto118284 Node: rewrite vs print --auto120766
Ref: #rewrite-vs.-print---auto118463 Ref: #rewrite-vs.-print---auto120945
Node: roi119019 Node: roi121501
Ref: #roi119117 Ref: #roi121599
Node: stats120129 Node: stats122611
Ref: #stats120228 Ref: #stats122710
Node: tags121016 Node: tags123498
Ref: #tags121114 Ref: #tags123596
Node: test121408 Node: test123890
Ref: #test121516 Ref: #test123998
Node: Add-on Commands122263 Node: Add-on Commands124745
Ref: #add-on-commands122380 Ref: #add-on-commands124862
Node: ui123723 Node: ui126205
Ref: #ui123811 Ref: #ui126293
Node: web123865 Node: web126347
Ref: #web123968 Ref: #web126450
Node: iadd124084 Node: iadd126566
Ref: #iadd124195 Ref: #iadd126677
Node: interest124277 Node: interest126759
Ref: #interest124384 Ref: #interest126866
Node: ENVIRONMENT124624 Node: ENVIRONMENT127106
Ref: #environment124736 Ref: #environment127218
Node: FILES125565 Node: FILES128047
Ref: #files-1125668 Ref: #files-1128150
Node: LIMITATIONS125881 Node: LIMITATIONS128363
Ref: #limitations126000 Ref: #limitations128482
Node: TROUBLESHOOTING126742 Node: TROUBLESHOOTING129224
Ref: #troubleshooting126855 Ref: #troubleshooting129337
 
End Tag Table End Tag Table

762
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff