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

doc: csv tweaks

Browse Source
This commit is contained in:
Simon Michael 2017-04-19 08:58:51 -07:00
parent 05f569f438
commit 2ac77338f8
8 changed files with 115 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
hledger-lib/doc/hledger_csv.5
View File

@ -18,7 +18,7 @@ hledger will create it if necessary, with some default rules which
you\[aq]ll need to adjust. you\[aq]ll need to adjust.
At minimum, the rules file must specify the \f[C]date\f[] and At minimum, the rules file must specify the \f[C]date\f[] and
\f[C]amount\f[] fields. \f[C]amount\f[] fields.
For an example, see How to read CSV files. For an example, see Cookbook: convert CSV files.
.PP .PP
To learn about \f[I]exporting\f[] CSV, see CSV output. To learn about \f[I]exporting\f[] CSV, see CSV output.
.SH CSV RULES .SH CSV RULES
@ -90,7 +90,7 @@ to journal entry fields if you use any of these standard field names:
\f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[],
\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[], \f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[],
\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[], \f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[],
\f[C]amount\-out\f[], \f[C]currency\f[]. \f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[].
Eg: Eg:
.IP .IP
.nf .nf
@ -195,7 +195,7 @@ Eg:
include\ common.rules include\ common.rules
\f[] \f[]
.fi .fi
.SH TIPS .SH CSV TIPS
.PP .PP
Each generated journal entry will have two postings, to Each generated journal entry will have two postings, to
\f[C]account1\f[] and \f[C]account2\f[] respectively. \f[C]account1\f[] and \f[C]account2\f[] respectively.
@ -211,6 +211,11 @@ If the CSV has the currency in a separate field, assign that to the
the amount. the amount.
(Or you can do the same thing with a field assignment.) (Or you can do the same thing with a field assignment.)
.PP .PP
If the CSV includes a running balance, you can assign that to the
\f[C]balance\f[] pseudo field to generate a balance assertion on
\f[C]account1\f[] whenever the balance field is non\-empty.
(Eg to double\-check your bank\[aq]s balance calculation.)
.PP
If an amount value is parenthesised, it will be de\-parenthesised and If an amount value is parenthesised, it will be de\-parenthesised and
sign\-flipped automatically. sign\-flipped automatically.
.PP .PP

52
hledger-lib/doc/hledger_csv.5.info
View File

@ -13,16 +13,16 @@ file". This file should be named like the CSV file with an additional
with '--rules-file PATH'. hledger will create it if necessary, with with '--rules-file PATH'. hledger will create it if necessary, with
some default rules which you'll need to adjust. At minimum, the rules some default rules which you'll need to adjust. At minimum, the rules
file must specify the 'date' and 'amount' fields. For an example, see file must specify the 'date' and 'amount' fields. For an example, see
How to read CSV files. Cookbook: convert CSV files.
To learn about _exporting_ CSV, see CSV output. To learn about _exporting_ CSV, see CSV output.
* Menu: * Menu:
* CSV RULES:: * CSV RULES::
* TIPS:: * CSV TIPS::
 
File: hledger_csv.5.info, Node: CSV RULES, Next: TIPS, Prev: Top, Up: Top File: hledger_csv.5.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top
1 CSV RULES 1 CSV RULES
*********** ***********
@ -89,7 +89,8 @@ File: hledger_csv.5.info, Node: field list, Next: field assignment, Prev: dat
whitespace; uninteresting names may be left blank), and (b) assigns them whitespace; uninteresting names may be left blank), and (b) assigns them
to journal entry fields if you use any of these standard field names: to journal entry fields if you use any of these standard field names:
'date', 'date2', 'status', 'code', 'description', 'comment', 'account1', 'date', 'date2', 'status', 'code', 'description', 'comment', 'account1',
'account2', 'amount', 'amount-in', 'amount-out', 'currency'. Eg: 'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'.
Eg:
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
# and give the 7th and 8th fields meaningful names for later reference: # and give the 7th and 8th fields meaningful names for later reference:
@ -170,10 +171,10 @@ Eg:
include common.rules include common.rules
 
File: hledger_csv.5.info, Node: TIPS, Prev: CSV RULES, Up: Top File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
2 TIPS 2 CSV TIPS
****** **********
Each generated journal entry will have two postings, to 'account1' and Each generated journal entry will have two postings, to 'account1' and
'account2' respectively. Currently it's not possible to generate 'account2' respectively. Currently it's not possible to generate
@ -186,6 +187,11 @@ entries with more than two postings.
'currency' pseudo field which will be automatically prepended to the 'currency' pseudo field which will be automatically prepended to the
amount. (Or you can do the same thing with a field assignment.) amount. (Or you can do the same thing with a field assignment.)
If the CSV includes a running balance, you can assign that to the
'balance' pseudo field to generate a balance assertion on 'account1'
whenever the balance field is non-empty. (Eg to double-check your
bank's balance calculation.)
If an amount value is parenthesised, it will be de-parenthesised and If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped automatically. sign-flipped automatically.
@ -195,21 +201,21 @@ order of same-day entries will be preserved, usually.
 
Tag Table: Tag Table:
Node: Top74 Node: Top74
Node: CSV RULES800 Node: CSV RULES810
Ref: #csv-rules906 Ref: #csv-rules920
Node: skip1149 Node: skip1163
Ref: #skip1245 Ref: #skip1259
Node: date-format1417 Node: date-format1431
Ref: #date-format1546 Ref: #date-format1560
Node: field list2052 Node: field list2066
Ref: #field-list2191 Ref: #field-list2205
Node: field assignment2886 Node: field assignment2910
Ref: #field-assignment3043 Ref: #field-assignment3067
Node: conditional block3547 Node: conditional block3571
Ref: #conditional-block3703 Ref: #conditional-block3727
Node: include4599 Node: include4623
Ref: #include4710 Ref: #include4734
Node: TIPS4941 Node: CSV TIPS4965
Ref: #tips5025 Ref: #csv-tips5061
 
End Tag Table End Tag Table

10
hledger-lib/doc/hledger_csv.5.m4.md
View File

@ -24,7 +24,7 @@ This file should be named like the CSV file with an additional `.rules` suffix (
or, you can specify the file with `--rules-file PATH`. or, you can specify the file with `--rules-file PATH`.
hledger will create it if necessary, with some default rules which you'll need to adjust. hledger will create it if necessary, with some default rules which you'll need to adjust.
At minimum, the rules file must specify the `date` and `amount` fields. At minimum, the rules file must specify the `date` and `amount` fields.
For an example, see [How to read CSV files](how-to-read-csv-files.html). For an example, see [Cookbook: convert CSV files](csv-import.html).
To learn about *exporting* CSV, see [CSV output](hledger.html#csv-output). To learn about *exporting* CSV, see [CSV output](hledger.html#csv-output).
@ -157,7 +157,7 @@ a path relative to the current file's directory. Eg:
include common.rules include common.rules
``` ```
# TIPS # CSV TIPS
Each generated journal entry will have two postings, to `account1` and `account2` respectively. Each generated journal entry will have two postings, to `account1` and `account2` respectively.
Currently it's not possible to generate entries with more than two postings. Currently it's not possible to generate entries with more than two postings.
@ -167,10 +167,14 @@ If the CSV has debit/credit amounts in separate fields, assign to the `amount-in
If the CSV has the currency in a separate field, assign that to the `currency` pseudo field which will be automatically prepended to the amount. If the CSV has the currency in a separate field, assign that to the `currency` pseudo field which will be automatically prepended to the amount.
(Or you can do the same thing with a field assignment.) (Or you can do the same thing with a field assignment.)
If the CSV includes a running balance, you can assign that to the `balance` pseudo field
to generate a [balance assertion](/journal.html#balance-assertoins) on `account1`
whenever the balance field is non-empty.
(Eg to double-check your bank's balance calculation.)
If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically.
The generated journal entries will be sorted by date. The generated journal entries will be sorted by date.
The original order of same-day entries will be preserved, usually. The original order of same-day entries will be preserved, usually.
<!-- (by reversing the CSV entries if they seem to be in reverse date order). --> <!-- (by reversing the CSV entries if they seem to be in reverse date order). -->
If you assign anything to the `balance` pseudo field, it would become an assertion of the balance of `account1`. If you assign empty string to it, no assertion will be generated (this can be used to omit balance assertions on some transactions).

21
hledger-lib/doc/hledger_csv.5.txt
View File

@ -13,8 +13,8 @@ DESCRIPTION
.rules suffix (eg: mybank.csv.rules); or, you can specify the file with .rules suffix (eg: mybank.csv.rules); or, you can specify the file with
--rules-file PATH. hledger will create it if necessary, with some --rules-file PATH. hledger will create it if necessary, with some
default rules which you'll need to adjust. At minimum, the rules file default rules which you'll need to adjust. At minimum, the rules file
must specify the date and amount fields. For an example, see How to must specify the date and amount fields. For an example, see Cookbook:
read CSV files. convert CSV files.
To learn about exporting CSV, see CSV output. To learn about exporting CSV, see CSV output.
@ -58,7 +58,7 @@ CSV RULES
space; uninteresting names may be left blank), and (b) assigns them to space; uninteresting names may be left blank), and (b) assigns them to
journal entry fields if you use any of these standard field names: journal entry fields if you use any of these standard field names:
date, date2, status, code, description, comment, account1, account2, date, date2, status, code, description, comment, account1, account2,
amount, amount-in, amount-out, currency. Eg: amount, amount-in, amount-out, currency, balance. Eg:
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
# and give the 7th and 8th fields meaningful names for later reference: # and give the 7th and 8th fields meaningful names for later reference:
@ -123,7 +123,7 @@ CSV RULES
# rules reused with several CSV files # rules reused with several CSV files
include common.rules include common.rules
TIPS CSV TIPS
Each generated journal entry will have two postings, to account1 and Each generated journal entry will have two postings, to account1 and
account2 respectively. Currently it's not possible to generate entries account2 respectively. Currently it's not possible to generate entries
with more than two postings. with more than two postings.
@ -135,16 +135,21 @@ TIPS
currency pseudo field which will be automatically prepended to the currency pseudo field which will be automatically prepended to the
amount. (Or you can do the same thing with a field assignment.) amount. (Or you can do the same thing with a field assignment.)
If an amount value is parenthesised, it will be de-parenthesised and If the CSV includes a running balance, you can assign that to the bal-
ance pseudo field to generate a balance assertion on account1 whenever
the balance field is non-empty. (Eg to double-check your bank's bal-
ance calculation.)
If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped automatically. sign-flipped automatically.
The generated journal entries will be sorted by date. The original The generated journal entries will be sorted by date. The original
order of same-day entries will be preserved, usually. order of same-day entries will be preserved, usually.
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)
@ -158,7 +163,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)

3
hledger-lib/doc/hledger_journal.5
View File

@ -739,8 +739,7 @@ alias\ checking\ =\ assets:bank:wells\ fargo:checking
.SS Regex aliases .SS Regex aliases
.PP .PP
There is also a more powerful variant that uses a regular expression, There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. indicated by the forward slashes:
(This was the default behaviour in hledger 0.24\-0.25):
.IP .IP
.nf .nf
\f[C] \f[C]

43
hledger-lib/doc/hledger_journal.5.info
View File

@ -736,8 +736,7 @@ File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Pr
...................... ......................
There is also a more powerful variant that uses a regular expression, There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in indicated by the forward slashes:
hledger 0.24-0.25):
alias /REGEX/ = REPLACEMENT alias /REGEX/ = REPLACEMENT
@ -1018,25 +1017,25 @@ Node: Basic aliases25540
Ref: #basic-aliases25685 Ref: #basic-aliases25685
Node: Regex aliases26375 Node: Regex aliases26375
Ref: #regex-aliases26545 Ref: #regex-aliases26545
Node: Multiple aliases27316 Node: Multiple aliases27260
Ref: #multiple-aliases27490 Ref: #multiple-aliases27434
Node: end aliases27988 Node: end aliases27932
Ref: #end-aliases28130 Ref: #end-aliases28074
Node: account directive28231 Node: account directive28175
Ref: #account-directive28413 Ref: #account-directive28357
Node: apply account directive28709 Node: apply account directive28653
Ref: #apply-account-directive28907 Ref: #apply-account-directive28851
Node: Multi-line comments29566 Node: Multi-line comments29510
Ref: #multi-line-comments29758 Ref: #multi-line-comments29702
Node: commodity directive29886 Node: commodity directive29830
Ref: #commodity-directive30072 Ref: #commodity-directive30016
Node: Default commodity30944 Node: Default commodity30888
Ref: #default-commodity31119 Ref: #default-commodity31063
Node: Default year31656 Node: Default year31600
Ref: #default-year31823 Ref: #default-year31767
Node: Including other files32246 Node: Including other files32190
Ref: #including-other-files32405 Ref: #including-other-files32349
Node: EDITOR SUPPORT32802 Node: EDITOR SUPPORT32746
Ref: #editor-support32922 Ref: #editor-support32866
 
End Tag Table End Tag Table

69
hledger-lib/doc/hledger_journal.5.txt
View File

@ -559,44 +559,43 @@ FILE FORMAT
Regex aliases Regex aliases
There is also a more powerful variant that uses a regular expression, There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in indicated by the forward slashes:
hledger 0.24-0.25):
alias /REGEX/ = REPLACEMENT alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'. or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE- inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref- MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Note, cur- erenced by the usual numeric backreferences in REPLACEMENT. Note, cur-
rently regular expression aliases may cause noticeable slow-downs. rently regular expression aliases may cause noticeable slow-downs.
(And if you use Ledger on your hledger file, they will be ignored.) Eg: (And if you use Ledger on your hledger file, they will be ignored.) Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Multiple aliases Multiple aliases
You can define as many aliases as you like using directives or com- You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol- aliases are non-recursive by default). Aliases are applied in the fol-
lowing order: lowing order:
1. alias directives, most recently seen first (recent directives take 1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored) precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line 2. alias options, in the order they appear on the command line
end aliases end aliases
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases with the
end aliases directive: end aliases directive:
end aliases end aliases
account directive account directive
The account directive predefines account names, as in Ledger and Bean- The account directive predefines account names, as in Ledger and Bean-
count. This may be useful for your own documentation; hledger doesn't count. This may be useful for your own documentation; hledger doesn't
make use of it yet. make use of it yet.
; account ACCT ; account ACCT
@ -611,8 +610,8 @@ FILE FORMAT
; etc. ; etc.
apply account directive apply account directive
You can specify a parent account which will be prepended to all You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and accounts within a section of the journal. Use the apply account and
end apply account directives like so: end apply account directives like so:
apply account home apply account home
@ -629,7 +628,7 @@ FILE FORMAT
home:food $10 home:food $10
home:cash $-10 home:cash $-10
If end apply account is omitted, the effect lasts to the end of the If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg: file. Included files are also affected, eg:
apply account business apply account business
@ -638,16 +637,16 @@ FILE FORMAT
apply account personal apply account personal
include personal.journal include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup- Prior to hledger 1.0, legacy account and end spellings were also sup-
ported. ported.
Multi-line comments Multi-line comments
A line containing just comment starts a multi-line comment, and a line A line containing just comment starts a multi-line comment, and a line
containing just end comment ends it. See comments. containing just end comment ends it. See comments.
commodity directive commodity directive
The commodity directive predefines commodities (currently this is just The commodity directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format). in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this: It may be written on a single line, like this:
@ -659,8 +658,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places: places:
; commodity SYMBOL ; commodity SYMBOL
@ -673,10 +672,10 @@ FILE FORMAT
format INR 9,99,99,999.00 format INR 9,99,99,999.00
Default commodity Default commodity
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive. amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars # commodity-less amounts should be treated as dollars
@ -688,8 +687,8 @@ FILE FORMAT
b b
Default year Default year
You can set a default year to be used for subsequent dates which don't You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -709,24 +708,24 @@ FILE FORMAT
assets assets
Including other files Including other files
You can pull in the content of additional journal files by writing an You can pull in the content of additional journal files by writing an
include directive, like this: include directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported. file. Glob patterns (*) are not currently supported.
The include directive can only be used in journal files. It can The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files. include journal, timeclock or timedot files, but not CSV files.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger These were written with Ledger in mind, but also work with hledger
files: files:
@ -743,7 +742,7 @@ EDITOR SUPPORT
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)
@ -757,7 +756,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)

2
site/csv-import.md
View File

@ -55,3 +55,5 @@ using conversion rules file checking.csv.rules
-------------------- --------------------
0 0
``` ```
Here are more [CSV rules examples](http://code.hledger.org/tree/master/examples/csv).