summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.otherdocs/hledger-api.1 (renamed from doc/other/hledger-api.1)2
-rw-r--r--.otherdocs/hledger-api.info (renamed from doc/other/hledger-api.1.info)14
-rw-r--r--.otherdocs/hledger-api.txt (renamed from doc/other/hledger-api.1.txt)2
-rw-r--r--.otherdocs/hledger-ui.1 (renamed from doc/other/hledger-ui.1)69
-rw-r--r--.otherdocs/hledger-ui.info (renamed from doc/other/hledger-ui.1.info)63
-rw-r--r--.otherdocs/hledger-ui.txt (renamed from doc/other/hledger-ui.1.txt)184
-rw-r--r--.otherdocs/hledger-web.1 (renamed from doc/other/hledger-web.1)33
-rw-r--r--.otherdocs/hledger-web.info (renamed from doc/other/hledger-web.1.info)23
-rw-r--r--.otherdocs/hledger-web.txt (renamed from doc/other/hledger-web.1.txt)26
-rw-r--r--.otherdocs/hledger_csv.5 (renamed from doc/other/hledger_csv.5)125
-rw-r--r--.otherdocs/hledger_csv.info (renamed from doc/other/hledger_csv.5.info)157
-rw-r--r--.otherdocs/hledger_csv.txt (renamed from doc/other/hledger_csv.5.txt)69
-rw-r--r--.otherdocs/hledger_journal.5 (renamed from doc/other/hledger_journal.5)284
-rw-r--r--.otherdocs/hledger_journal.info (renamed from doc/other/hledger_journal.5.info)374
-rw-r--r--.otherdocs/hledger_journal.txt (renamed from doc/other/hledger_journal.5.txt)210
-rw-r--r--.otherdocs/hledger_timeclock.5 (renamed from doc/other/hledger_timeclock.5)18
-rw-r--r--.otherdocs/hledger_timeclock.info (renamed from doc/other/hledger_timeclock.5.info)16
-rw-r--r--.otherdocs/hledger_timeclock.txt (renamed from doc/other/hledger_timeclock.5.txt)8
-rw-r--r--.otherdocs/hledger_timedot.5 (renamed from doc/other/hledger_timedot.5)14
-rw-r--r--.otherdocs/hledger_timedot.info (renamed from doc/other/hledger_timedot.5.info)34
-rw-r--r--.otherdocs/hledger_timedot.txt (renamed from doc/other/hledger_timedot.5.txt)2
-rw-r--r--CHANGES30
-rw-r--r--Hledger/Cli/CliOptions.hs2
-rw-r--r--Hledger/Cli/Commands/Add.hs4
-rw-r--r--Hledger/Cli/Commands/Balance.hs134
-rwxr-xr-xHledger/Cli/Commands/Equity.hs4
-rwxr-xr-xHledger/Cli/Commands/Import.hs2
-rw-r--r--Hledger/Cli/Commands/Print.hs11
-rwxr-xr-xHledger/Cli/Commands/Tags.hs26
-rw-r--r--Hledger/Cli/DocFiles.hs48
-rw-r--r--Hledger/Cli/Utils.hs57
-rw-r--r--README.md2
-rw-r--r--hledger.1 (renamed from doc/hledger.1)517
-rw-r--r--hledger.cabal227
-rw-r--r--hledger.info (renamed from doc/hledger.1.info)711
-rw-r--r--hledger.txt (renamed from doc/hledger.1.txt)547
36 files changed, 2628 insertions, 1421 deletions
diff --git a/doc/other/hledger-api.1 b/.otherdocs/hledger-api.1
index 360b35a..c130ca9 100644
--- a/doc/other/hledger-api.1
+++ b/.otherdocs/hledger-api.1
@@ -1,5 +1,5 @@
-.TH "hledger\-api" "1" "September 2017" "hledger\-api 1.4" "hledger User Manuals"
+.TH "hledger\-api" "1" "December 2017" "hledger\-api 1.5" "hledger User Manuals"
diff --git a/doc/other/hledger-api.1.info b/.otherdocs/hledger-api.info
index f40636d..17e72e1 100644
--- a/doc/other/hledger-api.1.info
+++ b/.otherdocs/hledger-api.info
@@ -1,9 +1,9 @@
-This is hledger-api.1.info, produced by makeinfo version 6.0 from stdin.
+This is hledger-api.info, produced by makeinfo version 6.5 from stdin.

-File: hledger-api.1.info, Node: Top, Next: OPTIONS, Up: (dir)
+File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir)
-hledger-api(1) hledger-api 1.4
+hledger-api(1) hledger-api 1.5
******************************
hledger-api is a simple web API server, intended to support client-side
@@ -30,7 +30,7 @@ the API docs will be printed in Swagger 2.0 format.
* OPTIONS::

-File: hledger-api.1.info, Node: OPTIONS, Prev: Top, Up: Top
+File: hledger-api.info, Node: OPTIONS, Prev: Top, Up: Top
1 OPTIONS
*********
@@ -63,8 +63,8 @@ options as shown above.

Tag Table:
-Node: Top74
-Node: OPTIONS1220
-Ref: #options1307
+Node: Top72
+Node: OPTIONS1216
+Ref: #options1301

End Tag Table
diff --git a/doc/other/hledger-api.1.txt b/.otherdocs/hledger-api.txt
index 1dc6340..fc47fb6 100644
--- a/doc/other/hledger-api.1.txt
+++ b/.otherdocs/hledger-api.txt
@@ -102,4 +102,4 @@ SEE ALSO
-hledger-api 1.4 September 2017 hledger-api(1)
+hledger-api 1.5 December 2017 hledger-api(1)
diff --git a/doc/other/hledger-ui.1 b/.otherdocs/hledger-ui.1
index df44699..d94244e 100644
--- a/doc/other/hledger-ui.1
+++ b/.otherdocs/hledger-ui.1
@@ -1,5 +1,5 @@
-.TH "hledger\-ui" "1" "September 2017" "hledger\-ui 1.4" "hledger User Manuals"
+.TH "hledger\-ui" "1" "December 2017" "hledger\-ui 1.5" "hledger User Manuals"
@@ -20,10 +20,10 @@ other commodity, using double\-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
-hledger\-ui is hledger\[aq]s curses\-style interface, providing an
-efficient full\-window text UI for viewing accounts and transactions,
-and some limited data entry capability.
-It is easier than hledger\[aq]s command\-line interface, and sometimes
+hledger\-ui is hledger's curses\-style interface, providing an efficient
+full\-window text UI for viewing accounts and transactions, and some
+limited data entry capability.
+It is easier than hledger's command\-line interface, and sometimes
quicker and more convenient than the web interface.
.PP
Like hledger, it reads data from one or more files in hledger journal,
@@ -50,7 +50,7 @@ use this custom display theme
.RE
.TP
.B \f[C]\-\-register=ACCTREGEX\f[]
-start in the (first) matched account\[aq]s register screen
+start in the (first) matched account's register screen
.RS
.RE
.TP
@@ -136,8 +136,8 @@ multiperiod/multicolumn report by year
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
-set start date, end date, and/or reporting interval all at once
-(overrides the flags above)
+set start date, end date, and/or reporting interval all at once using
+period expressions syntax (overrides the flags above)
.RS
.RE
.TP
@@ -187,6 +187,17 @@ convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
+.TP
+.B \f[C]\-\-auto\f[]
+apply automated posting rules to modify transactions.
+.RS
+.RE
+.TP
+.B \f[C]\-\-forecast\f[]
+apply periodic transaction rules to generate future transactions, to 6
+months from now or report end date.
+.RS
+.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@@ -230,7 +241,7 @@ Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style
movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it.
-(If you\[aq]re on a mac, the Karabiner app is one way to do that.)
+(If you're on a mac, the Karabiner app is one way to do that.)
.PP
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
@@ -238,9 +249,9 @@ the transactions to be shown (by default, all are shown).
report period durations: year, quarter, month, week, day.
Then, \f[C]shift\-left/right\f[] moves to the previous/next period.
\f[C]t\f[] sets the report period to today.
-With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the
-current day, week, month, quarter, or year), the period will move
-automatically to track the current date.
+With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq]
+period (the current day, week, month, quarter, or year), the period will
+move automatically to track the current date.
To set a non\-standard period, you can use \f[C]/\f[] and a
\f[C]date:\f[] query.
.PP
@@ -257,8 +268,8 @@ transactions.
Or, it cancels a minibuffer edit or help dialog in progress.
.PP
\f[C]CTRL\-l\f[] redraws the screen and centers the selection if
-possible (selections near the top won\[aq]t be centered, since we
-don\[aq]t scroll above the top).
+possible (selections near the top won't be centered, since we don't
+scroll above the top).
.PP
\f[C]g\f[] reloads from the data file(s) and updates the current screen
and any previous screens.
@@ -268,10 +279,15 @@ and any previous screens.
Disabling balance assertions temporarily can be useful for
troubleshooting.
.PP
-\f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the
+\f[C]a\f[] runs command\-line hledger's add command, and reloads the
updated file.
This allows some basic data entry.
.PP
+\f[C]A\f[] is like \f[C]a\f[], but runs the hledger\-iadd tool, which
+provides a curses\-style interface.
+This key will be available if \f[C]hledger\-iadd\f[] is installed in
+$PATH.
+.PP
\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default
(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file.
With some editors (emacs, vi), the cursor will be positioned at the
@@ -286,8 +302,7 @@ Additional screen\-specific keys are described below.
.SS Accounts screen
.PP
This is normally the first screen displayed.
-It lists accounts and their balances, like hledger\[aq]s balance
-command.
+It lists accounts and their balances, like hledger's balance command.
By default, it shows all accounts and their latest ending balances
(including the balances of subaccounts).
if you specify a query on the command line, it shows just the matched
@@ -306,7 +321,7 @@ or press \f[C]ESCAPE\f[].
\f[C]F\f[] toggles flat mode, in which accounts are shown as a flat
list, with their full names.
In this mode, account balances exclude subaccounts, except for accounts
-at the depth limit (as with hledger\[aq]s balance command).
+at the depth limit (as with hledger's balance command).
.PP
\f[C]H\f[] toggles between showing historical balances or period
balances.
@@ -334,8 +349,8 @@ all three, the filter is removed.)
balances are shown (hledger\-ui shows zero items by default, unlike
command\-line hledger).
.PP
-Press \f[C]right\f[] or \f[C]enter\f[] to view an account\[aq]s
-transactions register.
+Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions
+register.
.SS Register screen
.PP
This screen shows the transactions affecting a particular account, like
@@ -346,7 +361,7 @@ the other account(s) involved, in abbreviated form.
(If there are both real and virtual postings, it shows only the accounts
affected by real postings.)
.IP \[bu] 2
-the overall change to the current account\[aq]s balance; positive for an
+the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow.
.IP \[bu] 2
the running historical total or period total for the current account,
@@ -387,10 +402,10 @@ transaction in detail.
.SS Transaction screen
.PP
This screen shows a single transaction, as a general journal entry,
-similar to hledger\[aq]s print command and journal format
+similar to hledger's print command and journal format
(hledger_journal(5)).
.PP
-The transaction\[aq]s date(s) and any cleared flag, transaction code,
+The transaction's date(s) and any cleared flag, transaction code,
description, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
certain cases, fewer).
@@ -401,9 +416,9 @@ In the title bar, the numbers in parentheses show your position within
that account register.
They will vary depending on which account register you came from
(remember most transactions appear in multiple account registers).
-The #N number preceding them is the transaction\[aq]s position within
-the complete unfiltered journal, which is a more stable id (at least
-until the next reload).
+The #N number preceding them is the transaction's position within the
+complete unfiltered journal, which is a more stable id (at least until
+the next reload).
.SS Error screen
.PP
This screen will appear if there is a problem, such as a parse error,
@@ -431,7 +446,7 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
-\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin).
+\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin).
.PP
\f[C]\-V\f[] affects only the accounts screen.
.PP
diff --git a/doc/other/hledger-ui.1.info b/.otherdocs/hledger-ui.info
index e9b2fd1..4a0927f 100644
--- a/doc/other/hledger-ui.1.info
+++ b/.otherdocs/hledger-ui.info
@@ -1,9 +1,9 @@
-This is hledger-ui.1.info, produced by makeinfo version 6.0 from stdin.
+This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.

-File: hledger-ui.1.info, Node: Top, Next: OPTIONS, Up: (dir)
+File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
-hledger-ui(1) hledger-ui 1.4
+hledger-ui(1) hledger-ui 1.5
****************************
hledger-ui is hledger's curses-style interface, providing an efficient
@@ -24,7 +24,7 @@ hledger_journal(5) etc.
* SCREENS::

-File: hledger-ui.1.info, Node: OPTIONS, Next: KEYS, Prev: Top, Up: Top
+File: hledger-ui.info, Node: OPTIONS, Next: KEYS, Prev: Top, Up: Top
1 OPTIONS
*********
@@ -100,7 +100,7 @@ the data.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
- (overrides the flags above)
+ using period expressions syntax (overrides the flags above)
'--date2'
match the secondary date instead (see command help for other
@@ -131,6 +131,13 @@ the data.
convert amounts to their market value on the report end date (using
the most recent applicable market price, if any)
+'--auto'
+
+ apply automated posting rules to modify transactions.
+'--forecast'
+
+ apply periodic transaction rules to generate future transactions,
+ to 6 months from now or report end date.
When a reporting option appears more than once in the command line,
the last one takes precedence.
@@ -154,7 +161,7 @@ should contain one command line option/argument per line. (To prevent
this, insert a '--' argument before.)

-File: hledger-ui.1.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top
+File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top
2 KEYS
******
@@ -207,6 +214,10 @@ temporarily can be useful for troubleshooting.
'a' runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry.
+ 'A' is like 'a', but runs the hledger-iadd tool, which provides a
+curses-style interface. This key will be available if 'hledger-iadd' is
+installed in $PATH.
+
'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient
-a "" -nw') on the journal file. With some editors (emacs, vi), the
cursor will be positioned at the current transaction when invoked from
@@ -218,7 +229,7 @@ possible) when invoked from the error screen.
Additional screen-specific keys are described below.

-File: hledger-ui.1.info, Node: SCREENS, Prev: KEYS, Up: Top
+File: hledger-ui.info, Node: SCREENS, Prev: KEYS, Up: Top
3 SCREENS
*********
@@ -231,7 +242,7 @@ File: hledger-ui.1.info, Node: SCREENS, Prev: KEYS, Up: Top
* Error screen::

-File: hledger-ui.1.info, Node: Accounts screen, Next: Register screen, Up: SCREENS
+File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCREENS
3.1 Accounts screen
===================
@@ -280,7 +291,7 @@ command-line hledger).
Press 'right' or 'enter' to view an account's transactions register.

-File: hledger-ui.1.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS
+File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS
3.2 Register screen
===================
@@ -328,7 +339,7 @@ command-line hledger).
detail.

-File: hledger-ui.1.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS
+File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS
3.3 Transaction screen
======================
@@ -352,7 +363,7 @@ unfiltered journal, which is a more stable id (at least until the next
reload).

-File: hledger-ui.1.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS
+File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS
3.4 Error screen
================
@@ -364,20 +375,20 @@ to cancel the reload attempt.)

Tag Table:
-Node: Top73
-Node: OPTIONS825
-Ref: #options924
-Node: KEYS3861
-Ref: #keys3958
-Node: SCREENS6754
-Ref: #screens6841
-Node: Accounts screen6931
-Ref: #accounts-screen7061
-Node: Register screen9291
-Ref: #register-screen9448
-Node: Transaction screen11522
-Ref: #transaction-screen11682
-Node: Error screen12552
-Ref: #error-screen12676
+Node: Top71
+Node: OPTIONS821
+Ref: #options918
+Node: KEYS4087
+Ref: #keys4182
+Node: SCREENS7141
+Ref: #screens7226
+Node: Accounts screen7316
+Ref: #accounts-screen7444
+Node: Register screen9674
+Ref: #register-screen9829
+Node: Transaction screen11903
+Ref: #transaction-screen12061
+Node: Error screen12931
+Ref: #error-screen13053

End Tag Table
diff --git a/doc/other/hledger-ui.1.txt b/.otherdocs/hledger-ui.txt
index e1385ac..19559eb 100644
--- a/doc/other/hledger-ui.1.txt
+++ b/.otherdocs/hledger-ui.txt
@@ -96,7 +96,7 @@ OPTIONS
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
- (overrides the flags above)
+ using period expressions syntax (overrides the flags above)
--date2
match the secondary date instead (see command help for other
@@ -128,6 +128,12 @@ OPTIONS
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
+ --auto apply automated posting rules to modify transactions.
+
+ --forecast
+ apply periodic transaction rules to generate future transac-
+ tions, to 6 months from now or report end date.
+
When a reporting option appears more than once in the command line, the
last one takes precedence.
@@ -145,60 +151,64 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
- contain one command line option/argument per line. (To prevent this,
+ contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
KEYS
- ? shows a help dialog listing all keys. (Some of these also appear in
+ ? shows a help dialog listing all keys. (Some of these also appear in
the quick help at the bottom of each screen.) Press ? again (or ESCAPE,
or LEFT) to close it. The following keys work on most screens:
The cursor keys navigate: right (or enter) goes deeper, left returns to
- the previous screen, up/down/page up/page down/home/end move up and
- down through lists. Vi-style (h/j/k/l) and Emacs-style
+ the previous screen, up/down/page up/page down/home/end move up and
+ down through lists. Vi-style (h/j/k/l) and Emacs-style
(CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip:
- movement speed is limited by your keyboard repeat rate, to move faster
- you may want to adjust it. (If you're on a mac, the Karabiner app is
+ movement speed is limited by your keyboard repeat rate, to move faster
+ you may want to adjust it. (If you're on a mac, the Karabiner app is
one way to do that.)
- With shift pressed, the cursor keys adjust the report period, limiting
- the transactions to be shown (by default, all are shown).
- shift-down/up steps downward and upward through these standard report
+ With shift pressed, the cursor keys adjust the report period, limiting
+ the transactions to be shown (by default, all are shown).
+ shift-down/up steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then,
- shift-left/right moves to the previous/next period. t sets the report
- period to today. With the --watch option, when viewing a "current"
- period (the current day, week, month, quarter, or year), the period
- will move automatically to track the current date. To set a non-stan-
+ shift-left/right moves to the previous/next period. t sets the report
+ period to today. With the --watch option, when viewing a "current"
+ period (the current day, week, month, quarter, or year), the period
+ will move automatically to track the current date. To set a non-stan-
dard period, you can use / and a date: query.
- / lets you set a general filter query limiting the data shown, using
- the same query terms as in hledger and hledger-web. While editing the
- query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
+ / lets you set a general filter query limiting the data shown, using
+ the same query terms as in hledger and hledger-web. While editing the
+ query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
it, or ESCAPEto cancel. There are also keys for quickly adjusting some
- common filters like account depth and transaction status (see below).
+ common filters like account depth and transaction status (see below).
BACKSPACE or DELETE removes all filters, showing all transactions.
- ESCAPE removes all filters and jumps back to the top screen. Or, it
+ ESCAPE removes all filters and jumps back to the top screen. Or, it
cancels a minibuffer edit or help dialog in progress.
CTRL-l redraws the screen and centers the selection if possible (selec-
- tions near the top won't be centered, since we don't scroll above the
+ tions near the top won't be centered, since we don't scroll above the
top).
- g reloads from the data file(s) and updates the current screen and any
- previous screens. (With large files, this could cause a noticeable
+ g reloads from the data file(s) and updates the current screen and any
+ previous screens. (With large files, this could cause a noticeable
pause.)
- I toggles balance assertion checking. Disabling balance assertions
+ I toggles balance assertion checking. Disabling balance assertions
temporarily can be useful for troubleshooting.
- a runs command-line hledger's add command, and reloads the updated
+ a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry.
- E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac-
+ A is like a, but runs the hledger-iadd tool, which provides a
+ curses-style interface. This key will be available if hledger-iadd is
+ installed in $PATH.
+
+ E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac-
sclient -a "" -nw) on the journal file. With some editors (emacs, vi),
- the cursor will be positioned at the current transaction when invoked
- from the register and transaction screens, and at the error location
+ the cursor will be positioned at the current transaction when invoked
+ from the register and transaction screens, and at the error location
(if possible) when invoked from the error screen.
q quits the application.
@@ -207,44 +217,44 @@ KEYS
SCREENS
Accounts screen
- This is normally the first screen displayed. It lists accounts and
- their balances, like hledger's balance command. By default, it shows
- all accounts and their latest ending balances (including the balances
- of subaccounts). if you specify a query on the command line, it shows
+ This is normally the first screen displayed. It lists accounts and
+ their balances, like hledger's balance command. By default, it shows
+ all accounts and their latest ending balances (including the balances
+ of subaccounts). if you specify a query on the command line, it shows
just the matched accounts and the balances from matched transactions.
- Account names are normally indented to show the hierarchy (tree mode).
+ Account names are normally indented to show the hierarchy (tree mode).
To see less detail, set a depth limit by pressing a number key, 1 to 9.
0 shows even less detail, collapsing all accounts to a single total. -
- and + (or =) decrease and increase the depth limit. To remove the
- depth limit, set it higher than the maximum account depth, or press
+ and + (or =) decrease and increase the depth limit. To remove the
+ depth limit, set it higher than the maximum account depth, or press
ESCAPE.
- F toggles flat mode, in which accounts are shown as a flat list, with
- their full names. In this mode, account balances exclude subaccounts,
- except for accounts at the depth limit (as with hledger's balance com-
+ F toggles flat mode, in which accounts are shown as a flat list, with
+ their full names. In this mode, account balances exclude subaccounts,
+ except for accounts at the depth limit (as with hledger's balance com-
mand).
H toggles between showing historical balances or period balances. His-
- torical balances (the default) are ending balances at the end of the
- report period, taking into account all transactions before that date
- (filtered by the filter query if any), including transactions before
- the start of the report period. In other words, historical balances
- are what you would see on a bank statement for that account (unless
- disturbed by a filter query). Period balances ignore transactions
+ torical balances (the default) are ending balances at the end of the
+ report period, taking into account all transactions before that date
+ (filtered by the filter query if any), including transactions before
+ the start of the report period. In other words, historical balances
+ are what you would see on a bank statement for that account (unless
+ disturbed by a filter query). Period balances ignore transactions
before the report start date, so they show the change in balance during
the report period. They are more useful eg when viewing a time log.
U toggles filtering by unmarked status, including or excluding unmarked
postings in the balances. Similarly, P toggles pending postings, and C
- toggles cleared postings. (By default, balances include all postings;
- if you activate one or two status filters, only those postings are
+ toggles cleared postings. (By default, balances include all postings;
+ if you activate one or two status filters, only those postings are
included; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
- Z toggles nonzero mode, in which only accounts with nonzero balances
- are shown (hledger-ui shows zero items by default, unlike command-line
+ Z toggles nonzero mode, in which only accounts with nonzero balances
+ are shown (hledger-ui shows zero items by default, unlike command-line
hledger).
Press right or enter to view an account's transactions register.
@@ -253,65 +263,65 @@ SCREENS
This screen shows the transactions affecting a particular account, like
a check register. Each line represents one transaction and shows:
- o the other account(s) involved, in abbreviated form. (If there are
- both real and virtual postings, it shows only the accounts affected
+ o the other account(s) involved, in abbreviated form. (If there are
+ both real and virtual postings, it shows only the accounts affected
by real postings.)
- o the overall change to the current account's balance; positive for an
+ o the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow.
o the running historical total or period total for the current account,
- after the transaction. This can be toggled with H. Similar to the
- accounts screen, the historical total is affected by transactions
- (filtered by the filter query) before the report start date, while
+ after the transaction. This can be toggled with H. Similar to the
+ accounts screen, the historical total is affected by transactions
+ (filtered by the filter query) before the report start date, while
the period total is not. If the historical total is not disturbed by
- a filter query, it will be the running historical balance you would
+ a filter query, it will be the running historical balance you would
see on a bank register for the current account.
- If the accounts screen was in tree mode, the register screen will
+ If the accounts screen was in tree mode, the register screen will
include transactions from both the current account and its subaccounts.
- If the accounts screen was in flat mode, and a non-depth-clipped
- account was selected, the register screen will exclude transactions
+ If the accounts screen was in flat mode, and a non-depth-clipped
+ account was selected, the register screen will exclude transactions
from subaccounts. In other words, the register always shows the trans-
- actions responsible for the period balance shown on the accounts
+ actions responsible for the period balance shown on the accounts
screen. As on the accounts screen, this can be toggled with F.
- U toggles filtering by unmarked status, showing or hiding unmarked
+ U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles
- cleared transactions. (By default, transactions with all statuses are
- shown; if you activate one or two status filters, only those transac-
- tions are shown; and if you activate all three, the filter is
+ cleared transactions. (By default, transactions with all statuses are
+ shown; if you activate one or two status filters, only those transac-
+ tions are shown; and if you activate all three, the filter is
removed.)q
R toggles real mode, in which virtual postings are ignored.
- Z toggles nonzero mode, in which only transactions posting a nonzero
- change are shown (hledger-ui shows zero items by default, unlike com-
+ Z toggles nonzero mode, in which only transactions posting a nonzero
+ change are shown (hledger-ui shows zero items by default, unlike com-
mand-line hledger).
Press right (or enter) to view the selected transaction in detail.
Transaction screen
- This screen shows a single transaction, as a general journal entry,
- similar to hledger's print command and journal format (hledger_jour-
+ This screen shows a single transaction, as a general journal entry,
+ similar to hledger's print command and journal format (hledger_jour-
nal(5)).
- The transaction's date(s) and any cleared flag, transaction code,
- description, comments, along with all of its account postings are
- shown. Simple transactions have two postings, but there can be more
+ The transaction's date(s) and any cleared flag, transaction code,
+ description, comments, along with all of its account postings are
+ shown. Simple transactions have two postings, but there can be more
(or in certain cases, fewer).
- up and down will step through all transactions listed in the previous
- account register screen. In the title bar, the numbers in parentheses
- show your position within that account register. They will vary
+ up and down will step through all transactions listed in the previous
+ account register screen. In the title bar, the numbers in parentheses
+ show your position within that account register. They will vary
depending on which account register you came from (remember most trans-
actions appear in multiple account registers). The #N number preceding
them is the transaction's position within the complete unfiltered jour-
nal, which is a more stable id (at least until the next reload).
Error screen
- This screen will appear if there is a problem, such as a parse error,
- when you press g to reload. Once you have fixed the problem, press g
+ This screen will appear if there is a problem, such as a parse error,
+ when you press g to reload. Once you have fixed the problem, press g
again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)
@@ -319,17 +329,17 @@ ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
- Reads data from one or more files in hledger journal, timeclock, time-
- dot, or CSV format specified with -f, or $LEDGER_FILE, or
- $HOME/.hledger.journal (on windows, perhaps
+ Reads data from one or more files in hledger journal, timeclock, time-
+ dot, or CSV format specified with -f, or $LEDGER_FILE, or
+ $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
- The need to precede options with -- when invoked from hledger is awk-
+ The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-ui can't read from stdin).
@@ -337,13 +347,13 @@ BUGS
-V affects only the accounts screen.
When you press g, the current and all previous screens are regenerated,
- which may cause a noticeable pause with large files. Also there is no
+ which may cause a noticeable pause with large files. Also there is no
visual indication that this is in progress.
- --watch is not yet fully robust. It works well for normal usage, but
- many file changes in a short time (eg saving the file thousands of
- times with an editor macro) can cause problems at least on OSX. Symp-
- toms include: unresponsive UI, periodic resetting of the cursor posi-
+ --watch is not yet fully robust. It works well for normal usage, but
+ many file changes in a short time (eg saving the file thousands of
+ times with an editor macro) can cause problems at least on OSX. Symp-
+ toms include: unresponsive UI, periodic resetting of the cursor posi-
tion, momentary display of parse errors, high CPU usage eventually sub-
siding, and possibly a small but persistent build-up of CPU usage until
the program is restarted.
@@ -351,7 +361,7 @@ 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)
@@ -365,7 +375,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -373,4 +383,4 @@ SEE ALSO
-hledger-ui 1.4 September 2017 hledger-ui(1)
+hledger-ui 1.5 December 2017 hledger-ui(1)
diff --git a/doc/other/hledger-web.1 b/.otherdocs/hledger-web.1
index ec4ad58..8a7d7c4 100644
--- a/doc/other/hledger-web.1
+++ b/.otherdocs/hledger-web.1
@@ -1,5 +1,5 @@
-.TH "hledger\-web" "1" "September 2017" "hledger\-web 1.4" "hledger User Manuals"
+.TH "hledger\-web" "1" "December 2017" "hledger\-web 1.5" "hledger User Manuals"
@@ -20,7 +20,7 @@ other commodity, using double\-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
-hledger\-web is hledger\[aq]s web interface.
+hledger\-web is hledger's web interface.
It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible.
It provides a more user\-friendly UI than the hledger CLI or hledger\-ui
@@ -42,8 +42,8 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
For more about this see hledger(1), hledger_journal(5) etc.
.PP
-By default, hledger\-web starts the web app in "transient mode" and also
-opens it in your default web browser if possible.
+By default, hledger\-web starts the web app in \[lq]transient mode\[rq]
+and also opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
@@ -61,9 +61,8 @@ if you are running multiple hledger\-web instances.
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website.
-The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
-configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
-80).
+The default is \f[C]http://HOST:PORT/\f[] using the server's configured
+host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80).
.PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static
files, eg for better caching or cookie\-less serving on high performance
@@ -91,7 +90,7 @@ Note: if invoking hledger\-web as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
.TP
.B \f[C]\-\-serve\f[]
-serve and log requests, don\[aq]t browse or auto\-exit
+serve and log requests, don't browse or auto\-exit
.RS
.RE
.TP
@@ -192,8 +191,8 @@ multiperiod/multicolumn report by year
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
-set start date, end date, and/or reporting interval all at once
-(overrides the flags above)
+set start date, end date, and/or reporting interval all at once using
+period expressions syntax (overrides the flags above)
.RS
.RE
.TP
@@ -243,6 +242,17 @@ convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
+.TP
+.B \f[C]\-\-auto\f[]
+apply automated posting rules to modify transactions.
+.RS
+.RE
+.TP
+.B \f[C]\-\-forecast\f[]
+apply periodic transaction rules to generate future transactions, to 6
+months from now or report end date.
+.RS
+.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@@ -286,8 +296,7 @@ perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
is awkward.
.PP
-\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from
-stdin).
+\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin).
.PP
Query arguments and some hledger options are ignored.
.PP
diff --git a/doc/other/hledger-web.1.info b/.otherdocs/hledger-web.info
index 137f595..173978e 100644
--- a/doc/other/hledger-web.1.info
+++ b/.otherdocs/hledger-web.info
@@ -1,9 +1,9 @@
-This is hledger-web.1.info, produced by makeinfo version 6.0 from stdin.
+This is hledger-web.info, produced by makeinfo version 6.5 from stdin.

-File: hledger-web.1.info, Node: Top, Next: OPTIONS, Up: (dir)
+File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
-hledger-web(1) hledger-web 1.4
+hledger-web(1) hledger-web 1.5
******************************
hledger-web is hledger's web interface. It starts a simple web
@@ -68,7 +68,7 @@ hledger-web will show an error until the file has been fixed.
* OPTIONS::

-File: hledger-web.1.info, Node: OPTIONS, Prev: Top, Up: Top
+File: hledger-web.info, Node: OPTIONS, Prev: Top, Up: Top
1 OPTIONS
*********
@@ -145,7 +145,7 @@ options as shown above.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
- (overrides the flags above)
+ using period expressions syntax (overrides the flags above)
'--date2'
match the secondary date instead (see command help for other
@@ -176,6 +176,13 @@ options as shown above.
convert amounts to their market value on the report end date (using
the most recent applicable market price, if any)
+'--auto'
+
+ apply automated posting rules to modify transactions.
+'--forecast'
+
+ apply periodic transaction rules to generate future transactions,
+ to 6 months from now or report end date.
When a reporting option appears more than once in the command line,
the last one takes precedence.
@@ -200,8 +207,8 @@ this, insert a '--' argument before.)

Tag Table:
-Node: Top74
-Node: OPTIONS3156
-Ref: #options3243
+Node: Top72
+Node: OPTIONS3152
+Ref: #options3237

End Tag Table
diff --git a/doc/other/hledger-web.1.txt b/.otherdocs/hledger-web.txt
index 3f0d19a..6d04ea1 100644
--- a/doc/other/hledger-web.1.txt
+++ b/.otherdocs/hledger-web.txt
@@ -141,7 +141,7 @@ OPTIONS
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
- (overrides the flags above)
+ using period expressions syntax (overrides the flags above)
--date2
match the secondary date instead (see command help for other
@@ -173,6 +173,12 @@ OPTIONS
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
+ --auto apply automated posting rules to modify transactions.
+
+ --forecast
+ apply periodic transaction rules to generate future transac-
+ tions, to 6 months from now or report end date.
+
When a reporting option appears more than once in the command line, the
last one takes precedence.
@@ -190,22 +196,22 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
- contain one command line option/argument per line. (To prevent this,
+ contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
- Reads data from one or more files in hledger journal, timeclock, time-
- dot, or CSV format specified with -f, or $LEDGER_FILE, or
- $HOME/.hledger.journal (on windows, perhaps
+ Reads data from one or more files in hledger journal, timeclock, time-
+ dot, or CSV format specified with -f, or $LEDGER_FILE, or
+ $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
- The need to precede options with -- when invoked from hledger is awk-
+ The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-web can't read from stdin).
@@ -219,7 +225,7 @@ 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)
@@ -233,7 +239,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -241,4 +247,4 @@ SEE ALSO
-hledger-web 1.4 September 2017 hledger-web(1)
+hledger-web 1.5 December 2017 hledger-web(1)
diff --git a/doc/other/hledger_csv.5 b/.otherdocs/hledger_csv.5
index 7df3714..7b01eba 100644
--- a/doc/other/hledger_csv.5
+++ b/.otherdocs/hledger_csv.5
@@ -1,5 +1,5 @@
-.TH "hledger_csv" "5" "September 2017" "hledger 1.4" "hledger User Manuals"
+.TH "hledger_csv" "5" "December 2017" "hledger 1.5" "hledger User Manuals"
@@ -8,19 +8,77 @@
CSV \- how hledger reads CSV data, and the CSV rules file format
.SH DESCRIPTION
.PP
-hledger can read CSV files, converting each CSV record into a journal
-entry (transaction), if you provide some conversion hints in a "rules
-file".
-This file should be named like the CSV file with an additional
-\f[C]\&.rules\f[] suffix (eg: \f[C]mybank.csv.rules\f[]); or, you can
-specify the file with \f[C]\-\-rules\-file\ PATH\f[].
-hledger will create it if necessary, with some default rules which
-you\[aq]ll need to adjust.
-At minimum, the rules file must specify the \f[C]date\f[] and
+hledger can read CSV (comma\-separated value) files as if they were
+journal files, automatically converting each CSV record into a
+transaction.
+(To learn about \f[I]writing\f[] CSV, see CSV output.)
+.PP
+Converting CSV to transactions requires some special conversion rules.
+These do several things:
+.IP \[bu] 2
+they describe the layout and format of the CSV data
+.IP \[bu] 2
+they can customize the generated journal entries using a simple
+templating language
+.IP \[bu] 2
+they can add refinements based on patterns in the CSV data, eg
+categorizing transactions with more detailed account names.
+.PP
+When reading a CSV file named \f[C]FILE.csv\f[], hledger looks for a
+conversion rules file named \f[C]FILE.csv.rules\f[] in the same
+directory.
+You can override this with the \f[C]\-\-rules\-file\f[] option.
+If the rules file does not exist, hledger will auto\-create one with
+some example rules, which you'll need to adjust.
+.PP
+At minimum, the rules file must identify the \f[C]date\f[] and
\f[C]amount\f[] fields.
-For an example, see Cookbook: convert CSV files.
+It may also be necessary to specify the date format, and the number of
+header lines to skip.
+Eg:
+.IP
+.nf
+\f[C]
+fields\ date,\ _,\ _,\ amount
+date\-format\ \ %d/%m/%Y
+skip\ 1
+\f[]
+.fi
+.PP
+A more complete example:
+.IP
+.nf
+\f[C]
+#\ hledger\ CSV\ rules\ for\ amazon.com\ order\ history
+
+#\ sample:
+#\ "Date","Type","To/From","Name","Status","Amount","Fees","Transaction\ ID"
+#\ "Jul\ 29,\ 2012","Payment","To","Adapteva,\ Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"
+
+#\ skip\ one\ header\ line
+skip\ 1
+
+#\ name\ the\ csv\ fields\ (and\ assign\ the\ transaction\[aq]s\ date,\ amount\ and\ code)
+fields\ date,\ _,\ toorfrom,\ name,\ amzstatus,\ amount,\ fees,\ code
+
+#\ how\ to\ parse\ the\ date
+date\-format\ %b\ %\-d,\ %Y
+
+#\ combine\ two\ fields\ to\ make\ the\ description
+description\ %toorfrom\ %name
+
+#\ save\ these\ fields\ as\ tags
+comment\ \ \ \ \ status:%amzstatus,\ fees:%fees
+
+#\ set\ the\ base\ account\ for\ all\ transactions
+account1\ \ \ \ assets:amazon
+
+#\ flip\ the\ sign\ on\ the\ amount
+amount\ \ \ \ \ \ \-%amount
+\f[]
+.fi
.PP
-To learn about \f[I]exporting\f[] CSV, see CSV output.
+For more examples, see Convert CSV files.
.SH CSV RULES
.PP
The following seven kinds of rule can appear in the rules file, in any
@@ -29,10 +87,10 @@ Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
ignored.
.SS skip
.PP
-\f[C]skip\f[]\f[I]\f[C]N\f[]\f[]
+\f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[]
.PP
Skip this number of CSV records at the beginning.
-You\[aq]ll need this whenever your CSV data contains header lines.
+You'll need this whenever your CSV data contains header lines.
Eg:
.IP
.nf
@@ -43,11 +101,11 @@ skip\ 1
.fi
.SS date\-format
.PP
-\f[C]date\-format\f[]\f[I]\f[C]DATEFMT\f[]\f[]
+\f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[]
.PP
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
-\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
-specify the format.
+\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you'll need to specify
+the format.
DATEFMT is a strptime\-like date parsing pattern, which must parse the
date field values completely.
Examples:
@@ -81,8 +139,8 @@ date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
.fi
.SS field list
.PP
-\f[C]fields\f[]\f[I]\f[C]FIELDNAME1\f[]\f[],
-\f[I]\f[C]FIELDNAME2\f[]\f[]...
+\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[],
+\f[I]\f[CI]FIELDNAME2\f[I]\f[]\&...
.PP
This (a) names the CSV fields, in order (names may not contain
whitespace; uninteresting names may be left blank), and (b) assigns them
@@ -106,7 +164,7 @@ fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield
.fi
.SS field assignment
.PP
-\f[I]\f[C]ENTRYFIELDNAME\f[]\f[] \f[I]\f[C]FIELDVALUE\f[]\f[]
+\f[I]\f[CI]ENTRYFIELDNAME\f[I]\f[] \f[I]\f[CI]FIELDVALUE\f[I]\f[]
.PP
This sets a journal entry field (one of the standard names above) to the
given text value, which can include CSV field values interpolated by
@@ -130,30 +188,30 @@ comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
Field assignments can be used instead of or in addition to a field list.
.SS conditional block
.PP
-\f[C]if\f[] \f[I]\f[C]PATTERN\f[]\f[]
+\f[C]if\f[] \f[I]\f[CI]PATTERN\f[I]\f[]
.PD 0
.P
.PD
-\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
+\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&...
.PP
\f[C]if\f[]
.PD 0
.P
.PD
-\f[I]\f[C]PATTERN\f[]\f[]
+\f[I]\f[CI]PATTERN\f[I]\f[]
.PD 0
.P
.PD
-\f[I]\f[C]PATTERN\f[]\f[]...
+\f[I]\f[CI]PATTERN\f[I]\f[]\&...
.PD 0
.P
.PD
-\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
+\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&...
.PP
This applies one or more field assignments, only to those CSV records
matched by one of the PATTERNs.
The patterns are case\-insensitive regular expressions which match
-anywhere within the whole CSV record (it\[aq]s not yet possible to match
+anywhere within the whole CSV record (it's not yet possible to match
within a specific field).
When there are multiple patterns they can be written on separate lines,
unindented.
@@ -182,11 +240,11 @@ banking\ thru\ software
.fi
.SS include
.PP
-\f[C]include\f[]\f[I]\f[C]RULESFILE\f[]\f[]
+\f[C]include\f[]\f[I]\f[CI]RULESFILE\f[I]\f[]
.PP
Include another rules file at this point.
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
-the current file\[aq]s directory.
+the current file's directory.
Eg:
.IP
.nf
@@ -203,9 +261,9 @@ Consider adding this rule if all of the following are true: you might be
processing just one day of data, your CSV records are in reverse
chronological order (newest first), and you care about preserving the
order of same\-day transactions.
-It usually isn\[aq]t needed, because hledger autodetects the CSV order,
-but when all CSV records have the same date it will assume they are
-oldest first.
+It usually isn't needed, because hledger autodetects the CSV order, but
+when all CSV records have the same date it will assume they are oldest
+first.
.SH CSV TIPS
.SS CSV ordering
.PP
@@ -216,9 +274,8 @@ case where you might need \f[C]newest\-first\f[], see above).
.PP
Each journal entry will have two postings, to \f[C]account1\f[] and
\f[C]account2\f[] respectively.
-It\[aq]s not yet possible to generate entries with more than two
-postings.
-It\[aq]s conventional and recommended to use \f[C]account1\f[] for the
+It's not yet possible to generate entries with more than two postings.
+It's conventional and recommended to use \f[C]account1\f[] for the
account whose CSV we are reading.
.SS CSV amounts
.PP
diff --git a/doc/other/hledger_csv.5.info b/.otherdocs/hledger_csv.info
index 15cb6ce..b420094 100644
--- a/doc/other/hledger_csv.5.info
+++ b/.otherdocs/hledger_csv.info
@@ -1,28 +1,75 @@
-This is hledger_csv.5.info, produced by makeinfo version 6.0 from stdin.
+This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.

-File: hledger_csv.5.info, Node: Top, Next: CSV RULES, Up: (dir)
+File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)
-hledger_csv(5) hledger 1.4
+hledger_csv(5) hledger 1.5
**************************
-hledger can read CSV files, converting each CSV record into a journal
-entry (transaction), if you provide some conversion hints in a "rules
-file". This file should be named like the CSV file with an additional
-'.rules' suffix (eg: 'mybank.csv.rules'); 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. At minimum, the rules
-file must specify the 'date' and 'amount' fields. For an example, see
-Cookbook: convert CSV files.
+hledger can read CSV (comma-separated value) files as if they were
+journal files, automatically converting each CSV record into a
+transaction. (To learn about _writing_ CSV, see CSV output.)
- To learn about _exporting_ CSV, see CSV output.
+ Converting CSV to transactions requires some special conversion
+rules. These do several things:
+
+ * they describe the layout and format of the CSV data
+ * they can customize the generated journal entries using a simple
+ templating language
+ * they can add refinements based on patterns in the CSV data, eg
+ categorizing transactions with more detailed account names.
+
+ When reading a CSV file named 'FILE.csv', hledger looks for a
+conversion rules file named 'FILE.csv.rules' in the same directory. You
+can override this with the '--rules-file' option. If the rules file
+does not exist, hledger will auto-create one with some example rules,
+which you'll need to adjust.
+
+ At minimum, the rules file must identify the 'date' and 'amount'
+fields. It may also be necessary to specify the date format, and the
+number of header lines to skip. Eg:
+
+fields date, _, _, amount
+date-format %d/%m/%Y
+skip 1
+
+ A more complete example:
+
+# hledger CSV rules for amazon.com order history
+
+# sample:
+# "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
+# "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"
+
+# skip one header line
+skip 1
+
+# name the csv fields (and assign the transaction's date, amount and code)
+fields date, _, toorfrom, name, amzstatus, amount, fees, code
+
+# how to parse the date
+date-format %b %-d, %Y
+
+# combine two fields to make the description
+description %toorfrom %name
+
+# save these fields as tags
+comment status:%amzstatus, fees:%fees
+
+# set the base account for all transactions
+account1 assets:amazon
+
+# flip the sign on the amount
+amount -%amount
+
+ For more examples, see Convert CSV files.
* Menu:
* CSV RULES::
* CSV TIPS::

-File: hledger_csv.5.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top
+File: hledger_csv.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top
1 CSV RULES
***********
@@ -40,7 +87,7 @@ order. Blank lines and lines beginning with '#' or ';' are ignored.
* newest-first::

-File: hledger_csv.5.info, Node: skip, Next: date-format, Up: CSV RULES
+File: hledger_csv.info, Node: skip, Next: date-format, Up: CSV RULES
1.1 skip
========
@@ -54,7 +101,7 @@ whenever your CSV data contains header lines. Eg:
skip 1

-File: hledger_csv.5.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES
+File: hledger_csv.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES
1.2 date-format
===============
@@ -79,7 +126,7 @@ date-format %Y-%h-%d
date-format %-m/%-d/%Y %l:%M %p

-File: hledger_csv.5.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES
+File: hledger_csv.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES
1.3 field list
==============
@@ -102,7 +149,7 @@ Eg:
fields date, description, , amount, , , somefield, anotherfield

-File: hledger_csv.5.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES
+File: hledger_csv.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES
1.4 field assignment
====================
@@ -123,7 +170,7 @@ comment note: %somefield - %anotherfield, date: %1
list.

-File: hledger_csv.5.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES
+File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES
1.5 conditional block
=====================
@@ -157,7 +204,7 @@ banking thru software
comment XXX deductible ? check it

-File: hledger_csv.5.info, Node: include, Next: newest-first, Prev: conditional block, Up: CSV RULES
+File: hledger_csv.info, Node: include, Next: newest-first, Prev: conditional block, Up: CSV RULES
1.6 include
===========
@@ -172,7 +219,7 @@ Eg:
include common.rules

-File: hledger_csv.5.info, Node: newest-first, Prev: include, Up: CSV RULES
+File: hledger_csv.info, Node: newest-first, Prev: include, Up: CSV RULES
1.7 newest-first
================
@@ -187,7 +234,7 @@ hledger autodetects the CSV order, but when all CSV records have the
same date it will assume they are oldest first.

-File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
+File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
2 CSV TIPS
**********
@@ -201,7 +248,7 @@ File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
* Reading multiple CSV files::

-File: hledger_csv.5.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS
+File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS
2.1 CSV ordering
================
@@ -211,7 +258,7 @@ same-day entries will be preserved (except in the special case where you
might need 'newest-first', see above).

-File: hledger_csv.5.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS
+File: hledger_csv.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS
2.2 CSV accounts
================
@@ -222,7 +269,7 @@ two postings. It's conventional and recommended to use 'account1' for
the account whose CSV we are reading.

-File: hledger_csv.5.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS
+File: hledger_csv.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS
2.3 CSV amounts
===============
@@ -247,7 +294,7 @@ fields (giving more control, eg to put the currency symbol on the
right).

-File: hledger_csv.5.info, Node: CSV balance assertions, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS
+File: hledger_csv.info, Node: CSV balance assertions, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS
2.4 CSV balance assertions
==========================
@@ -257,7 +304,7 @@ If the CSV includes a running balance, you can assign that to the
it will be asserted as the balance after the 'account1' posting.

-File: hledger_csv.5.info, Node: Reading multiple CSV files, Prev: CSV balance assertions, Up: CSV TIPS
+File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions, Up: CSV TIPS
2.5 Reading multiple CSV files
==============================
@@ -269,34 +316,34 @@ one rules file will be used for all the CSV files being read.

Tag Table:
-Node: Top74
-Node: CSV RULES810
-Ref: #csv-rules920
-Node: skip1182
-Ref: #skip1278
-Node: date-format1450
-Ref: #date-format1579
-Node: field list2085
-Ref: #field-list2224
-Node: field assignment2929
-Ref: #field-assignment3086
-Node: conditional block3590
-Ref: #conditional-block3746
-Node: include4642
-Ref: #include4774
-Node: newest-first5005
-Ref: #newest-first5121
-Node: CSV TIPS5532
-Ref: #csv-tips5628
-Node: CSV ordering5746
-Ref: #csv-ordering5866
-Node: CSV accounts6047
-Ref: #csv-accounts6187
-Node: CSV amounts6441
-Ref: #csv-amounts6589
-Node: CSV balance assertions7364
-Ref: #csv-balance-assertions7548
-Node: Reading multiple CSV files7753
-Ref: #reading-multiple-csv-files7925
+Node: Top72
+Node: CSV RULES2161
+Ref: #csv-rules2269
+Node: skip2531
+Ref: #skip2625
+Node: date-format2797
+Ref: #date-format2924
+Node: field list3430
+Ref: #field-list3567
+Node: field assignment4272
+Ref: #field-assignment4427
+Node: conditional block4931
+Ref: #conditional-block5085
+Node: include5981
+Ref: #include6111
+Node: newest-first6342
+Ref: #newest-first6456
+Node: CSV TIPS6867
+Ref: #csv-tips6961
+Node: CSV ordering7079
+Ref: #csv-ordering7197
+Node: CSV accounts7378
+Ref: #csv-accounts7516
+Node: CSV amounts7770
+Ref: #csv-amounts7916
+Node: CSV balance assertions8691
+Ref: #csv-balance-assertions8873
+Node: Reading multiple CSV files9078
+Ref: #reading-multiple-csv-files9248

End Tag Table
diff --git a/doc/other/hledger_csv.5.txt b/.otherdocs/hledger_csv.txt
index 166c008..fa19627 100644
--- a/doc/other/hledger_csv.5.txt
+++ b/.otherdocs/hledger_csv.txt
@@ -7,16 +7,65 @@ NAME
CSV - how hledger reads CSV data, and the CSV rules file format
DESCRIPTION
- hledger can read CSV files, converting each CSV record into a journal
- entry (transaction), if you provide some conversion hints in a "rules
- file". This file should be named like the CSV file with an additional
- .rules suffix (eg: mybank.csv.rules); 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. At minimum, the rules file
- must specify the date and amount fields. For an example, see Cookbook:
- convert CSV files.
+ hledger can read CSV (comma-separated value) files as if they were
+ journal files, automatically converting each CSV record into a transac-
+ tion. (To learn about writing CSV, see CSV output.)
- To learn about exporting CSV, see CSV output.
+ Converting CSV to transactions requires some special conversion rules.
+ These do several things:
+
+ o they describe the layout and format of the CSV data
+
+ o they can customize the generated journal entries using a simple tem-
+ plating language
+
+ o they can add refinements based on patterns in the CSV data, eg cate-
+ gorizing transactions with more detailed account names.
+
+ When reading a CSV file named FILE.csv, hledger looks for a conversion
+ rules file named FILE.csv.rules in the same directory. You can over-
+ ride this with the --rules-file option. If the rules file does not
+ exist, hledger will auto-create one with some example rules, which
+ you'll need to adjust.
+
+ At minimum, the rules file must identify the date and amount fields.
+ It may also be necessary to specify the date format, and the number of
+ header lines to skip. Eg:
+
+ fields date, _, _, amount
+ date-format %d/%m/%Y
+ skip 1
+
+ A more complete example:
+
+ # hledger CSV rules for amazon.com order history
+
+ # sample:
+ # "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
+ # "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"
+
+ # skip one header line
+ skip 1
+
+ # name the csv fields (and assign the transaction's date, amount and code)
+ fields date, _, toorfrom, name, amzstatus, amount, fees, code
+
+ # how to parse the date
+ date-format %b %-d, %Y
+
+ # combine two fields to make the description
+ description %toorfrom %name
+
+ # save these fields as tags
+ comment status:%amzstatus, fees:%fees
+
+ # set the base account for all transactions
+ account1 assets:amazon
+
+ # flip the sign on the amount
+ amount -%amount
+
+ For more examples, see Convert CSV files.
CSV RULES
The following seven kinds of rule can appear in the rules file, in any
@@ -200,4 +249,4 @@ SEE ALSO
-hledger 1.4 September 2017 hledger_csv(5)
+hledger 1.5 December 2017 hledger_csv(5)
diff --git a/doc/other/hledger_journal.5 b/.otherdocs/hledger_journal.5
index 6b868f7..ae43d51 100644
--- a/doc/other/hledger_journal.5
+++ b/.otherdocs/hledger_journal.5
@@ -1,36 +1,34 @@
.\"t
-.TH "hledger_journal" "5" "September 2017" "hledger 1.4" "hledger User Manuals"
+.TH "hledger_journal" "5" "December 2017" "hledger 1.5" "hledger User Manuals"
.SH NAME
.PP
-Journal \- hledger\[aq]s default file format, representing a General
-Journal
+Journal \- hledger's default file format, representing a General Journal
.SH DESCRIPTION
.PP
-hledger\[aq]s usual data source is a plain text file containing journal
+hledger's usual data source is a plain text file containing journal
entries in hledger journal format.
This file represents a standard accounting general journal.
-I use file names ending in \f[C]\&.journal\f[], but that\[aq]s not
-required.
+I use file names ending in \f[C]\&.journal\f[], but that's not required.
The journal file contains a number of transaction entries, each
describing a transfer of money (or any commodity) between two or more
named accounts, in a simple format readable by both hledger and humans.
.PP
-hledger\[aq]s journal format is a compatible subset, mostly, of
-ledger\[aq]s journal format, so hledger can work with compatible ledger
-journal files as well.
-It\[aq]s safe, and encouraged, to run both hledger and ledger on the
-same journal file, eg to validate the results you\[aq]re getting.
+hledger's journal format is a compatible subset, mostly, of ledger's
+journal format, so hledger can work with compatible ledger journal files
+as well.
+It's safe, and encouraged, to run both hledger and ledger on the same
+journal file, eg to validate the results you're getting.
.PP
You can use hledger without learning any more about this file; just use
the add or web commands to create and update it.
Many users, though, also edit the journal file directly with a text
editor, perhaps assisted by the helper modes for emacs or vim.
.PP
-Here\[aq]s an example:
+Here's an example:
.IP
.nf
\f[C]
@@ -83,7 +81,7 @@ line or a semicolon)
semicolon until end of line)
.PP
Then comes zero or more (but usually at least 2) indented lines
-representing...
+representing\&...
.SS Postings
.PP
A posting is an addition of some amount to, or removal of some amount
@@ -136,12 +134,12 @@ The primary date, on the left, is used by default; the secondary date,
on the right, is used when the \f[C]\-\-date2\f[] flag is specified
(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work).
.PP
-The meaning of secondary dates is up to you, but it\[aq]s best to follow
-a consistent rule.
-Eg write the bank\[aq]s clearing date as primary, and when needed, the
-date the transaction was initiated as secondary.
+The meaning of secondary dates is up to you, but it's best to follow a
+consistent rule.
+Eg write the bank's clearing date as primary, and when needed, the date
+the transaction was initiated as secondary.
.PP
-Here\[aq]s an example.
+Here's an example.
Note that a secondary date will use the year of the primary date if
unspecified.
.IP
@@ -205,14 +203,14 @@ $\ hledger\ \-f\ t.j\ register\ checking
.fi
.PP
DATE should be a simple date; if the year is not specified it will use
-the year of the transaction\[aq]s date.
+the year of the transaction's date.
You can set the secondary date similarly, with \f[C]date2:DATE2\f[].
The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date
value if they are present, eg a \f[C]date:\f[] tag with no value is not
allowed.
.PP
-Ledger\[aq]s earlier, more compact bracketed date syntax is also
-supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
+Ledger's earlier, more compact bracketed date syntax is also supported:
+\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[].
hledger will attempt to parse any square\-bracketed sequence of the
\f[C]0123456789/\-.=\f[] characters in this way.
With this syntax, DATE infers its year from the transaction and DATE2
@@ -256,11 +254,11 @@ When reporting, you can filter by status with the
\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in
hledger\-ui.
.PP
-Note, in Ledger and in older versions of hledger, the "unmarked" state
-is called "uncleared".
+Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq]
+state is called \[lq]uncleared\[rq].
As of hledger 1.3 we have renamed it to unmarked for clarity.
.PP
-To replicate Ledger and old hledger\[aq]s behaviour of also matching
+To replicate Ledger and old hledger's behaviour of also matching
pending, combine \-U and \-P.
.PP
Status marks are optional, but can be helpful eg for reconciling with
@@ -270,12 +268,13 @@ status.
Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c
C\-e, or posting status with C\-c C\-c.
.PP
-What "uncleared", "pending", and "cleared" actually mean is up to you.
-Here\[aq]s one suggestion:
+What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq]
+actually mean is up to you.
+Here's one suggestion:
.PP
.TS
tab(@);
-lw(10.5n) lw(59.5n).
+lw(9.9n) lw(60.1n).
T{
status
T}@T{
@@ -305,10 +304,10 @@ bank soon (like uncashed checks), and no flags to see the most
up\-to\-date state of your finances.
.SS Description
.PP
-A transaction\[aq]s description is the rest of the line following the
-date and status mark (or until a comment begins).
-Sometimes called the "narration" in traditional bookkeeping, it can be
-used for whatever you wish, or left blank.
+A transaction's description is the rest of the line following the date
+and status mark (or until a comment begins).
+Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it
+can be used for whatever you wish, or left blank.
Transaction descriptions can be queried, unlike comments.
.SS Payee and note
.PP
@@ -366,11 +365,15 @@ Some examples:
.P
.PD
\f[C]EUR\ \-2.000.000,00\f[]
+.PD 0
+.P
+.PD
+\f[C]1\ 999\ 999.9455\f[]
.PP
As you can see, the amount format is somewhat flexible:
.IP \[bu] 2
-amounts are a number (the "quantity") and optionally a currency
-symbol/commodity name (the "commodity").
+amounts are a number (the \[lq]quantity\[rq]) and optionally a currency
+symbol/commodity name (the \[lq]commodity\[rq]).
.IP \[bu] 2
the commodity is a symbol, word, or phrase, on the left or right, with
or without a separating space.
@@ -381,10 +384,32 @@ negative amounts with a commodity on the left can have the minus sign
before or after it
.IP \[bu] 2
digit groups (thousands, or any other grouping) can be separated by
-commas (in which case period is used for decimal point) or periods (in
-which case comma is used for decimal point)
+space or comma or period and should be used as separator between all
+groups
+.IP \[bu] 2
+decimal part can be separated by comma or period and should be different
+from digit groups separator
+.PP
+You can use any of these variations when recording data.
+However, there is some ambiguous way of representing numbers like
+\f[C]$1.000\f[] and \f[C]$1,000\f[] both may mean either one thousand or
+one dollar.
+By default hledger will assume that this is sole delimiter is used only
+for decimals.
+On the other hand commodity format declared prior to that line will help
+to resolve that ambiguity differently:
+.IP
+.nf
+\f[C]
+commodity\ $1,000.00
+
+2017/12/25\ New\ life\ of\ Scrooge
+\ \ \ \ expenses:gifts\ \ $1,000
+\ \ \ \ assets
+\f[]
+.fi
.PP
-You can use any of these variations when recording data, but when
+Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity.
(Except for price amounts, which are always formatted as written).
@@ -399,13 +424,12 @@ will be the maximum from all posting amounts in that commmodity
or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[]).
.PP
-Price amounts and amounts in D directives usually don\[aq]t affect
-amount format inference, but in some situations they can do so
-indirectly.
-(Eg when D\[aq]s default commodity is applied to a commodity\-less
-amount, or when an amountless posting is balanced using a price\[aq]s
-commodity, or when \-V is used.) If you find this causing problems, set
-the desired format with a commodity directive.
+Price amounts and amounts in D directives usually don't affect amount
+format inference, but in some situations they can do so indirectly.
+(Eg when D's default commodity is applied to a commodity\-less amount,
+or when an amountless posting is balanced using a price's commodity, or
+when \-V is used.) If you find this causing problems, set the desired
+format with a commodity directive.
.SS Virtual Postings
.PP
When you parenthesise the account name in a posting, we call that a
@@ -416,7 +440,7 @@ it is ignored when checking that the transaction is balanced
it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used,
or the \f[C]real:1\f[] query.
.PP
-You could use this, eg, to set an account\[aq]s opening balance without
+You could use this, eg, to set an account's opening balance without
needing to use the \f[C]equity:opening\ balances\f[] account:
.IP
.nf
@@ -450,8 +474,7 @@ which is more correct and provides better error checking.
.SS Balance Assertions
.PP
hledger supports Ledger\-style balance assertions in journal files.
-These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
-amount.
+These look like \f[C]=EXPECTEDBALANCE\f[] following a posting's amount.
Eg in this example we assert the expected dollar balance in accounts a
and b after each posting:
.IP
@@ -476,7 +499,7 @@ You can disable them temporarily with the
troubleshooting or for reading Ledger files.
.SS Assertions and ordering
.PP
-hledger sorts an account\[aq]s postings and assertions first by date and
+hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order.
Note this is different from Ledger, which sorts assertions only by parse
order.
@@ -495,33 +518,33 @@ intra\-day balances.
With included files, things are a little more complicated.
Including preserves the ordering of postings and assertions.
If you have multiple postings to an account on the same day, split
-across different files, and you also want to assert the account\[aq]s
-balance on the same day, you\[aq]ll have to put the assertion in the
-right file.
+across different files, and you also want to assert the account's
+balance on the same day, you'll have to put the assertion in the right
+file.
.SS Assertions and multiple \-f options
.PP
-Balance assertions don\[aq]t work well across files specified with
-multiple \-f options.
+Balance assertions don't work well across files specified with multiple
+\-f options.
Use include or concatenate the files instead.
.SS Assertions and commodities
.PP
The asserted balance must be a simple single\-commodity amount, and in
-fact the assertion checks only this commodity\[aq]s balance within the
+fact the assertion checks only this commodity's balance within the
(possibly multi\-commodity) account balance.
We could call this a partial balance assertion.
This is compatible with Ledger, and makes it possible to make assertions
about accounts containing multiple commodities.
.PP
-To assert each commodity\[aq]s balance in such a multi\-commodity
-account, you can add multiple postings (with amount 0 if necessary).
-But note that no matter how many assertions you add, you can\[aq]t be
-sure the account does not contain some unexpected commodity.
-(We\[aq]ll add support for this kind of total balance assertion if
-there\[aq]s demand.)
+To assert each commodity's balance in such a multi\-commodity account,
+you can add multiple postings (with amount 0 if necessary).
+But note that no matter how many assertions you add, you can't be sure
+the account does not contain some unexpected commodity.
+(We'll add support for this kind of total balance assertion if there's
+demand.)
.SS Assertions and subaccounts
.PP
Balance assertions do not count the balance from subaccounts; they check
-the posted account\[aq]s exclusive balance.
+the posted account's exclusive balance.
For example:
.IP
.nf
@@ -533,7 +556,7 @@ For example:
\f[]
.fi
.PP
-The balance report\[aq]s flat mode shows these exclusive balances more
+The balance report's flat mode shows these exclusive balances more
clearly:
.IP
.nf
@@ -582,9 +605,9 @@ or when adjusting a balance to reality:
\f[]
.fi
.PP
-The calculated amount depends on the account\[aq]s balance in the
-commodity at that point (which depends on the previously\-dated postings
-of the commodity to that account since the last balance assertion or
+The calculated amount depends on the account's balance in the commodity
+at that point (which depends on the previously\-dated postings of the
+commodity to that account since the last balance assertion or
assignment).
Note that using balance assignments makes your journal a little less
explicit; to know the exact amount posted, you have to run hledger or do
@@ -592,7 +615,7 @@ the calculations yourself, instead of just reading it.
.SS Prices
.SS Transaction prices
.PP
-Within a transaction, you can note an amount\[aq]s price in another
+Within a transaction, you can note an amount's price in another
commodity.
This can be used to document the cost (in a purchase) or selling price
(in a sale).
@@ -643,8 +666,8 @@ hledger infer the price that balances the transaction:
.RE
.PP
Amounts with transaction prices can be displayed in the transaction
-price\[aq]s commodity by using the \f[C]\-B/\-\-cost\f[] flag (except
-for #551) ("B" is from "cost Basis").
+price's commodity by using the \f[C]\-B/\-\-cost\f[] flag (except for
+#551) (\[lq]B\[rq] is from \[lq]cost Basis\[rq]).
Eg for the above, here is how \-B affects the balance report:
.IP
.nf
@@ -661,7 +684,7 @@ $\ hledger\ bal\ \-N\ \-\-flat\ \-B
Note \-B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last
amount.
-So if example 3\[aq]s postings are reversed, while the transaction is
+So if example 3's postings are reversed, while the transaction is
equivalent, \-B shows something different:
.IP
.nf
@@ -716,9 +739,9 @@ P\ 2010/1/1\ €\ $1.40
.SS Comments
.PP
Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
-(\f[C]#\f[]) or asterisk (\f[C]*\f[]) are comments, and will be ignored.
-(Asterisk comments make it easy to treat your journal like an org\-mode
-outline in emacs.)
+(\f[C]#\f[]) or star (\f[C]*\f[]) are comments, and will be ignored.
+(Star comments cause org\-mode nodes to be ignored, allowing emacs users
+to fold and navigate their journals with org\-mode or orgstruct\-mode.)
.PP
Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[]
directives is a (multi\-line) comment.
@@ -730,20 +753,22 @@ description and/or indented on the following lines (before the
postings).
Similarly, you can attach comments to an individual posting by writing
them after the amount and/or indented on the following lines.
+Transaction and posting comments must begin with a semicolon
+(\f[C];\f[]).
.PP
Some examples:
.IP
.nf
\f[C]
-#\ a\ journal\ comment
+#\ a\ file\ comment
-;\ also\ a\ journal\ comment
+;\ also\ a\ file\ comment
comment
-This\ is\ a\ multiline\ comment,
+This\ is\ a\ multiline\ file\ comment,
which\ continues\ until\ a\ line
where\ the\ "end\ comment"\ string
-appears\ on\ its\ own.
+appears\ on\ its\ own\ (or\ end\ of\ file).
end\ comment
2012/5/14\ something\ \ ;\ a\ transaction\ comment
@@ -752,7 +777,7 @@ end\ comment
\ \ \ \ posting2
\ \ \ \ ;\ a\ comment\ for\ posting\ 2
\ \ \ \ ;\ another\ comment\ line\ for\ posting\ 2
-;\ a\ journal\ comment\ (because\ not\ indented)
+;\ a\ file\ comment\ (because\ not\ indented)
\f[]
.fi
.SS Tags
@@ -778,8 +803,7 @@ comma or end of line, with leading/trailing whitespace removed:
\f[]
.fi
.PP
-Note this means hledger\[aq]s tag values can not contain commas or
-newlines.
+Note this means hledger's tag values can not contain commas or newlines.
Ending at commas means you can write multiple short tags on one line,
comma separated:
.IP
@@ -791,12 +815,13 @@ comma separated:
.PP
Here,
.IP \[bu] 2
-"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag
+\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a
+tag
.IP \[bu] 2
-"\f[C]tag1\f[]" is a tag with no value
+\[lq]\f[C]tag1\f[]\[rq] is a tag with no value
.IP \[bu] 2
-"\f[C]tag2\f[]" is another tag, whose value is
-"\f[C]some\ value\ ...\f[]"
+\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is
+\[lq]\f[C]some\ value\ ...\f[]\[rq]
.PP
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
@@ -812,14 +837,14 @@ For example, the following transaction has three tags (\f[C]A\f[],
\f[]
.fi
.PP
-Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
-values are simple strings.
+Tags are like Ledger's metadata feature, except hledger's tag values are
+simple strings.
.SS Directives
.SS Account aliases
.PP
You can define aliases which rewrite your account names (after reading
the journal, before generating reports).
-hledger\[aq]s account aliases can be useful for:
+hledger's account aliases can be useful for:
.IP \[bu] 2
expanding shorthand account names to their full form, allowing easier
data entry and a less verbose journal
@@ -849,7 +874,7 @@ alias\ OLD\ =\ NEW
Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the
command line.
This affects all entries.
-It\[aq]s useful for trying out aliases interactively.
+It's useful for trying out aliases interactively.
.PP
OLD and NEW are full account names.
hledger will replace any occurrence of the old account name with the new
@@ -920,8 +945,8 @@ end\ aliases
.PP
The \f[C]account\f[] directive predefines account names, as in Ledger
and Beancount.
-This may be useful for your own documentation; hledger doesn\[aq]t make
-use of it yet.
+This may be useful for your own documentation; hledger doesn't make use
+of it yet.
.IP
.nf
\f[C]
@@ -1007,7 +1032,7 @@ commodity\ 1,000.0000\ AAAA
\f[]
.fi
.PP
-or on multiple lines, using the "format" subdirective.
+or on multiple lines, using the \[lq]format\[rq] subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
@@ -1027,7 +1052,7 @@ commodity\ INR
.PP
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers).
-(Note this differs from Ledger\[aq]s default commodity directive.) The
+(Note this differs from Ledger's default commodity directive.) The
commodity and display format will be applied to all subsequent
commodity\-less amounts, or until the next D directive.
.IP
@@ -1038,14 +1063,14 @@ commodity\-less amounts, or until the next D directive.
D\ $1,000.00
1/1
-\ \ a\ \ \ \ \ 5\ \ \ \ #\ <\-\ commodity\-less\ amount,\ becomes\ $1
+\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1
\ \ b
\f[]
.fi
.SS Default year
.PP
-You can set a default year to be used for subsequent dates which
-don\[aq]t specify a year.
+You can set a default year to be used for subsequent dates which don't
+specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year.
Eg:
.IP
@@ -1085,6 +1110,77 @@ Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
+.SH Periodic transactions
+.PP
+A periodic transaction starts with a tilde `~' in place of a date
+followed by a period expression:
+.IP
+.nf
+\f[C]
+~\ weekly
+\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck
+\ \ income:acme\ inc
+\f[]
+.fi
+.PP
+Periodic transactions are used for forecasting and budgeting only, they
+have no effect unless the \f[C]\-\-forecast\f[] or \f[C]\-\-budget\f[]
+flag is used.
+With \f[C]\-\-forecast\f[], each periodic transaction rule generates
+recurring forecast transactions at the specified interval, beginning the
+day after the last recorded journal transaction and ending 6 months from
+today, or at the specified report end date.
+With \f[C]balance\ \-\-budget\f[], each periodic transaction declares
+recurring budget goals for one or more accounts.
+.PD 0
+.P
+.PD
+For more details, see: balance > Budgeting, Budgeting and Forecasting.
+.SH Automated posting rules
+.PP
+Automated posting rule starts with an equal sign `=' in place of a date,
+followed by a query:
+.IP
+.nf
+\f[C]
+=\ expenses:gifts
+\ \ \ \ budget:gifts\ \ *\-1
+\ \ \ \ assets:budget\ \ *1
+\f[]
+.fi
+.PP
+When \f[C]\-\-auto\f[] option is specified on the command line,
+automated posting rule will add its postings to all transactions that
+match the query.
+.PP
+If amount in the automated posting rule includes commodity name, new
+posting will be made in the given commodity, otherwise commodity of the
+matched transaction will be used.
+.PP
+When amount in the automated posting rule begins with the '*', amount
+will be treated as a multiplier that is applied to the amount of the
+first posting in the matched transaction.
+.PP
+In example above, every transaction in \f[C]expenses:gifts\f[] account
+will have two additional postings added to it: amount of the original
+gift will be debited from \f[C]budget:gifts\f[] and credited into
+\f[C]assets:budget\f[]:
+.IP
+.nf
+\f[C]
+;\ Original\ transaction
+2017\-12\-14
+\ \ expenses:gifts\ \ $20
+\ \ assets
+
+;\ With\ automated\ postings\ applied
+2017/12/14
+\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
+\ \ \ \ assets
+\ \ \ \ budget:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20
+\ \ \ \ assets:budget\ \ \ \ \ \ \ \ \ \ \ \ \ \ $20
+\f[]
+.fi
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with
@@ -1098,7 +1194,7 @@ files:
.PP
.TS
tab(@);
-lw(16.5n) lw(51.5n).
+lw(16.5n) lw(53.5n).
T{
Emacs
T}@T{
diff --git a/doc/other/hledger_journal.5.info b/.otherdocs/hledger_journal.info
index f71cc46..29fa944 100644
--- a/doc/other/hledger_journal.5.info
+++ b/.otherdocs/hledger_journal.info
@@ -1,10 +1,10 @@
-This is hledger_journal.5.info, produced by makeinfo version 6.0 from
+This is hledger_journal.info, produced by makeinfo version 6.5 from
stdin.

-File: hledger_journal.5.info, Node: Top, Next: FILE FORMAT, Up: (dir)
+File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
-hledger_journal(5) hledger 1.4
+hledger_journal(5) hledger 1.5
******************************
hledger's usual data source is a plain text file containing journal
@@ -57,10 +57,12 @@ assisted by the helper modes for emacs or vim.
* Menu:
* FILE FORMAT::
+* Periodic transactions::
+* Automated posting rules::
* EDITOR SUPPORT::

-File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top
+File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top
1 FILE FORMAT
*************
@@ -83,7 +85,7 @@ File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev:
* Directives::

-File: hledger_journal.5.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
+File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
1.1 Transactions
================
@@ -105,7 +107,7 @@ following, separated by spaces:
representing...

-File: hledger_journal.5.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT
+File: hledger_journal.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT
1.2 Postings
============
@@ -133,7 +135,7 @@ spaces. But if you accidentally leave only one space (or tab) before
the amount, the amount will be considered part of the account name.

-File: hledger_journal.5.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT
+File: hledger_journal.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT
1.3 Dates
=========
@@ -145,7 +147,7 @@ File: hledger_journal.5.info, Node: Dates, Next: Status, Prev: Postings, Up:
* Posting dates::

-File: hledger_journal.5.info, Node: Simple dates, Next: Secondary dates, Up: Dates
+File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: Dates
1.3.1 Simple dates
------------------
@@ -158,7 +160,7 @@ command is run. Some examples: '2010/01/31', '1/31', '2010-01-31',
'2010.1.31'.

-File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates
+File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates
1.3.2 Secondary dates
---------------------
@@ -199,7 +201,7 @@ Ledger compatibility, but posting dates are a more powerful and less
confusing alternative.

-File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up: Dates
+File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: Dates
1.3.3 Posting dates
-------------------
@@ -234,7 +236,7 @@ characters in this way. With this syntax, DATE infers its year from the
transaction and DATE2 infers its year from DATE.

-File: hledger_journal.5.info, Node: Status, Next: Description, Prev: Dates, Up: FILE FORMAT
+File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: FILE FORMAT
1.4 Status
==========
@@ -270,13 +272,13 @@ toggle transaction status with C-c C-e, or posting status with C-c C-c.
What "uncleared", "pending", and "cleared" actually mean is up to
you. Here's one suggestion:
-status meaning
+status meaning
--------------------------------------------------------------------------
-uncleared recorded but not yet reconciled; needs review
-pending tentatively reconciled (if needed, eg during a big
- reconciliation)
-cleared complete, reconciled as far as possible, and considered
- correct
+uncleared recorded but not yet reconciled; needs review
+pending tentatively reconciled (if needed, eg during a big
+ reconciliation)
+cleared complete, reconciled as far as possible, and considered
+ correct
With this scheme, you would use '-PC' to see the current balance at
your bank, '-U' to see things which will probably hit your bank soon
@@ -284,7 +286,7 @@ your bank, '-U' to see things which will probably hit your bank soon
your finances.

-File: hledger_journal.5.info, Node: Description, Next: Account names, Prev: Status, Up: FILE FORMAT
+File: hledger_journal.info, Node: Description, Next: Account names, Prev: Status, Up: FILE FORMAT
1.5 Description
===============
@@ -299,7 +301,7 @@ comments.
* Payee and note::

-File: hledger_journal.5.info, Node: Payee and note, Up: Description
+File: hledger_journal.info, Node: Payee and note, Up: Description
1.5.1 Payee and note
--------------------
@@ -310,7 +312,7 @@ the right. This may be worthwhile if you need to do more precise
querying and pivoting by payee.

-File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT
+File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT
1.6 Account names
=================
@@ -328,7 +330,7 @@ more spaces* (or newline).
Account names can be aliased.

-File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT
+File: hledger_journal.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT
1.7 Amounts
===========
@@ -346,6 +348,7 @@ commodity name. Some examples:
'-$1,000,000.00'
'INR 9,99,99,999.00'
'EUR -2.000.000,00'
+'1 999 999.9455'
As you can see, the amount format is somewhat flexible:
@@ -358,10 +361,25 @@ commodity name. Some examples:
* negative amounts with a commodity on the left can have the minus
sign before or after it
* digit groups (thousands, or any other grouping) can be separated by
- commas (in which case period is used for decimal point) or periods
- (in which case comma is used for decimal point)
+ space or comma or period and should be used as separator between
+ all groups
+ * decimal part can be separated by comma or period and should be
+ different from digit groups separator
- You can use any of these variations when recording data, but when
+ You can use any of these variations when recording data. However,
+there is some ambiguous way of representing numbers like '$1.000' and
+'$1,000' both may mean either one thousand or one dollar. By default
+hledger will assume that this is sole delimiter is used only for
+decimals. On the other hand commodity format declared prior to that
+line will help to resolve that ambiguity differently:
+
+commodity $1,000.00
+
+2017/12/25 New life of Scrooge
+ expenses:gifts $1,000
+ assets
+
+ Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
@@ -383,7 +401,7 @@ when -V is used.) If you find this causing problems, set the desired
format with a commodity directive.

-File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT
+File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT
1.8 Virtual Postings
====================
@@ -418,7 +436,7 @@ can usually find an equivalent journal entry using real postings, which
is more correct and provides better error checking.

-File: hledger_journal.5.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT
+File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT
1.9 Balance Assertions
======================
@@ -452,7 +470,7 @@ or for reading Ledger files.
* Assertions and virtual postings::

-File: hledger_journal.5.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions
+File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions
1.9.1 Assertions and ordering
-----------------------------
@@ -471,7 +489,7 @@ control over the order of postings and assertions within a day, so you
can assert intra-day balances.

-File: hledger_journal.5.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions
+File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions
1.9.2 Assertions and included files
-----------------------------------
@@ -483,7 +501,7 @@ and you also want to assert the account's balance on the same day,
you'll have to put the assertion in the right file.

-File: hledger_journal.5.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions
+File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions
1.9.3 Assertions and multiple -f options
----------------------------------------
@@ -492,7 +510,7 @@ Balance assertions don't work well across files specified with multiple
-f options. Use include or concatenate the files instead.

-File: hledger_journal.5.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and multiple -f options, Up: Balance Assertions
+File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and multiple -f options, Up: Balance Assertions
1.9.4 Assertions and commodities
--------------------------------
@@ -511,7 +529,7 @@ account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)

-File: hledger_journal.5.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions
+File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions
1.9.5 Assertions and subaccounts
--------------------------------
@@ -534,7 +552,7 @@ $ hledger bal checking --flat
2

-File: hledger_journal.5.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions
+File: hledger_journal.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions
1.9.6 Assertions and virtual postings
-------------------------------------
@@ -544,7 +562,7 @@ virtual. They are not affected by the '--real/-R' flag or 'real:'
query.

-File: hledger_journal.5.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT
+File: hledger_journal.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT
1.10 Balance Assignments
========================
@@ -555,7 +573,7 @@ equals sign; instead it is calculated automatically so as to satisfy the
assertion. This can be a convenience during data entry, eg when setting
opening balances:
-; starting a new journal, set asset account balances
+; starting a new journal, set asset account balances
2016/1/1 opening balances
assets:checking = $409.32
assets:savings = $735.24
@@ -577,7 +595,7 @@ little less explicit; to know the exact amount posted, you have to run
hledger or do the calculations yourself, instead of just reading it.

-File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT
+File: hledger_journal.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT
1.11 Prices
===========
@@ -588,7 +606,7 @@ File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Ass
* Market prices::

-File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, Up: Prices
+File: hledger_journal.info, Node: Transaction prices, Next: Market prices, Up: Prices
1.11.1 Transaction prices
-------------------------
@@ -649,7 +667,7 @@ $ hledger bal -N --flat -B
€100 assets:euros

-File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices
+File: hledger_journal.info, Node: Market prices, Prev: Transaction prices, Up: Prices
1.11.2 Market prices
--------------------
@@ -678,14 +696,15 @@ P 2009/1/1 € $1.35
P 2010/1/1 € $1.40

-File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT
+File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT
1.12 Comments
=============
Lines in the journal beginning with a semicolon (';') or hash ('#') or
-asterisk ('*') are comments, and will be ignored. (Asterisk comments
-make it easy to treat your journal like an org-mode outline in emacs.)
+star ('*') are comments, and will be ignored. (Star comments cause
+org-mode nodes to be ignored, allowing emacs users to fold and navigate
+their journals with org-mode or orgstruct-mode.)
Also, anything between 'comment' and 'end comment' directives is a
(multi-line) comment. If there is no 'end comment', the comment extends
@@ -695,18 +714,19 @@ to the end of the file.
description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual posting
by writing them after the amount and/or indented on the following lines.
+Transaction and posting comments must begin with a semicolon (';').
Some examples:
-# a journal comment
+# a file comment
-; also a journal comment
+; also a file comment
comment
-This is a multiline comment,
+This is a multiline file comment,
which continues until a line
where the "end comment" string
-appears on its own.
+appears on its own (or end of file).
end comment
2012/5/14 something ; a transaction comment
@@ -715,10 +735,10 @@ end comment
posting2
; a comment for posting 2
; another comment line for posting 2
-; a journal comment (because not indented)
+; a file comment (because not indented)

-File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
+File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
1.13 Tags
=========
@@ -761,7 +781,7 @@ example, the following transaction has three tags ('A', 'TAG2',
are simple strings.

-File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
+File: hledger_journal.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
1.14 Directives
===============
@@ -778,7 +798,7 @@ File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
* Including other files::

-File: hledger_journal.5.info, Node: Account aliases, Next: account directive, Up: Directives
+File: hledger_journal.info, Node: Account aliases, Next: account directive, Up: Directives
1.14.1 Account aliases
----------------------
@@ -803,7 +823,7 @@ be useful for:
* end aliases::

-File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
+File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
1.14.1.1 Basic aliases
......................
@@ -826,7 +846,7 @@ alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

-File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
+File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
1.14.1.2 Regex aliases
......................
@@ -851,7 +871,7 @@ command line, to end of option argument), so it can contain trailing
whitespace.

-File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
+File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
1.14.1.3 Multiple aliases
.........................
@@ -867,7 +887,7 @@ following order:
2. alias options, in the order they appear on the command line

-File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
+File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
1.14.1.4 end aliases
....................
@@ -878,7 +898,7 @@ aliases' directive:
end aliases

-File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
+File: hledger_journal.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
1.14.2 account directive
------------------------
@@ -899,7 +919,7 @@ account expenses:food
; etc.

-File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
+File: hledger_journal.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
1.14.3 apply account directive
------------------------------
@@ -935,7 +955,7 @@ include personal.journal
supported.

-File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
+File: hledger_journal.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
1.14.4 Multi-line comments
--------------------------
@@ -944,7 +964,7 @@ A line containing just 'comment' starts a multi-line comment, and a line
containing just 'end comment' ends it. See comments.

-File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
+File: hledger_journal.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
1.14.5 commodity directive
--------------------------
@@ -976,7 +996,7 @@ commodity INR
format INR 9,99,99,999.00

-File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
+File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
1.14.6 Default commodity
------------------------
@@ -992,11 +1012,11 @@ amounts, or until the next D directive.
D $1,000.00
1/1
- a 5 # <- commodity-less amount, becomes $1
+ a 5 ; <- commodity-less amount, becomes $1
b

-File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
+File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
1.14.7 Default year
-------------------
@@ -1022,7 +1042,7 @@ Y2010 ; change default year to 2010
assets

-File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives
+File: hledger_journal.info, Node: Including other files, Prev: Default year, Up: Directives
1.14.8 Including other files
----------------------------
@@ -1039,9 +1059,73 @@ current file. Glob patterns ('*') are not currently supported.
include journal, timeclock or timedot files, but not CSV files.

-File: hledger_journal.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
+File: hledger_journal.info, Node: Periodic transactions, Next: Automated posting rules, Prev: FILE FORMAT, Up: Top
+
+2 Periodic transactions
+***********************
+
+A periodic transaction starts with a tilde '~' in place of a date
+followed by a period expression:
+
+~ weekly
+ assets:bank:checking $400 ; paycheck
+ income:acme inc
+
+ Periodic transactions are used for forecasting and budgeting only,
+they have no effect unless the '--forecast' or '--budget' flag is used.
+With '--forecast', each periodic transaction rule generates recurring
+forecast transactions at the specified interval, beginning the day after
+the last recorded journal transaction and ending 6 months from today, or
+at the specified report end date. With 'balance --budget', each
+periodic transaction declares recurring budget goals for one or more
+accounts.
+For more details, see: balance > Budgeting, Budgeting and Forecasting.
+
+
+File: hledger_journal.info, Node: Automated posting rules, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top
+
+3 Automated posting rules
+*************************
+
+Automated posting rule starts with an equal sign '=' in place of a date,
+followed by a query:
+
+= expenses:gifts
+ budget:gifts *-1
+ assets:budget *1
+
+ When '--auto' option is specified on the command line, automated
+posting rule will add its postings to all transactions that match the
+query.
+
+ If amount in the automated posting rule includes commodity name, new
+posting will be made in the given commodity, otherwise commodity of the
+matched transaction will be used.
+
+ When amount in the automated posting rule begins with the '*', amount
+will be treated as a multiplier that is applied to the amount of the
+first posting in the matched transaction.
+
+ In example above, every transaction in 'expenses:gifts' account will
+have two additional postings added to it: amount of the original gift
+will be debited from 'budget:gifts' and credited into 'assets:budget':
+
+; Original transaction
+2017-12-14
+ expenses:gifts $20
+ assets
+
+; With automated postings applied
+2017/12/14
+ expenses:gifts $20
+ assets
+ budget:gifts $-20
+ assets:budget $20
+
+
+File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated posting rules, Up: Top
-2 EDITOR SUPPORT
+4 EDITOR SUPPORT
****************
Add-on modes exist for various text editors, to make working with
@@ -1062,86 +1146,90 @@ Code

Tag Table:
-Node: Top78
-Node: FILE FORMAT2374
-Ref: #file-format2500
-Node: Transactions2723
-Ref: #transactions2846
-Node: Postings3530
-Ref: #postings3659
-Node: Dates4654
-Ref: #dates4771
-Node: Simple dates4836
-Ref: #simple-dates4964
-Node: Secondary dates5330
-Ref: #secondary-dates5486
-Node: Posting dates7049
-Ref: #posting-dates7180
-Node: Status8554
-Ref: #status8676
-Node: Description10390
-Ref: #description10530
-Node: Payee and note10849
-Ref: #payee-and-note10965
-Node: Account names11207
-Ref: #account-names11352
-Node: Amounts11839
-Ref: #amounts11977
-Node: Virtual Postings14078
-Ref: #virtual-postings14239
-Node: Balance Assertions15459
-Ref: #balance-assertions15636
-Node: Assertions and ordering16532
-Ref: #assertions-and-ordering16720
-Node: Assertions and included files17420
-Ref: #assertions-and-included-files17663
-Node: Assertions and multiple -f options17996
-Ref: #assertions-and-multiple--f-options18252
-Node: Assertions and commodities18384
-Ref: #assertions-and-commodities18621
-Node: Assertions and subaccounts19317
-Ref: #assertions-and-subaccounts19551
-Node: Assertions and virtual postings20072
-Ref: #assertions-and-virtual-postings20281
-Node: Balance Assignments20423
-Ref: #balance-assignments20594
-Node: Prices21713
-Ref: #prices21848
-Node: Transaction prices21899
-Ref: #transaction-prices22046
-Node: Market prices24202
-Ref: #market-prices24339
-Node: Comments25299
-Ref: #comments25423
-Node: Tags26536
-Ref: #tags26656
-Node: Directives28058
-Ref: #directives28173
-Node: Account aliases28366
-Ref: #account-aliases28512
-Node: Basic aliases29116
-Ref: #basic-aliases29261
-Node: Regex aliases29951
-Ref: #regex-aliases30121
-Node: Multiple aliases30839
-Ref: #multiple-aliases31013
-Node: end aliases31511
-Ref: #end-aliases31653
-Node: account directive31754
-Ref: #account-directive31936
-Node: apply account directive32232
-Ref: #apply-account-directive32430
-Node: Multi-line comments33089
-Ref: #multi-line-comments33281
-Node: commodity directive33409
-Ref: #commodity-directive33595
-Node: Default commodity34467
-Ref: #default-commodity34642
-Node: Default year35179
-Ref: #default-year35346
-Node: Including other files35769
-Ref: #including-other-files35928
-Node: EDITOR SUPPORT36325
-Ref: #editor-support36445
+Node: Top76
+Node: FILE FORMAT2424
+Ref: #file-format2555
+Node: Transactions2778
+Ref: #transactions2899
+Node: Postings3583
+Ref: #postings3710
+Node: Dates4705
+Ref: #dates4820
+Node: Simple dates4885
+Ref: #simple-dates5011
+Node: Secondary dates5377
+Ref: #secondary-dates5531
+Node: Posting dates7094
+Ref: #posting-dates7223
+Node: Status8597
+Ref: #status8717
+Node: Description10425
+Ref: #description10563
+Node: Payee and note10882
+Ref: #payee-and-note10996
+Node: Account names11238
+Ref: #account-names11381
+Node: Amounts11868
+Ref: #amounts12004
+Node: Virtual Postings14684
+Ref: #virtual-postings14843
+Node: Balance Assertions16063
+Ref: #balance-assertions16238
+Node: Assertions and ordering17134
+Ref: #assertions-and-ordering17320
+Node: Assertions and included files18020
+Ref: #assertions-and-included-files18261
+Node: Assertions and multiple -f options18594
+Ref: #assertions-and-multiple--f-options18848
+Node: Assertions and commodities18980
+Ref: #assertions-and-commodities19215
+Node: Assertions and subaccounts19911
+Ref: #assertions-and-subaccounts20143
+Node: Assertions and virtual postings20664
+Ref: #assertions-and-virtual-postings20871
+Node: Balance Assignments21013
+Ref: #balance-assignments21182
+Node: Prices22302
+Ref: #prices22435
+Node: Transaction prices22486
+Ref: #transaction-prices22631
+Node: Market prices24787
+Ref: #market-prices24922
+Node: Comments25882
+Ref: #comments26004
+Node: Tags27246
+Ref: #tags27364
+Node: Directives28766
+Ref: #directives28879
+Node: Account aliases29072
+Ref: #account-aliases29216
+Node: Basic aliases29820
+Ref: #basic-aliases29963
+Node: Regex aliases30653
+Ref: #regex-aliases30821
+Node: Multiple aliases31539
+Ref: #multiple-aliases31711
+Node: end aliases32209
+Ref: #end-aliases32349
+Node: account directive32450
+Ref: #account-directive32630
+Node: apply account directive32926
+Ref: #apply-account-directive33122
+Node: Multi-line comments33781
+Ref: #multi-line-comments33971
+Node: commodity directive34099
+Ref: #commodity-directive34283
+Node: Default commodity35155
+Ref: #default-commodity35328
+Node: Default year35865
+Ref: #default-year36030
+Node: Including other files36453
+Ref: #including-other-files36610
+Node: Periodic transactions37007
+Ref: #periodic-transactions37178
+Node: Automated posting rules37921
+Ref: #automated-posting-rules38099
+Node: EDITOR SUPPORT39208
+Ref: #editor-support39338

End Tag Table
diff --git a/doc/other/hledger_journal.5.txt b/.otherdocs/hledger_journal.txt
index 7377cbd..9df70a9 100644
--- a/doc/other/hledger_journal.5.txt
+++ b/.otherdocs/hledger_journal.txt
@@ -211,10 +211,10 @@ FILE FORMAT
status meaning
--------------------------------------------------------------------------
uncleared recorded but not yet reconciled; needs review
- pending tentatively reconciled (if needed, eg during a big recon-
- ciliation)
- cleared complete, reconciled as far as possible, and considered
- correct
+ pending tentatively reconciled (if needed, eg during a big reconcil-
+ iation)
+ cleared complete, reconciled as far as possible, and considered cor-
+ rect
With this scheme, you would use -PC to see the current balance at your
bank, -U to see things which will probably hit your bank soon (like
@@ -260,6 +260,7 @@ FILE FORMAT
-$1,000,000.00
INR 9,99,99,999.00
EUR -2.000.000,00
+ 1 999 999.9455
As you can see, the amount format is somewhat flexible:
@@ -275,10 +276,26 @@ FILE FORMAT
before or after it
o digit groups (thousands, or any other grouping) can be separated by
- commas (in which case period is used for decimal point) or periods
- (in which case comma is used for decimal point)
+ space or comma or period and should be used as separator between all
+ groups
- You can use any of these variations when recording data, but when
+ o decimal part can be separated by comma or period and should be dif-
+ ferent from digit groups separator
+
+ You can use any of these variations when recording data. However,
+ there is some ambiguous way of representing numbers like $1.000 and
+ $1,000 both may mean either one thousand or one dollar. By default
+ hledger will assume that this is sole delimiter is used only for deci-
+ mals. On the other hand commodity format declared prior to that line
+ will help to resolve that ambiguity differently:
+
+ commodity $1,000.00
+
+ 2017/12/25 New life of Scrooge
+ expenses:gifts $1,000
+ assets
+
+ Though journal may contain mixed styles to represent amount, when
hledger displays amounts, it will choose a consistent format for each
commodity. (Except for price amounts, which are always formatted as
written). The display format is chosen as follows:
@@ -523,9 +540,10 @@ FILE FORMAT
P 2010/1/1 $1.40
Comments
- Lines in the journal beginning with a semicolon (;) or hash (#) or
- asterisk (*) are comments, and will be ignored. (Asterisk comments
- make it easy to treat your journal like an org-mode outline in emacs.)
+ Lines in the journal beginning with a semicolon (;) or hash (#) or star
+ (*) are comments, and will be ignored. (Star comments cause org-mode
+ nodes to be ignored, allowing emacs users to fold and navigate their
+ journals with org-mode or orgstruct-mode.)
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
@@ -534,19 +552,20 @@ FILE FORMAT
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
- writing them after the amount and/or indented on the following lines.
+ writing them after the amount and/or indented on the following lines.
+ Transaction and posting comments must begin with a semicolon (;).
Some examples:
- # a journal comment
+ # a file comment
- ; also a journal comment
+ ; also a file comment
comment
- This is a multiline comment,
+ This is a multiline file comment,
which continues until a line
where the "end comment" string
- appears on its own.
+ appears on its own (or end of file).
end comment
2012/5/14 something ; a transaction comment
@@ -555,23 +574,23 @@ FILE FORMAT
posting2
; a comment for posting 2
; another comment line for posting 2
- ; a journal comment (because not indented)
+ ; a file comment (because not indented)
Tags
- Tags are a way to add extra labels or labelled data to postings and
+ Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
- A simple tag is a word (which may contain hyphens) followed by a full
+ A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
- Tags can have a value, which is the text after the colon, up to the
+ Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
- Note this means hledger's tag values can not contain commas or new-
+ Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@@ -585,21 +604,21 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
- Tags in a transaction comment affect the transaction and all of its
- postings, while tags in a posting comment affect only that posting.
- For example, the following transaction has three tags (A, TAG2,
+ Tags in a transaction comment affect the transaction and all of its
+ postings, while tags in a posting comment affect only that posting.
+ For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
- Tags are like Ledger's metadata feature, except hledger's tag values
+ Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
Account aliases
- You can define aliases which rewrite your account names (after reading
+ You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
@@ -616,8 +635,8 @@ FILE FORMAT
See also Cookbook: rewrite account names.
Basic aliases
- To set an account alias, use the alias directive in your journal file.
- This affects all subsequent journal entries in the current file or its
+ To set an account alias, use the alias directive in your journal file.
+ This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@@ -625,54 +644,54 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
- OLD and NEW are full account names. hledger will replace any occur-
- rence of the old account name with the new one. Subaccounts are also
+ OLD and NEW are full account names. hledger will replace any occur-
+ rence of the old account name with the new one. Subaccounts are also
affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
- There is also a more powerful variant that uses a regular expression,
+ There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
- REGEX is a case-insensitive regular expression. Anywhere it matches
- inside an account name, the matched part will be replaced by REPLACE-
- MENT. If REGEX contains parenthesised match groups, these can be ref-
+ REGEX is a case-insensitive regular expression. Anywhere it matches
+ inside an account name, the matched part will be replaced by REPLACE-
+ MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
- Also note that REPLACEMENT continues to the end of line (or on command
- line, to end of option argument), so it can contain trailing white-
+ Also note that REPLACEMENT continues to the end of line (or on command
+ line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
- You can define as many aliases as you like using directives or com-
- mand-line options. Aliases are recursive - each alias sees the result
- of applying previous ones. (This is different from Ledger, where
+ You can define as many aliases as you like using directives or com-
+ mand-line options. Aliases are recursive - each alias sees the result
+ of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
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)
2. alias options, in the order they appear on the command line
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
account directive
- The account directive predefines account names, as in Ledger and Bean-
- count. This may be useful for your own documentation; hledger doesn't
+ The account directive predefines account names, as in Ledger and Bean-
+ count. This may be useful for your own documentation; hledger doesn't
make use of it yet.
; account ACCT
@@ -687,8 +706,8 @@ FILE FORMAT
; etc.
apply account directive
- You can specify a parent account which will be prepended to all
- accounts within a section of the journal. Use the apply account and
+ You can specify a parent account which will be prepended to all
+ accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@@ -705,7 +724,7 @@ FILE FORMAT
home:food $10
home:cash $-10
- If end apply account is omitted, the effect lasts to the end of the
+ If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@@ -714,16 +733,16 @@ FILE FORMAT
apply account personal
include personal.journal
- Prior to hledger 1.0, legacy account and end spellings were also sup-
+ Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
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.
commodity directive
- The commodity directive predefines commodities (currently this is just
- informational), and also it may define the display format for amounts
+ The commodity directive predefines commodities (currently this is just
+ informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this:
@@ -735,8 +754,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
- or on multiple lines, using the "format" subdirective. In this case
- the commodity symbol appears twice and should be the same in both
+ or on multiple lines, using the "format" subdirective. In this case
+ the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
@@ -749,10 +768,10 @@ FILE FORMAT
format INR 9,99,99,999.00
Default commodity
- The D directive sets a default commodity (and display format), to be
+ The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
- this differs from Ledger's default commodity directive.) The commodity
- and display format will be applied to all subsequent commodity-less
+ this differs from Ledger's default commodity directive.) The commodity
+ and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
@@ -760,12 +779,12 @@ FILE FORMAT
D $1,000.00
1/1
- a 5 # <- commodity-less amount, becomes $1
+ a 5 ; <- commodity-less amount, becomes $1
b
Default year
- You can set a default year to be used for subsequent dates which don't
- specify a year. This is a line beginning with Y followed by the year.
+ You can set a default year to be used for subsequent dates which don't
+ specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@@ -785,45 +804,96 @@ FILE FORMAT
assets
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 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.
- 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.
+Periodic transactions
+ A periodic transaction starts with a tilde `~' in place of a date fol-
+ lowed by a period expression:
+
+ ~ weekly
+ assets:bank:checking $400 ; paycheck
+ income:acme inc
+
+ Periodic transactions are used for forecasting and budgeting only, they
+ have no effect unless the --forecast or --budget flag is used. With
+ --forecast, each periodic transaction rule generates recurring forecast
+ transactions at the specified interval, beginning the day after the
+ last recorded journal transaction and ending 6 months from today, or at
+ the specified report end date. With balance --budget, each periodic
+ transaction declares recurring budget goals for one or more accounts.
+ For more details, see: balance > Budgeting, Budgeting and Forecasting.
+
+Automated posting rules
+ Automated posting rule starts with an equal sign `=' in place of a
+ date, followed by a query:
+
+ = expenses:gifts
+ budget:gifts *-1
+ assets:budget *1
+
+ When --auto option is specified on the command line, automated posting
+ rule will add its postings to all transactions that match the query.
+
+ If amount in the automated posting rule includes commodity name, new
+ posting will be made in the given commodity, otherwise commodity of the
+ matched transaction will be used.
+
+ When amount in the automated posting rule begins with the '*', amount
+ will be treated as a multiplier that is applied to the amount of the
+ first posting in the matched transaction.
+
+ In example above, every transaction in expenses:gifts account will have
+ two additional postings added to it: amount of the original gift will
+ be debited from budget:gifts and credited into assets:budget:
+
+ ; Original transaction
+ 2017-12-14
+ expenses:gifts $20
+ assets
+
+ ; With automated postings applied
+ 2017/12/14
+ expenses:gifts $20
+ assets
+ budget:gifts $-20
+ assets:budget $20
+
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
- nal files easier. They add colour, navigation aids and helpful com-
- mands. For hledger users who edit the journal file directly (the
+ nal files easier. They add colour, navigation aids and helpful com-
+ mands. For hledger users who edit the journal file directly (the
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:
Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html
- Vim https://github.com/ledger/ledger/wiki/Get-
- ting-started
+ Vim https://github.com/ledger/ledger/wiki/Getting-started
+
+
Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub-
lime-Text
Textmate https://github.com/ledger/ledger/wiki/Using-Text-
Mate-2
Text Wrangler https://github.com/ledger/ledger/wiki/Edit-
ing-Ledger-files-with-TextWrangler
-
-
Visual Studio https://marketplace.visualstudio.com/items?item-
Code Name=mark-hansen.hledger-vscode
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)
@@ -837,7 +907,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -845,4 +915,4 @@ SEE ALSO
-hledger 1.4 September 2017 hledger_journal(5)
+hledger 1.5 December 2017 hledger_journal(5)
diff --git a/doc/other/hledger_timeclock.5 b/.otherdocs/hledger_timeclock.5
index 0ba0757..d0fe986 100644
--- a/doc/other/hledger_timeclock.5
+++ b/.otherdocs/hledger_timeclock.5
@@ -1,5 +1,5 @@
-.TH "hledger_timeclock" "5" "September 2017" "hledger 1.4" "hledger User Manuals"
+.TH "hledger_timeclock" "5" "December 2017" "hledger 1.5" "hledger User Manuals"
@@ -9,7 +9,7 @@ Timeclock \- the time logging format of timeclock.el, as read by hledger
.SH DESCRIPTION
.PP
hledger can read timeclock files.
-As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
+As with Ledger, these are (a subset of) timeclock.el's format,
containing clock\-in and clock\-out entries as in the example below.
The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ].
@@ -63,20 +63,12 @@ use emacs and the built\-in timeclock.el, or the extended
timeclock\-x.el and perhaps the extras in ledgerutils.el
.IP \[bu] 2
at the command line, use these bash aliases:
-.RS 2
-.IP
-.nf
-\f[C]
-alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG"
-alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG"
-\f[]
-.fi
-.RE
+\f[C]shell\ \ \ alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG"\ \ \ alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG"\f[]
.IP \[bu] 2
or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x
repository.
-These rely on a "timeclock" executable which I think is just the ledger
-2 executable renamed.
+These rely on a \[lq]timeclock\[rq] executable which I think is just the
+ledger 2 executable renamed.
.SH "REPORTING BUGS"
diff --git a/doc/other/hledger_timeclock.5.info b/.otherdocs/hledger_timeclock.info
index 6ba2a52..3403f6a 100644
--- a/doc/other/hledger_timeclock.5.info
+++ b/.otherdocs/hledger_timeclock.info
@@ -1,10 +1,10 @@
-This is hledger_timeclock.5.info, produced by makeinfo version 6.0 from
+This is hledger_timeclock.info, produced by makeinfo version 6.5 from
stdin.

-File: hledger_timeclock.5.info, Node: Top, Up: (dir)
+File: hledger_timeclock.info, Node: Top, Up: (dir)
-hledger_timeclock(5) hledger 1.4
+hledger_timeclock(5) hledger 1.5
********************************
hledger can read timeclock files. As with Ledger, these are (a subset
@@ -45,11 +45,9 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa
* use emacs and the built-in timeclock.el, or the extended
timeclock-x.el and perhaps the extras in ledgerutils.el
- * at the command line, use these bash aliases:
-
- alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG"
- alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
-
+ * at the command line, use these bash aliases: 'shell alias ti="echo
+ i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
+ `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'
* or use the old 'ti' and 'to' scripts in the ledger 2.x repository.
These rely on a "timeclock" executable which I think is just the
ledger 2 executable renamed.
@@ -57,6 +55,6 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa

Tag Table:
-Node: Top80
+Node: Top78

End Tag Table
diff --git a/doc/other/hledger_timeclock.5.txt b/.otherdocs/hledger_timeclock.txt
index 5840820..a0d9878 100644
--- a/doc/other/hledger_timeclock.5.txt
+++ b/.otherdocs/hledger_timeclock.txt
@@ -45,10 +45,8 @@ DESCRIPTION
o use emacs and the built-in timeclock.el, or the extended time-
clock-x.el and perhaps the extras in ledgerutils.el
- o at the command line, use these bash aliases:
-
- alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG"
- alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
+ o at the command line, use these bash aliases:
+ shell alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2
@@ -79,4 +77,4 @@ SEE ALSO
-hledger 1.4 September 2017 hledger_timeclock(5)
+hledger 1.5 December 2017 hledger_timeclock(5)
diff --git a/doc/other/hledger_timedot.5 b/.otherdocs/hledger_timedot.5
index 13a7324..c516289 100644
--- a/doc/other/hledger_timedot.5
+++ b/.otherdocs/hledger_timedot.5
@@ -1,11 +1,11 @@
-.TH "hledger_timedot" "5" "September 2017" "hledger 1.4" "hledger User Manuals"
+.TH "hledger_timedot" "5" "December 2017" "hledger 1.5" "hledger User Manuals"
.SH NAME
.PP
-Timedot \- hledger\[aq]s human\-friendly time logging format
+Timedot \- hledger's human\-friendly time logging format
.SH DESCRIPTION
.PP
Timedot is a plain text format for logging dated, categorised quantities
@@ -16,10 +16,10 @@ precise or too interruptive.
It can be formatted like a bar chart, making clear at a glance where
time was spent.
.PP
-Though called "timedot", this format is read by hledger as commodityless
-quantities, so it could be used to represent dated quantities other than
-time.
-In the docs below we\[aq]ll assume it\[aq]s time.
+Though called \[lq]timedot\[rq], this format is read by hledger as
+commodityless quantities, so it could be used to represent dated
+quantities other than time.
+In the docs below we'll assume it's time.
.SH FILE FORMAT
.PP
A timedot file contains a series of day entries.
@@ -34,7 +34,7 @@ Quantities can be written as:
.IP \[bu] 2
a sequence of dots (.) representing quarter hours.
Spaces may optionally be used for grouping and readability.
-Eg: ....
+Eg: \&....
\&..
.IP \[bu] 2
an integral or decimal number, representing hours.
diff --git a/doc/other/hledger_timedot.5.info b/.otherdocs/hledger_timedot.info
index e3e9fa2..ac76544 100644
--- a/doc/other/hledger_timedot.5.info
+++ b/.otherdocs/hledger_timedot.info
@@ -1,10 +1,10 @@
-This is hledger_timedot.5.info, produced by makeinfo version 6.0 from
+This is hledger_timedot.info, produced by makeinfo version 6.5 from
stdin.

-File: hledger_timedot.5.info, Node: Top, Next: FILE FORMAT, Up: (dir)
+File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir)
-hledger_timedot(5) hledger 1.4
+hledger_timedot(5) hledger 1.5
******************************
Timedot is a plain text format for logging dated, categorised quantities
@@ -22,7 +22,7 @@ quantities other than time. In the docs below we'll assume it's time.
* FILE FORMAT::

-File: hledger_timedot.5.info, Node: FILE FORMAT, Prev: Top, Up: Top
+File: hledger_timedot.info, Node: FILE FORMAT, Prev: Top, Up: Top
1 FILE FORMAT
*************
@@ -53,7 +53,7 @@ example:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1
inc:client1 .... .... .... .... .... ....
-fos:haskell .... ..
+fos:haskell .... ..
biz:research .
2016/2/2
@@ -79,17 +79,17 @@ $ hledger -f t.timedot print date:2016/2/2
$ hledger -f t.timedot bal --daily --tree
Balance changes in 2016/02/01-2016/02/03:
- || 2016/02/01d 2016/02/02d 2016/02/03d
+ || 2016/02/01d 2016/02/02d 2016/02/03d
============++========================================
- biz || 0.25 0.25 1.00
- research || 0.25 0.25 1.00
- fos || 1.50 0 3.00
- haskell || 1.50 0 0
- hledger || 0 0 3.00
- inc || 6.00 2.00 4.00
- client1 || 6.00 2.00 4.00
+ biz || 0.25 0.25 1.00
+ research || 0.25 0.25 1.00
+ fos || 1.50 0 3.00
+ haskell || 1.50 0 0
+ hledger || 0 0 3.00
+ inc || 6.00 2.00 4.00
+ client1 || 6.00 2.00 4.00
------------++----------------------------------------
- || 7.75 2.25 8.00
+ || 7.75 2.25 8.00
I prefer to use period for separating account components. We can
make this work with an account alias:
@@ -109,8 +109,8 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4

Tag Table:
-Node: Top78
-Node: FILE FORMAT809
-Ref: #file-format912
+Node: Top76
+Node: FILE FORMAT805
+Ref: #file-format906

End Tag Table
diff --git a/doc/other/hledger_timedot.5.txt b/.otherdocs/hledger_timedot.txt
index fa7d582..757f679 100644
--- a/doc/other/hledger_timedot.5.txt
+++ b/.otherdocs/hledger_timedot.txt
@@ -124,4 +124,4 @@ SEE ALSO
-hledger 1.4 September 2017 hledger_timedot(5)
+hledger 1.5 December 2017 hledger_timedot(5)
diff --git a/CHANGES b/CHANGES
index 6ba856e..ac88a5c 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,31 @@
-User-visible changes in the hledger and hledger-lib packages.
-See also the project change log.
+User-visible changes in the hledger CLI tool. See also hledger-lib.
+
+
+# 1.5 (2017/12/31)
+
+* --auto adds Ledger-style automated postings to transactions (Dmitry Astapov, Mykola Orliuk)
+
+* --forecast generates Ledger-style periodic transactions in the future (Dmitry Astapov, Mykola Orliuk)
+
+* -V/--value uses today's market prices by default, not those of last transaction date. #683, #648
+
+* add: suggest implied (parent) and declared (by account directives) account names also
+
+* bal: --budget shows performance compared to budget goals defined
+ with periodic transactions. Accounts with budget goals are
+ displayed folded (depth-clipped) at a depth matching the budget
+ specification. Unbudgeted accounts are hidden, or with
+ --show-unbudgeted, shown at their usual depth. (Dmitry Astapov)
+
+* import: the output of --dry-run is now valid journal format
+
+* print: -B shows converted amounts again, as in 1.1, even without
+ -x. #551 (Mykola Orliuk, Simon Michael)
+
+* tag: the first argument now filters tag names, additional arguments
+ filter transactions (#261)
+
+* remove upper bounds on all but hledger* and base (experimental)
# 1.4 (2017/9/30)
diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs
index 35c6537..530515c 100644
--- a/Hledger/Cli/CliOptions.hs
+++ b/Hledger/Cli/CliOptions.hs
@@ -155,6 +155,8 @@ reportflags = [
,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden"
,flagNone ["cost","B"] (setboolopt "cost") "convert amounts to their cost at transaction time (using the transaction price, if any)"
,flagNone ["value","V"] (setboolopt "value") "convert amounts to their market value on the report end date (using the most recent applicable market price, if any)"
+ ,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions"
+ ,flagNone ["forecast"] (setboolopt "forecast") "apply periodic transaction rules to generate future transactions, to 6 months from now or report end date"
]
-- | Common output-related flags: --output-file, --output-format...
diff --git a/Hledger/Cli/Commands/Add.hs b/Hledger/Cli/Commands/Add.hs
index 8896753..bfb406f 100644
--- a/Hledger/Cli/Commands/Add.hs
+++ b/Hledger/Cli/Commands/Add.hs
@@ -262,7 +262,7 @@ accountWizard EntryState{..} = do
flip evalState esJournal $ runParserT (accountnamep <* eof) "" (T.pack s) -- otherwise, try to parse the input as an accountname
where
validateAccount :: Text -> Maybe Text
- validateAccount t | no_new_accounts_ esOpts && not (t `elem` journalAccountNames esJournal) = Nothing
+ validateAccount t | no_new_accounts_ esOpts && not (t `elem` journalAccountNamesDeclaredOrImplied esJournal) = Nothing
| otherwise = Just t
dbg1 = id -- strace
@@ -337,7 +337,7 @@ descriptionCompleter :: Journal -> String -> CompletionFunc IO
descriptionCompleter j = completer (map T.unpack $ journalDescriptions j)
accountCompleter :: Journal -> String -> CompletionFunc IO
-accountCompleter j = completer (map T.unpack $ journalAccountNamesUsed j)
+accountCompleter j = completer (map T.unpack $ journalAccountNamesDeclaredOrImplied j)
amountCompleter :: String -> CompletionFunc IO
amountCompleter = completer []
diff --git a/Hledger/Cli/Commands/Balance.hs b/Hledger/Cli/Commands/Balance.hs
index 896987f..d346f0c 100644
--- a/Hledger/Cli/Commands/Balance.hs
+++ b/Hledger/Cli/Commands/Balance.hs
@@ -246,11 +246,13 @@ module Hledger.Cli.Commands.Balance (
,tests_Hledger_Cli_Commands_Balance
) where
-import Data.List (intercalate)
+import Data.List (intercalate, nub)
import Data.Maybe
+import qualified Data.Map as Map
-- import Data.Monoid
import qualified Data.Text as T
import System.Console.CmdArgs.Explicit as C
+import Data.Decimal (roundTo)
import Text.CSV
import Test.HUnit
import Text.Printf (printf)
@@ -281,8 +283,10 @@ balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don
,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)"
,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)"
,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)"
- ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode when displaying tables"
- ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name"
+ ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode to display prettier tables"
+ ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed."
+ ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions"
+ ,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "with --budget, show unbudgeted accounts also"
]
++ outputflags
,groupHidden = []
@@ -293,7 +297,7 @@ balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don
-- | The balance command, prints a balance report.
balance :: CliOpts -> Journal -> IO ()
-balance opts@CliOpts{reportopts_=ropts} j = do
+balance opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do
d <- getCurrentDay
case lineFormatFromOpts ropts of
Left err -> error' $ unlines [err]
@@ -319,12 +323,58 @@ balance opts@CliOpts{reportopts_=ropts} j = do
"csv" -> \ropts r -> (++ "\n") $ printCSV $ balanceReportAsCsv ropts r
_ -> balanceReportAsText
writeOutput opts $ render ropts report
- _ -> do
+
+ _ | boolopt "budget" rawopts -> do
+ let budget = budgetJournal opts j
+ j' = budgetRollUp opts budget j
+ report = multiBalanceReport ropts (queryFromOpts d ropts) j'
+ budgetReport = multiBalanceReport ropts (queryFromOpts d ropts) budget
+ render = case format of
+ -- XXX: implement csv rendering
+ "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv ropts
+ _ -> multiBalanceReportWithBudgetAsText ropts budgetReport
+ writeOutput opts $ render report
+
+ | otherwise -> do
let report = multiBalanceReport ropts (queryFromOpts d ropts) j
render = case format of
- "csv" -> \ropts r -> (++ "\n") $ printCSV $ multiBalanceReportAsCsv ropts r
- _ -> multiBalanceReportAsText
- writeOutput opts $ render ropts report
+ "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv ropts
+ _ -> multiBalanceReportAsText ropts
+ writeOutput opts $ render report
+
+-- | Re-map account names to closet parent with periodic transaction from budget.
+-- Accounts that dont have suitable parent are either remapped to "<unbudgeted>:topAccount"
+-- or left as-is if --show-unbudgeted is provided
+budgetRollUp :: CliOpts -> Journal -> Journal -> Journal
+budgetRollUp CliOpts{rawopts_=rawopts} budget j = j { jtxns = remapTxn <$> jtxns j }
+ where
+ budgetAccounts = nub $ concatMap (map paccount . ptpostings) $ jperiodictxns budget
+ remapAccount origAcctName = remapAccount' origAcctName
+ where
+ remapAccount' acctName
+ | acctName `elem` budgetAccounts = acctName
+ | otherwise =
+ case parentAccountName acctName of
+ "" | boolopt "show-unbudgeted" rawopts -> origAcctName
+ | otherwise -> T.append (T.pack "<unbudgeted>:") acctName
+ parent -> remapAccount' parent
+ remapPosting p = p { paccount = remapAccount $ paccount p, porigin = Just . fromMaybe p $ porigin p }
+ remapTxn = mapPostings (map remapPosting)
+ mapPostings f t = txnTieKnot $ t { tpostings = f $ tpostings t }
+
+-- | Generate journal of all periodic transactions in the given journal for the
+-- entireity of its history or reporting period, whatever is smaller
+budgetJournal :: CliOpts -> Journal -> Journal
+budgetJournal opts j = journalBalanceTransactions' opts j { jtxns = budget }
+ where
+ dates = spanIntersect (jdatespan j) (periodAsDateSpan $ period_ $ reportopts_ opts)
+ budget = [makeBudget t | pt <- jperiodictxns j, t <- runPeriodicTransaction pt dates]
+ makeBudget t = txnTieKnot $ t { tdescription = T.pack "Budget transaction" }
+ journalBalanceTransactions' opts j =
+ let assrt = not . ignore_assertions_ $ inputopts_ opts
+ in
+ either error' id $ journalBalanceTransactions assrt j
+
-- single-column balance reports
@@ -494,16 +544,78 @@ multiBalanceReportAsText opts r =
CumulativeChange -> "Ending balances (cumulative)"
HistoricalBalance -> "Ending balances (historical)"
+-- | Render two multi-column balance reports as plain text suitable for console output.
+-- They are assumed to have same number of columns, one of them representing
+-- a budget
+multiBalanceReportWithBudgetAsText :: ReportOpts -> MultiBalanceReport -> MultiBalanceReport -> String
+multiBalanceReportWithBudgetAsText opts budget r =
+ printf "%s in %s:\n\n" typeStr (showDateSpan $ multiBalanceReportSpan r)
+ ++ renderBalanceReportTable' opts showcell tabl
+ where
+ tabl = combine (balanceReportAsTable opts r) (balanceReportAsTable opts budget)
+ typeStr :: String
+ typeStr = case balancetype_ opts of
+ PeriodChange -> "Balance changes"
+ CumulativeChange -> "Ending balances (cumulative)"
+ HistoricalBalance -> "Ending balances (historical)"
+ showcell (real, Nothing) = showamt real
+ showcell (real, Just budget) =
+ case percentage real budget of
+ Just pct -> printf "%s [%s%% of %s]" (showamt real) (show $ roundTo 0 pct) (showamt budget)
+ Nothing -> printf "%s [%s]" (showamt real) (showamt budget)
+ percentage real budget =
+ -- percentage of budget consumed is always computed in the cost basis
+ case (toCost real, toCost budget) of
+ (Mixed [a1], Mixed [a2])
+ | isReallyZeroAmount a1 -> Just 0 -- if there are no postings, we consumed 0% of budget
+ | acommodity a1 == acommodity a2 && aquantity a2 /= 0 ->
+ Just $ 100 * aquantity a1 / aquantity a2
+ _ -> Nothing
+ where
+ toCost = normaliseMixedAmount . costOfMixedAmount
+ showamt | color_ opts = cshowMixedAmountOneLineWithoutPrice
+ | otherwise = showMixedAmountOneLineWithoutPrice
+ -- combine reportTable budgetTable will combine them into a single table where cells
+ -- are tuples of (actual, Maybe budget) numbers. Main assumptions is that
+ -- row/column titles of budgetTable are subset of row/column titles or reportTable,
+ -- and there are now row/column titles in budgetTable that are not mentioned in reporTable.
+ -- Both of these are satisfied by construction of budget report and process of rolling up
+ -- account names.
+ combine (Table l t d) (Table l' t' d') = Table l t combinedRows
+ where
+ -- For all accounts that are present in the budget, zip real amounts with budget amounts
+ combinedRows = [ combineRow row budgetRow
+ | (acct, row) <- zip (headerContents l) d
+ , let budgetRow =
+ if acct == "" then [] -- "" is totals row
+ else fromMaybe [] $ Map.lookup acct budgetAccts
+ ]
+ -- Budget could cover smaller interval of time than the whole journal.
+ -- Headers for budget row will always be a sublist of headers of row
+ combineRow r br =
+ let reportRow = zip (headerContents t) r
+ budgetRow = Map.fromList $ zip (headerContents t') br
+ findBudgetVal hdr = Map.lookup hdr budgetRow
+ in map (\(hdr, val) -> (val, findBudgetVal hdr)) reportRow
+ budgetAccts = Map.fromList $ zip (headerContents l') d'
+
-- | Given a table representing a multi-column balance report (for example,
-- made using 'balanceReportAsTable'), render it in a format suitable for
-- console output.
renderBalanceReportTable :: ReportOpts -> Table String String MixedAmount -> String
-renderBalanceReportTable (ReportOpts { pretty_tables_ = pretty, color_=usecolor }) =
+renderBalanceReportTable ropts =
+ renderBalanceReportTable' ropts showamt
+ where
+ showamt | color_ ropts = cshowMixedAmountOneLineWithoutPrice
+ | otherwise = showMixedAmountOneLineWithoutPrice
+
+renderBalanceReportTable' :: ReportOpts -> (a -> String) -> Table String String a -> String
+renderBalanceReportTable' (ReportOpts { pretty_tables_ = pretty}) showCell =
unlines
. addtrailingblank
. trimborder
. lines
- . render pretty id id showamt
+ . render pretty id id showCell
. align
where
addtrailingblank = (++[""])
@@ -512,8 +624,6 @@ renderBalanceReportTable (ReportOpts { pretty_tables_ = pretty, color_=usecolor
where
acctswidth = maximum' $ map strWidth (headerContents l)
l' = padRightWide acctswidth <$> l
- showamt | usecolor = cshowMixedAmountOneLineWithoutPrice
- | otherwise = showMixedAmountOneLineWithoutPrice
-- | Build a 'Table' from a multi-column balance report.
balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount
diff --git a/Hledger/Cli/Commands/Equity.hs b/Hledger/Cli/Commands/Equity.hs
index ea1fdcc..98cd405 100755
--- a/Hledger/Cli/Commands/Equity.hs
+++ b/Hledger/Cli/Commands/Equity.hs
@@ -66,7 +66,7 @@ equity CliOpts{reportopts_=ropts} j = do
balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmountSquashPricesForDisplay b) acctbals
ps = [posting{paccount=a
,pamount=mixed [b]
- ,pbalanceassertion=Just b
+ ,pbalanceassertion=Just (b,nullsourcepos)
}
|(a,_,_,mb) <- acctbals
,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb
@@ -75,7 +75,7 @@ equity CliOpts{reportopts_=ropts} j = do
enddate = fromMaybe today $ queryEndDate (date2_ ropts_) q
nps = [posting{paccount=a
,pamount=mixed [negate b]
- ,pbalanceassertion=Just b{aquantity=0}
+ ,pbalanceassertion=Just (b{aquantity=0}, nullsourcepos)
}
|(a,_,_,mb) <- acctbals
,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb
diff --git a/Hledger/Cli/Commands/Import.hs b/Hledger/Cli/Commands/Import.hs
index 02e6b95..d4b3da2 100755
--- a/Hledger/Cli/Commands/Import.hs
+++ b/Hledger/Cli/Commands/Import.hs
@@ -51,7 +51,7 @@ importcmd opts@CliOpts{rawopts_=rawopts,inputopts_=iopts} j = do
case sortBy (comparing tdate) $ jtxns newj of
[] -> putStrLn "no new transactions"
newts | dryrun -> do
- printf "would import %d new transactions:\n\n" (length newts)
+ printf "; would import %d new transactions:\n\n" (length newts)
-- TODO how to force output here ?
-- length (jtxns newj) `seq` print' opts{rawopts_=("explicit",""):rawopts} newj
mapM_ (putStr . showTransactionUnelided) newts
diff --git a/Hledger/Cli/Commands/Print.hs b/Hledger/Cli/Commands/Print.hs
index 5756c1a..cd60a60 100644
--- a/Hledger/Cli/Commands/Print.hs
+++ b/Hledger/Cli/Commands/Print.hs
@@ -66,8 +66,15 @@ printEntries opts@CliOpts{reportopts_=ropts} j = do
entriesReportAsText :: CliOpts -> EntriesReport -> String
entriesReportAsText opts = concatMap (showTransactionUnelided . gettxn)
where
- gettxn | boolopt "explicit" $ rawopts_ opts = id -- use the fully inferred/explicit txn
- | otherwise = originalTransaction -- use the original txn (more or less)
+ gettxn | useexplicittxn = id -- use the fully inferred/explicit txn
+ | otherwise = originalTransaction -- use the original as-written txn, more or less
+ -- Original vs inferred transactions/postings were causing problems here, disabling -B (#551).
+ -- Use the explicit one if -B or -x are active.
+ -- This passes tests; does it also mean -B sometimes shows missing amounts unnecessarily ?
+ useexplicittxn = or
+ [ boolopt "explicit" $ rawopts_ opts
+ , cost_ $ reportopts_ opts
+ ]
-- Replace this transaction's postings with the original postings if any, but keep the
-- current possibly rewritten account names.
diff --git a/Hledger/Cli/Commands/Tags.hs b/Hledger/Cli/Commands/Tags.hs
index dae289c..665c939 100755
--- a/Hledger/Cli/Commands/Tags.hs
+++ b/Hledger/Cli/Commands/Tags.hs
@@ -9,26 +9,34 @@ where
import Data.List
import Data.String.Here
-import qualified Data.Text.IO as T
+import qualified Data.Text as T
+import Safe
import Hledger
import Hledger.Cli.CliOptions
tagsmode = hledgerCommandMode
[here| tags
-List all the tag names in use.
-With a query, only matched transactions' tags are shown.
+List all the tag names used in the journal. With a TAGREGEX argument,
+only tag names matching the regular expression (case insensitive) are shown.
+With QUERY arguments, only transactions matching the query are considered.
Reads the default journal file, or another specified with -f.
FLAGS
|]
[] -- [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] --
[generalflagsgroup1]
[]
- ([], Just $ argsFlag "[QUERY]")
+ ([], Just $ argsFlag "[TAGREGEX [QUERY...]]")
-tags CliOpts{rawopts_=_rawopts,reportopts_=ropts} j = do
+tags CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do
d <- getCurrentDay
let
- q = queryFromOpts d ropts
- ts = filter (q `matchesTransaction`) $ jtxns $ journalSelectingAmountFromOpts ropts j
- tags = nub $ sort $ map fst $ concatMap transactionAllTags ts
- mapM_ T.putStrLn tags
+ args = listofstringopt "args" rawopts
+ mtagpats = headMay args
+ queryargs = drop 1 args
+ q = queryFromOpts d $ ropts{query_ = unwords queryargs}
+ txns = filter (q `matchesTransaction`) $ jtxns $ journalSelectingAmountFromOpts ropts j
+ tags =
+ nub $ sort $
+ (maybe id (filter . regexMatchesCI) mtagpats) $
+ map (T.unpack . fst) $ concatMap transactionAllTags txns
+ mapM_ putStrLn tags
diff --git a/Hledger/Cli/DocFiles.hs b/Hledger/Cli/DocFiles.hs
index ac3cbc7..05c289a 100644
--- a/Hledger/Cli/DocFiles.hs
+++ b/Hledger/Cli/DocFiles.hs
@@ -35,44 +35,44 @@ type Topic = String
docFiles :: IsString a => [(Topic, (a, a, a))]
docFiles = [
("hledger",
- ($(makeRelativeToProject "doc/hledger.1" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/hledger.1.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/hledger.1.info" >>= embedStringFile)
+ ($(makeRelativeToProject "hledger.1" >>= embedStringFile)
+ ,$(makeRelativeToProject "hledger.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject "hledger.info" >>= embedStringFile)
))
,("hledger-ui",
- ($(makeRelativeToProject "doc/other/hledger-ui.1" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger-ui.1.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger-ui.1.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger-ui.1" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger-ui.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger-ui.info" >>= embedStringFile)
))
,("hledger-web",
- ($(makeRelativeToProject "doc/other/hledger-web.1" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger-web.1.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger-web.1.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger-web.1" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger-web.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger-web.info" >>= embedStringFile)
))
,("hledger-api",
- ($(makeRelativeToProject "doc/other/hledger-api.1" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger-api.1.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger-api.1.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger-api.1" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger-api.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger-api.info" >>= embedStringFile)
))
,("journal",
- ($(makeRelativeToProject "doc/other/hledger_journal.5" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_journal.5.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_journal.5.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger_journal.5" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_journal.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_journal.info" >>= embedStringFile)
))
,("csv",
- ($(makeRelativeToProject "doc/other/hledger_csv.5" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_csv.5.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_csv.5.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger_csv.5" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_csv.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_csv.info" >>= embedStringFile)
))
,("timeclock",
- ($(makeRelativeToProject "doc/other/hledger_timeclock.5" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_timeclock.5.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_timeclock.5.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger_timeclock.5" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_timeclock.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_timeclock.info" >>= embedStringFile)
))
,("timedot",
- ($(makeRelativeToProject "doc/other/hledger_timedot.5" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_timedot.5.txt" >>= embedStringFile)
- ,$(makeRelativeToProject "doc/other/hledger_timedot.5.info" >>= embedStringFile)
+ ($(makeRelativeToProject ".otherdocs/hledger_timedot.5" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_timedot.txt" >>= embedStringFile)
+ ,$(makeRelativeToProject ".otherdocs/hledger_timedot.info" >>= embedStringFile)
))
]
diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs
index 1934b3f..4c1bb61 100644
--- a/Hledger/Cli/Utils.hs
+++ b/Hledger/Cli/Utils.hs
@@ -10,6 +10,9 @@ module Hledger.Cli.Utils
(
withJournalDo,
writeOutput,
+ journalApplyValue,
+ journalAddForecast,
+ generateAutomaticPostings,
journalReload,
journalReloadIfChanged,
journalFileIsNewer,
@@ -31,7 +34,7 @@ import Data.List
import Data.Maybe
import qualified Data.Text as T
import qualified Data.Text.IO as T
-import Data.Time (Day)
+import Data.Time (Day, addDays)
import Data.Word
import Numeric
import Safe (readMay)
@@ -54,6 +57,7 @@ import Hledger.Data
import Hledger.Read
import Hledger.Reports
import Hledger.Utils
+import Hledger.Query (Query(Any))
-- | Parse the user's specified journal file, maybe apply some transformations
@@ -70,6 +74,8 @@ withJournalDo opts cmd = do
. anonymiseByOpts opts
. journalApplyAliases (aliasesFromOpts opts)
<=< journalApplyValue (reportopts_ opts)
+ <=< journalAddForecast opts
+ . generateAutomaticPostings (reportopts_ opts)
either error' f ej
-- | Apply the pivot transformation on a journal, if option is present.
@@ -103,20 +109,53 @@ anonymise j
where
anon = T.pack . flip showHex "" . (fromIntegral :: Int -> Word32) . hash
--- XXX as of since 2017/4 this is used instead of
--- balanceReportValue/multiBalanceReportValue (mostly; not yet hledger-ui)
+-- TODO move journalApplyValue and friends to Hledger.Data.Journal ? They are here because they use ReportOpts
+
-- | If -V/--value was requested, convert all journal amounts to their market value
-- as of the report end date. Cf http://hledger.org/manual.html#market-value
+-- Since 2017/4 we do this early, before commands run, which affects all commands
+-- and seems to have the same effect as doing it last on the reported values.
journalApplyValue :: ReportOpts -> Journal -> IO Journal
journalApplyValue ropts j = do
- mvaluedate <- reportEndDate j ropts
- let convert | value_ ropts
- , Just d <- mvaluedate
- = overJournalAmounts (amountValue j d)
- | otherwise
- = id
+ today <- getCurrentDay
+ mspecifiedenddate <- specifiedEndDate ropts
+ let d = fromMaybe today mspecifiedenddate
+ convert | value_ ropts = overJournalAmounts (amountValue j d)
+ | otherwise = id
return $ convert j
+-- | Run PeriodicTransactions from journal from today or journal end to requested end day.
+-- Add generated transactions to the journal
+journalAddForecast :: CliOpts -> Journal -> IO Journal
+journalAddForecast opts j = do
+ today <- getCurrentDay
+ -- Create forecast starting from end of journal + 1 day, and until the end of requested reporting period
+ -- If end is not provided, do 180 days of forecast.
+ -- Note that jdatespan already returns last day + 1
+ let startDate = fromMaybe today $ spanEnd (jdatespan j)
+ endDate = fromMaybe (addDays 180 today) $ periodEnd (period_ ropts)
+ dates = DateSpan (Just startDate) (Just endDate)
+ withForecast = [makeForecast t | pt <- jperiodictxns j, t <- runPeriodicTransaction pt dates, spanContainsDate dates (tdate t) ] ++ (jtxns j)
+ makeForecast t = txnTieKnot $ t { tdescription = T.pack "Forecast transaction" }
+ ropts = reportopts_ opts
+ if forecast_ ropts
+ then return $ journalBalanceTransactions' opts j { jtxns = withForecast }
+ else return j
+ where
+ journalBalanceTransactions' opts j =
+ let assrt = not . ignore_assertions_ $ inputopts_ opts
+ in
+ either error' id $ journalBalanceTransactions assrt j
+
+-- | Generate Automatic postings and add them to the current journal.
+generateAutomaticPostings :: ReportOpts -> Journal -> Journal
+generateAutomaticPostings ropts j =
+ if auto_ ropts then j { jtxns = map modifier $ jtxns j } else j
+ where
+ modifier = foldr (flip (.) . runModifierTransaction') id mtxns
+ runModifierTransaction' = fmap txnTieKnot . runModifierTransaction Any
+ mtxns = jmodifiertxns j
+
-- | Write some output to stdout or to a file selected by --output-file.
-- If the file exists it will be overwritten.
writeOutput :: CliOpts -> String -> IO ()
diff --git a/README.md b/README.md
index eab04ce..cadcd92 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ For some, it is a simpler, less distracting, more future-proof alternative to Qu
For more, see http://hledger.org.
-##Support
+## Support
### Backers
Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/hledger#backer)]
diff --git a/doc/hledger.1 b/hledger.1
index 2b130ce..b7e6fea 100644
--- a/doc/hledger.1
+++ b/hledger.1
@@ -1,6 +1,6 @@
.\"t
-.TH "hledger" "1" "September 2017" "hledger 1.4" "hledger User Manuals"
+.TH "hledger" "1" "December 2017" "hledger 1.5" "hledger User Manuals"
@@ -246,8 +246,8 @@ multiperiod/multicolumn report by year
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
-set start date, end date, and/or reporting interval all at once
-(overrides the flags above)
+set start date, end date, and/or reporting interval all at once using
+period expressions syntax (overrides the flags above)
.RS
.RE
.TP
@@ -297,6 +297,17 @@ convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
+.TP
+.B \f[C]\-\-auto\f[]
+apply automated posting rules to modify transactions.
+.RS
+.RE
+.TP
+.B \f[C]\-\-forecast\f[]
+apply periodic transaction rules to generate future transactions, to 6
+months from now or report end date.
+.RS
+.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@@ -319,12 +330,14 @@ Or, you can run the addon executable directly:
.PP
Most hledger commands accept arguments after the command name, which are
often a query, filtering the data in some way.
-.SS Argument expansion
+.SS Argument files
.PP
You can save a set of command line options/arguments in a file, one per
-line, and then reuse them by writing \f[C]\@FILE\f[] in a command line.
-(To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with
-a \f[C]\-\-\f[] argument.)
+line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command
+line.
+To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a
+\f[C]\-\-\f[] argument.
+For more, see Save frequently used options.
.SS Special characters
.PP
Option and argument values which contain problematic characters should
@@ -364,7 +377,7 @@ enclose problematic args in single quotes
.IP \[bu] 2
if needed, also add a backslash to escape regexp metacharacters
.PP
-If you\[aq]re really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot.
+If you're really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot.
.SS Input files
.PP
hledger reads transactions from a data file (and the add command writes
@@ -397,14 +410,15 @@ $\ cat\ some.journal\ |\ hledger\ \-f\-
\f[]
.fi
.PP
-Usually the data file is in hledger\[aq]s journal format, but it can
-also be one of several other formats, listed below.
+Usually the data file is in hledger's journal format, but it can also be
+one of several other formats, listed below.
hledger detects the format automatically based on the file extension, or
-if that is not recognised, by trying each built\-in "reader" in turn:
+if that is not recognised, by trying each built\-in \[lq]reader\[rq] in
+turn:
.PP
.TS
tab(@);
-lw(10.7n) lw(33.2n) lw(26.1n).
+lw(10.3n) lw(33.5n) lw(26.2n).
T{
Reader:
T}@T{
@@ -416,7 +430,7 @@ _
T{
\f[C]journal\f[]
T}@T{
-hledger\[aq]s journal format, also some Ledger journals
+hledger's journal format, also some Ledger journals
T}@T{
\f[C]\&.journal\f[] \f[C]\&.j\f[] \f[C]\&.hledger\f[] \f[C]\&.ledger\f[]
T}
@@ -444,8 +458,8 @@ T}
.TE
.PP
If needed (eg to ensure correct error messages when a file has the
-"wrong" extension), you can force a specific reader/format by prepending
-it to the file path with a colon.
+\[lq]wrong\[rq] extension), you can force a specific reader/format by
+prepending it to the file path with a colon.
Examples:
.IP
.nf
@@ -467,11 +481,10 @@ 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[].
.SS Smart dates
.PP
-hledger\[aq]s user interfaces accept a flexible "smart date" syntax
+hledger's user interfaces accept a flexible \[lq]smart date\[rq] syntax
(unlike dates in the journal file).
-Smart dates allow some english words, can be relative to today\[aq]s
-date, and can have less\-significant date parts omitted (defaulting to
-1).
+Smart dates allow some english words, can be relative to today's date,
+and can have less\-significant date parts omitted (defaulting to 1).
.PP
Examples:
.PP
@@ -549,8 +562,7 @@ l l.
T{
\f[C]\-b\ 2016/3/17\f[]
T}@T{
-begin on St.
-Patrick\[aq]s day 2016
+begin on St.\ Patrick's day 2016
T}
T{
\f[C]\-e\ 12/1\f[]
@@ -601,16 +613,15 @@ The \f[C]\-p/\-\-period\f[] option accepts period expressions, a
shorthand way of expressing a start date, end date, and/or report
interval all at once.
.PP
-Here\[aq]s a basic period expression specifying the first quarter of
-2009.
+Here's a basic period expression specifying the first quarter of 2009.
Note, hledger always treats start dates as inclusive and end dates as
exclusive:
.PP
\f[C]\-p\ "from\ 2009/1/1\ to\ 2009/4/1"\f[]
.PP
-Keywords like "from" and "to" are optional, and so are the spaces, as
-long as you don\[aq]t run two dates together.
-"to" can also be written as "\-".
+Keywords like \[lq]from\[rq] and \[lq]to\[rq] are optional, and so are
+the spaces, as long as you don't run two dates together.
+\[lq]to\[rq] can also be written as \[lq]\-\[rq].
These are equivalent to the above:
.PP
.TS
@@ -672,8 +683,8 @@ everything before january 1, 2009
T}
.TE
.PP
-A single date with no "from" or "to" defines both the start and end date
-like so:
+A single date with no \[lq]from\[rq] or \[lq]to\[rq] defines both the
+start and end date like so:
.PP
.TS
tab(@);
@@ -681,17 +692,17 @@ l l.
T{
\f[C]\-p\ "2009"\f[]
T}@T{
-the year 2009; equivalent to "2009/1/1 to 2010/1/1"
+the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq]
T}
T{
\f[C]\-p\ "2009/1"\f[]
T}@T{
-the month of jan; equivalent to "2009/1/1 to 2009/2/1"
+the month of jan; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq]
T}
T{
\f[C]\-p\ "2009/1/1"\f[]
T}@T{
-just that day; equivalent to "2009/1/1 to 2009/1/2"
+just that day; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq]
T}
.TE
.PP
@@ -719,11 +730,70 @@ T{
T}
.TE
.PP
+Note that \f[C]weekly\f[], \f[C]monthly\f[], \f[C]quarterly\f[] and
+\f[C]yearly\f[] intervals will always start on the first day on week,
+month, quarter or year accordingly, and will end on the last day of same
+period, even if associated period expression specifies different
+explicit start and end date.
+.PP
+For example:
+.PP
+.TS
+tab(@);
+l.
+T{
+\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] \[en] starts on
+2008/12/29, closest preceeding Monday
+T}
+T{
+\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \[en] starts on 2018/11/01
+T}
+T{
+\f[C]\-p\ "quarterly\ from\ 2009\-05\-05\ to\ 2009\-06\-01"\f[] \-
+starts on 2009/04/01, ends on 2009/06/30, which are first and last days
+of Q2 2009
+T}
+T{
+\f[C]\-p\ "yearly\ from\ 2009\-12\-29"\f[] \- starts on 2009/01/01,
+first day of 2009
+T}
+.TE
+.PP
The following more complex report intervals are also supported:
\f[C]biweekly\f[], \f[C]bimonthly\f[],
-\f[C]every\ N\ days|weeks|months|quarters|years\f[],
+\f[C]every\ day|week|month|quarter|year\f[],
+\f[C]every\ N\ days|weeks|months|quarters|years\f[].
+.PP
+All of these will start on the first day of the requested period and end
+on the last one, as described above.
+.PP
+Examples:
+.PP
+.TS
+tab(@);
+l.
+T{
+\f[C]\-p\ "bimonthly\ from\ 2008"\f[] \[en] periods will have boundaries
+on 2008/01/01, 2008/03/01, \&...
+T}
+T{
+\f[C]\-p\ "every\ 2\ weeks"\f[] \[en] starts on closest preceeding
+Monday
+T}
+T{
+\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \[en] periods will have
+boundaries on 2009/03/01, 2009/08/01, \&...
+T}
+.TE
+.PP
+If you want intervals that start on arbitrary day of your choosing and
+span a week, month or year, you need to use any of the following:
+.PP
+\f[C]every\ Nth\ day\ of\ week\f[], \f[C]every\ <weekday>\f[],
\f[C]every\ Nth\ day\ [of\ month]\f[],
-\f[C]every\ Nth\ day\ of\ week\f[].
+\f[C]every\ Nth\ weekday\ [of\ month]\f[],
+\f[C]every\ MM/DD\ [of\ year]\f[], \f[C]every\ Nth\ MMM\ [of\ year]\f[],
+\f[C]every\ MMM\ Nth\ [of\ year]\f[].
.PP
Examples:
.PP
@@ -731,13 +801,29 @@ Examples:
tab(@);
l.
T{
-\f[C]\-p\ "bimonthly\ from\ 2008"\f[]
+\f[C]\-p\ "every\ 2nd\ day\ of\ week"\f[] \[en] periods will go from Tue
+to Tue
+T}
+T{
+\f[C]\-p\ "every\ Tue"\f[] \[en] same
+T}
+T{
+\f[C]\-p\ "every\ 15th\ day"\f[] \[en] period boundaries will be on 15th
+of each month
+T}
+T{
+\f[C]\-p\ "every\ 2nd\ Monday"\f[] \[en] period boundaries will be on
+second Monday of each month
+T}
+T{
+\f[C]\-p\ "every\ 11/05"\f[] \[en] yearly periods with boundaries on 5th
+of Nov
T}
T{
-\f[C]\-p\ "every\ 2\ weeks"\f[]
+\f[C]\-p\ "every\ 5th\ Nov"\f[] \[en] same
T}
T{
-\f[C]\-p\ "every\ 5\ days\ from\ 1/3"\f[]
+\f[C]\-p\ "every\ Nov\ 5th"\f[] \[en] same
T}
.TE
.PP
@@ -772,9 +858,9 @@ will be displayed hierarchically in reports.
.PP
\f[C]\-\-pivot\f[] is a general option affecting all reports; you can
think of hledger transforming the journal before any other processing,
-replacing every posting\[aq]s account name with the value of the
-specified field on that posting, inheriting it from the transaction or
-using a blank value if it\[aq]s not present.
+replacing every posting's account name with the value of the specified
+field on that posting, inheriting it from the transaction or using a
+blank value if it's not present.
.PP
An example:
.IP
@@ -822,8 +908,8 @@ $\ hledger\ balance\ \-\-pivot\ member\ tag:member=.
\f[]
.fi
.PP
-Another way (the acct: query matches against the pivoted "account
-name"):
+Another way (the acct: query matches against the pivoted \[lq]account
+name\[rq]):
.IP
.nf
\f[C]
@@ -839,15 +925,15 @@ The \f[C]\-B/\-\-cost\f[] flag converts amounts to their cost at
transaction time, if they have a transaction price specified.
.SS Market value
.PP
-The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their
-market value on the report end date, using the most recent applicable
-market prices, when known.
+The \f[C]\-V/\-\-value\f[] flag converts reported amounts to their
+current market value.
Specifically, when there is a market price (P directive) for the
-amount\[aq]s commodity, dated on or before the report end date (see
-hledger \-> Report start & end date), the amount will be converted to
-the price\[aq]s commodity.
-If multiple applicable prices are defined, the latest\-dated one is used
-(and if dates are equal, the one last parsed).
+amount's commodity, dated on or before today's date (or the report end
+date if specified), the amount will be converted to the price's
+commodity.
+.PP
+When there are multiple applicable P directives, \-V chooses the most
+recent one, or in case of equal dates, the last\-parsed one.
.PP
For example:
.IP
@@ -894,10 +980,13 @@ $\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21
\f[]
.fi
.PP
-Currently, hledger\[aq]s \-V only uses market prices recorded with P
+Currently, hledger's \-V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
+.SS Combining \-B and \-V
.PP
-Using \-B and \-V together is allowed.
+Using \-B/\[en]cost and \-V/\[en]value together is currently allowed,
+but the results are probably not meaningful.
+Let us know if you find a use for this.
.SS Regular expressions
.PP
hledger uses regular expressions in a number of places:
@@ -912,7 +1001,7 @@ account alias directives and options:
\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[],
\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[]
.PP
-hledger\[aq]s regular expressions come from the regex\-tdfa library.
+hledger's regular expressions come from the regex\-tdfa library.
In general they:
.IP \[bu] 2
are case insensitive
@@ -944,8 +1033,8 @@ meaning to the shell and so must be escaped at least once more.
See Special characters.
.SH QUERIES
.PP
-One of hledger\[aq]s strengths is being able to quickly report on
-precise subsets of your data.
+One of hledger's strengths is being able to quickly report on precise
+subsets of your data.
Most commands accept an optional query expression, written as arguments
after the command name, to filter the data by date, account name or
other criteria.
@@ -976,21 +1065,21 @@ have no postings matching any of the negative account terms AND
match all the other terms.
.PP
The following kinds of search terms can be used.
-Remember these can also be prefixed with \f[B]\f[C]not:\f[]\f[], eg to
+Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to
exclude a particular subaccount.
.TP
-.B \f[B]\f[C]REGEX\f[]\f[]
+.B \f[B]\f[BC]REGEX\f[B]\f[]
match account names by this regular expression.
(No prefix is equivalent to \f[C]acct:\f[]).
.RS
.RE
.TP
-.B \f[B]\f[C]acct:REGEX\f[]\f[]
+.B \f[B]\f[BC]acct:REGEX\f[B]\f[]
same as above
.RS
.RE
.TP
-.B \f[B]\f[C]amt:N,\ amt:<N,\ amt:<=N,\ amt:>N,\ amt:>=N\f[]\f[]
+.B \f[B]\f[BC]amt:N,\ amt:<N,\ amt:<=N,\ amt:>N,\ amt:>=N\f[B]\f[]
match postings with a single\-commodity amount that is equal to, less
than, or greater than N.
(Multi\-commodity amounts are not tested, and will always match.) The
@@ -1000,12 +1089,12 @@ Otherwise, the absolute magnitudes are compared, ignoring sign.
.RS
.RE
.TP
-.B \f[B]\f[C]code:REGEX\f[]\f[]
+.B \f[B]\f[BC]code:REGEX\f[B]\f[]
match by transaction code (eg check number)
.RS
.RE
.TP
-.B \f[B]\f[C]cur:REGEX\f[]\f[]
+.B \f[B]\f[BC]cur:REGEX\f[B]\f[]
match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX.
(For a partial match, use \f[C]\&.*REGEX.*\f[]).
@@ -1018,12 +1107,12 @@ quoting to hide it from the shell, so eg do:
.RS
.RE
.TP
-.B \f[B]\f[C]desc:REGEX\f[]\f[]
+.B \f[B]\f[BC]desc:REGEX\f[B]\f[]
match transaction descriptions.
.RS
.RE
.TP
-.B \f[B]\f[C]date:PERIODEXPR\f[]\f[]
+.B \f[B]\f[BC]date:PERIODEXPR\f[B]\f[]
match dates within the specified period.
PERIODEXPR is a period expression (with no report interval).
Examples: \f[C]date:2016\f[], \f[C]date:thismonth\f[],
@@ -1033,39 +1122,39 @@ secondary dates instead.
.RS
.RE
.TP
-.B \f[B]\f[C]date2:PERIODEXPR\f[]\f[]
+.B \f[B]\f[BC]date2:PERIODEXPR\f[B]\f[]
match secondary dates within the specified period.
.RS
.RE
.TP
-.B \f[B]\f[C]depth:N\f[]\f[]
+.B \f[B]\f[BC]depth:N\f[B]\f[]
match (or display, depending on command) accounts at or above this depth
.RS
.RE
.TP
-.B \f[B]\f[C]note:REGEX\f[]\f[]
+.B \f[B]\f[BC]note:REGEX\f[B]\f[]
match transaction notes (part of description right of \f[C]|\f[], or
-whole description when there\[aq]s no \f[C]|\f[])
+whole description when there's no \f[C]|\f[])
.RS
.RE
.TP
-.B \f[B]\f[C]payee:REGEX\f[]\f[]
+.B \f[B]\f[BC]payee:REGEX\f[B]\f[]
match transaction payee/payer names (part of description left of
-\f[C]|\f[], or whole description when there\[aq]s no \f[C]|\f[])
+\f[C]|\f[], or whole description when there's no \f[C]|\f[])
.RS
.RE
.TP
-.B \f[B]\f[C]real:,\ real:0\f[]\f[]
+.B \f[B]\f[BC]real:,\ real:0\f[B]\f[]
match real or virtual postings respectively
.RS
.RE
.TP
-.B \f[B]\f[C]status:,\ status:!,\ status:*\f[]\f[]
+.B \f[B]\f[BC]status:,\ status:!,\ status:*\f[B]\f[]
match unmarked, pending, or cleared transactions respectively
.RS
.RE
.TP
-.B \f[B]\f[C]tag:REGEX[=REGEX]\f[]\f[]
+.B \f[B]\f[BC]tag:REGEX[=REGEX]\f[B]\f[]
match by tag name, and optionally also by tag value.
Note a tag: query is considered to match a transaction if it matches any
of the postings.
@@ -1077,7 +1166,7 @@ transaction.
The following special search term is used automatically in hledger\-web,
only:
.TP
-.B \f[B]\f[C]inacct:ACCTNAME\f[]\f[]
+.B \f[B]\f[BC]inacct:ACCTNAME\f[B]\f[]
tells hledger\-web to show the transaction register for this account.
Can be filtered further with \f[C]acct\f[] etc.
.RS
@@ -1208,7 +1297,7 @@ $\ hledger\ activity\ \-\-quarterly
Prompt for transactions and add them to the journal.
.TP
.B \f[C]\-\-no\-new\-accounts\f[]
-don\[aq]t allow creating new accounts; helps prevent typos when entering
+don't allow creating new accounts; helps prevent typos when entering
account names
.RS
.RE
@@ -1327,7 +1416,7 @@ show a row total column (in multicolumn mode)
.RE
.TP
.B \f[C]\-N\ \-\-no\-total\f[]
-don\[aq]t show the final total row
+don't show the final total row
.RS
.RE
.TP
@@ -1337,7 +1426,7 @@ omit N leading account name parts (in flat mode)
.RE
.TP
.B \f[C]\-\-no\-elide\f[]
-don\[aq]t squash boring parent accounts (in tree mode)
+don't squash boring parent accounts (in tree mode)
.RS
.RE
.TP
@@ -1359,18 +1448,30 @@ A file extension matching one of the above formats selects that format.
.RE
.TP
.B \f[C]\-\-pretty\-tables\f[]
-Use unicode to display prettier tables.
+use unicode to display prettier tables.
.RS
.RE
.TP
.B \f[C]\-\-sort\-amount\f[]
-Sort by amount (total row amount, or by average if that is displayed),
-instead of account name (in flat mode)
+sort by amount instead of account name (in flat mode).
+With multiple columns, sorts by the row total, or by row average if that
+is displayed.
+.RS
+.RE
+.TP
+.B \f[C]\-\-budget\f[]
+show performance compared to budget goals defined by periodic
+transactions
+.RS
+.RE
+.TP
+.B \f[C]\-\-show\-unbudgeted\f[]
+with \[en]budget, show unbudgeted accounts also
.RS
.RE
.PP
The balance command displays accounts and balances.
-It is hledger\[aq]s most featureful and versatile command.
+It is hledger's most featureful and versatile command.
.IP
.nf
\f[C]
@@ -1391,21 +1492,21 @@ $\ hledger\ balance
.fi
.PP
More precisely, the balance command shows the \f[I]change\f[] to each
-account\[aq]s balance caused by all (matched) postings.
+account's balance caused by all (matched) postings.
In the common case where you do not filter by date and your journal sets
-the correct opening balances, this is the same as the account\[aq]s
-ending balance.
+the correct opening balances, this is the same as the account's ending
+balance.
.PP
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent.
-"Boring" accounts, which contain a single interesting subaccount and no
-balance of their own, are elided into the following line for more
+\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
+and no balance of their own, are elided into the following line for more
compact output.
(Use \f[C]\-\-no\-elide\f[] to prevent this.
Eliding of boring accounts is not yet supported in multicolumn reports.)
.PP
-Each account\[aq]s balance is the "inclusive" balance \- it includes the
-balances of any subaccounts.
+Each account's balance is the \[lq]inclusive\[rq] balance \- it includes
+the balances of any subaccounts.
.PP
Accounts which have zero balance (and no non\-zero subaccounts) are
omitted.
@@ -1426,8 +1527,8 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
.PP
To see a flat list of full account names instead of the default
hierarchical display, use \f[C]\-\-flat\f[].
-In this mode, accounts (unless depth\-clipped) show their "exclusive"
-balance, excluding any subaccount balances.
+In this mode, accounts (unless depth\-clipped) show their
+\[lq]exclusive\[rq] balance, excluding any subaccount balances.
In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first
few account name components.
.IP
@@ -1463,7 +1564,7 @@ There are three types of multi\-column balance report, showing different
information:
.IP "1." 3
By default: each column shows the sum of postings in that period, ie the
-account\[aq]s change of balance in that period.
+account's change of balance in that period.
This is useful eg for a monthly income statement:
.RS 4
.IP
@@ -1537,8 +1638,8 @@ to see the hierarchy, use \f[C]\-\-tree\f[].
With a reporting interval (like \f[C]\-\-quarterly\f[] above), the
report start/end dates will be adjusted if necessary so that they
encompass the displayed report periods.
-This is so that the first and last periods will be "full" and comparable
-to the others.
+This is so that the first and last periods will be \[lq]full\[rq] and
+comparable to the others.
.PP
The \f[C]\-E/\-\-empty\f[] flag does two things in multicolumn balance
reports: first, the report will show all columns within the specified
@@ -1555,7 +1656,7 @@ the total for each row.
The \f[C]\-A/\-\-average\f[] flag adds a column showing the average
value in each row.
.PP
-Here\[aq]s an example of all three:
+Here's an example of all three:
.IP
.nf
\f[C]
@@ -1576,6 +1677,110 @@ Balance\ changes\ in\ 2008:
#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
\f[]
.fi
+.SS Budgets
+.PP
+With \f[C]\-\-budget\f[] and a report interval, all periodic
+transactions in your journal with that interval, active during the
+requested report period, are interpreted as recurring budget goals for
+the specified accounts (and subaccounts), and the report will show the
+difference between actual and budgeted balances.
+.PP
+For example, you can take average monthly expenses in the common expense
+categories to construct a minimal monthly budget:
+.IP
+.nf
+\f[C]
+;;\ Budget
+~\ monthly
+\ \ income\ \ $2000
+\ \ expenses:food\ \ \ \ $400
+\ \ expenses:bus\ \ \ \ \ $50
+\ \ expenses:movies\ \ $30
+\ \ assets:bank:checking
+
+;;\ Two\ months\ worth\ of\ expenses
+2017\-11\-01
+\ \ income\ \ $1950
+\ \ expenses:food\ \ \ \ $396
+\ \ expenses:bus\ \ \ \ \ $49
+\ \ expenses:movies\ \ $30
+\ \ expenses:supplies\ \ $20
+\ \ assets:bank:checking
+
+2017\-12\-01
+\ \ income\ \ $2100
+\ \ expenses:food\ \ \ \ $412
+\ \ expenses:bus\ \ \ \ \ $53
+\ \ expenses:gifts\ \ \ $100
+\ \ assets:bank:checking
+\f[]
+.fi
+.PP
+You can now see a monthly budget performance report:
+.IP
+.nf
+\f[C]
+$\ hledger\ balance\ \-M\ \-\-budget
+Balance\ changes\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
+=======================++=================================================
+\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
+\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
+\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
+\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
+\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
+\f[]
+.fi
+.PP
+You can roll over unspent budgets to next period with
+\f[C]\-\-cumulative\f[]:
+.IP
+.nf
+\f[C]
+$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
+Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
+=======================++=================================================
+\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
+\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
+\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
+\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
+\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
+\f[]
+.fi
+.PP
+Accounts with no budget goals (not mentioned in the periodic
+transactions) will be aggregated under \f[C]<unbudgeted>\f[], unless you
+add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally:
+.IP
+.nf
+\f[C]
+$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted
+Balance\ changes\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
+======================++=================================================
+\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
+\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
+\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
+\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
+\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
+\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
+\f[]
+.fi
+.PP
+For more examples and details, see Budgeting and Forecasting.
.SS Custom balance output
.PP
In simple (non\-multi\-column) balance reports, you can customise the
@@ -1612,13 +1817,12 @@ MAX truncates at this width (optional)
FIELDNAME must be enclosed in parentheses, and can be one of:
.RS 2
.IP \[bu] 2
-\f[C]depth_spacer\f[] \- a number of spaces equal to the account\[aq]s
+\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
depth, or if MIN is specified, MIN * depth spaces.
.IP \[bu] 2
-\f[C]account\f[] \- the account\[aq]s name
+\f[C]account\f[] \- the account's name
.IP \[bu] 2
-\f[C]total\f[] \- the account\[aq]s balance/posted total, right
-justified
+\f[C]total\f[] \- the account's balance/posted total, right justified
.RE
.PP
Also, FMT can begin with an optional prefix to control how
@@ -1637,10 +1841,10 @@ Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
.PP
Some example formats:
.IP \[bu] 2
-\f[C]%(total)\f[] \- the account\[aq]s total
+\f[C]%(total)\f[] \- the account's total
.IP \[bu] 2
-\f[C]%\-20.20(account)\f[] \- the account\[aq]s name, left justified,
-padded to 20 characters and clipped at 20 characters
+\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
+to 20 characters and clipped at 20 characters
.IP \[bu] 2
\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
characters, total padded to 20 characters, with multiple commodities
@@ -1728,7 +1932,7 @@ show a row total column (in multicolumn mode)
.RE
.TP
.B \f[C]\-N\ \-\-no\-total\f[]
-don\[aq]t show the final total row
+don't show the final total row
.RS
.RE
.TP
@@ -1738,7 +1942,7 @@ omit N leading account name parts (in flat mode)
.RE
.TP
.B \f[C]\-\-no\-elide\f[]
-don\[aq]t squash boring parent accounts (in tree mode)
+don't squash boring parent accounts (in tree mode)
.RS
.RE
.TP
@@ -1872,7 +2076,7 @@ show a row total column (in multicolumn mode)
.RE
.TP
.B \f[C]\-N\ \-\-no\-total\f[]
-don\[aq]t show the final total row (in simple reports)
+don't show the final total row (in simple reports)
.RS
.RE
.TP
@@ -1882,7 +2086,7 @@ omit N leading account name parts (in flat mode)
.RE
.TP
.B \f[C]\-\-no\-elide\f[]
-don\[aq]t squash boring parent accounts (in tree mode)
+don't squash boring parent accounts (in tree mode)
.RS
.RE
.TP
@@ -1897,7 +2101,7 @@ sort by amount instead of account name
.RE
.PP
This command displays a simple cashflow statement It shows the change in
-all "cash" (ie, liquid assets) accounts for the period.
+all \[lq]cash\[rq] (ie, liquid assets) accounts for the period.
It currently assumes that cash accounts are under a top\-level account
named \f[C]asset\f[] and do not contain \f[C]receivable\f[],
\f[C]:A/R\f[] or \f[C]:fixed\f[].
@@ -1928,7 +2132,7 @@ multicolumn balance reports you can alter the report mode with
.SS check\-dates
.PP
Check that transactions are sorted by increasing date.
-With a query, only matched transactions\[aq] dates are checked.
+With a query, only matched transactions' dates are checked.
.SS check\-dupes
.PP
Report account names having the same leaf but different prefixes.
@@ -1990,12 +2194,23 @@ just show the transactions to be imported
.RS
.RE
.PP
-Input files are provided as arguments, or glob patterns.
-So eg to add new transactions from all CSV files to the main journal:
-hledger import *.csv
+The input files are specified as arguments \- no need to write \-f
+before each one.
+So eg to add new transactions from all CSV files to the main journal,
+it's just: \f[C]hledger\ import\ *.csv\f[]
+.PP
+New transactions are detected in the same way as print \[en]new: by
+assuming transactions are always added to the input files in increasing
+date order, and by saving \f[C]\&.latest.FILE\f[] state files.
.PP
-New transactions are detected like print \-\-new (using .latest.FILE
-state files).
+The \[en]dry\-run output is in journal format, so you can filter it, eg
+to see only uncategorised transactions:
+.IP
+.nf
+\f[C]
+$\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\-assertions
+\f[]
+.fi
.SS incomestatement
.PP
Show an income statement.
@@ -2041,7 +2256,7 @@ show a row total column (in multicolumn mode)
.RE
.TP
.B \f[C]\-N\ \-\-no\-total\f[]
-don\[aq]t show the final total row
+don't show the final total row
.RS
.RE
.TP
@@ -2051,7 +2266,7 @@ omit N leading account name parts (in flat mode)
.RE
.TP
.B \f[C]\-\-no\-elide\f[]
-don\[aq]t squash boring parent accounts (in tree mode)
+don't squash boring parent accounts (in tree mode)
.RS
.RE
.TP
@@ -2164,11 +2379,11 @@ $\ hledger\ print
.PP
The print command displays full journal entries (transactions) from the
journal file in date order, tidily formatted.
-print\[aq]s output is always a valid hledger journal.
+print's output is always a valid hledger journal.
It preserves all transaction information, but it does not preserve
directives or inter\-transaction comments
.PP
-Normally, the journal entry\[aq]s explicit or implicit amount style is
+Normally, the journal entry's explicit or implicit amount style is
preserved.
Ie when an amount is omitted in the journal, it will be omitted in the
output.
@@ -2182,6 +2397,7 @@ valid journal output.
.PP
With \f[C]\-B\f[]/\f[C]\-\-cost\f[], amounts with transaction prices are
converted to cost using that price.
+This can be used for troubleshooting.
.PP
With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show
at most one transaction: the one one whose description is most similar
@@ -2212,7 +2428,7 @@ reordered.
See also the import command.
.PP
The print command also supports output destination and CSV output.
-Here\[aq]s an example of print\[aq]s CSV output:
+Here's an example of print's CSV output:
.IP
.nf
\f[C]
@@ -2232,19 +2448,19 @@ $\ hledger\ print\ \-Ocsv
\f[]
.fi
.IP \[bu] 2
-There is one CSV record per posting, with the parent transaction\[aq]s
+There is one CSV record per posting, with the parent transaction's
fields repeated.
.IP \[bu] 2
-The "txnidx" (transaction index) field shows which postings belong to
-the same transaction.
+The \[lq]txnidx\[rq] (transaction index) field shows which postings
+belong to the same transaction.
(This number might change if transactions are reordered within the file,
files are parsed/included in a different order, etc.)
.IP \[bu] 2
-The amount is separated into "commodity" (the symbol) and "amount"
-(numeric quantity) fields.
+The amount is separated into \[lq]commodity\[rq] (the symbol) and
+\[lq]amount\[rq] (numeric quantity) fields.
.IP \[bu] 2
-The numeric amount is repeated in either the "credit" or "debit" column,
-for convenience.
+The numeric amount is repeated in either the \[lq]credit\[rq] or
+\[lq]debit\[rq] column, for convenience.
(Those names are not accurate in the accounting sense; it just puts
negative amounts under credit and zero or greater amounts under debit.)
.SS print\-unique
@@ -2268,12 +2484,12 @@ start date)
.TP
.B \f[C]\-A\ \-\-average\f[]
show running average of posting amounts instead of total (implies
-\-\-empty)
+\[en]empty)
.RS
.RE
.TP
.B \f[C]\-r\ \-\-related\f[]
-show postings\[aq] siblings instead
+show postings' siblings instead
.RS
.RE
.TP
@@ -2298,7 +2514,7 @@ A file extension matching one of the above formats selects that format.
The register command displays postings, one per line, and their running
total.
This is typically used with a query selecting a particular account, to
-see that account\[aq]s activity:
+see that account's activity:
.IP
.nf
\f[C]
@@ -2371,7 +2587,7 @@ $\ hledger\ register\ \-\-monthly\ income\ \-E
\f[]
.fi
.PP
-Often, you\[aq]ll want to see just one line per interval.
+Often, you'll want to see just one line per interval.
The \f[C]\-\-depth\f[] option helps with this, causing subaccounts to be
aggregated:
.IP
@@ -2399,8 +2615,8 @@ variable (not a bash shell variable) or by using the
The description and account columns normally share the space equally
(about half of (width \- 40) each).
You can adjust this by adding a description width as part of
-\-\-width\[aq]s argument, comma\-separated: \f[C]\-\-width\ W,D\f[] .
-Here\[aq]s a diagram:
+\[en]width's argument, comma\-separated: \f[C]\-\-width\ W,D\f[] .
+Here's a diagram:
.IP
.nf
\f[C]
@@ -2468,7 +2684,11 @@ The stats command also supports \f[C]\-o/\-\-output\-file\f[] for
controlling output destination.
.SS tags
.PP
-List all the tag names in use.
+List all the tag names used in the journal.
+With a TAGREGEX argument, only tag names matching the regular expression
+(case insensitive) are shown.
+With additional QUERY arguments, only transactions matching the query
+are considered.
.SS test
.PP
Run built\-in unit tests.
@@ -2480,12 +2700,12 @@ Cases:\ 74\ \ Tried:\ 74\ \ Errors:\ 0\ \ Failures:\ 0
\f[]
.fi
.PP
-This command runs hledger\[aq]s built\-in unit tests and displays a
-quick report.
+This command runs hledger's built\-in unit tests and displays a quick
+report.
With a regular expression argument, it selects only tests with matching
names.
-It\[aq]s mainly used in development, but it\[aq]s also nice to be able
-to check your hledger executable for smoke at any time.
+It's mainly used in development, but it's also nice to be able to check
+your hledger executable for smoke at any time.
.SH ADD\-ON COMMANDS
.PP
hledger also searches for external add\-on commands, and will include
@@ -2499,8 +2719,8 @@ Add\-ons can be invoked like any hledger command, but there are a few
things to be aware of.
Eg if the \f[C]hledger\-web\f[] add\-on is installed,
.IP \[bu] 2
-\f[C]hledger\ \-h\ web\f[] shows hledger\[aq]s help, while
-\f[C]hledger\ web\ \-h\f[] shows hledger\-web\[aq]s help.
+\f[C]hledger\ \-h\ web\f[] shows hledger's help, while
+\f[C]hledger\ web\ \-h\f[] shows hledger\-web's help.
.IP \[bu] 2
Flags specific to the add\-on must have a preceding \f[C]\-\-\f[] to
hide them from hledger.
@@ -2536,8 +2756,8 @@ These are maintained separately, and usually updated shortly after a
hledger release.
.SS diff
.PP
-hledger\-diff shows differences in an account\[aq]s transactions between
-one journal file and another.
+hledger\-diff shows differences in an account's transactions between one
+journal file and another.
.SS iadd
.PP
hledger\-iadd is a curses\-style, more interactive replacement for the
@@ -2552,8 +2772,8 @@ hledger\-irr calculates the internal rate of return of an investment
account.
.SS Experimental add\-ons
.PP
-These are available in source form in the hledger repo\[aq]s bin/
-directory; installing them is pretty easy.
+These are available in source form in the hledger repo's bin/ directory;
+installing them is pretty easy.
They may be less mature and documented than built\-in commands.
Reading and tweaking these is a good way to start making your own!
.SS autosync
@@ -2602,7 +2822,7 @@ not supported.
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
.PP
-Not all of Ledger\[aq]s journal file syntax is supported.
+Not all of Ledger's journal file syntax is supported.
See file format differences.
.PP
On large data files, hledger is slower and uses more memory than Ledger.
@@ -2612,8 +2832,8 @@ Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
tracker):
.PP
-\f[B]Successfully installed, but "No command \[aq]hledger\[aq]
-found"\f[]
+\f[B]Successfully installed, but \[lq]No command `hledger'
+found\[rq]\f[]
.PD 0
.P
.PD
@@ -2631,10 +2851,10 @@ file\f[]
shell variable.
The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it.
You may need to use \f[C]export\f[].
-Here\[aq]s an explanation.
+Here's an explanation.
.PP
-\f[B]"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
-character" errors\f[]
+\f[B]\[lq]Illegal byte sequence\[rq] or \[lq]Invalid or incomplete
+multibyte or wide character\[rq] errors\f[]
.PD 0
.P
.PD
@@ -2643,9 +2863,9 @@ needs an appropriate locale.
This is usually configured system\-wide; you can also configure it
temporarily.
The locale may need to be one that supports UTF\-8, if you built hledger
-with GHC < 7.2 (or possibly always, I\[aq]m not sure yet).
+with GHC < 7.2 (or possibly always, I'm not sure yet).
.PP
-Here\[aq]s an example of setting the locale temporarily, on ubuntu
+Here's an example of setting the locale temporarily, on ubuntu
gnu/linux:
.IP
.nf
@@ -2660,8 +2880,7 @@ $\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ t
\f[]
.fi
.PP
-Here\[aq]s one way to set it permanently, there are probably better
-ways:
+Here's one way to set it permanently, there are probably better ways:
.IP
.nf
\f[C]
diff --git a/hledger.cabal b/hledger.cabal
index 7ca141a..f505971 100644
--- a/hledger.cabal
+++ b/hledger.cabal
@@ -1,9 +1,11 @@
--- This file has been generated from package.yaml by hpack version 0.17.1.
+-- This file has been generated from package.yaml by hpack version 0.20.0.
--
-- see: https://github.com/sol/hpack
+--
+-- hash: 8e14dbb3cafd99102e0a85bd39076ca0af4c9554f348cd6cacb0d59faf63623b
name: hledger
-version: 1.4
+version: 1.5
synopsis: Command-line interface for the hledger accounting tool
description: This is hledger's command-line interface.
Its basic function is to read a plain text file describing
@@ -34,30 +36,30 @@ extra-source-files:
test/test.hs
data-files:
- doc/hledger.1
- doc/hledger.1.info
- doc/hledger.1.txt
- doc/other/hledger-api.1
- doc/other/hledger-api.1.info
- doc/other/hledger-api.1.txt
- doc/other/hledger-ui.1
- doc/other/hledger-ui.1.info
- doc/other/hledger-ui.1.txt
- doc/other/hledger-web.1
- doc/other/hledger-web.1.info
- doc/other/hledger-web.1.txt
- doc/other/hledger_csv.5
- doc/other/hledger_csv.5.info
- doc/other/hledger_csv.5.txt
- doc/other/hledger_journal.5
- doc/other/hledger_journal.5.info
- doc/other/hledger_journal.5.txt
- doc/other/hledger_timeclock.5
- doc/other/hledger_timeclock.5.info
- doc/other/hledger_timeclock.5.txt
- doc/other/hledger_timedot.5
- doc/other/hledger_timedot.5.info
- doc/other/hledger_timedot.5.txt
+ .otherdocs/hledger-api.1
+ .otherdocs/hledger-api.info
+ .otherdocs/hledger-api.txt
+ .otherdocs/hledger-ui.1
+ .otherdocs/hledger-ui.info
+ .otherdocs/hledger-ui.txt
+ .otherdocs/hledger-web.1
+ .otherdocs/hledger-web.info
+ .otherdocs/hledger-web.txt
+ .otherdocs/hledger_csv.5
+ .otherdocs/hledger_csv.info
+ .otherdocs/hledger_csv.txt
+ .otherdocs/hledger_journal.5
+ .otherdocs/hledger_journal.info
+ .otherdocs/hledger_journal.txt
+ .otherdocs/hledger_timeclock.5
+ .otherdocs/hledger_timeclock.info
+ .otherdocs/hledger_timeclock.txt
+ .otherdocs/hledger_timedot.5
+ .otherdocs/hledger_timedot.info
+ .otherdocs/hledger_timedot.txt
+ hledger.1
+ hledger.info
+ hledger.txt
source-repository head
type: git
@@ -75,44 +77,45 @@ flag threaded
library
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans
- cpp-options: -DVERSION="1.4"
+ cpp-options: -DVERSION="1.5"
build-depends:
- base >=4.8 && <5
+ Decimal
+ , Diff
+ , HUnit
+ , ansi-terminal >=0.6.2.3
+ , base >=4.8 && <5
, base-compat >=0.8.1
- , ansi-terminal >= 0.6.2.3 && < 0.8
- , directory
- , file-embed >=0.0.10 && <0.1
- , filepath
- , here
- , pretty-show >=1.6.4
- , process
- , shakespeare >=2.0.2.2 && <2.1
- , temporary
- , tabular >=0.2 && <0.3
- , time >=1.5
- , utility-ht >= 0.0.13
- , hledger-lib >= 1.4 && < 1.5
, bytestring
+ , cmdargs >=0.10
, containers
- , unordered-containers
- , cmdargs >=0.10 && <0.11
, csv
, data-default >=0.5
- , Diff
+ , directory
+ , file-embed >=0.0.10
+ , filepath
, hashable >=1.2.4
- , haskeline >=0.6 && <=0.8
- , HUnit
+ , haskeline >=0.6
+ , here
+ , hledger-lib >=1.5 && <1.6
+ , megaparsec >=5.0
, mtl
, mtl-compat
, old-time
- , megaparsec >=5.0 && < 6.2
+ , pretty-show >=1.6.4
+ , process
, regex-tdfa
, safe >=0.2
- , split >=0.1 && <0.3
- , transformers
+ , shakespeare >=2.0.2.2
+ , split >=0.1
+ , tabular >=0.2
+ , temporary
, text >=0.11
- , utf8-string >=0.3.5 && <1.1
- , wizards ==1.0.*
+ , time >=1.5
+ , transformers
+ , unordered-containers
+ , utf8-string >=0.3.5
+ , utility-ht >=0.0.13
+ , wizards >=1.0
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
@@ -156,47 +159,50 @@ executable hledger
hs-source-dirs:
app
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans
- cpp-options: -DVERSION="1.4"
+ cpp-options: -DVERSION="1.5"
build-depends:
- base >=4.8 && <5
+ Decimal
+ , HUnit
+ , ansi-terminal >=0.6.2.3
+ , base >=4.8 && <5
, base-compat >=0.8.1
- , ansi-terminal >= 0.6.2.3 && < 0.8
- , directory
- , file-embed >=0.0.10 && <0.1
- , filepath
- , here
- , pretty-show >=1.6.4
- , process
- , shakespeare >=2.0.2.2 && <2.1
- , temporary
- , tabular >=0.2 && <0.3
- , time >=1.5
- , utility-ht >= 0.0.13
- , hledger-lib >= 1.4 && < 1.5
- , hledger
, bytestring
+ , cmdargs >=0.10
, containers
- , unordered-containers
- , cmdargs >=0.10 && <0.11
, csv
, data-default >=0.5
- , haskeline >=0.6 && <=0.8
- , HUnit
+ , directory
+ , file-embed >=0.0.10
+ , filepath
+ , haskeline >=0.6
+ , here
+ , hledger
+ , hledger-lib >=1.5 && <1.6
, mtl
, mtl-compat
, old-time
, parsec >=3
+ , pretty-show >=1.6.4
+ , process
, regex-tdfa
, safe >=0.2
- , split >=0.1 && <0.3
+ , shakespeare >=2.0.2.2
+ , split >=0.1
+ , tabular >=0.2
+ , temporary
, text >=0.11
- , utf8-string >=0.3.5 && <1.1
- , wizards ==1.0.*
+ , time >=1.5
+ , unordered-containers
+ , utf8-string >=0.3.5
+ , utility-ht >=0.0.13
+ , wizards >=1.0
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
if flag(threaded)
ghc-options: -threaded
+ other-modules:
+ Paths_hledger
default-language: Haskell2010
test-suite test
@@ -205,47 +211,50 @@ test-suite test
hs-source-dirs:
test
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans
- cpp-options: -DVERSION="1.4"
+ cpp-options: -DVERSION="1.5"
build-depends:
- base >=4.8 && <5
+ Decimal
+ , HUnit
+ , ansi-terminal >=0.6.2.3
+ , base >=4.8 && <5
, base-compat >=0.8.1
- , ansi-terminal >= 0.6.2.3 && < 0.8
- , directory
- , file-embed >=0.0.10 && <0.1
- , filepath
- , here
- , pretty-show >=1.6.4
- , process
- , shakespeare >=2.0.2.2 && <2.1
- , temporary
- , tabular >=0.2 && <0.3
- , time >=1.5
- , utility-ht >= 0.0.13
- , hledger-lib >= 1.4 && < 1.5
- , hledger
, bytestring
+ , cmdargs >=0.10
, containers
- , unordered-containers
- , cmdargs >=0.10 && <0.11
, csv
, data-default >=0.5
- , haskeline >=0.6 && <=0.8
- , HUnit
+ , directory
+ , file-embed >=0.0.10
+ , filepath
+ , haskeline >=0.6
+ , here
+ , hledger
+ , hledger-lib >=1.5 && <1.6
, mtl
, mtl-compat
, old-time
, parsec >=3
+ , pretty-show >=1.6.4
+ , process
, regex-tdfa
, safe >=0.2
- , split >=0.1 && <0.3
- , text >=0.11
- , utf8-string >=0.3.5 && <1.1
- , wizards ==1.0.*
+ , shakespeare >=2.0.2.2
+ , split >=0.1
+ , tabular >=0.2
+ , temporary
, test-framework
, test-framework-hunit
+ , text >=0.11
+ , time >=1.5
+ , unordered-containers
+ , utf8-string >=0.3.5
+ , utility-ht >=0.0.13
+ , wizards >=1.0
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
+ other-modules:
+ Paths_hledger
default-language: Haskell2010
benchmark bench
@@ -255,26 +264,28 @@ benchmark bench
bench
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans
build-depends:
- base >=4.8 && <5
+ ansi-terminal >=0.6.2.3
+ , base >=4.8 && <5
, base-compat >=0.8.1
- , ansi-terminal >= 0.6.2.3 && < 0.8
+ , criterion
, directory
- , file-embed >=0.0.10 && <0.1
+ , file-embed >=0.0.10
, filepath
, here
+ , hledger
+ , hledger-lib >=1.5 && <1.6
+ , html
, pretty-show >=1.6.4
, process
- , shakespeare >=2.0.2.2 && <2.1
+ , shakespeare >=2.0.2.2
+ , tabular >=0.2
, temporary
- , tabular >=0.2 && <0.3
, time >=1.5
- , utility-ht >= 0.0.13
- , hledger-lib >= 1.4 && < 1.5
- , hledger
- , criterion
- , html
, timeit
+ , utility-ht >=0.0.13
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
+ other-modules:
+ Paths_hledger
default-language: Haskell2010
diff --git a/doc/hledger.1.info b/hledger.info
index 0272f19..becb0ab 100644
--- a/doc/hledger.1.info
+++ b/hledger.info
@@ -1,9 +1,9 @@
-This is hledger.1.info, produced by makeinfo version 6.0 from stdin.
+This is hledger.info, produced by makeinfo version 6.5 from stdin.

-File: hledger.1.info, Node: Top, Next: EXAMPLES, Up: (dir)
+File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
-hledger(1) hledger 1.4
+hledger(1) hledger 1.5
**********************
This is hledger's command-line interface (there are also curses and web
@@ -49,7 +49,7 @@ try some commands like 'hledger print' or 'hledger balance'. Run
* ADD-ON COMMANDS::

-File: hledger.1.info, Node: EXAMPLES, Next: OPTIONS, Prev: Top, Up: Top
+File: hledger.info, Node: EXAMPLES, Next: OPTIONS, Prev: Top, Up: Top
1 EXAMPLES
**********
@@ -108,7 +108,7 @@ $ hledger print desc:shop # show transactions with shop in the d
$ hledger activity -W # show transaction counts per week as a bar chart

-File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
+File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
2 OPTIONS
*********
@@ -118,7 +118,7 @@ File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* General options::
* Command options::
* Command arguments::
-* Argument expansion::
+* Argument files::
* Special characters::
* Input files::
* Smart dates::
@@ -129,10 +129,11 @@ File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Pivoting::
* Cost::
* Market value::
+* Combining -B and -V::
* Regular expressions::

-File: hledger.1.info, Node: General options, Next: Command options, Up: OPTIONS
+File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS
2.1 General options
===================
@@ -200,7 +201,7 @@ by most hledger commands, run 'hledger -h'.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
- (overrides the flags above)
+ using period expressions syntax (overrides the flags above)
'--date2'
match the secondary date instead (see command help for other
@@ -231,6 +232,13 @@ by most hledger commands, run 'hledger -h'.
convert amounts to their market value on the report end date (using
the most recent applicable market price, if any)
+'--auto'
+
+ apply automated posting rules to modify transactions.
+'--forecast'
+
+ apply periodic transaction rules to generate future transactions,
+ to 6 months from now or report end date.
When a reporting option appears more than once in the command line,
the last one takes precedence.
@@ -238,7 +246,7 @@ the last one takes precedence.
Some reporting options can also be written as query arguments.

-File: hledger.1.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS
+File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS
2.2 Command options
===================
@@ -254,7 +262,7 @@ options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can
run the addon executable directly: 'hledger-ui --watch'.

-File: hledger.1.info, Node: Command arguments, Next: Argument expansion, Prev: Command options, Up: OPTIONS
+File: hledger.info, Node: Command arguments, Next: Argument files, Prev: Command options, Up: OPTIONS
2.3 Command arguments
=====================
@@ -263,18 +271,18 @@ Most hledger commands accept arguments after the command name, which are
often a query, filtering the data in some way.

-File: hledger.1.info, Node: Argument expansion, Next: Special characters, Prev: Command arguments, Up: OPTIONS
+File: hledger.info, Node: Argument files, Next: Special characters, Prev: Command arguments, Up: OPTIONS
-2.4 Argument expansion
-======================
+2.4 Argument files
+==================
You can save a set of command line options/arguments in a file, one per
-line, and then reuse them by writing '@FILE' in a command line. (To
+line, and then reuse them by writing '@FILENAME' in a command line. To
prevent this expansion of '@'-arguments, precede them with a '--'
-argument.)
+argument. For more, see Save frequently used options.

-File: hledger.1.info, Node: Special characters, Next: Input files, Prev: Argument expansion, Up: OPTIONS
+File: hledger.info, Node: Special characters, Next: Input files, Prev: Argument files, Up: OPTIONS
2.5 Special characters
======================
@@ -312,7 +320,7 @@ quotes. Eg: 'cur:\$').
If you're really stumped, add '--debug=2' to troubleshoot.

-File: hledger.1.info, Node: Input files, Next: Smart dates, Prev: Special characters, Up: OPTIONS
+File: hledger.info, Node: Input files, Next: Smart dates, Prev: Special characters, Up: OPTIONS
2.6 Input files
===============
@@ -338,15 +346,15 @@ be one of several other formats, listed below. hledger detects the
format automatically based on the file extension, or if that is not
recognised, by trying each built-in "reader" in turn:
-Reader: Reads: Used for file extensions:
----------------------------------------------------------------------------
-'journal' hledger's journal format, also '.journal' '.j'
- some Ledger journals '.hledger' '.ledger'
-'timeclock' timeclock files (precise time '.timeclock'
+Reader: Reads: Used for file extensions:
+----------------------------------------------------------------------------
+'journal' hledger's journal format, also '.journal' '.j'
+ some Ledger journals '.hledger' '.ledger'
+'timeclock' timeclock files (precise time '.timeclock'
logging)
-'timedot' timedot files (approximate time '.timedot'
+'timedot' timedot files (approximate time '.timedot'
logging)
-'csv' comma-separated values (data '.csv'
+'csv' comma-separated values (data '.csv'
interchange)
If needed (eg to ensure correct error messages when a file has the
@@ -367,7 +375,7 @@ one big journal. There are some limitations with this:
the files, eg: 'cat a.journal b.journal | hledger -f- CMD'.

-File: hledger.1.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS
+File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS
2.7 Smart dates
===============
@@ -390,7 +398,7 @@ omitted (defaulting to 1).
'today', 'yesterday', 'tomorrow'

-File: hledger.1.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS
+File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS
2.8 Report start & end date
===========================
@@ -409,7 +417,7 @@ need to write the date _after_ the last day you want to include.
Examples:
-'-b 2016/3/17' begin on St. Patrick's day 2016
+'-b 2016/3/17' begin on St. Patrick's day 2016
'-e 12/1' end at the start of december 1st of the current year (11/30 will be the last date included)
'-b thismonth' all transactions on or after the 1st of the current month
'-p thismonth' all transactions in the current month
@@ -419,7 +427,7 @@ need to write the date _after_ the last day you want to include.
'date:thismonth'

-File: hledger.1.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS
+File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS
2.9 Report intervals
====================
@@ -432,7 +440,7 @@ complex intervals may be specified with a period expression. Report
intervals can not be specified with a query, currently.

-File: hledger.1.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS
+File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS
2.10 Period expressions
=======================
@@ -486,15 +494,48 @@ start/end dates (if any), the word 'in' is optional. Examples:
'-p "monthly in 2008"'
'-p "quarterly"'
+ Note that 'weekly', 'monthly', 'quarterly' and 'yearly' intervals
+will always start on the first day on week, month, quarter or year
+accordingly, and will end on the last day of same period, even if
+associated period expression specifies different explicit start and end
+date.
+
+ For example:
+
+'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceeding Monday
+'-p "monthly in 2008/11/25"' - starts on 2018/11/01
+'-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009
+'-p "yearly from 2009-12-29"' - starts on 2009/01/01, first day of 2009
+
The following more complex report intervals are also supported:
-'biweekly', 'bimonthly', 'every N days|weeks|months|quarters|years',
-'every Nth day [of month]', 'every Nth day of week'.
+'biweekly', 'bimonthly', 'every day|week|month|quarter|year', 'every N
+days|weeks|months|quarters|years'.
+
+ All of these will start on the first day of the requested period and
+end on the last one, as described above.
+
+ Examples:
+
+'-p "bimonthly from 2008"' - periods will have boundaries on 2008/01/01, 2008/03/01, ...
+'-p "every 2 weeks"' - starts on closest preceeding Monday
+'-p "every 5 month from 2009/03"' - periods will have boundaries on 2009/03/01, 2009/08/01, ...
+
+ If you want intervals that start on arbitrary day of your choosing
+and span a week, month or year, you need to use any of the following:
+
+ 'every Nth day of week', 'every <weekday>', 'every Nth day [of
+month]', 'every Nth weekday [of month]', 'every MM/DD [of year]', 'every
+Nth MMM [of year]', 'every MMM Nth [of year]'.
Examples:
-'-p "bimonthly from 2008"'
-'-p "every 2 weeks"'
-'-p "every 5 days from 1/3"'
+'-p "every 2nd day of week"' - periods will go from Tue to Tue
+'-p "every Tue"' - same
+'-p "every 15th day"' - period boundaries will be on 15th of each month
+'-p "every 2nd Monday"' - period boundaries will be on second Monday of each month
+'-p "every 11/05"' - yearly periods with boundaries on 5th of Nov
+'-p "every 5th Nov"' - same
+'-p "every Nov 5th"' - same
Show historical balances at end of 15th each month (N is exclusive
end date):
@@ -507,7 +548,7 @@ start date and exclusive end date):
'hledger register checking -p "every 3rd day of week"'

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

-File: hledger.1.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS
+File: hledger.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS
2.12 Pivoting
=============
@@ -576,7 +617,7 @@ $ hledger balance --pivot member acct:.
-2 EUR

-File: hledger.1.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS
+File: hledger.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS
2.13 Cost
=========
@@ -585,19 +626,19 @@ The '-B/--cost' flag converts amounts to their cost at transaction time,
if they have a transaction price specified.

-File: hledger.1.info, Node: Market value, Next: Regular expressions, Prev: Cost, Up: OPTIONS
+File: hledger.info, Node: Market value, Next: Combining -B and -V, Prev: Cost, Up: OPTIONS
2.14 Market value
=================
-The '-V/--value' flag converts the reported amounts to their market
-value on the report end date, using the most recent applicable market
-prices, when known. Specifically, when there is a market price (P
-directive) for the amount's commodity, dated on or before the report end
-date (see hledger -> Report start & end date), the amount will be
-converted to the price's commodity. If multiple applicable prices are
-defined, the latest-dated one is used (and if dates are equal, the one
-last parsed).
+The '-V/--value' flag converts reported amounts to their current market
+value. Specifically, when there is a market price (P directive) for the
+amount's commodity, dated on or before today's date (or the report end
+date if specified), the amount will be converted to the price's
+commodity.
+
+ When there are multiple applicable P directives, -V chooses the most
+recent one, or in case of equal dates, the last-parsed one.
For example:
@@ -631,12 +672,20 @@ $ hledger -f t.j bal euros -V -e 2016/12/21
Currently, hledger's -V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
- Using -B and -V together is allowed.
+
+File: hledger.info, Node: Combining -B and -V, Next: Regular expressions, Prev: Market value, Up: OPTIONS
+
+2.15 Combining -B and -V
+========================
+
+Using -B/-cost and -V/-value together is currently allowed, but the
+results are probably not meaningful. Let us know if you find a use for
+this.

-File: hledger.1.info, Node: Regular expressions, Prev: Market value, Up: OPTIONS
+File: hledger.info, Node: Regular expressions, Prev: Combining -B and -V, Up: OPTIONS
-2.15 Regular expressions
+2.16 Regular expressions
========================
hledger uses regular expressions in a number of places:
@@ -674,7 +723,7 @@ general they:
See Special characters.

-File: hledger.1.info, Node: QUERIES, Next: COMMANDS, Prev: OPTIONS, Up: Top
+File: hledger.info, Node: QUERIES, Next: COMMANDS, Prev: OPTIONS, Up: Top
3 QUERIES
*********
@@ -785,7 +834,7 @@ and query arguments, and the resulting query will be their intersection
(perhaps excluding the '-p/--period' option).

-File: hledger.1.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top
+File: hledger.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top
4 COMMANDS
**********
@@ -831,7 +880,7 @@ detailed command help.
* test::

-File: hledger.1.info, Node: accounts, Next: activity, Up: COMMANDS
+File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS
4.1 accounts
============
@@ -896,7 +945,7 @@ income:salary
liabilities:debts

-File: hledger.1.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS
+File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS
4.2 activity
============
@@ -910,11 +959,11 @@ default). With query arguments, it counts only matched transactions.
$ hledger activity --quarterly
2008-01-01 **
2008-04-01 *******
-2008-07-01
+2008-07-01
2008-10-01 **

-File: hledger.1.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS
+File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS
4.3 add
=======
@@ -967,24 +1016,24 @@ An optional ; COMMENT may follow descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
-Date [2015/05/22]:
+Date [2015/05/22]:
Description: supermarket
Account 1: expenses:food
Amount 1: $10
Account 2: assets:checking
-Amount 2 [$-10.0]:
+Amount 2 [$-10.0]:
Account 3 (or . or enter to finish this transaction): .
2015/05/22 supermarket
expenses:food $10
assets:checking $-10.0
-Save this transaction to the journal ? [y]:
+Save this transaction to the journal ? [y]:
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $

-File: hledger.1.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS
+File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS
4.4 balance
===========
@@ -1037,11 +1086,19 @@ Show accounts and their balances. Aliases: b, bal.
formats selects that format.
'--pretty-tables'
- Use unicode to display prettier tables.
+ use unicode to display prettier tables.
'--sort-amount'
- Sort by amount (total row amount, or by average if that is
- displayed), instead of account name (in flat mode)
+ sort by amount instead of account name (in flat mode). With
+ multiple columns, sorts by the row total, or by row average if that
+ is displayed.
+'--budget'
+
+ show performance compared to budget goals defined by periodic
+ transactions
+'--show-unbudgeted'
+
+ with -budget, show unbudgeted accounts also
The balance command displays accounts and balances. It is hledger's
most featureful and versatile command.
@@ -1091,13 +1148,14 @@ $ hledger balance -p 2008/6 expenses --no-total
* Flat mode::
* Depth limited balance reports::
* Multicolumn balance reports::
+* Budgets::
* Custom balance output::
* Colour support::
* Output destination::
* CSV output::

-File: hledger.1.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance
+File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance
4.4.1 Flat mode
---------------
@@ -1113,7 +1171,7 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 supplies

-File: hledger.1.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance
+File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance
4.4.2 Depth limited balance reports
-----------------------------------
@@ -1130,7 +1188,7 @@ $ hledger balance -N --depth 1
$1 liabilities

-File: hledger.1.info, Node: Multicolumn balance reports, Next: Custom balance output, Prev: Depth limited balance reports, Up: balance
+File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance
4.4.3 Multicolumn balance reports
---------------------------------
@@ -1145,15 +1203,15 @@ report, showing different information:
$ hledger balance --quarterly income expenses -E
Balance changes in 2008:
-
- || 2008q1 2008q2 2008q3 2008q4
+
+ || 2008q1 2008q2 2008q3 2008q4
===================++=================================
- expenses:food || 0 $1 0 0
- expenses:supplies || 0 $1 0 0
- income:gifts || 0 $-1 0 0
- income:salary || $-1 0 0 0
+ expenses:food || 0 $1 0 0
+ expenses:supplies || 0 $1 0 0
+ income:gifts || 0 $-1 0 0
+ income:salary || $-1 0 0 0
-------------------++---------------------------------
- || $-1 $1 0 0
+ || $-1 $1 0 0
2. With '--cumulative': each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
@@ -1161,15 +1219,15 @@ report, showing different information:
$ hledger balance --quarterly income expenses -E --cumulative
Ending balances (cumulative) in 2008:
-
- || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
+
+ || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
===================++=================================================
- expenses:food || 0 $1 $1 $1
- expenses:supplies || 0 $1 $1 $1
- income:gifts || 0 $-1 $-1 $-1
- income:salary || $-1 $-1 $-1 $-1
+ expenses:food || 0 $1 $1 $1
+ expenses:supplies || 0 $1 $1 $1
+ income:gifts || 0 $-1 $-1 $-1
+ income:salary || $-1 $-1 $-1 $-1
-------------------++-------------------------------------------------
- || $-1 0 0 0
+ || $-1 0 0 0
3. With '--historical/-H': each column shows the actual historical
ending balance for that period, accumulating the changes across
@@ -1179,15 +1237,15 @@ report, showing different information:
$ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
Ending balances (historical) in 2008/04/01-2008/12/31:
-
- || 2008/06/30 2008/09/30 2008/12/31
+
+ || 2008/06/30 2008/09/30 2008/12/31
======================++=====================================
- assets:bank:checking || $1 $1 0
- assets:bank:saving || $1 $1 $1
- assets:cash || $-2 $-2 $-2
- liabilities:debts || 0 0 $1
+ assets:bank:checking || $1 $1 0
+ assets:bank:saving || $1 $1 $1
+ assets:cash || $-2 $-2 $-2
+ liabilities:debts || 0 0 $1
----------------------++-------------------------------------
- || 0 0 0
+ || 0 0 0
Multi-column balance reports display accounts in flat mode by
default; to see the hierarchy, use '--tree'.
@@ -1216,23 +1274,115 @@ each row.
$ hledger balance -Q income expenses --tree -ETA
Balance changes in 2008:
- || 2008q1 2008q2 2008q3 2008q4 Total Average
+ || 2008q1 2008q2 2008q3 2008q4 Total Average
============++===================================================
- expenses || 0 $2 0 0 $2 $1
- food || 0 $1 0 0 $1 0
- supplies || 0 $1 0 0 $1 0
- income || $-1 $-1 0 0 $-2 $-1
- gifts || 0 $-1 0 0 $-1 0
- salary || $-1 0 0 0 $-1 0
+ expenses || 0 $2 0 0 $2 $1
+ food || 0 $1 0 0 $1 0
+ supplies || 0 $1 0 0 $1 0
+ income || $-1 $-1 0 0 $-2 $-1
+ gifts || 0 $-1 0 0 $-1 0
+ salary || $-1 0 0 0 $-1 0
------------++---------------------------------------------------
- || $-1 $1 0 0 0 0
+ || $-1 $1 0 0 0 0
# Average is rounded to the dollar here since all journal amounts are

-File: hledger.1.info, Node: Custom balance output, Next: Colour support, Prev: Multicolumn balance reports, Up: balance
-
-4.4.4 Custom balance output
+File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance
+
+4.4.4 Budgets
+-------------
+
+With '--budget' and a report interval, all periodic transactions in your
+journal with that interval, active during the requested report period,
+are interpreted as recurring budget goals for the specified accounts
+(and subaccounts), and the report will show the difference between
+actual and budgeted balances.
+
+ For example, you can take average monthly expenses in the common
+expense categories to construct a minimal monthly budget:
+
+;; Budget
+~ monthly
+ income $2000
+ expenses:food $400
+ expenses:bus $50
+ expenses:movies $30
+ assets:bank:checking
+
+;; Two months worth of expenses
+2017-11-01
+ income $1950
+ expenses:food $396
+ expenses:bus $49
+ expenses:movies $30
+ expenses:supplies $20
+ assets:bank:checking
+
+2017-12-01
+ income $2100
+ expenses:food $412
+ expenses:bus $53
+ expenses:gifts $100
+ assets:bank:checking
+
+ You can now see a monthly budget performance report:
+
+$ hledger balance -M --budget
+Balance changes in 2017/11/01-2017/12/31:
+
+ || 2017/11 2017/12
+=======================++=================================================
+ <unbudgeted>:expenses || $20 $100
+ assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
+ expenses:bus || $49 [98% of $50] $53 [106% of $50]
+ expenses:food || $396 [99% of $400] $412 [103% of $400]
+ expenses:movies || $30 [100% of $30] 0 [0% of $30]
+ income || $1950 [98% of $2000] $2100 [105% of $2000]
+-----------------------++-------------------------------------------------
+ || 0 0
+
+ You can roll over unspent budgets to next period with '--cumulative':
+
+$ hledger balance -M --budget --cumulative
+Ending balances (cumulative) in 2017/11/01-2017/12/31:
+
+ || 2017/11/30 2017/12/31
+=======================++=================================================
+ <unbudgeted>:expenses || $20 $120
+ assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
+ expenses:bus || $49 [98% of $50] $102 [102% of $100]
+ expenses:food || $396 [99% of $400] $808 [101% of $800]
+ expenses:movies || $30 [100% of $30] $30 [50% of $60]
+ income || $1950 [98% of $2000] $4050 [101% of $4000]
+-----------------------++-------------------------------------------------
+ || 0 0
+
+ Accounts with no budget goals (not mentioned in the periodic
+transactions) will be aggregated under '<unbudgeted>', unless you add
+the '--show-unbudgeted' flag to display them normally:
+
+$ hledger balance --budget --show-unbudgeted
+Balance changes in 2017/11/01-2017/12/31:
+
+ || 2017/11 2017/12
+======================++=================================================
+ assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
+ expenses:bus || $49 [98% of $50] $53 [106% of $50]
+ expenses:food || $396 [99% of $400] $412 [103% of $400]
+ expenses:gifts || 0 $100
+ expenses:movies || $30 [100% of $30] 0 [0% of $30]
+ expenses:supplies || $20 0
+ income || $1950 [98% of $2000] $2100 [105% of $2000]
+----------------------++-------------------------------------------------
+ || 0 0
+
+ For more examples and details, see Budgeting and Forecasting.
+
+
+File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance
+
+4.4.5 Custom balance output
---------------------------
In simple (non-multi-column) balance reports, you can customise the
@@ -1290,9 +1440,9 @@ may be needed to get pleasing results.
the single-column balance report

-File: hledger.1.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance
+File: hledger.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance
-4.4.5 Colour support
+4.4.6 Colour support
--------------------
The balance command shows negative amounts in red, if:
@@ -1301,9 +1451,9 @@ The balance command shows negative amounts in red, if:
* the output is not being redirected or piped anywhere

-File: hledger.1.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance
+File: hledger.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance
-4.4.6 Output destination
+4.4.7 Output destination
------------------------
The balance, print, register and stats commands can write their output
@@ -1314,9 +1464,9 @@ $ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE

-File: hledger.1.info, Node: CSV output, Prev: Output destination, Up: balance
+File: hledger.info, Node: CSV output, Prev: Output destination, Up: balance
-4.4.7 CSV output
+4.4.8 CSV output
----------------
The balance, print and register commands can write their output as CSV.
@@ -1329,7 +1479,7 @@ $ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv

-File: hledger.1.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
+File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
4.5 balancesheet
================
@@ -1408,7 +1558,7 @@ balancesheet shows historical ending balances, which is what you need
for a balance sheet; note this means it ignores report begin dates.

-File: hledger.1.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS
+File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS
4.6 balancesheetequity
======================
@@ -1448,7 +1598,7 @@ Total:
0

-File: hledger.1.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS
+File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS
4.7 cashflow
============
@@ -1521,7 +1671,7 @@ period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'.

-File: hledger.1.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS
+File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS
4.8 check-dates
===============
@@ -1530,7 +1680,7 @@ Check that transactions are sorted by increasing date. With a query,
only matched transactions' dates are checked.

-File: hledger.1.info, Node: check-dupes, Next: equity, Prev: check-dates, Up: COMMANDS
+File: hledger.info, Node: check-dupes, Next: equity, Prev: check-dates, Up: COMMANDS
4.9 check-dupes
===============
@@ -1539,7 +1689,7 @@ Report account names having the same leaf but different prefixes. An
example: http://stefanorodighiero.net/software/hledger-dupes.html

-File: hledger.1.info, Node: equity, Next: help, Prev: check-dupes, Up: COMMANDS
+File: hledger.info, Node: equity, Next: help, Prev: check-dupes, Up: COMMANDS
4.10 equity
===========
@@ -1549,7 +1699,7 @@ balances to zero and back. Can be useful for bringing account balances
across file boundaries.

-File: hledger.1.info, Node: help, Next: import, Prev: equity, Up: COMMANDS
+File: hledger.info, Node: help, Next: import, Prev: equity, Up: COMMANDS
4.11 help
=========
@@ -1586,7 +1736,7 @@ DESCRIPTION
...

-File: hledger.1.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS
+File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS
4.12 import
===========
@@ -1598,15 +1748,21 @@ the main journal file.
just show the transactions to be imported
- Input files are provided as arguments, or glob patterns. So eg to
-add new transactions from all CSV files to the main journal: hledger
-import *.csv
+ The input files are specified as arguments - no need to write -f
+before each one. So eg to add new transactions from all CSV files to
+the main journal, it's just: 'hledger import *.csv'
+
+ New transactions are detected in the same way as print -new: by
+assuming transactions are always added to the input files in increasing
+date order, and by saving '.latest.FILE' state files.
+
+ The -dry-run output is in journal format, so you can filter it, eg to
+see only uncategorised transactions:
- New transactions are detected like print -new (using .latest.FILE
-state files).
+$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions

-File: hledger.1.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS
+File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS
4.13 incomestatement
====================
@@ -1685,7 +1841,7 @@ per period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'.

-File: hledger.1.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS
+File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS
4.14 prices
===========
@@ -1693,7 +1849,7 @@ File: hledger.1.info, Node: prices, Next: print, Prev: incomestatement, Up:
Print all market prices from the journal.

-File: hledger.1.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS
+File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS
4.15 print
==========
@@ -1757,7 +1913,7 @@ arise when a multi-commodity transaction has an implicit amount) will be
split into multiple single-commodity postings, for valid journal output.
With '-B'/'--cost', amounts with transaction prices are converted to
-cost using that price.
+cost using that price. This can be used for troubleshooting.
With '-m'/'--match' and a STR argument, print will show at most one
transaction: the one one whose description is most similar to STR, and
@@ -1810,7 +1966,7 @@ $ hledger print -Ocsv
zero or greater amounts under debit.)

-File: hledger.1.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS
+File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS
4.16 print-unique
=================
@@ -1818,7 +1974,7 @@ File: hledger.1.info, Node: print-unique, Next: register, Prev: print, Up: C
Print transactions which do not reuse an already-seen description.

-File: hledger.1.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS
+File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS
4.17 register
=============
@@ -1923,7 +2079,7 @@ length and comparable to the others in the report.
* Custom register output::

-File: hledger.1.info, Node: Custom register output, Up: register
+File: hledger.info, Node: Custom register output, Up: register
4.17.1 Custom register output
-----------------------------
@@ -1955,7 +2111,7 @@ $ hledger reg -w $COLUMNS,40 # use terminal width, and set description widt
output.

-File: hledger.1.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
+File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
4.18 register-match
===================
@@ -1965,7 +2121,7 @@ in the style of the register command. Helps ledger-autosync detect
already-seen transactions when importing.

-File: hledger.1.info, Node: rewrite, Next: stats, Prev: register-match, Up: COMMANDS
+File: hledger.info, Node: rewrite, Next: stats, Prev: register-match, Up: COMMANDS
4.19 rewrite
============
@@ -1973,7 +2129,7 @@ File: hledger.1.info, Node: rewrite, Next: stats, Prev: register-match, Up:
Print all transactions, adding custom postings to the matched ones.

-File: hledger.1.info, Node: stats, Next: tags, Prev: rewrite, Up: COMMANDS
+File: hledger.info, Node: stats, Next: tags, Prev: rewrite, Up: COMMANDS
4.20 stats
==========
@@ -1987,7 +2143,7 @@ Show some journal statistics.
$ hledger stats
Main journal file : /src/hledger/examples/sample.journal
-Included journal files :
+Included journal files :
Transactions span : 2008-01-01 to 2009-01-01 (366 days)
Last transaction : 2008-12-31 (2333 days ago)
Transactions : 5 (0.0 per day)
@@ -2005,15 +2161,18 @@ for each report period.
output destination.

-File: hledger.1.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS
+File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS
4.21 tags
=========
-List all the tag names in use.
+List all the tag names used in the journal. With a TAGREGEX argument,
+only tag names matching the regular expression (case insensitive) are
+shown. With additional QUERY arguments, only transactions matching the
+query are considered.

-File: hledger.1.info, Node: test, Prev: tags, Up: COMMANDS
+File: hledger.info, Node: test, Prev: tags, Up: COMMANDS
4.22 test
=========
@@ -2029,7 +2188,7 @@ matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.

-File: hledger.1.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top
+File: hledger.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top
5 ADD-ON COMMANDS
*****************
@@ -2067,7 +2226,7 @@ options, journal parsing, reporting, etc.
* Experimental add-ons::

-File: hledger.1.info, Node: Official add-ons, Next: Third party add-ons, Up: ADD-ON COMMANDS
+File: hledger.info, Node: Official add-ons, Next: Third party add-ons, Up: ADD-ON COMMANDS
5.1 Official add-ons
====================
@@ -2080,7 +2239,7 @@ These are maintained and released along with hledger.
* web::

-File: hledger.1.info, Node: api, Next: ui, Up: Official add-ons
+File: hledger.info, Node: api, Next: ui, Up: Official add-ons
5.1.1 api
---------
@@ -2088,7 +2247,7 @@ File: hledger.1.info, Node: api, Next: ui, Up: Official add-ons
hledger-api serves hledger data as a JSON web API.

-File: hledger.1.info, Node: ui, Next: web, Prev: api, Up: Official add-ons
+File: hledger.info, Node: ui, Next: web, Prev: api, Up: Official add-ons
5.1.2 ui
--------
@@ -2096,7 +2255,7 @@ File: hledger.1.info, Node: ui, Next: web, Prev: api, Up: Official add-ons
hledger-ui provides an efficient curses-style interface.

-File: hledger.1.info, Node: web, Prev: ui, Up: Official add-ons
+File: hledger.info, Node: web, Prev: ui, Up: Official add-ons
5.1.3 web
---------
@@ -2104,7 +2263,7 @@ File: hledger.1.info, Node: web, Prev: ui, Up: Official add-ons
hledger-web provides a simple web interface.

-File: hledger.1.info, Node: Third party add-ons, Next: Experimental add-ons, Prev: Official add-ons, Up: ADD-ON COMMANDS
+File: hledger.info, Node: Third party add-ons, Next: Experimental add-ons, Prev: Official add-ons, Up: ADD-ON COMMANDS
5.2 Third party add-ons
=======================
@@ -2119,7 +2278,7 @@ hledger release.
* irr::

-File: hledger.1.info, Node: diff, Next: iadd, Up: Third party add-ons
+File: hledger.info, Node: diff, Next: iadd, Up: Third party add-ons
5.2.1 diff
----------
@@ -2128,7 +2287,7 @@ hledger-diff shows differences in an account's transactions between one
journal file and another.

-File: hledger.1.info, Node: iadd, Next: interest, Prev: diff, Up: Third party add-ons
+File: hledger.info, Node: iadd, Next: interest, Prev: diff, Up: Third party add-ons
5.2.2 iadd
----------
@@ -2137,7 +2296,7 @@ hledger-iadd is a curses-style, more interactive replacement for the add
command.

-File: hledger.1.info, Node: interest, Next: irr, Prev: iadd, Up: Third party add-ons
+File: hledger.info, Node: interest, Next: irr, Prev: iadd, Up: Third party add-ons
5.2.3 interest
--------------
@@ -2146,7 +2305,7 @@ hledger-interest generates interest transactions for an account
according to various schemes.

-File: hledger.1.info, Node: irr, Prev: interest, Up: Third party add-ons
+File: hledger.info, Node: irr, Prev: interest, Up: Third party add-ons
5.2.4 irr
---------
@@ -2155,7 +2314,7 @@ hledger-irr calculates the internal rate of return of an investment
account.

-File: hledger.1.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS
+File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS
5.3 Experimental add-ons
========================
@@ -2172,7 +2331,7 @@ start making your own!
* check::

-File: hledger.1.info, Node: autosync, Next: budget, Up: Experimental add-ons
+File: hledger.info, Node: autosync, Next: budget, Up: Experimental add-ons
5.3.1 autosync
--------------
@@ -2183,7 +2342,7 @@ and some CSV formats, and can also download the data if your bank offers
OFX Direct Connect.

-File: hledger.1.info, Node: budget, Next: chart, Prev: autosync, Up: Experimental add-ons
+File: hledger.info, Node: budget, Next: chart, Prev: autosync, Up: Experimental add-ons
5.3.2 budget
------------
@@ -2191,7 +2350,7 @@ File: hledger.1.info, Node: budget, Next: chart, Prev: autosync, Up: Experim
hledger-budget.hs adds more budget-tracking features to hledger.

-File: hledger.1.info, Node: chart, Next: check, Prev: budget, Up: Experimental add-ons
+File: hledger.info, Node: chart, Next: check, Prev: budget, Up: Experimental add-ons
5.3.3 chart
-----------
@@ -2199,7 +2358,7 @@ File: hledger.1.info, Node: chart, Next: check, Prev: budget, Up: Experiment
hledger-chart.hs is an old pie chart generator, in need of some love.

-File: hledger.1.info, Node: check, Prev: chart, Up: Experimental add-ons
+File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons
5.3.4 check
-----------
@@ -2208,134 +2367,138 @@ hledger-check.hs checks more powerful account balance assertions.

Tag Table:
-Node: Top70
-Node: EXAMPLES1886
-Ref: #examples1988
-Node: OPTIONS3634
-Ref: #options3738
-Node: General options4042
-Ref: #general-options4169
-Node: Command options6488
-Ref: #command-options6641
-Node: Command arguments7039
-Ref: #command-arguments7199
-Node: Argument expansion7320
-Ref: #argument-expansion7485
-Node: Special characters7704
-Ref: #special-characters7863
-Node: Input files9282
-Ref: #input-files9420
-Node: Smart dates11383
-Ref: #smart-dates11526
-Node: Report start & end date12505
-Ref: #report-start-end-date12677
-Node: Report intervals13743
-Ref: #report-intervals13908
-Node: Period expressions14309
-Ref: #period-expressions14471
-Node: Depth limiting16811
-Ref: #depth-limiting16957
-Node: Pivoting17299
-Ref: #pivoting17419
-Node: Cost19095
-Ref: #cost19205
-Node: Market value19323
-Ref: #market-value19460
-Node: Regular expressions20760
-Ref: #regular-expressions20898
-Node: QUERIES22259
-Ref: #queries22363
-Node: COMMANDS26330
-Ref: #commands26444
-Node: accounts27427
-Ref: #accounts27527
-Node: activity28520
-Ref: #activity28632
-Node: add28991
-Ref: #add29092
-Node: balance31750
-Ref: #balance31863
-Node: Flat mode35020
-Ref: #flat-mode35147
-Node: Depth limited balance reports35567
-Ref: #depth-limited-balance-reports35770
-Node: Multicolumn balance reports36190
-Ref: #multicolumn-balance-reports36401
-Node: Custom balance output41049
-Ref: #custom-balance-output41233
-Node: Colour support43326
-Ref: #colour-support43487
-Node: Output destination43660
-Ref: #output-destination43818
-Node: CSV output44088
-Ref: #csv-output44207
-Node: balancesheet44604
-Ref: #balancesheet44742
-Node: balancesheetequity46710
-Ref: #balancesheetequity46861
-Node: cashflow47650
-Ref: #cashflow47780
-Node: check-dates49692
-Ref: #check-dates49821
-Node: check-dupes49938
-Ref: #check-dupes50065
-Node: equity50202
-Ref: #equity50314
-Node: help50477
-Ref: #help50580
-Node: import51654
-Ref: #import51770
-Node: incomestatement52165
-Ref: #incomestatement52301
-Node: prices54254
-Ref: #prices54371
-Node: print54414
-Ref: #print54526
-Node: print-unique59372
-Ref: #print-unique59500
-Node: register59568
-Ref: #register59697
-Node: Custom register output64198
-Ref: #custom-register-output64329
-Node: register-match65626
-Ref: #register-match65762
-Node: rewrite65945
-Ref: #rewrite66064
-Node: stats66133
-Ref: #stats66238
-Node: tags67119
-Ref: #tags67219
-Node: test67251
-Ref: #test67337
-Node: ADD-ON COMMANDS67705
-Ref: #add-on-commands67817
-Node: Official add-ons69104
-Ref: #official-add-ons69246
-Node: api69333
-Ref: #api69424
-Node: ui69476
-Ref: #ui69577
-Node: web69635
-Ref: #web69726
-Node: Third party add-ons69772
-Ref: #third-party-add-ons69949
-Node: diff70084
-Ref: #diff70183
-Node: iadd70282
-Ref: #iadd70398
-Node: interest70481
-Ref: #interest70604
-Node: irr70699
-Ref: #irr70799
-Node: Experimental add-ons70877
-Ref: #experimental-add-ons71031
-Node: autosync71322
-Ref: #autosync71436
-Node: budget71675
-Ref: #budget71799
-Node: chart71865
-Ref: #chart71984
-Node: check72055
-Ref: #check72159
+Node: Top68
+Node: EXAMPLES1882
+Ref: #examples1982
+Node: OPTIONS3628
+Ref: #options3730
+Node: General options4054
+Ref: #general-options4179
+Node: Command options6730
+Ref: #command-options6881
+Node: Command arguments7279
+Ref: #command-arguments7433
+Node: Argument files7554
+Ref: #argument-files7705
+Node: Special characters7971
+Ref: #special-characters8124
+Node: Input files9543
+Ref: #input-files9679
+Node: Smart dates11649
+Ref: #smart-dates11790
+Node: Report start & end date12769
+Ref: #report-start-end-date12939
+Node: Report intervals14004
+Ref: #report-intervals14167
+Node: Period expressions14568
+Ref: #period-expressions14728
+Node: Depth limiting18685
+Ref: #depth-limiting18829
+Node: Pivoting19171
+Ref: #pivoting19289
+Node: Cost20965
+Ref: #cost21073
+Node: Market value21191
+Ref: #market-value21326
+Node: Combining -B and -V22509
+Ref: #combining--b-and--v22673
+Node: Regular expressions22820
+Ref: #regular-expressions22963
+Node: QUERIES24324
+Ref: #queries24426
+Node: COMMANDS28393
+Ref: #commands28505
+Node: accounts29488
+Ref: #accounts29586
+Node: activity30579
+Ref: #activity30689
+Node: add31049
+Ref: #add31148
+Node: balance33809
+Ref: #balance33920
+Node: Flat mode37294
+Ref: #flat-mode37419
+Node: Depth limited balance reports37839
+Ref: #depth-limited-balance-reports38040
+Node: Multicolumn balance reports38460
+Ref: #multicolumn-balance-reports38655
+Node: Budgets43344
+Ref: #budgets43491
+Node: Custom balance output47322
+Ref: #custom-balance-output47484
+Node: Colour support49577
+Ref: #colour-support49736
+Node: Output destination49909
+Ref: #output-destination50065
+Node: CSV output50335
+Ref: #csv-output50452
+Node: balancesheet50849
+Ref: #balancesheet50985
+Node: balancesheetequity52953
+Ref: #balancesheetequity53102
+Node: cashflow53891
+Ref: #cashflow54019
+Node: check-dates55931
+Ref: #check-dates56058
+Node: check-dupes56175
+Ref: #check-dupes56300
+Node: equity56437
+Ref: #equity56547
+Node: help56710
+Ref: #help56811
+Node: import57885
+Ref: #import57999
+Node: incomestatement58729
+Ref: #incomestatement58863
+Node: prices60816
+Ref: #prices60931
+Node: print60974
+Ref: #print61084
+Node: print-unique65969
+Ref: #print-unique66095
+Node: register66163
+Ref: #register66290
+Node: Custom register output70791
+Ref: #custom-register-output70920
+Node: register-match72217
+Ref: #register-match72351
+Node: rewrite72534
+Ref: #rewrite72651
+Node: stats72720
+Ref: #stats72823
+Node: tags73705
+Ref: #tags73803
+Node: test74039
+Ref: #test74123
+Node: ADD-ON COMMANDS74491
+Ref: #add-on-commands74601
+Node: Official add-ons75888
+Ref: #official-add-ons76028
+Node: api76115
+Ref: #api76204
+Node: ui76256
+Ref: #ui76355
+Node: web76413
+Ref: #web76502
+Node: Third party add-ons76548
+Ref: #third-party-add-ons76723
+Node: diff76858
+Ref: #diff76955
+Node: iadd77054
+Ref: #iadd77168
+Node: interest77251
+Ref: #interest77372
+Node: irr77467
+Ref: #irr77565
+Node: Experimental add-ons77643
+Ref: #experimental-add-ons77795
+Node: autosync78086
+Ref: #autosync78198
+Node: budget78437
+Ref: #budget78559
+Node: chart78625
+Ref: #chart78742
+Node: check78813
+Ref: #check78915

End Tag Table
diff --git a/doc/hledger.1.txt b/hledger.txt
index d7cc191..5b1c6a1 100644
--- a/doc/hledger.1.txt
+++ b/hledger.txt
@@ -170,7 +170,7 @@ OPTIONS
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
- (overrides the flags above)
+ using period expressions syntax (overrides the flags above)
--date2
match the secondary date instead (see command help for other
@@ -202,30 +202,37 @@ OPTIONS
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
+ --auto apply automated posting rules to modify transactions.
+
+ --forecast
+ apply periodic transaction rules to generate future transac-
+ tions, to 6 months from now or report end date.
+
When a reporting option appears more than once in the command line, the
last one takes precedence.
Some reporting options can also be written as query arguments.
Command options
- To see options for a particular command, including command-specific
+ To see options for a particular command, including command-specific
options, run: hledger COMMAND -h.
- Command-specific options must be written after the command name, eg:
+ Command-specific options must be written after the command name, eg:
hledger print -x.
- Additionally, if the command is an addon, you may need to put its
- options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
+ Additionally, if the command is an addon, you may need to put its
+ options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
run the addon executable directly: hledger-ui --watch.
Command arguments
- Most hledger commands accept arguments after the command name, which
+ Most hledger commands accept arguments after the command name, which
are often a query, filtering the data in some way.
- Argument expansion
+ Argument files
You can save a set of command line options/arguments in a file, one per
- line, and then reuse them by writing @FILE in a command line. (To pre-
- vent this expansion of @-arguments, precede them with a -- argument.)
+ line, and then reuse them by writing @FILENAME in a command line. To
+ prevent this expansion of @-arguments, precede them with a -- argument.
+ For more, see Save frequently used options.
Special characters
Option and argument values which contain problematic characters should
@@ -286,16 +293,16 @@ OPTIONS
recognised, by trying each built-in "reader" in turn:
- Reader: Reads: Used for file extensions:
+ Reader: Reads: Used for file extensions:
-----------------------------------------------------------------------------
- journal hledger's journal format, also .journal .j .hledger
- some Ledger journals .ledger
- timeclock timeclock files (precise time .timeclock
- logging)
- timedot timedot files (approximate time .timedot
- logging)
- csv comma-separated values (data .csv
- interchange)
+ journal hledger's journal format, also .journal .j .hledger
+ some Ledger journals .ledger
+ timeclock timeclock files (precise time .timeclock
+ logging)
+ timedot timedot files (approximate time .timedot
+ logging)
+ csv comma-separated values (data .csv
+ interchange)
If needed (eg to ensure correct error messages when a file has the
"wrong" extension), you can force a specific reader/format by prepend-
@@ -334,7 +341,6 @@ OPTIONS
next year january 1 of next year
this month the 1st of the current
month
-
this week the most recent monday
last week the monday of the week
before this one
@@ -357,8 +363,8 @@ OPTIONS
Examples:
- -b 2016/3/17 begin on St. Patrick's
- day 2016
+ -b 2016/3/17 begin on St. Patrick's day
+ 2016
-e 12/1 end at the start of decem-
ber 1st of the current
year (11/30 will be the
@@ -443,45 +449,100 @@ OPTIONS
-p "monthly in 2008"
-p "quarterly"
+ Note that weekly, monthly, quarterly and yearly intervals will always
+ start on the first day on week, month, quarter or year accordingly, and
+ will end on the last day of same period, even if associated period
+ expression specifies different explicit start and end date.
+
+ For example:
+
+
+ -p "weekly from 2009/1/1 to 2009/4/1" -
+ starts on 2008/12/29, closest preceed-
+ ing Monday
+ -p "monthly in 2008/11/25" - starts on
+ 2018/11/01
+
+
+
+ -p "quar-
+ terly from 2009-05-05 to 2009-06-01" -
+ starts on 2009/04/01, ends on
+ 2009/06/30, which are first and last
+ days of Q2 2009
+ -p "yearly from 2009-12-29" - starts on
+ 2009/01/01, first day of 2009
+
The following more complex report intervals are also supported:
- biweekly, bimonthly, every N days|weeks|months|quarters|years,
- every Nth day [of month], every Nth day of week.
+ biweekly, bimonthly, every day|week|month|quarter|year,
+ every N days|weeks|months|quarters|years.
+
+ All of these will start on the first day of the requested period and
+ end on the last one, as described above.
Examples:
- -p "bimonthly from 2008"
- -p "every 2 weeks"
- -p "every 5 days from 1/3"
+ -p "bimonthly from 2008" - periods will
+ have boundaries on 2008/01/01,
+ 2008/03/01, ...
+ -p "every 2 weeks" - starts on closest
+ preceeding Monday
+ -p "every 5 month from 2009/03" - peri-
+ ods will have boundaries on 2009/03/01,
+ 2009/08/01, ...
+
+ If you want intervals that start on arbitrary day of your choosing and
+ span a week, month or year, you need to use any of the following:
+
+ every Nth day of week, every <weekday>, every Nth day [of month],
+ every Nth weekday [of month], every MM/DD [of year],
+ every Nth MMM [of year], every MMM Nth [of year].
- Show historical balances at end of 15th each month (N is exclusive end
+ Examples:
+
+
+ -p "every 2nd day of week" - periods
+ will go from Tue to Tue
+ -p "every Tue" - same
+ -p "every 15th day" - period boundaries
+ will be on 15th of each month
+ -p "every 2nd Monday" - period bound-
+ aries will be on second Monday of each
+ month
+ -p "every 11/05" - yearly periods with
+ boundaries on 5th of Nov
+ -p "every 5th Nov" - same
+ -p "every Nov 5th" - same
+
+ Show historical balances at end of 15th each month (N is exclusive end
date):
hledger balance -H -p "every 16th day"
- Group postings from start of wednesday to end of next tuesday (N is
+ Group postings from start of wednesday to end of next tuesday (N is
start date and exclusive end date):
hledger register checking -p "every 3rd day of week"
Depth limiting
With the --depth N option (short form: -N), commands like account, bal-
- ance and register will show only the uppermost accounts in the account
- tree, down to level N. Use this when you want a summary with less
- detail. This flag has the same effect as a depth: query argument (so
+ ance and register will show only the uppermost accounts in the account
+ tree, down to level N. Use this when you want a summary with less
+ detail. This flag has the same effect as a depth: query argument (so
-2, --depth=2 or depth:2 are basically equivalent).
Pivoting
Normally hledger sums amounts, and organizes them in a hierarchy, based
- on account name. The --pivot FIELD option causes it to sum and orga-
- nize hierarchy based on the value of some other field instead. FIELD
+ on account name. The --pivot FIELD option causes it to sum and orga-
+ nize hierarchy based on the value of some other field instead. FIELD
can be: code, description, payee, note, or the full name (case insensi-
tive) of any tag. As with account names, values containing colon:sepa-
rated:parts will be displayed hierarchically in reports.
- --pivot is a general option affecting all reports; you can think of
+ --pivot is a general option affecting all reports; you can think of
hledger transforming the journal before any other processing, replacing
- every posting's account name with the value of the specified field on
+ every posting's account name with the value of the specified field on
that posting, inheriting it from the transaction or using a blank value
if it's not present.
@@ -507,7 +568,7 @@ OPTIONS
--------------------
0
- One way to show only amounts with a member: value (using a query,
+ One way to show only amounts with a member: value (using a query,
described below):
$ hledger balance --pivot member tag:member=.
@@ -515,7 +576,7 @@ OPTIONS
--------------------
-2 EUR
- Another way (the acct: query matches against the pivoted "account
+ Another way (the acct: query matches against the pivoted "account
name"):
$ hledger balance --pivot member acct:.
@@ -524,17 +585,18 @@ OPTIONS
-2 EUR
Cost
- The -B/--cost flag converts amounts to their cost at transaction time,
+ The -B/--cost flag converts amounts to their cost at transaction time,
if they have a transaction price specified.
Market value
- The -V/--value flag converts the reported amounts to their market value
- on the report end date, using the most recent applicable market prices,
- when known. Specifically, when there is a market price (P directive)
- for the amount's commodity, dated on or before the report end date (see
- hledger -> Report start & end date), the amount will be converted to
- the price's commodity. If multiple applicable prices are defined, the
- latest-dated one is used (and if dates are equal, the one last parsed).
+ The -V/--value flag converts reported amounts to their current market
+ value. Specifically, when there is a market price (P directive) for
+ the amount's commodity, dated on or before today's date (or the report
+ end date if specified), the amount will be converted to the price's
+ commodity.
+
+ When there are multiple applicable P directives, -V chooses the most
+ recent one, or in case of equal dates, the last-parsed one.
For example:
@@ -565,64 +627,67 @@ OPTIONS
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
- Currently, hledger's -V only uses market prices recorded with P direc-
+ Currently, hledger's -V only uses market prices recorded with P direc-
tives, not transaction prices (unlike Ledger).
- Using -B and -V together is allowed.
+ Combining -B and -V
+ Using -B/-cost and -V/-value together is currently allowed, but the
+ results are probably not meaningful. Let us know if you find a use for
+ this.
Regular expressions
hledger uses regular expressions in a number of places:
- o query terms, on the command line and in the hledger-web search form:
+ o query terms, on the command line and in the hledger-web search form:
REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
o CSV rules conditional blocks: if REGEX ...
- o account alias directives and options: alias /REGEX/ = REPLACEMENT,
+ o account alias directives and options: alias /REGEX/ = REPLACEMENT,
--alias /REGEX/=REPLACEMENT
- hledger's regular expressions come from the regex-tdfa library. In
+ hledger's regular expressions come from the regex-tdfa library. In
general they:
o are case insensitive
- o are infix matching (do not need to match the entire thing being
+ o are infix matching (do not need to match the entire thing being
matched)
o are POSIX extended regular expressions
o also support GNU word boundaries (\<, \>, \b, \B)
- o and parenthesised capturing groups and numeric backreferences in
+ o and parenthesised capturing groups and numeric backreferences in
replacement strings
o do not support mode modifiers like (?s)
Some things to note:
- o In the alias directive and --alias option, regular expressions must
- be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
+ o In the alias directive and --alias option, regular expressions must
+ be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
these are not required.
- o In queries, to match a regular expression metacharacter like $ as a
- literal character, prepend a backslash. Eg to search for amounts
+ o In queries, to match a regular expression metacharacter like $ as a
+ literal character, prepend a backslash. Eg to search for amounts
with the dollar sign in hledger-web, write cur:\$.
- o On the command line, some metacharacters like $ have a special mean-
+ o On the command line, some metacharacters like $ have a special mean-
ing to the shell and so must be escaped at least once more. See Spe-
cial characters.
QUERIES
- One of hledger's strengths is being able to quickly report on precise
- subsets of your data. Most commands accept an optional query expres-
- sion, written as arguments after the command name, to filter the data
- by date, account name or other criteria. The syntax is similar to a
+ One of hledger's strengths is being able to quickly report on precise
+ subsets of your data. Most commands accept an optional query expres-
+ sion, written as arguments after the command name, to filter the data
+ by date, account name or other criteria. The syntax is similar to a
web search: one or more space-separated search terms, quotes to enclose
- whitespace, prefixes to match specific fields, a not: prefix to negate
+ whitespace, prefixes to match specific fields, a not: prefix to negate
the match.
- We do not yet support arbitrary boolean combinations of search terms;
- instead most commands show transactions/postings/accounts which match
+ We do not yet support arbitrary boolean combinations of search terms;
+ instead most commands show transactions/postings/accounts which match
(or negatively match):
o any of the description terms AND
@@ -643,32 +708,32 @@ QUERIES
o match all the other terms.
- The following kinds of search terms can be used. Remember these can
+ The following kinds of search terms can be used. Remember these can
also be prefixed with not:, eg to exclude a particular subaccount.
- REGEX match account names by this regular expression. (No prefix is
+ REGEX match account names by this regular expression. (No prefix is
equivalent to acct:).
acct:REGEX
same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
- match postings with a single-commodity amount that is equal to,
- less than, or greater than N. (Multi-commodity amounts are not
+ match postings with a single-commodity amount that is equal to,
+ less than, or greater than N. (Multi-commodity amounts are not
tested, and will always match.) The comparison has two modes: if
N is preceded by a + or - sign (or is 0), the two signed numbers
- are compared. Otherwise, the absolute magnitudes are compared,
+ are compared. Otherwise, the absolute magnitudes are compared,
ignoring sign.
code:REGEX
match by transaction code (eg check number)
cur:REGEX
- match postings or transactions including any amounts whose cur-
- rency/commodity symbol is fully matched by REGEX. (For a par-
+ match postings or transactions including any amounts whose cur-
+ rency/commodity symbol is fully matched by REGEX. (For a par-
tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend
- \. And when using the command line you need to add one more
+ \. And when using the command line you need to add one more
level of quoting to hide it from the shell, so eg do:
hledger print cur:'\$' or hledger print cur:\\$.
@@ -677,20 +742,20 @@ QUERIES
date:PERIODEXPR
match dates within the specified period. PERIODEXPR is a period
- expression (with no report interval). Examples: date:2016,
- date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
- --date2 command line flag is present, this matches secondary
+ expression (with no report interval). Examples: date:2016,
+ date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
+ --date2 command line flag is present, this matches secondary
dates instead.
date2:PERIODEXPR
match secondary dates within the specified period.
depth:N
- match (or display, depending on command) accounts at or above
+ match (or display, depending on command) accounts at or above
this depth
note:REGEX
- match transaction notes (part of description right of |, or
+ match transaction notes (part of description right of |, or
whole description when there's no |)
payee:REGEX
@@ -704,38 +769,38 @@ QUERIES
match unmarked, pending, or cleared transactions respectively
tag:REGEX[=REGEX]
- match by tag name, and optionally also by tag value. Note a
- tag: query is considered to match a transaction if it matches
- any of the postings. Also remember that postings inherit the
+ match by tag name, and optionally also by tag value. Note a
+ tag: query is considered to match a transaction if it matches
+ any of the postings. Also remember that postings inherit the
tags of their parent transaction.
The following special search term is used automatically in hledger-web,
only:
inacct:ACCTNAME
- tells hledger-web to show the transaction register for this
+ tells hledger-web to show the transaction register for this
account. Can be filtered further with acct etc.
Some of these can also be expressed as command-line options (eg depth:2
- is equivalent to --depth 2). Generally you can mix options and query
- arguments, and the resulting query will be their intersection (perhaps
+ is equivalent to --depth 2). Generally you can mix options and query
+ arguments, and the resulting query will be their intersection (perhaps
excluding the -p/--period option).
COMMANDS
- hledger provides a number of subcommands; hledger with no arguments
+ hledger provides a number of subcommands; hledger with no arguments
shows a list.
If you install additional hledger-* packages, or if you put programs or
- scripts named hledger-NAME in your PATH, these will also be listed as
+ scripts named hledger-NAME in your PATH, these will also be listed as
subcommands.
- Run a subcommand by writing its name as first argument (eg
+ Run a subcommand by writing its name as first argument (eg
hledger incomestatement). You can also write one of the standard short
- aliases displayed in parentheses in the command list (hledger b), or
+ aliases displayed in parentheses in the command list (hledger b), or
any any unambiguous prefix of a command name (hledger inc).
- Here are all the builtin commands in alphabetical order. See also
- hledger for a more organised command list, and hledger CMD -h for
+ Here are all the builtin commands in alphabetical order. See also
+ hledger for a more organised command list, and hledger CMD -h for
detailed command help.
accounts
@@ -748,14 +813,14 @@ COMMANDS
--drop=N
in flat mode: omit N leading account name parts
- This command lists all account names that are in use (ie, all the
- accounts which have at least one transaction posting to them). With
+ This command lists all account names that are in use (ie, all the
+ accounts which have at least one transaction posting to them). With
query arguments, only matched account names are shown.
- It shows a flat list by default. With --tree, it uses indentation to
+ It shows a flat list by default. With --tree, it uses indentation to
show the account hierarchy.
- In flat mode you can add --drop N to omit the first few account name
+ In flat mode you can add --drop N to omit the first few account name
components.
Examples:
@@ -798,8 +863,8 @@ COMMANDS
activity
Show an ascii barchart of posting counts per interval.
- The activity command displays an ascii histogram showing transaction
- counts by day, week, month or other reporting interval (by day is the
+ The activity command displays an ascii histogram showing transaction
+ counts by day, week, month or other reporting interval (by day is the
default). With query arguments, it counts only matched transactions.
$ hledger activity --quarterly
@@ -812,24 +877,24 @@ COMMANDS
Prompt for transactions and add them to the journal.
--no-new-accounts
- don't allow creating new accounts; helps prevent typos when
+ don't allow creating new accounts; helps prevent typos when
entering account names
- Many hledger users edit their journals directly with a text editor, or
- generate them from CSV. For more interactive data entry, there is the
- add command, which prompts interactively on the console for new trans-
- actions, and appends them to the journal file (if there are multiple
+ Many hledger users edit their journals directly with a text editor, or
+ generate them from CSV. For more interactive data entry, there is the
+ add command, which prompts interactively on the console for new trans-
+ actions, and appends them to the journal file (if there are multiple
-f FILE options, the first file is used.) Existing transactions are not
- changed. This is the only hledger command that writes to the journal
+ changed. This is the only hledger command that writes to the journal
file.
To use it, just run hledger add and follow the prompts. You can add as
- many transactions as you like; when you are finished, enter . or press
+ many transactions as you like; when you are finished, enter . or press
control-d or control-c to exit.
Features:
- o add tries to provide useful defaults, using the most similar recent
+ o add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
o You can also set the initial defaults with command line arguments.
@@ -837,20 +902,20 @@ COMMANDS
o Readline-style edit keys can be used during data entry.
o The tab key will auto-complete whenever possible - accounts, descrip-
- tions, dates (yesterday, today, tomorrow). If the input area is
+ tions, dates (yesterday, today, tomorrow). If the input area is
empty, it will insert the default value.
- o If the journal defines a default commodity, it will be added to any
+ o If the journal defines a default commodity, it will be added to any
bare numbers entered.
o A parenthesised transaction code may be entered following a date.
o Comments and tags may be entered following a description or amount.
- o If you make a mistake, enter < at any prompt to restart the transac-
+ o If you make a mistake, enter < at any prompt to restart the transac-
tion.
- o Input prompts are displayed in a different colour when the terminal
+ o Input prompts are displayed in a different colour when the terminal
supports it.
Example (see the tutorial for a detailed explanation):
@@ -887,7 +952,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports)
-H --historical
@@ -922,17 +987,25 @@ COMMANDS
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
--pretty-tables
- Use unicode to display prettier tables.
+ use unicode to display prettier tables.
--sort-amount
- Sort by amount (total row amount, or by average if that is dis-
- played), instead of account name (in flat mode)
+ sort by amount instead of account name (in flat mode). With
+ multiple columns, sorts by the row total, or by row average if
+ that is displayed.
- The balance command displays accounts and balances. It is hledger's
+ --budget
+ show performance compared to budget goals defined by periodic
+ transactions
+
+ --show-unbudgeted
+ with -budget, show unbudgeted accounts also
+
+ The balance command displays accounts and balances. It is hledger's
most featureful and versatile command.
$ hledger balance
@@ -949,25 +1022,25 @@ COMMANDS
--------------------
0
- More precisely, the balance command shows the change to each account's
+ More precisely, the balance command shows the change to each account's
balance caused by all (matched) postings. In the common case where you
- do not filter by date and your journal sets the correct opening bal-
+ do not filter by date and your journal sets the correct opening bal-
ances, this is the same as the account's ending balance.
- By default, accounts are displayed hierarchically, with subaccounts
+ By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. "Boring" accounts, which contain a single
interesting subaccount and no balance of their own, are elided into the
- following line for more compact output. (Use --no-elide to prevent
- this. Eliding of boring accounts is not yet supported in multicolumn
+ following line for more compact output. (Use --no-elide to prevent
+ this. Eliding of boring accounts is not yet supported in multicolumn
reports.)
- Each account's balance is the "inclusive" balance - it includes the
+ Each account's balance is the "inclusive" balance - it includes the
balances of any subaccounts.
- Accounts which have zero balance (and no non-zero subaccounts) are
+ Accounts which have zero balance (and no non-zero subaccounts) are
omitted. Use -E/--empty to show them.
- A final total is displayed by default; use -N/--no-total to suppress
+ A final total is displayed by default; use -N/--no-total to suppress
it:
$ hledger balance -p 2008/6 expenses --no-total
@@ -977,9 +1050,9 @@ COMMANDS
Flat mode
To see a flat list of full account names instead of the default hierar-
- chical display, use --flat. In this mode, accounts (unless
+ chical display, use --flat. In this mode, accounts (unless
depth-clipped) show their "exclusive" balance, excluding any subaccount
- balances. In this mode, you can also use --drop N to omit the first
+ balances. In this mode, you can also use --drop N to omit the first
few account name components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
@@ -987,9 +1060,9 @@ COMMANDS
$1 supplies
Depth limited balance reports
- With --depth N, balance shows accounts only to the specified depth.
- This is very useful to show a complex charts of accounts in less
- detail. In flat mode, balances from accounts below the depth limit
+ With --depth N, balance shows accounts only to the specified depth.
+ This is very useful to show a complex charts of accounts in less
+ detail. In flat mode, balances from accounts below the depth limit
will be shown as part of a parent account at the depth limit.
$ hledger balance -N --depth 1
@@ -999,12 +1072,12 @@ COMMANDS
$1 liabilities
Multicolumn balance reports
- With a reporting interval, multiple balance columns will be shown, one
- for each report period. There are three types of multi-column balance
+ With a reporting interval, multiple balance columns will be shown, one
+ for each report period. There are three types of multi-column balance
report, showing different information:
1. By default: each column shows the sum of postings in that period, ie
- the account's change of balance in that period. This is useful eg
+ the account's change of balance in that period. This is useful eg
for a monthly income statement:
$ hledger balance --quarterly income expenses -E
@@ -1019,8 +1092,8 @@ COMMANDS
-------------------++---------------------------------
|| $-1 $1 0 0
- 2. With --cumulative: each column shows the ending balance for that
- period, accumulating the changes across periods, starting from 0 at
+ 2. With --cumulative: each column shows the ending balance for that
+ period, accumulating the changes across periods, starting from 0 at
the report start date:
$ hledger balance --quarterly income expenses -E --cumulative
@@ -1036,8 +1109,8 @@ COMMANDS
|| $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending
- balance for that period, accumulating the changes across periods,
- starting from the actual balance at the report start date. This is
+ balance for that period, accumulating the changes across periods,
+ starting from the actual balance at the report start date. This is
useful eg for a multi-period balance sheet, and when you are showing
only the data after a certain start date:
@@ -1053,26 +1126,26 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
- Multi-column balance reports display accounts in flat mode by default;
+ Multi-column balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
- With a reporting interval (like --quarterly above), the report
- start/end dates will be adjusted if necessary so that they encompass
+ With a reporting interval (like --quarterly above), the report
+ start/end dates will be adjusted if necessary so that they encompass
the displayed report periods. This is so that the first and last peri-
ods will be "full" and comparable to the others.
- The -E/--empty flag does two things in multicolumn balance reports:
- first, the report will show all columns within the specified report
- period (without -E, leading and trailing columns with all zeroes are
- not shown). Second, all accounts which existed at the report start
- date will be considered, not just the ones with activity during the
+ The -E/--empty flag does two things in multicolumn balance reports:
+ first, the report will show all columns within the specified report
+ period (without -E, leading and trailing columns with all zeroes are
+ not shown). Second, all accounts which existed at the report start
+ date will be considered, not just the ones with activity during the
report period (use -E to include low-activity accounts which would oth-
erwise would be omitted).
The -T/--row-total flag adds an additional column showing the total for
each row.
- The -A/--average flag adds a column showing the average value in each
+ The -A/--average flag adds a column showing the average value in each
row.
Here's an example of all three:
@@ -1093,6 +1166,93 @@ COMMANDS
# Average is rounded to the dollar here since all journal amounts are
+ Budgets
+ With --budget and a report interval, all periodic transactions in your
+ journal with that interval, active during the requested report period,
+ are interpreted as recurring budget goals for the specified accounts
+ (and subaccounts), and the report will show the difference between
+ actual and budgeted balances.
+
+ For example, you can take average monthly expenses in the common
+ expense categories to construct a minimal monthly budget:
+
+ ;; Budget
+ ~ monthly
+ income $2000
+ expenses:food $400
+ expenses:bus $50
+ expenses:movies $30
+ assets:bank:checking
+
+ ;; Two months worth of expenses
+ 2017-11-01
+ income $1950
+ expenses:food $396
+ expenses:bus $49
+ expenses:movies $30
+ expenses:supplies $20
+ assets:bank:checking
+
+ 2017-12-01
+ income $2100
+ expenses:food $412
+ expenses:bus $53
+ expenses:gifts $100
+ assets:bank:checking
+
+ You can now see a monthly budget performance report:
+
+ $ hledger balance -M --budget
+ Balance changes in 2017/11/01-2017/12/31:
+
+ || 2017/11 2017/12
+ =======================++=================================================
+ <unbudgeted>:expenses || $20 $100
+ assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
+ expenses:bus || $49 [98% of $50] $53 [106% of $50]
+ expenses:food || $396 [99% of $400] $412 [103% of $400]
+ expenses:movies || $30 [100% of $30] 0 [0% of $30]
+ income || $1950 [98% of $2000] $2100 [105% of $2000]
+ -----------------------++-------------------------------------------------
+ || 0 0
+
+ You can roll over unspent budgets to next period with --cumulative:
+
+ $ hledger balance -M --budget --cumulative
+ Ending balances (cumulative) in 2017/11/01-2017/12/31:
+
+ || 2017/11/30 2017/12/31
+ =======================++=================================================
+ <unbudgeted>:expenses || $20 $120
+ assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
+ expenses:bus || $49 [98% of $50] $102 [102% of $100]
+ expenses:food || $396 [99% of $400] $808 [101% of $800]
+ expenses:movies || $30 [100% of $30] $30 [50% of $60]
+ income || $1950 [98% of $2000] $4050 [101% of $4000]
+ -----------------------++-------------------------------------------------
+ || 0 0
+
+ Accounts with no budget goals (not mentioned in the periodic transac-
+ tions) will be aggregated under <unbudgeted>, unless you add the
+ --show-unbudgeted flag to display them normally:
+
+ $ hledger balance --budget --show-unbudgeted
+ Balance changes in 2017/11/01-2017/12/31:
+
+ || 2017/11 2017/12
+ ======================++=================================================
+ assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
+ expenses:bus || $49 [98% of $50] $53 [106% of $50]
+ expenses:food || $396 [99% of $400] $412 [103% of $400]
+ expenses:gifts || 0 $100
+ expenses:movies || $30 [100% of $30] 0 [0% of $30]
+ expenses:supplies || $20 0
+ income || $1950 [98% of $2000] $2100 [105% of $2000]
+ ----------------------++-------------------------------------------------
+ || 0 0
+
+ For more examples and details, see Budgeting and Forecasting.
+
Custom balance output
In simple (non-multi-column) balance reports, you can customise the
output with --format FMT:
@@ -1404,12 +1564,18 @@ COMMANDS
--dry-run
just show the transactions to be imported
- Input files are provided as arguments, or glob patterns. So eg to add
- new transactions from all CSV files to the main journal: hledger import
- *.csv
+ The input files are specified as arguments - no need to write -f before
+ each one. So eg to add new transactions from all CSV files to the main
+ journal, it's just: hledger import *.csv
- New transactions are detected like print --new (using .latest.FILE
- state files).
+ New transactions are detected in the same way as print -new: by assum-
+ ing transactions are always added to the input files in increasing date
+ order, and by saving .latest.FILE state files.
+
+ The -dry-run output is in journal format, so you can filter it, eg to
+ see only uncategorised transactions:
+
+ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
incomestatement
Show an income statement. Alias: is.
@@ -1543,7 +1709,7 @@ COMMANDS
put.
With -B/--cost, amounts with transaction prices are converted to cost
- using that price.
+ using that price. This can be used for troubleshooting.
With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is
@@ -1613,7 +1779,7 @@ COMMANDS
-A --average
show running average of posting amounts instead of total
- (implies --empty)
+ (implies -empty)
-r --related
show postings' siblings instead
@@ -1703,7 +1869,7 @@ COMMANDS
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
- description width as part of --width's argument, comma-separated:
+ description width as part of -width's argument, comma-separated:
--width W,D . Here's a diagram:
<--------------------------------- width (W) ---------------------------------->
@@ -1757,7 +1923,10 @@ COMMANDS
destination.
tags
- List all the tag names in use.
+ List all the tag names used in the journal. With a TAGREGEX argument,
+ only tag names matching the regular expression (case insensitive) are
+ shown. With additional QUERY arguments, only transactions matching the
+ query are considered.
test
Run built-in unit tests.
@@ -1765,34 +1934,34 @@ COMMANDS
$ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
- This command runs hledger's built-in unit tests and displays a quick
+ This command runs hledger's built-in unit tests and displays a quick
report. With a regular expression argument, it selects only tests with
matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.
ADD-ON COMMANDS
- hledger also searches for external add-on commands, and will include
+ hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
- whose name starts with hledger- and ends with a recognised file exten-
+ whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
- Add-ons can be invoked like any hledger command, but there are a few
+ Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
- o Flags specific to the add-on must have a preceding -- to hide them
- from hledger. So hledger web --serve --port 9000 will be rejected;
+ o Flags specific to the add-on must have a preceding -- to hide them
+ from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
- o You can always run add-ons directly if preferred:
+ o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
- Add-ons are a relatively easy way to add local features or experiment
- with new ideas. They can be written in any language, but haskell
- scripts have a big advantage: they can use the same hledger (and
- haskell) library functions that built-in commands do, for command-line
+ Add-ons are a relatively easy way to add local features or experiment
+ with new ideas. They can be written in any language, but haskell
+ scripts have a big advantage: they can use the same hledger (and
+ haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
@@ -1810,7 +1979,7 @@ ADD-ON COMMANDS
hledger-web provides a simple web interface.
Third party add-ons
- These are maintained separately, and usually updated shortly after a
+ These are maintained separately, and usually updated shortly after a
hledger release.
diff
@@ -1818,7 +1987,7 @@ ADD-ON COMMANDS
journal file and another.
iadd
- hledger-iadd is a curses-style, more interactive replacement for the
+ hledger-iadd is a curses-style, more interactive replacement for the
add command.
interest
@@ -1826,19 +1995,19 @@ ADD-ON COMMANDS
ing to various schemes.
irr
- hledger-irr calculates the internal rate of return of an investment
+ hledger-irr calculates the internal rate of return of an investment
account.
Experimental add-ons
- These are available in source form in the hledger repo's bin/ direc-
+ These are available in source form in the hledger repo's bin/ direc-
tory; installing them is pretty easy. They may be less mature and doc-
- umented than built-in commands. Reading and tweaking these is a good
+ umented than built-in commands. Reading and tweaking these is a good
way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
- if installed. ledger-autosync does deduplicating conversion of OFX
- data and some CSV formats, and can also download the data if your bank
+ if installed. ledger-autosync does deduplicating conversion of OFX
+ data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
budget
@@ -1851,21 +2020,21 @@ ADD-ON COMMANDS
hledger-check.hs checks more powerful account balance assertions.
ENVIRONMENT
- COLUMNS The screen width used by the register command. Default: the
+ COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
- Reads data from one or more files in hledger journal, timeclock, time-
- dot, or CSV format specified with -f, or $LEDGER_FILE, or
- $HOME/.hledger.journal (on windows, perhaps
+ Reads data from one or more files in hledger journal, timeclock, time-
+ dot, or CSV format specified with -f, or $LEDGER_FILE, or
+ $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
- The need to precede addon command options with -- when invoked from
+ The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@@ -1878,33 +2047,33 @@ BUGS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
- Not all of Ledger's journal file syntax is supported. See file format
+ Not all of Ledger's journal file syntax is supported. See file format
differences.
- On large data files, hledger is slower and uses more memory than
+ On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
- Here are some issues you might encounter when you run hledger (and
- remember you can also seek help from the IRC channel, mail list or bug
+ Here are some issues you might encounter when you run hledger (and
+ remember you can also seek help from the IRC channel, mail list or bug
tracker):
- Successfully installed, but "No command 'hledger' found"
+ Successfully installed, but "No command `hledger' found"
stack and cabal install binaries into a special directory, which should
- be added to your PATH environment variable. Eg on unix-like systems,
+ be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
- LEDGER_FILE should be a real environment variable, not just a shell
- variable. The command env | grep LEDGER_FILE should show it. You may
+ LEDGER_FILE should be a real environment variable, not just a shell
+ variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
- "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
+ "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
- ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
+ ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu
@@ -1923,7 +2092,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
- If we preferred to use eg fr_FR.utf8, we might have to install that
+ If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr
@@ -1944,7 +2113,7 @@ TROUBLESHOOTING
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)
@@ -1958,7 +2127,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -1966,4 +2135,4 @@ SEE ALSO
-hledger 1.4 September 2017 hledger(1)
+hledger 1.5 December 2017 hledger(1)