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

;doc: regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-02-08 11:56:03 -08:00
parent 54e633e186
commit 98d0cc9c17
6 changed files with 544 additions and 532 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
hledger-lib/hledger_journal.5
View File

@ -239,7 +239,7 @@ Here\[aq]s one suggestion:
.PP
.TS
tab(@);
lw(9.9n) lw(60.1n).
lw(9.7n) lw(60.3n).
T{
status
T}@T{
@ -1033,7 +1033,7 @@ And some definitions:
.PP
.TS
tab(@);
lw(8.9n) lw(61.1n).
lw(6.0n) lw(64.0n).
T{
subdirective
T}@T{

123
hledger-lib/hledger_journal.info
View File

@ -913,16 +913,15 @@ account' apply account names inline/included
And some definitions:
subdirectiveoptional indented directive line immediately following a
parent directive
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
subdirectiveoptional indented directive line immediately following a parent
directive
number how to interpret numbers when parsing journal entries (the
notationidentity of the decimal separator character). (Currently each
commodity can have its own notation, even in the same file.)
displayhow to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
directivewhich 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
@ -1789,58 +1788,58 @@ Node: Balance assignments and prices29327
Ref: #balance-assignments-and-prices29499
Node: Directives29723
Ref: #directives29882
Node: Comment blocks35561
Ref: #comment-blocks35706
Node: Including other files35882
Ref: #including-other-files36062
Node: Default year36470
Ref: #default-year36639
Node: Declaring commodities37046
Ref: #declaring-commodities37229
Node: Default commodity38890
Ref: #default-commodity39066
Node: Market prices39700
Ref: #market-prices39865
Node: Declaring accounts40706
Ref: #declaring-accounts40882
Node: Account comments41807
Ref: #account-comments41970
Node: Account subdirectives42394
Ref: #account-subdirectives42589
Node: Account types42902
Ref: #account-types43086
Node: Account display order44728
Ref: #account-display-order44898
Node: Rewriting accounts46049
Ref: #rewriting-accounts46234
Node: Basic aliases46960
Ref: #basic-aliases47106
Node: Regex aliases47810
Ref: #regex-aliases47982
Node: Combining aliases48700
Ref: #combining-aliases48878
Node: end aliases50154
Ref: #end-aliases50302
Node: Default parent account50403
Ref: #default-parent-account50569
Node: Periodic transactions51453
Ref: #periodic-transactions51652
Node: Periodic rule syntax53524
Ref: #periodic-rule-syntax53730
Node: Two spaces between period expression and description!54434
Ref: #two-spaces-between-period-expression-and-description54753
Node: Forecasting with periodic transactions55437
Ref: #forecasting-with-periodic-transactions55742
Node: Budgeting with periodic transactions57768
Ref: #budgeting-with-periodic-transactions58007
Node: Auto postings / transaction modifiers58456
Ref: #auto-postings-transaction-modifiers58668
Node: Auto postings and dates61153
Ref: #auto-postings-and-dates61410
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61585
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61960
Node: Auto posting tags62338
Ref: #auto-posting-tags62577
Node: Comment blocks35530
Ref: #comment-blocks35675
Node: Including other files35851
Ref: #including-other-files36031
Node: Default year36439
Ref: #default-year36608
Node: Declaring commodities37015
Ref: #declaring-commodities37198
Node: Default commodity38859
Ref: #default-commodity39035
Node: Market prices39669
Ref: #market-prices39834
Node: Declaring accounts40675
Ref: #declaring-accounts40851
Node: Account comments41776
Ref: #account-comments41939
Node: Account subdirectives42363
Ref: #account-subdirectives42558
Node: Account types42871
Ref: #account-types43055
Node: Account display order44697
Ref: #account-display-order44867
Node: Rewriting accounts46018
Ref: #rewriting-accounts46203
Node: Basic aliases46929
Ref: #basic-aliases47075
Node: Regex aliases47779
Ref: #regex-aliases47951
Node: Combining aliases48669
Ref: #combining-aliases48847
Node: end aliases50123
Ref: #end-aliases50271
Node: Default parent account50372
Ref: #default-parent-account50538
Node: Periodic transactions51422
Ref: #periodic-transactions51621
Node: Periodic rule syntax53493
Ref: #periodic-rule-syntax53699
Node: Two spaces between period expression and description!54403
Ref: #two-spaces-between-period-expression-and-description54722
Node: Forecasting with periodic transactions55406
Ref: #forecasting-with-periodic-transactions55711
Node: Budgeting with periodic transactions57737
Ref: #budgeting-with-periodic-transactions57976
Node: Auto postings / transaction modifiers58425
Ref: #auto-postings-transaction-modifiers58637
Node: Auto postings and dates61122
Ref: #auto-postings-and-dates61379
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61554
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61929
Node: Auto posting tags62307
Ref: #auto-posting-tags62546

End Tag Table

314
hledger-lib/hledger_journal.txt
View File

@ -710,49 +710,51 @@ FILE FORMAT
And some definitions:
subdirec- optional indented directive line immediately following a par-
tive ent directive
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
subdi- optional indented directive line immediately following a parent
rec- directive
tive
number how to interpret numbers when parsing journal entries (the iden-
nota- tity of the decimal separator character). (Currently each com-
tion modity can have its own notation, even in the same file.)
dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places)
style
direc- which entries and (when there are multiple files) which files
tive are affected by a directive
scope
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output (re-
ports). 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-
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
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,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can in-
The include directive can only be used in journal files. It can in-
clude journal, timeclock or timedot files, but not CSV files.
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
@ -774,18 +776,18 @@ FILE FORMAT
Declaring commodities
The commodity directive has several functions:
1. It declares commodities which may be used in the journal. This is
1. It declares commodities which may be used in the journal. This is
currently not enforced, but can serve as documentation.
2. It declares what decimal mark character to expect when parsing input
- useful to disambiguate international number formats in your data.
- useful to disambiguate international number formats in your data.
(Without this, hledger will parse both 1,000 and 1.000 as 1).
3. It declares the amount display format to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them
You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them
to declare your commodities.
A commodity directive is just the word commodity followed by an amount.
@ -798,8 +800,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
@ -812,14 +814,14 @@ FILE FORMAT
format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi-
cant. The number must include a decimal mark: either a period or a
cant. The number must include a decimal mark: either a period or a
comma, followed by 0 or more decimal digits.
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
@ -834,9 +836,9 @@ FILE FORMAT
a decimal point.
Market prices
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@ -847,16 +849,16 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, giving the price in commodity B of one unit of commodity A.
These two market price directives say that one euro was worth 1.35 US
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40
The -V/--value flag can be used to convert reported amounts to another
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
@ -866,20 +868,20 @@ FILE FORMAT
o They can document your intended chart of accounts, providing a refer-
ence.
o They can store extra information about accounts (account numbers,
o They can store extra information about accounts (account numbers,
notes, etc.)
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
o They control account display order in reports, allowing non-alpha-
o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command, hledger-
o They help with account name completion in the add command, hledger-
iadd, hledger-web, ledger-mode etc.
The simplest form is just the word account followed by a hledger-style
The simplest form is just the word account followed by a hledger-style
account name, eg:
account assets:bank:checking
@ -887,7 +889,7 @@ FILE FORMAT
Account comments
Comments, beginning with a semicolon, can be added:
o on the same line, after two or more spaces (because ; is allowed in
o on the same line, after two or more spaces (because ; is allowed in
account names)
o on the next lines, indented
@ -901,7 +903,7 @@ FILE FORMAT
Same-line comments are not supported by Ledger, or hledger <1.13.
Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just
We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
@ -914,18 +916,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are
bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
Account types declared with tags
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@ -936,8 +938,8 @@ FILE FORMAT
account expenses ; type:Expenses
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A
@ -947,7 +949,7 @@ FILE FORMAT
account expenses X
Overriding auto-detected types
If you ever override the types of those auto-detected english account
If you ever override the types of those auto-detected english account
names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why
@ -958,8 +960,8 @@ FILE FORMAT
account - ; type:L
Account display order
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal:
@ -981,20 +983,20 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means:
o you will sometimes declare parent accounts (eg account other above)
o you will sometimes declare parent accounts (eg account other above)
that you don't intend to post to, just to customize their display or-
der
o sibling accounts stay together (you couldn't display x:y in between
o sibling accounts stay together (you couldn't display x:y in between
a:b and a:c).
Rewriting accounts
@ -1012,14 +1014,14 @@ 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-
do not affect account names being entered via hledger add or hledger-
web.
See also 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
@ -1027,49 +1029,49 @@ 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 case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
OLD and NEW are case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
counts 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.
Combining aliases
You can define as many aliases as you like, using journal directives
You can define as many aliases as you like, using journal directives
and/or command line options.
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases.
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. alias directives preceding the journal entry, most recently parsed
1. alias directives preceding the journal entry, most recently parsed
first (ie, reading upward from the journal entry, bottom to top)
2. --alias options, in the order they appeared on the command line
2. --alias options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
@ -1080,22 +1082,22 @@ FILE FORMAT
o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order.
In case of trouble, adding --debug=6 to the command line will show
In case of trouble, adding --debug=6 to the command line will show
which aliases are being applied when.
end aliases
You can clear (forget) all currently defined aliases with the end
You can clear (forget) all currently defined aliases with the end
aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
apply account directives like so:
apply account home
@ -1112,7 +1114,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
@ -1121,50 +1123,50 @@ 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
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 al-
low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal,
and it's easy to try out different forecasts. Secondly, they are also
Periodic transaction rules describe transactions that recur. They al-
low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal,
and it's easy to try out different forecasts. Secondly, they are also
used to define the budgets shown in budget reports.
Periodic transactions can be a little tricky, so before you use them,
Periodic transactions can be a little tricky, so before you use them,
read this whole section - or at least these tips:
1. Two spaces accidentally added or omitted will cause you trouble -
1. Two spaces accidentally added or omitted will cause you trouble -
read about this below.
2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast
2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast
tag:generated.
3. Forecasted transactions will begin only after the last non-fore-
3. Forecasted transactions will begin only after the last non-fore-
casted transaction's date.
4. Forecasted transactions will end 6 months from today, by default.
4. Forecasted transactions will end 6 months from today, by default.
See below for the exact start/end rules.
5. period expressions can be tricky. Their documentation needs im-
5. period expressions can be tricky. Their documentation needs im-
provement, but is worth studying.
6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
error.
7. Other period expressions with an interval are automatically expanded
to cover a whole number of that interval. (This is done to improve
to cover a whole number of that interval. (This is done to improve
reports, but it also affects periodic transactions. Yes, it's a bit
inconsistent with the above.) Eg: ~ every 10th day of month from
2020/01, which is equivalent to ~ every 10th day of month from
inconsistent with the above.) Eg: ~ every 10th day of month from
2020/01, which is equivalent to ~ every 10th day of month from
2020/01/01, will be adjusted to start on 2019/12/10.
Periodic rule syntax
@ -1176,17 +1178,17 @@ FILE FORMAT
expenses:rent $2000
assets:bank:checking
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg monthly from
There is an additional constraint on the period expression: the start
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.
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
Two spaces between period expression and description!
If the period expression is followed by a transaction description,
If the period expression is followed by a transaction description,
these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example:
@ -1200,82 +1202,82 @@ FILE FORMAT
So,
o Do write two spaces between your period expression and your transac-
o Do write two spaces between your period expression and your transac-
tion description, if any.
o Don't accidentally write two spaces in the middle of your period ex-
o Don't accidentally write two spaces in the middle of your period ex-
pression.
Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates fu-
ture transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
With the --forecast flag, each periodic transaction rule generates fu-
ture 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:
o generated-transaction:~ PERIODICEXPR - shows that this was generated
o generated-transaction:~ PERIODICEXPR - shows that this was generated
by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
o _generated-transaction:~ PERIODICEXPR
This can be used to match transactions generated "just now", rather
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
forecast period:
o begins on the later of
o the report start date if specified with -b/-p/date:
o the day after the latest normal (non-periodic) transaction in the
o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
o ends on the report end date if specified with -e/-p/date:, or 180
o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
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
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
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
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
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
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
For more details, see: balance: Budget report and Budgeting and Fore-
For more details, see: balance: Budget report and Budgeting and Fore-
casting.
Auto postings / transaction modifiers
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
active when you use the --auto flag.
A transaction modifier rule looks much like a normal transaction except
the first line is an equals sign followed by a query that matches cer-
tain postings (mnemonic: = suggests matching). And each "posting" is
the first line is an equals sign followed by a query that matches cer-
tain postings (mnemonic: = suggests matching). And each "posting" is
actually a posting-generating rule:
= QUERY
@ -1283,25 +1285,25 @@ FILE FORMAT
ACCT [AMT]
...
These posting-generating rules look like normal postings, except the
These posting-generating rules look like normal postings, except the
amount can be:
o a normal amount with a commodity symbol, eg $2. This will be used
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
o a numeric multiplier, eg *2 (a star followed by a number N). The
o a numeric multiplier, eg *2 (a star followed by a number N). The
matched posting's amount (and total price, if any) will be multiplied
by N.
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
A query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second
A query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second
query term below:
= expenses:groceries 'expenses:dining out'
@ -1343,20 +1345,20 @@ FILE FORMAT
assets:checking $20
Auto postings and dates
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also
be used in the generated posting.
Auto postings and transaction balancing / inferred amounts / balance asser-
tions
Currently, transaction modifiers are applied / auto postings are added:
o after missing amounts are inferred, and transactions are checked for
o after missing amounts are inferred, and transactions are checked for
balancedness,
o but before balance assertions are checked.
Note this means that journal entries must be balanced both before and
Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893
for background.
@ -1366,11 +1368,11 @@ FILE FORMAT
o generated-posting:= QUERY - shows this was generated by an auto post-
ing rule, and the query
o _generated-posting:= QUERY - a hidden tag, which does not appear in
o _generated-posting:= QUERY - a hidden tag, which does not appear in
hledger's output. This can be used to match postings generated "just
now", rather than generated in the past and saved to the journal.
Also, any transaction that has been changed by transaction modifier
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
o modified: - this transaction was modified
@ -1381,7 +1383,7 @@ FILE FORMAT
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)
@ -1395,7 +1397,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)

91
hledger/hledger.1
View File

@ -1117,7 +1117,7 @@ Examples:
.PP
.TS
tab(@);
l l.
lw(24.2n) lw(45.8n).
T{
\f[C]2004/10/1\f[R], \f[C]2004-01-01\f[R], \f[C]2004.9.1\f[R]
T}@T{
@ -1176,7 +1176,7 @@ results:
.PP
.TS
tab(@);
l l.
lw(11.4n) lw(58.6n).
T{
\f[C]201813\f[R]
T}@T{
@ -1230,12 +1230,11 @@ Examples:
.PP
.TS
tab(@);
l l.
lw(11.9n) lw(58.1n).
T{
\f[C]-b 2016/3/17\f[R]
T}@T{
begin on St.
Patrick\[aq]s day 2016
begin on St.\ Patrick\[cq]s day 2016
T}
T{
\f[C]-e 12/1\f[R]
@ -1362,21 +1361,21 @@ start and end date like so:
.PP
.TS
tab(@);
l r.
l l.
T{
\f[C]-p \[dq]2009\[dq]\f[R]
T}@T{
the year 2009; equivalent to \[dq]2009/1/1 to 2010/1/1\[dq]
the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq]
T}
T{
\f[C]-p \[dq]2009/1\[dq]\f[R]
T}@T{
the month of jan; equivalent to \[dq]2009/1/1 to 2009/2/1\[dq]
the month of jan; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq]
T}
T{
\f[C]-p \[dq]2009/1/1\[dq]\f[R]
T}@T{
just that day; equivalent to \[dq]2009/1/1 to 2009/1/2\[dq]
just that day; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq]
T}
.TE
.PP
@ -1415,22 +1414,27 @@ For example:
.PP
.TS
tab(@);
l.
lw(25.5n) lw(44.5n).
T{
\f[C]-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R] -- starts on
2008/12/29, closest preceding Monday
\f[C]-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R]
T}@T{
starts on 2008/12/29, closest preceding Monday
T}
T{
\f[C]-p \[dq]monthly in 2008/11/25\[dq]\f[R] -- starts on 2018/11/01
\f[C]-p \[dq]monthly in 2008/11/25\[dq]\f[R]
T}@T{
starts on 2018/11/01
T}
T{
\f[C]-p \[dq]quarterly from 2009-05-05 to 2009-06-01\[dq]\f[R] - starts
on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2
2009
\f[C]-p \[dq]quarterly from 2009-05-05 to 2009-06-01\[dq]\f[R]
T}@T{
starts on 2009/04/01, ends on 2009/06/30, which are first and last days
of Q2 2009
T}
T{
\f[C]-p \[dq]yearly from 2009-12-29\[dq]\f[R] - starts on 2009/01/01,
first day of 2009
\f[C]-p \[dq]yearly from 2009-12-29\[dq]\f[R]
T}@T{
starts on 2009/01/01, first day of 2009
T}
.TE
.PP
@ -1446,18 +1450,21 @@ Examples:
.PP
.TS
tab(@);
l.
lw(25.5n) lw(44.5n).
T{
\f[C]-p \[dq]bimonthly from 2008\[dq]\f[R] -- periods will have
boundaries on 2008/01/01, 2008/03/01, ...
\f[C]-p \[dq]bimonthly from 2008\[dq]\f[R]
T}@T{
periods will have boundaries on 2008/01/01, 2008/03/01, ...
T}
T{
\f[C]-p \[dq]every 2 weeks\[dq]\f[R] -- starts on closest preceding
Monday
\f[C]-p \[dq]every 2 weeks\[dq]\f[R]
T}@T{
starts on closest preceding Monday
T}
T{
\f[C]-p \[dq]every 5 month from 2009/03\[dq]\f[R] -- periods will have
boundaries on 2009/03/01, 2009/08/01, ...
\f[C]-p \[dq]every 5 month from 2009/03\[dq]\f[R]
T}@T{
periods will have boundaries on 2009/03/01, 2009/08/01, ...
T}
.TE
.PP
@ -1473,31 +1480,41 @@ Examples:
.PP
.TS
tab(@);
l.
lw(23.9n) lw(46.1n).
T{
\f[C]-p \[dq]every 2nd day of week\[dq]\f[R] -- periods will go from Tue
to Tue
\f[C]-p \[dq]every 2nd day of week\[dq]\f[R]
T}@T{
periods will go from Tue to Tue
T}
T{
\f[C]-p \[dq]every Tue\[dq]\f[R] -- same
\f[C]-p \[dq]every Tue\[dq]\f[R]
T}@T{
same
T}
T{
\f[C]-p \[dq]every 15th day\[dq]\f[R] -- period boundaries will be on
15th of each month
\f[C]-p \[dq]every 15th day\[dq]\f[R]
T}@T{
period boundaries will be on 15th of each month
T}
T{
\f[C]-p \[dq]every 2nd Monday\[dq]\f[R] -- period boundaries will be on
second Monday of each month
\f[C]-p \[dq]every 2nd Monday\[dq]\f[R]
T}@T{
period boundaries will be on second Monday of each month
T}
T{
\f[C]-p \[dq]every 11/05\[dq]\f[R] -- yearly periods with boundaries on
5th of Nov
\f[C]-p \[dq]every 11/05\[dq]\f[R]
T}@T{
yearly periods with boundaries on 5th of Nov
T}
T{
\f[C]-p \[dq]every 5th Nov\[dq]\f[R] -- same
\f[C]-p \[dq]every 5th Nov\[dq]\f[R]
T}@T{
same
T}
T{
\f[C]-p \[dq]every Nov 5th\[dq]\f[R] -- same
\f[C]-p \[dq]every Nov 5th\[dq]\f[R]
T}@T{
same
T}
.TE
.PP

358
hledger/hledger.info
View File

@ -1051,25 +1051,31 @@ omitted (defaulting to 1).
Examples:
'2004/10/1', '2004-01-01', '2004.9.1' exact date, several separators allowed. Year is 4+ digits, month is 1-12, day is 1-31
'2004' start of year
'2004/10' start of month
'10/1' month and day in current year
'21' day in current month
'october, oct' start of month in current year
'yesterday, today, tomorrow' -1, 0, 1 days from today
'last/this/next -1, 0, 1 periods from the current period
'2004/10/1', exact date, several separators allowed. Year
'2004-01-01', is 4+ digits, month is 1-12, day is 1-31
'2004.9.1'
'2004' start of year
'2004/10' start of month
'10/1' month and day in current year
'21' day in current month
'october, oct' start of month in current year
'yesterday, today, -1, 0, 1 days from today
tomorrow'
'last/this/next -1, 0, 1 periods from the current period
day/week/month/quarter/year'
'20181201' 8 digit YYYYMMDD with valid year month and day
'201812' 6 digit YYYYMM with valid year and month
'20181201' 8 digit YYYYMMDD with valid year month and
day
'201812' 6 digit YYYYMM with valid year and month
Counterexamples - malformed digit sequences might give surprising
results:
'201813' 6 digits with an invalid month is parsed as start of 6-digit year
'20181301' 8 digits with an invalid month is parsed as start of 8-digit year
'20181232' 8 digits with an invalid day gives an error
'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error
'201813' 6 digits with an invalid month is parsed as start of
6-digit year
'20181301' 8 digits with an invalid month is parsed as start of
8-digit year
'20181232' 8 digits with an invalid day gives an error
'201801012' 9+ digits beginning with a valid YYYYMMDD gives an error

File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS
@ -1100,11 +1106,15 @@ these accept the smart date syntax.
Examples:
'-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
'date:2016/3/17-' the above written as queries instead
'-b begin on St. Patrick's day 2016
2016/3/17'
'-e 12/1' end at the start of december 1st of the current year
(11/30 will be the last date included)
'-b all transactions on or after the 1st of the current month
thismonth'
'-p all transactions in the current month
thismonth'
'date:2016/3/17-'the above written as queries instead
'date:-12/1'
'date:thismonth-'
'date:thismonth'
@ -1163,9 +1173,9 @@ the earliest or latest transaction in your journal:
A single date with no "from" or "to" defines both the start and end
date like so:
'-p "2009"' the year 2009; equivalent to "2009/1/1 to 2010/1/1"
'-p "2009/1"' the month of jan; equivalent to "2009/1/1 to 2009/2/1"
'-p "2009/1/1"' just that day; equivalent to "2009/1/1 to 2009/1/2"
'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1”
'-p "2009/1"' the month of jan; equivalent to “2009/1/1 to 2009/2/1”
'-p "2009/1/1"' just that day; equivalent to “2009/1/1 to 2009/1/2”
The argument of '-p' can also begin with, or be, a report interval
expression. The basic report intervals are 'daily', 'weekly',
@ -1185,10 +1195,15 @@ date.
For example:
'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceding 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
'-p "weekly from starts on 2008/12/29, closest preceding
2009/1/1 to 2009/4/1"' Monday
'-p "monthly in starts on 2018/11/01
2008/11/25"'
'-p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
2009-05-05 to which are first and last days of Q2 2009
2009-06-01"'
'-p "yearly from starts on 2009/01/01, first day of 2009
2009-12-29"'
The following more complex report intervals are also supported:
'biweekly', 'bimonthly', 'every day|week|month|quarter|year', 'every N
@ -1199,9 +1214,11 @@ 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 preceding Monday
'-p "every 5 month from 2009/03"' - periods will have boundaries on 2009/03/01, 2009/08/01, ...
'-p "bimonthly from periods will have boundaries on 2008/01/01,
2008"' 2008/03/01, ...
'-p "every 2 weeks"' starts on closest preceding Monday
'-p "every 5 month from periods will have boundaries on 2009/03/01,
2009/03"' 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:
@ -1212,13 +1229,16 @@ Nth MMM [of year]', 'every MMM Nth [of year]'.
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 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
'-p "every 2nd day of periods will go from Tue to Tue
week"'
'-p "every Tue"' same
'-p "every 15th day"' period boundaries will be on 15th of each
month
'-p "every 2nd period boundaries will be on second Monday of
Monday"' 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):
@ -3696,139 +3716,139 @@ Node: Regular expressions32899
Ref: #regular-expressions33056
Node: Smart dates34417
Ref: #smart-dates34568
Node: Report start & end date35974
Ref: #report-start-end-date36146
Node: Report intervals37570
Ref: #report-intervals37735
Node: Period expressions38125
Ref: #period-expressions38285
Node: Depth limiting42240
Ref: #depth-limiting42384
Node: Pivoting42726
Ref: #pivoting42849
Node: Valuation44525
Ref: #valuation44627
Node: -B Cost44807
Ref: #b-cost44918
Node: -V Market value45116
Ref: #v-market-value45290
Node: -X Market value in specified commodity46722
Ref: #x-market-value-in-specified-commodity46961
Node: --value Flexible valuation47137
Ref: #value-flexible-valuation47363
Node: Effect of --value on reports51553
Ref: #effect-of---value-on-reports51769
Node: Combining -B -V -X --value56700
Ref: #combining--b--v--x---value56883
Node: COMMANDS56919
Ref: #commands57027
Node: accounts58111
Ref: #accounts58209
Node: activity58908
Ref: #activity59018
Node: add59401
Ref: #add59500
Node: balance62239
Ref: #balance62350
Node: Classic balance report63808
Ref: #classic-balance-report63981
Node: Customising the classic balance report65350
Ref: #customising-the-classic-balance-report65578
Node: Colour support67654
Ref: #colour-support67821
Node: Flat mode67994
Ref: #flat-mode68142
Node: Depth limited balance reports68555
Ref: #depth-limited-balance-reports68740
Node: Percentages69196
Ref: #percentages69362
Node: Multicolumn balance report70499
Ref: #multicolumn-balance-report70679
Node: Budget report75993
Ref: #budget-report76136
Node: Nested budgets81338
Ref: #nested-budgets81450
Ref: #output-format-184931
Node: balancesheet85009
Ref: #balancesheet85145
Node: balancesheetequity86528
Ref: #balancesheetequity86677
Node: cashflow87238
Ref: #cashflow87366
Node: check-dates88462
Ref: #check-dates88589
Node: check-dupes88868
Ref: #check-dupes88992
Node: close89285
Ref: #close89399
Node: close usage90921
Ref: #close-usage91014
Node: commodities93827
Ref: #commodities93954
Node: descriptions94036
Ref: #descriptions94164
Node: diff94345
Ref: #diff94451
Node: files95498
Ref: #files95598
Node: help95745
Ref: #help95845
Node: import96926
Ref: #import97040
Node: Importing balance assignments97933
Ref: #importing-balance-assignments98081
Node: incomestatement98730
Ref: #incomestatement98863
Node: notes100267
Ref: #notes100380
Node: payees100506
Ref: #payees100612
Node: prices100770
Ref: #prices100876
Node: print101217
Ref: #print101327
Node: print-unique105971
Ref: #print-unique106097
Node: register106382
Ref: #register106509
Node: Custom register output110681
Ref: #custom-register-output110810
Node: register-match112072
Ref: #register-match112206
Node: rewrite112557
Ref: #rewrite112672
Node: Re-write rules in a file114527
Ref: #re-write-rules-in-a-file114661
Node: Diff output format115871
Ref: #diff-output-format116040
Node: rewrite vs print --auto117132
Ref: #rewrite-vs.-print---auto117311
Node: roi117867
Ref: #roi117965
Node: stats118977
Ref: #stats119076
Node: tags119864
Ref: #tags119962
Node: test120256
Ref: #test120364
Node: Add-on Commands121111
Ref: #add-on-commands121228
Node: ui122571
Ref: #ui122659
Node: web122713
Ref: #web122816
Node: iadd122932
Ref: #iadd123043
Node: interest123125
Ref: #interest123232
Node: ENVIRONMENT123472
Ref: #environment123584
Node: FILES124413
Ref: #files-1124516
Node: LIMITATIONS124729
Ref: #limitations124848
Node: TROUBLESHOOTING125590
Ref: #troubleshooting125703
Node: Report start & end date35929
Ref: #report-start-end-date36101
Node: Report intervals37539
Ref: #report-intervals37704
Node: Period expressions38094
Ref: #period-expressions38254
Node: Depth limiting42380
Ref: #depth-limiting42524
Node: Pivoting42866
Ref: #pivoting42989
Node: Valuation44665
Ref: #valuation44767
Node: -B Cost44947
Ref: #b-cost45058
Node: -V Market value45256
Ref: #v-market-value45430
Node: -X Market value in specified commodity46862
Ref: #x-market-value-in-specified-commodity47101
Node: --value Flexible valuation47277
Ref: #value-flexible-valuation47503
Node: Effect of --value on reports51693
Ref: #effect-of---value-on-reports51909
Node: Combining -B -V -X --value56840
Ref: #combining--b--v--x---value57023
Node: COMMANDS57059
Ref: #commands57167
Node: accounts58251
Ref: #accounts58349
Node: activity59048
Ref: #activity59158
Node: add59541
Ref: #add59640
Node: balance62379
Ref: #balance62490
Node: Classic balance report63948
Ref: #classic-balance-report64121
Node: Customising the classic balance report65490
Ref: #customising-the-classic-balance-report65718
Node: Colour support67794
Ref: #colour-support67961
Node: Flat mode68134
Ref: #flat-mode68282
Node: Depth limited balance reports68695
Ref: #depth-limited-balance-reports68880
Node: Percentages69336
Ref: #percentages69502
Node: Multicolumn balance report70639
Ref: #multicolumn-balance-report70819
Node: Budget report76133
Ref: #budget-report76276
Node: Nested budgets81478
Ref: #nested-budgets81590
Ref: #output-format-185071
Node: balancesheet85149
Ref: #balancesheet85285
Node: balancesheetequity86668
Ref: #balancesheetequity86817
Node: cashflow87378
Ref: #cashflow87506
Node: check-dates88602
Ref: #check-dates88729
Node: check-dupes89008
Ref: #check-dupes89132
Node: close89425
Ref: #close89539
Node: close usage91061
Ref: #close-usage91154
Node: commodities93967
Ref: #commodities94094
Node: descriptions94176
Ref: #descriptions94304
Node: diff94485
Ref: #diff94591
Node: files95638
Ref: #files95738
Node: help95885
Ref: #help95985
Node: import97066
Ref: #import97180
Node: Importing balance assignments98073
Ref: #importing-balance-assignments98221
Node: incomestatement98870
Ref: #incomestatement99003
Node: notes100407
Ref: #notes100520
Node: payees100646
Ref: #payees100752
Node: prices100910
Ref: #prices101016
Node: print101357
Ref: #print101467
Node: print-unique106111
Ref: #print-unique106237
Node: register106522
Ref: #register106649
Node: Custom register output110821
Ref: #custom-register-output110950
Node: register-match112212
Ref: #register-match112346
Node: rewrite112697
Ref: #rewrite112812
Node: Re-write rules in a file114667
Ref: #re-write-rules-in-a-file114801
Node: Diff output format116011
Ref: #diff-output-format116180
Node: rewrite vs print --auto117272
Ref: #rewrite-vs.-print---auto117451
Node: roi118007
Ref: #roi118105
Node: stats119117
Ref: #stats119216
Node: tags120004
Ref: #tags120102
Node: test120396
Ref: #test120504
Node: Add-on Commands121251
Ref: #add-on-commands121368
Node: ui122711
Ref: #ui122799
Node: web122853
Ref: #web122956
Node: iadd123072
Ref: #iadd123183
Node: interest123265
Ref: #interest123372
Node: ENVIRONMENT123612
Ref: #environment123724
Node: FILES124553
Ref: #files-1124656
Node: LIMITATIONS124869
Ref: #limitations124988
Node: TROUBLESHOOTING125730
Ref: #troubleshooting125843

End Tag Table

186
hledger/hledger.txt
View File

@ -894,112 +894,94 @@ OPTIONS
Examples:
2004/10/1, 2004-01-01, exact date, several sepa-
2004.9.1 rators allowed. Year is
4+ digits, month is 1-12,
day is 1-31
2004 start of year
2004/10 start of month
10/1 month and day in current
year
21 day in current month
october, oct start of month in current
year
yesterday, today, tomorrow -1, 0, 1 days from today
last/this/next -1, 0, 1 periods from the
day/week/month/quar- current period
2004/10/1, 2004-01-01, exact date, several separators allowed. Year
2004.9.1 is 4+ digits, month is 1-12, day is 1-31
2004 start of year
2004/10 start of month
10/1 month and day in current year
21 day in current month
october, oct start of month in current year
yesterday, today, tomor- -1, 0, 1 days from today
row
last/this/next -1, 0, 1 periods from the current period
day/week/month/quar-
ter/year
20181201 8 digit YYYYMMDD with
valid year month and day
201812 6 digit YYYYMM with valid
year and month
20181201 8 digit YYYYMMDD with valid year month and day
201812 6 digit YYYYMM with valid year and month
Counterexamples - malformed digit sequences might give surprising re-
sults:
201813 6 digits with an invalid
month is parsed as start
of 6-digit year
20181301 8 digits with an invalid
month is parsed as start
of 8-digit year
20181232 8 digits with an invalid
day gives an error
201801012 9+ digits beginning with a
valid YYYYMMDD gives an
error
201813 6 digits with an invalid month is parsed as start of
6-digit year
20181301 8 digits with an invalid month is parsed as start of
8-digit year
20181232 8 digits with an invalid day gives an error
201801012 9+ digits beginning with a valid YYYYMMDD gives an error
Report start & end date
Most hledger reports show the full span of time represented by the
Most hledger reports show the full span of time represented by the
journal data, by default. So, the effective report start and end dates
will be the earliest and latest transaction or posting dates found in
will be the earliest and latest transaction or posting dates found in
the journal.
Often you will want to see a shorter time span, such as the current
month. You can specify a start and/or end date using -b/--begin,
Often you will want to see a shorter time span, such as the current
month. You can specify a start and/or end date using -b/--begin,
-e/--end, -p/--period or a date: query (described below). All of these
accept the smart date syntax.
Some notes:
o As in Ledger, end dates are exclusive, so you need to write the date
o As in Ledger, end dates are exclusive, so you need to write the date
after the last day you want to include.
o As noted in reporting options: among start/end dates specified with
o As noted in reporting options: among start/end dates specified with
options, the last (i.e. right-most) option takes precedence.
o The effective report start and end dates are the intersection of the
start/end dates from options and that from date: queries. That is,
date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
o The effective report start and end dates are the intersection of the
start/end dates from options and that from date: queries. That is,
date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
smallest common time span.
Examples:
-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
last date included)
-b thismonth all transactions on or af-
ter the 1st of the current
month
-p thismonth all transactions in the
current month
date:2016/3/17- the above written as
queries instead
-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
date:2016/3/17- the above written as queries instead
date:-12/1
date:thismonth-
date:thismonth
Report intervals
A report interval can be specified so that commands like register, bal-
ance and activity will divide their reports into multiple subperiods.
The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
plex intervals may be specified with a period expression. Report in-
ance and activity will divide their reports into multiple subperiods.
The basic intervals can be selected with one of -D/--daily,
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
plex intervals may be specified with a period expression. Report in-
tervals can not be specified with a query.
Period expressions
The -p/--period option accepts period expressions, a shorthand way of
The -p/--period option accepts period expressions, a shorthand way of
expressing a start date, end date, and/or report interval all at once.
Here's a basic period expression specifying the first quarter of 2009.
Note, hledger always treats start dates as inclusive and end dates as
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:
-p "from 2009/1/1 to 2009/4/1"
Keywords like "from" and "to" are optional, and so are the spaces, as
long as you don't run two dates together. "to" can also be written as
Keywords like "from" and "to" are optional, and so are the spaces, as
long as you don't run two dates together. "to" can also be written as
"-". These are equivalent to the above:
-p "2009/1/1 2009/4/1"
-p2009/1/1to2009/4/1
-p2009/1/1-2009/4/1
Dates are smart dates, so if the current year is 2009, the above can
Dates are smart dates, so if the current year is 2009, the above can
also be written as:
-p "1/1 4/1"
@ -1013,48 +995,46 @@ OPTIONS
1, 2009
-p "from 2009/1" the same
-p "from 2009" the same
-p "to 2009" everything before january
-p "to 2009" everything before january
1, 2009
A single date with no "from" or "to" defines both the start and end
A single date with no "from" or "to" defines both the start and end
date like so:
-p "2009" the year 2009; equivalent
-p "2009" the year 2009; equivalent
to "2009/1/1 to 2010/1/1"
-p "2009/1" the month of jan; equiva-
-p "2009/1" the month of jan; equiva-
lent to "2009/1/1 to
2009/2/1"
-p "2009/1/1" just that day; equivalent
-p "2009/1/1" just that day; equivalent
to "2009/1/1 to 2009/1/2"
The argument of -p can also begin with, or be, a report interval ex-
The argument of -p can also begin with, or be, a report interval ex-
pression. The basic report intervals are daily, weekly, monthly, quar-
terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y
flags. Between report interval and start/end dates (if any), the word
terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y
flags. Between report interval and start/end dates (if any), the word
in is optional. Examples:
-p "weekly from 2009/1/1 to 2009/4/1"
-p "monthly in 2008"
-p "quarterly"
Note that weekly, monthly, quarterly and yearly intervals will always
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 ex-
will end on the last day of same period, even if associated period ex-
pression 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 pre-
ceding 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
-p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon-
to 2009/4/1" day
-p "monthly in starts on 2018/11/01
2008/11/25"
-p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
2009-05-05 to 2009-06-01" which are first and last days of Q2 2009
-p "yearly from starts on 2009/01/01, first day of 2009
2009-12-29"
The following more complex report intervals are also supported: bi-
weekly, bimonthly, every day|week|month|quarter|year, every N
@ -1065,14 +1045,11 @@ OPTIONS
Examples:
-p "bimonthly from 2008" -- periods
will have boundaries on 2008/01/01,
2008/03/01, ...
-p "every 2 weeks" -- starts on closest
preceding Monday
-p "every 5 month from 2009/03" -- pe-
riods will have boundaries on
2009/03/01, 2009/08/01, ...
-p "bimonthly from 2008" periods will have boundaries on 2008/01/01,
2008/03/01, ...
-p "every 2 weeks" starts on closest preceding Monday
-p "every 5 month from periods will have boundaries on 2009/03/01,
2009/03" 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:
@ -1083,18 +1060,17 @@ OPTIONS
Examples:
-p "every 2nd day of week" -- periods
will go from Tue to Tue
-p "every Tue" -- same
-p "every 15th day" -- period bound-
aries 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
-p "every 2nd day of periods will go from Tue to Tue
week"
-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):
@ -1403,9 +1379,6 @@ OPTIONS
ance (with -H) before report before report DATE/today
or journal or journal
start start
posting cost value at report value at report value at
amounts (no end or today or journal end DATE/today
report inter-
@ -1424,6 +1397,7 @@ OPTIONS
report inter- end or today of or journal end DATE/today of
val) sums of post- of sums of sums of post-
ings postings ings
balances (with sums of costs value at period value at period value at
report inter- ends of sums of ends of sums of DATE/today of
val) postings postings sums of post-