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

update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2018-06-30 22:08:48 +01:00
parent 6242b1d784
commit 22f2e90a4b
17 changed files with 622 additions and 308 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,5 +1,5 @@
.TH "hledger\-api" "1" "March 2018" "hledger\-api 1.9.99" "hledger User Manuals"
.TH "hledger\-api" "1" "June 2018" "hledger\-api 1.9.99" "hledger User Manuals"

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

@ -117,4 +117,4 @@ SEE ALSO
hledger-api 1.9.99 March 2018 hledger-api(1)
hledger-api 1.9.99 June 2018 hledger-api(1)

2
hledger-lib/hledger_csv.5
View File

@ -1,5 +1,5 @@
.TH "hledger_csv" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals"
.TH "hledger_csv" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals"

2
hledger-lib/hledger_csv.txt
View File

@ -249,4 +249,4 @@ SEE ALSO
hledger 1.9.99 March 2018 hledger_csv(5)
hledger 1.9.99 June 2018 hledger_csv(5)

303
hledger-lib/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_journal" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals"
.TH "hledger_journal" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals"
@ -825,50 +825,173 @@ simple strings.
.PP
A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed.
Some directives may also have indented sub\-directives on the following
lines (\f[C]commodity\f[]).
.SS Directive scope, multiple files
hledger's directives are based on a subset of Ledger's, but there are
many differences (and also some differences between hledger versions).
.PP
Directives vary in which journal entries they affect:
.IP \[bu] 2
some form a begin/end pair, and affect the enclosed journal entries (and
included files):
.PD 0
.P
.PD
\f[C]alias\f[] & \f[C]end\ aliases\f[]; \f[C]comment\f[] &
Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with links
to more detailed docs.
.PP
.TS
tab(@);
lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n).
T{
directive
T}@T{
end directive
T}@T{
subdirectives
T}@T{
purpose
T}@T{
can affect (as of 2018/06)
T}
_
T{
\f[C]account\f[]
T}@T{
T}@T{
any text
T}@T{
declare an account name & optional account code
T}@T{
account code: balance reports (except \f[C]balance\f[] single\-column
mode)
T}
T{
\f[C]alias\f[]
T}@T{
\f[C]end\ aliases\f[]
T}@T{
T}@T{
rewrite account names
T}@T{
following inline/included entries until end of current file or end
directive
T}
T{
\f[C]apply\ account\f[]
T}@T{
\f[C]end\ apply\ account\f[]
T}@T{
T}@T{
prepend a common parent to account names
T}@T{
following inline/included entries until end of current file or end
directive
T}
T{
\f[C]comment\f[]
T}@T{
\f[C]end\ comment\f[]
.IP \[bu] 2
some affect the subsequent journal entries (and included files) in the
current file:
.PD 0
.P
.PD
\f[C]alias\f[] or \f[C]comment\f[] without an end directive, \f[C]Y\f[]
.IP \[bu] 2
some affect all journal entries (and included files) anywhere in the
current file:
.PD 0
.P
.PD
\f[C]account\f[], \f[C]commodity\f[], \f[C]D\f[], \f[C]P\f[].
T}@T{
T}@T{
ignore part of journal
T}@T{
following inline/included entries until end of current file or end
directive
T}
T{
\f[C]commodity\f[]
T}@T{
T}@T{
\f[C]format\f[]
T}@T{
declare a commodity and its number notation & display style
T}@T{
number notation: following entries in that commodity in all files;
display style: amounts of that commodity in reports
T}
T{
\f[C]D\f[]
T}@T{
T}@T{
T}@T{
declare a commodity, number notation & display style for commodityless
amounts
T}@T{
commodity: all commodityless entries in all files; number notation:
following commodityless entries and entries in that commodity in all
files; display style: amounts of that commodity in reports
T}
T{
\f[C]include\f[]
T}@T{
T}@T{
T}@T{
include entries/directives from another file
T}@T{
what the included directives affect
T}
T{
\f[C]P\f[]
T}@T{
T}@T{
T}@T{
declare a market price for a commodity
T}@T{
amounts of that commodity in reports, when \-V is used
T}
T{
\f[C]Y\f[]
T}@T{
T}@T{
T}@T{
declare a year for yearless dates
T}@T{
following inline/included entries until end of current file
T}
.TE
.PP
It's important to note that directives can affect the current file and
child (included) files, but not sibling or parent (including) files.
This is by design, for simplicity and predictability of reports, but it
can be surprising at times.
Eg, in:
.IP
.nf
\f[C]
hledger\ \-f\ a.prices\ \-f\ b.journal
\f[]
.fi
And some definitions:
.PP
the prices defined in a.prices will not be effective in b.journal (a
sibling file).
Instead, you have to include (or inline) a.prices in b.journal, or vice
versa.
.TS
tab(@);
lw(8.9n) lw(61.1n).
T{
subdirective
T}@T{
optional indented directive or unparsed text lines immediately following
a parent directive
T}
T{
account code
T}@T{
numeric code influencing account display order in most balance reports
T}
T{
number notation
T}@T{
how to interpret numbers when parsing journal entries (the identity of
the decimal separator character).
(Currently each commodity can have its own notation, even in the same
file.)
T}
T{
display style
T}@T{
how to display amounts of a commodity in reports (symbol side and
spacing, digit groups, decimal separator, decimal places)
T}
T{
directive scope
T}@T{
which entries and (when there are multiple files) which files are
affected by a directive
T}
.TE
.PP
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
(reports).
Some directives have multiple effects.
.PP
If you have a journal made up of multiple files, or pass multiple \-f
options on the command line, note that directives which affect input
typically last only until the end of their defining file.
This provides more simplicity and predictability, eg reports are not
changed by writing file options in a different order.
It can be surprising at times though.
.SS Comment blocks
.PP
A line containing just \f[C]comment\f[] starts a commented region of the
@ -1047,11 +1170,24 @@ account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
\f[]
.fi
.PP
This affects account display order in reports: accounts with codes are
listed before accounts without codes, in increasing code order.
(Otherwise, accounts are listed alphabetically.) Account codes should be
all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces).
This affects how accounts are sorted in account and balance reports:
accounts with codes are listed before accounts without codes, and in
increasing code order (instead of listing all accounts alphabetically).
Warning, this feature is incomplete; account codes do not yet affect
sort order in
.IP \[bu] 2
the \f[C]accounts\f[] command
.IP \[bu] 2
the \f[C]balance\f[] command's single\-column mode
.IP \[bu] 2
flat mode balance reports (to work around this, declare account codes on
the subaccounts as well).
.IP \[bu] 2
hledger\-web's sidebar
.PP
Account codes should be all numeric digits, unique, and separated from
the account name by at least two spaces (since account names may contain
single spaces).
By convention, often the first digit indicates the type of account, as
in this numbering scheme and the example above.
In future, we might use this to recognize account types.
@ -1072,9 +1208,9 @@ account\ assets:bank:checking\ \ \ 1110
.fi
.SS Rewriting accounts
.PP
You can define aliases which rewrite your account names (after reading
the journal, before generating reports).
hledger's account aliases can be useful for:
You can define account alias rules which rewrite your account names, or
parts of them, before generating reports.
This can be useful for:
.IP \[bu] 2
expanding shorthand account names to their full form, allowing easier
data entry and a less verbose journal
@ -1086,6 +1222,10 @@ combining two accounts into one
.IP \[bu] 2
customising reports
.PP
Account aliases also rewrite account names in account directives.
They do not affect account names being entered via hledger add or
hledger\-web.
.PP
See also Cookbook: Rewrite account names.
.SS Basic aliases
.PP
@ -1106,7 +1246,7 @@ command line.
This affects all entries.
It's useful for trying out aliases interactively.
.PP
OLD and NEW are full account names.
OLD and NEW are case sensitive full account names.
hledger will replace any occurrence of the old account name with the new
one.
Subaccounts are also affected.
@ -1216,16 +1356,22 @@ include\ personal.journal
.PP
Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported.
.PP
A default parent account also affects account directives.
It does not affect account names being entered via hledger add or
hledger\-web.
If account aliases are present, they are applied after the default
parent account.
.SS Periodic transactions
.PP
Periodic transaction rules describe transactions that recur.
They allow you to generate future transactions for forecast reports
(with \f[C]\-\-forecast\f[]), without having to write them out
explicitly in the journal.
They allow you to generate future transactions for forecasting, without
having to write them out explicitly in the journal (with
\f[C]\-\-forecast\f[]).
Secondly, they also can be used to define budget goals (with
\f[C]\-\-budget\f[]).
.PP
A periodic transaction rule looks like a regular journal entry, with the
A periodic transaction rule looks like a normal journal entry, with the
date replaced by a tilde (\f[C]~\f[]) followed by a period expression
(mnemonic: \f[C]~\f[] looks like a repeating sine wave):
.IP
@ -1242,9 +1388,8 @@ date must fall on a natural boundary of the interval.
Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
\f[C]monthly\ from\ 2018/1/15\f[] is not.
.PP
Also, if you write a transaction description or same\-line comment, it
must be separated from the period expression by \f[B]two or more
spaces\f[].
If you write a transaction description or same\-line comment, it must be
separated from the period expression by \f[B]two or more spaces\f[].
Eg:
.IP
.nf
@ -1257,30 +1402,34 @@ Eg:
\ \ \ \ income:acme\ inc
\f[]
.fi
.SS Generating forecasts with periodic transactions
.SS Forecasting with periodic transactions
.PP
With the \f[C]\-\-forecast\f[] flag, each periodic transaction rule
generates future transactions recurring at the specified interval,
beginning the day after the latest recorded journal transaction (or
today, if there are no transactions), and ending 6 months from today (or
at the report end date, if specified).
The generated transactions will appear in all reports.
They will have a \[lq]recur:\[rq] transaction tag added, with the
generating period expression as its value.
generates future transactions recurring at the specified interval.
These are not saved in the journal, but appear in all reports.
They will look like normal transactions, but with an extra tag named
\f[C]recur\f[], whose value is the generating period expression.
.PP
This can be useful for forecasting balances into the future, and
experimenting with different scenarios, without having to write a lot of
journal entries.
It can also help with data entry (describe most of your transactions
with periodic rules, and every so often copy the output of
\f[C]print\ \-\-forecast\f[] to the journal).
Forecast transactions begin on or after the day after the latest normal
(non\-periodic) transaction in the journal, or today if there are none.
.PP
You can generate one\-time transactions too; just write a period
They end on or before the report end date if specified, or 180 days from
today if unspecified.
.PP
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios.
Note the start date logic means that forecasted transactions are
automatically replaced by normal transactions as you add those.
.PP
Forecasting can also help with data entry: describe most of your
transactions with periodic rules, and every so often copy the output of
\f[C]print\ \-\-forecast\f[] to the journal.
.PP
You can generate one\-time transactions too: just write a period
expression specifying a date with no report interval.
You could use this to forecast an estimated transaction, that is
automatically deactivated once the actual transaction (or any other
transaction on or after that date) is recorded.
.SS Setting budget goals with periodic transactions
(You could also write a normal transaction with a future date, but
remember this disables forecast transactions on previous dates.)
.SS Budgeting with periodic transactions
.PP
With the \f[C]\-\-budget\f[] flag, currently supported by the balance
command, each periodic transaction rule declares recurring budget goals
@ -1297,7 +1446,7 @@ Automated posting rules describe extra postings that should be added to
certain transactions at report time, when the \f[C]\-\-auto\f[] flag is
used.
.PP
An automated posting rule looks like a regular journal entry, except the
An automated posting rule looks like a normal journal entry, except the
first line is an equal sign (\f[C]=\f[]) followed by a query (mnemonic:
\f[C]=\f[] looks like posting lines):
.IP

341
hledger-lib/hledger_journal.info
View File

@ -755,11 +755,97 @@ File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Pr
===============
A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. Some directives may also
have indented sub-directives on the following lines ('commodity').
that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex,
so here is a table summarising the directives and their effects, with
links to more detailed docs.
directiveend subdirectivespurpose can affect (as of
directive 2018/06)
-----------------------------------------------------------------------------
'account' any declare an account name & account code:
text optional account code balance reports
(except 'balance'
single-column
mode)
'alias' 'end rewrite account names following
aliases' inline/included
entries until end
of current file
or end directive
'apply 'end prepend a common parent to following
account' apply account names inline/included
account' entries until end
of current file
or end directive
'comment''end ignore part of journal following
comment' inline/included
entries until end
of current file
or end directive
'commodity' 'format'declare a commodity and its number notation:
number notation & display following entries
style in that commodity
in all files;
display style:
amounts of that
commodity in
reports
'D' declare a commodity, number commodity: all
notation & display style commodityless
for commodityless amounts entries in all
files; number
notation:
following
commodityless
entries and
entries in that
commodity in all
files; display
style: amounts of
that commodity in
reports
'include' include entries/directives what the included
from another file directives affect
'P' declare a market price for amounts of that
a commodity commodity in
reports, when -V
is used
'Y' declare a year for yearless following
dates inline/included
entries until end
of current file
And some definitions:
subdirectiveoptional indented directive or unparsed text lines
immediately following a parent directive
account numeric code influencing account display order in most
code balance reports
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
directive which entries and (when there are multiple files) which files
scope are affected by a directive
As you can see, directives vary in which journal entries and files
they affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This provides
more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
times though.
* Menu:
* Directive scope multiple files::
* Comment blocks::
* Including other files::
* Default year::
@ -771,38 +857,9 @@ have indented sub-directives on the following lines ('commodity').
* Default parent account::

File: hledger_journal.info, Node: Directive scope multiple files, Next: Comment blocks, Up: Directives
File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives
1.14.1 Directive scope, multiple files
--------------------------------------
Directives vary in which journal entries they affect:
* some form a begin/end pair, and affect the enclosed journal entries
(and included files):
'alias' & 'end aliases'; 'comment' & 'end comment'
* some affect the subsequent journal entries (and included files) in
the current file:
'alias' or 'comment' without an end directive, 'Y'
* some affect all journal entries (and included files) anywhere in
the current file:
'account', 'commodity', 'D', 'P'.
It's important to note that directives can affect the current file
and child (included) files, but not sibling or parent (including) files.
This is by design, for simplicity and predictability of reports, but it
can be surprising at times. Eg, in:
hledger -f a.prices -f b.journal
the prices defined in a.prices will not be effective in b.journal (a
sibling file). Instead, you have to include (or inline) a.prices in
b.journal, or vice versa.

File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directive scope multiple files, Up: Directives
1.14.2 Comment blocks
1.14.1 Comment blocks
---------------------
A line containing just 'comment' starts a commented region of the file,
@ -812,7 +869,7 @@ file) ends it. See also comments.

File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives
1.14.3 Including other files
1.14.2 Including other files
----------------------------
You can pull in the content of additional files by writing an include
@ -829,7 +886,7 @@ include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives
1.14.4 Default year
1.14.3 Default year
-------------------
You can set a default year to be used for subsequent dates which don't
@ -855,7 +912,7 @@ Y2010 ; change default year to 2010

File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives
1.14.5 Declaring commodities
1.14.4 Declaring commodities
----------------------------
The 'commodity' directive declares commodities which may be used in the
@ -893,7 +950,7 @@ or more decimal digits).

File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
1.14.6 Default commodity
1.14.5 Default commodity
------------------------
The 'D' directive sets a default commodity (and display format), to be
@ -916,7 +973,7 @@ with a decimal point.

File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives
1.14.7 Market prices
1.14.6 Market prices
--------------------
The 'P' directive declares a market price, which is an exchange rate
@ -946,7 +1003,7 @@ another commodity using these prices.

File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives
1.14.8 Declaring accounts
1.14.7 Declaring accounts
-------------------------
The 'account' directive predeclares account names. The simplest form is
@ -966,14 +1023,23 @@ account liabilities 2000
account revenues 4000
account expenses 6000
This affects account display order in reports: accounts with codes
are listed before accounts without codes, in increasing code order.
(Otherwise, accounts are listed alphabetically.) Account codes should
be all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces). By
convention, often the first digit indicates the type of account, as in
this numbering scheme and the example above. In future, we might use
this to recognize account types.
This affects how accounts are sorted in account and balance reports:
accounts with codes are listed before accounts without codes, and in
increasing code order (instead of listing all accounts alphabetically).
Warning, this feature is incomplete; account codes do not yet affect
sort order in
* the 'accounts' command
* the 'balance' command's single-column mode
* flat mode balance reports (to work around this, declare account
codes on the subaccounts as well).
* hledger-web's sidebar
Account codes should be all numeric digits, unique, and separated
from the account name by at least two spaces (since account names may
contain single spaces). By convention, often the first digit indicates
the type of account, as in this numbering scheme and the example above.
In future, we might use this to recognize account types.
An account directive can also have indented subdirectives following
it, which are currently ignored. Here is the full syntax:
@ -988,12 +1054,11 @@ account assets:bank:checking 1110

File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
1.14.9 Rewriting accounts
1.14.8 Rewriting accounts
-------------------------
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
You can define account alias rules which rewrite your account names, or
parts of them, before generating reports. This can be useful for:
* expanding shorthand account names to their full form, allowing
easier data entry and a less verbose journal
@ -1002,6 +1067,10 @@ be useful for:
or combining two accounts into one
* customising reports
Account aliases also rewrite account names in account directives.
They do not affect account names being entered via hledger add or
hledger-web.
See also Cookbook: Rewrite account names.
* Menu:
@ -1013,7 +1082,7 @@ be useful for:

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
1.14.9.1 Basic aliases
1.14.8.1 Basic aliases
......................
To set an account alias, use the 'alias' directive in your journal file.
@ -1026,9 +1095,9 @@ alias OLD = NEW
This affects all entries. It's useful for trying out aliases
interactively.
OLD and NEW are full account names. hledger will replace any
occurrence of the old account name with the new one. Subaccounts are
also affected. Eg:
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence 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"
@ -1036,7 +1105,7 @@ alias checking = assets:bank:wells fargo:checking

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.9.2 Regex aliases
1.14.8.2 Regex aliases
......................
There is also a more powerful variant that uses a regular expression,
@ -1061,7 +1130,7 @@ whitespace.

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.9.3 Multiple aliases
1.14.8.3 Multiple aliases
.........................
You can define as many aliases as you like using directives or
@ -1077,7 +1146,7 @@ following order:

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts
1.14.9.4 'end aliases'
1.14.8.4 'end aliases'
......................
You can clear (forget) all currently defined aliases with the 'end
@ -1088,8 +1157,8 @@ end aliases

File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
1.14.10 Default parent account
------------------------------
1.14.9 Default parent account
-----------------------------
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
@ -1121,6 +1190,11 @@ include personal.journal
Prior to hledger 1.0, legacy 'account' and 'end' spellings were also
supported.
A default parent account also affects account directives. It does
not affect account names being entered via hledger add or hledger-web.
If account aliases are present, they are applied after the default
parent account.

File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: Directives, Up: FILE FORMAT
@ -1128,12 +1202,11 @@ File: hledger_journal.info, Node: Periodic transactions, Next: Automated posti
==========================
Periodic transaction rules describe transactions that recur. They allow
you to generate future transactions for forecast reports (with
'--forecast'), without having to write them out explicitly in the
journal. Secondly, they also can be used to define budget goals (with
'--budget').
you to generate future transactions for forecasting, without having to
write them out explicitly in the journal (with '--forecast'). Secondly,
they also can be used to define budget goals (with '--budget').
A periodic transaction rule looks like a regular journal entry, with
A periodic transaction rule looks like a normal journal entry, with
the date replaced by a tilde ('~') followed by a period expression
(mnemonic: '~' looks like a repeating sine wave):
@ -1145,9 +1218,8 @@ the date replaced by a tilde ('~') followed by a period expression
date must fall on a natural boundary of the interval. Eg 'monthly from
2018/1/1' is valid, but 'monthly from 2018/1/15' is not.
Also, if you write a transaction description or same-line comment, it
must be separated from the period expression by *two or more spaces*.
Eg:
If you write a transaction description or same-line comment, it must
be separated from the period expression by *two or more spaces*. Eg:
; 2 or more spaces
; ||
@ -1158,40 +1230,47 @@ Eg:
* Menu:
* Generating forecasts with periodic transactions::
* Setting budget goals with periodic transactions::
* Forecasting with periodic transactions::
* Budgeting with periodic transactions::

File: hledger_journal.info, Node: Generating forecasts with periodic transactions, Next: Setting budget goals with periodic transactions, Up: Periodic transactions
File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Up: Periodic transactions
1.15.1 Generating forecasts with periodic transactions
------------------------------------------------------
1.15.1 Forecasting with periodic transactions
---------------------------------------------
With the '--forecast' flag, each periodic transaction rule generates
future transactions recurring at the specified interval, beginning the
day after the latest recorded journal transaction (or today, if there
are no transactions), and ending 6 months from today (or at the report
end date, if specified). The generated transactions will appear in all
reports. They will have a "recur:" transaction tag added, with the
generating period expression as its value.
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named 'recur', whose value is
the generating period expression.
This can be useful for forecasting balances into the future, and
experimenting with different scenarios, without having to write a lot of
journal entries. It can also help with data entry (describe most of
your transactions with periodic rules, and every so often copy the
output of 'print --forecast' to the journal).
Forecast transactions begin on or after the day after the latest
normal (non-periodic) transaction in the journal, or today if there are
none.
You can generate one-time transactions too; just write a period
expression specifying a date with no report interval. You could use
this to forecast an estimated transaction, that is automatically
deactivated once the actual transaction (or any other transaction on or
after that date) is recorded.
They end on or before the report end date if specified, or 180 days
from today if unspecified.
Forecasting can be useful for estimating balances into the future,
and experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your
transactions with periodic rules, and every so often copy the output of
'print --forecast' to the journal.
You can generate one-time transactions too: just write a period
expression specifying a date with no report interval. (You could also
write a normal transaction with a future date, but remember this
disables forecast transactions on previous dates.)

File: hledger_journal.info, Node: Setting budget goals with periodic transactions, Prev: Generating forecasts with periodic transactions, Up: Periodic transactions
File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions
1.15.2 Setting budget goals with periodic transactions
------------------------------------------------------
1.15.2 Budgeting with periodic transactions
-------------------------------------------
With the '--budget' flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
@ -1212,7 +1291,7 @@ File: hledger_journal.info, Node: Automated postings, Prev: Periodic transacti
Automated posting rules describe extra postings that should be added to
certain transactions at report time, when the '--auto' flag is used.
An automated posting rule looks like a regular journal entry, except
An automated posting rule looks like a normal journal entry, except
the first line is an equal sign ('=') followed by a query (mnemonic: '='
looks like posting lines):
@ -1325,43 +1404,41 @@ Node: Tags26398
Ref: #tags26516
Node: Directives27918
Ref: #directives28061
Node: Directive scope multiple files28517
Ref: #directive-scope-multiple-files28705
Node: Comment blocks29655
Ref: #comment-blocks29839
Node: Including other files30015
Ref: #including-other-files30195
Node: Default year30584
Ref: #default-year30753
Node: Declaring commodities31176
Ref: #declaring-commodities31359
Node: Default commodity32586
Ref: #default-commodity32762
Node: Market prices33398
Ref: #market-prices33563
Node: Declaring accounts34404
Ref: #declaring-accounts34580
Node: Rewriting accounts35927
Ref: #rewriting-accounts36112
Node: Basic aliases36716
Ref: #basic-aliases36862
Node: Regex aliases37552
Ref: #regex-aliases37723
Node: Multiple aliases38441
Ref: #multiple-aliases38616
Node: end aliases39114
Ref: #end-aliases39261
Node: Default parent account39362
Ref: #default-parent-account39530
Node: Periodic transactions40189
Ref: #periodic-transactions40368
Node: Generating forecasts with periodic transactions41609
Ref: #generating-forecasts-with-periodic-transactions41890
Node: Setting budget goals with periodic transactions42983
Ref: #setting-budget-goals-with-periodic-transactions43264
Node: Automated postings43723
Ref: #automated-postings43877
Node: EDITOR SUPPORT45017
Ref: #editor-support45135
Node: Comment blocks33917
Ref: #comment-blocks34062
Node: Including other files34238
Ref: #including-other-files34418
Node: Default year34807
Ref: #default-year34976
Node: Declaring commodities35399
Ref: #declaring-commodities35582
Node: Default commodity36809
Ref: #default-commodity36985
Node: Market prices37621
Ref: #market-prices37786
Node: Declaring accounts38627
Ref: #declaring-accounts38803
Node: Rewriting accounts40474
Ref: #rewriting-accounts40659
Node: Basic aliases41393
Ref: #basic-aliases41539
Node: Regex aliases42243
Ref: #regex-aliases42414
Node: Multiple aliases43132
Ref: #multiple-aliases43307
Node: end aliases43805
Ref: #end-aliases43952
Node: Default parent account44053
Ref: #default-parent-account44219
Node: Periodic transactions45103
Ref: #periodic-transactions45282
Node: Forecasting with periodic transactions46492
Ref: #forecasting-with-periodic-transactions46735
Node: Budgeting with periodic transactions47976
Ref: #budgeting-with-periodic-transactions48215
Node: Automated postings48674
Ref: #automated-postings48828
Node: EDITOR SUPPORT49967
Ref: #editor-support50085

End Tag Table

258
hledger-lib/hledger_journal.txt
View File

@ -601,34 +601,97 @@ FILE FORMAT
Directives
A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. Some directives may also
have indented sub-directives on the following lines (commodity).
that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions).
Directive scope, multiple files
Directives vary in which journal entries they affect:
Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with
links to more detailed docs.
o some form a begin/end pair, and affect the enclosed journal entries
(and included files):
alias & end aliases; comment & end comment
o some affect the subsequent journal entries (and included files) in
the current file:
alias or comment without an end directive, Y
direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06)
tives
-------------------------------------------------------------------------------------------------
account any declare an account name & account code: bal-
text optional account code ance reports
(except balance
single-column mode)
alias end aliases rewrite account names following
inline/included
entries until end
of current file or
end directive
apply account end apply account prepend a common parent to following
account names inline/included
entries until end
of current file or
end directive
comment end comment ignore part of journal following
inline/included
entries until end
of current file or
end directive
commodity format declare a commodity and its number notation:
number notation & display following entries
style in that commodity
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
entries in that
commodity in all
files; display
style: amounts of
that commodity in
reports
include include entries/directives what the included
from another file directives affect
P declare a market price for a amounts of that
commodity commodity in
reports, when -V is
used
Y declare a year for yearless following
dates inline/included
entries until end
of current file
o some affect all journal entries (and included files) anywhere in the
current file:
account, commodity, D, P.
And some definitions:
It's important to note that directives can affect the current file and
child (included) files, but not sibling or parent (including) files.
This is by design, for simplicity and predictability of reports, but it
can be surprising at times. Eg, in:
hledger -f a.prices -f b.journal
subdirec- optional indented directive or unparsed text lines immedi-
tive ately following a parent directive
account numeric code influencing account display order in most bal-
code ance reports
the prices defined in a.prices will not be effective in b.journal (a
sibling file). Instead, you have to include (or inline) a.prices in
b.journal, or vice versa.
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
directive which entries and (when there are multiple files) which files
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
times though.
Comment blocks
A line containing just comment starts a commented region of the file,
@ -763,14 +826,26 @@ FILE FORMAT
account revenues 4000
account expenses 6000
This affects account display order in reports: accounts with codes are
listed before accounts without codes, in increasing code order. (Oth-
erwise, accounts are listed alphabetically.) Account codes should be
all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces). By
convention, often the first digit indicates the type of account, as in
this numbering scheme and the example above. In future, we might use
this to recognize account types.
This affects how accounts are sorted in account and balance reports:
accounts with codes are listed before accounts without codes, and in
increasing code order (instead of listing all accounts alphabetically).
Warning, this feature is incomplete; account codes do not yet affect
sort order in
o the accounts command
o the balance command's single-column mode
o flat mode balance reports (to work around this, declare account codes
on the subaccounts as well).
o hledger-web's sidebar
Account codes should be all numeric digits, unique, and separated from
the account name by at least two spaces (since account names may con-
tain single spaces). By convention, often the first digit indicates
the type of account, as in this numbering scheme and the example above.
In future, we might use this to recognize account types.
An account directive can also have indented subdirectives following it,
which are currently ignored. Here is the full syntax:
@ -783,9 +858,8 @@ FILE FORMAT
some-tag:12345
Rewriting accounts
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
You can define account alias rules which rewrite your account names, or
parts of them, before generating reports. This can be useful for:
o expanding shorthand account names to their full form, allowing easier
data entry and a less verbose journal
@ -797,11 +871,15 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or
hledger-web.
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
@ -809,54 +887,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
affected. Eg:
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub-
accounts 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
Default parent account
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
@ -873,7 +951,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
@ -882,19 +960,23 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
account.
Periodic transactions
Periodic transaction rules describe transactions that recur. They
allow you to generate future transactions for forecast reports (with
--forecast), without having to write them out explicitly in the jour-
nal. Secondly, they also can be used to define budget goals (with
--budget).
allow you to generate future transactions for forecasting, without hav-
ing to write them out explicitly in the journal (with --forecast).
Secondly, they also can be used to define budget goals (with --budget).
A periodic transaction rule looks like a regular journal entry, with
the date replaced by a tilde (~) followed by a period expression
(mnemonic: ~ looks like a repeating sine wave):
A periodic transaction rule looks like a normal journal entry, with the
date replaced by a tilde (~) followed by a period expression (mnemonic:
~ looks like a repeating sine wave):
~ monthly
expenses:rent $2000
@ -904,9 +986,8 @@ FILE FORMAT
date must fall on a natural boundary of the interval. Eg
monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not.
Also, if you write a transaction description or same-line comment, it
must be separated from the period expression by two or more spaces.
Eg:
If you write a transaction description or same-line comment, it must be
separated from the period expression by two or more spaces. Eg:
; 2 or more spaces
; ||
@ -915,28 +996,34 @@ FILE FORMAT
assets:bank:checking $1500
income:acme inc
Generating forecasts with periodic transactions
With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval, beginning the
day after the latest recorded journal transaction (or today, if there
are no transactions), and ending 6 months from today (or at the report
end date, if specified). The generated transactions will appear in all
reports. They will have a "recur:" transaction tag added, with the
generating period expression as its value.
Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
the generating period expression.
This can be useful for forecasting balances into the future, and exper-
imenting with different scenarios, without having to write a lot of
journal entries. It can also help with data entry (describe most of
your transactions with periodic rules, and every so often copy the out-
put of print --forecast to the journal).
Forecast transactions begin on or after the day after the latest normal
(non-periodic) transaction in the journal, or today if there are none.
You can generate one-time transactions too; just write a period expres-
sion specifying a date with no report interval. You could use this to
forecast an estimated transaction, that is automatically deactivated
once the actual transaction (or any other transaction on or after that
date) is recorded.
They end on or before the report end date if specified, or 180 days
from today if unspecified.
Setting budget goals with periodic transactions
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
@ -951,9 +1038,9 @@ FILE FORMAT
Automated posting rules describe extra postings that should be added to
certain transactions at report time, when the --auto flag is used.
An automated posting rule looks like a regular journal entry, except
the first line is an equal sign (=) followed by a query (mnemonic: =
looks like posting lines):
An automated posting rule looks like a normal journal entry, except the
first line is an equal sign (=) followed by a query (mnemonic: = looks
like posting lines):
= expenses:gifts
budget:gifts *-1
@ -1003,6 +1090,7 @@ EDITOR SUPPORT
Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2
Text Wran- https://github.com/ledger/ledger/wiki/Edit-
gler ing-Ledger-files-with-TextWrangler
Visual Stu- https://marketplace.visualstudio.com/items?item-
dio Code Name=mark-hansen.hledger-vscode
@ -1031,4 +1119,4 @@ SEE ALSO
hledger 1.9.99 March 2018 hledger_journal(5)
hledger 1.9.99 June 2018 hledger_journal(5)

2
hledger-lib/hledger_timeclock.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals"
.TH "hledger_timeclock" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals"

2
hledger-lib/hledger_timeclock.txt
View File

@ -77,4 +77,4 @@ SEE ALSO
hledger 1.9.99 March 2018 hledger_timeclock(5)
hledger 1.9.99 June 2018 hledger_timeclock(5)

2
hledger-lib/hledger_timedot.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "March 2018" "hledger 1.9.99" "hledger User Manuals"
.TH "hledger_timedot" "5" "June 2018" "hledger 1.9.99" "hledger User Manuals"

2
hledger-lib/hledger_timedot.txt
View File

@ -124,4 +124,4 @@ SEE ALSO
hledger 1.9.99 March 2018 hledger_timedot(5)
hledger 1.9.99 June 2018 hledger_timedot(5)

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

@ -1,5 +1,5 @@
.TH "hledger\-ui" "1" "March 2018" "hledger\-ui 1.9.99" "hledger User Manuals"
.TH "hledger\-ui" "1" "June 2018" "hledger\-ui 1.9.99" "hledger User Manuals"

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

@ -384,4 +384,4 @@ SEE ALSO
hledger-ui 1.9.99 March 2018 hledger-ui(1)
hledger-ui 1.9.99 June 2018 hledger-ui(1)

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

@ -1,5 +1,5 @@
.TH "hledger\-web" "1" "March 2018" "hledger\-web 1.9.99" "hledger User Manuals"
.TH "hledger\-web" "1" "June 2018" "hledger\-web 1.9.99" "hledger User Manuals"

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

@ -248,4 +248,4 @@ SEE ALSO
hledger-web 1.9.99 March 2018 hledger-web(1)
hledger-web 1.9.99 June 2018 hledger-web(1)

2
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger" "1" "March 2018" "hledger 1.9.99" "hledger User Manuals"
.TH "hledger" "1" "June 2018" "hledger 1.9.99" "hledger User Manuals"

2
hledger/hledger.txt
View File

@ -2210,4 +2210,4 @@ SEE ALSO
hledger 1.9.99 March 2018 hledger(1)
hledger 1.9.99 June 2018 hledger(1)