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 .PP
.TS .TS
tab(@); tab(@);
lw(9.9n) lw(60.1n). lw(9.7n) lw(60.3n).
T{ T{
status status
T}@T{ T}@T{
@ -1033,7 +1033,7 @@ And some definitions:
.PP .PP
.TS .TS
tab(@); tab(@);
lw(8.9n) lw(61.1n). lw(6.0n) lw(64.0n).
T{ T{
subdirective subdirective
T}@T{ T}@T{

123
hledger-lib/hledger_journal.info
View File

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

314
hledger-lib/hledger_journal.txt
View File

@ -710,49 +710,51 @@ FILE FORMAT
And some definitions: And some definitions:
subdirec- optional indented directive line immediately following a par- subdi- optional indented directive line immediately following a parent
tive ent directive rec- directive
number how to interpret numbers when parsing journal entries (the tive
notation identity of the decimal separator character). (Currently number how to interpret numbers when parsing journal entries (the iden-
each commodity can have its own notation, even in the same nota- tity of the decimal separator character). (Currently each com-
file.) tion modity can have its own notation, even in the same file.)
display how to display amounts of a commodity in reports (symbol side dis- how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places) play and spacing, digit groups, decimal separator, decimal places)
directive which entries and (when there are multiple files) which files style
scope are affected by a directive 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 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- affect, and whether they are focussed on input (parsing) or output (re-
ports). Some directives have multiple effects. ports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f 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 options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro- typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by 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. times though.
Comment blocks 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) and a line containing just end comment (or the end of the current file)
ends it. See also comments. ends it. See also comments.
Including other files 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: directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g. 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. clude journal, timeclock or timedot files, but not CSV files.
Default year Default year
You can set a default year to be used for subsequent dates which don't You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -774,18 +776,18 @@ FILE FORMAT
Declaring commodities Declaring commodities
The commodity directive has several functions: 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. currently not enforced, but can serve as documentation.
2. It declares what decimal mark character to expect when parsing input 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). (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 3. It declares the amount display format to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc. digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di- 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 rectives, sooner or later, so it's a good idea to just always use them
to declare your commodities. to declare your commodities.
A commodity directive is just the word commodity followed by an amount. A commodity directive is just the word commodity followed by an amount.
@ -798,8 +800,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. (In this case or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places.): places.):
; commodity SYMBOL ; commodity SYMBOL
@ -812,14 +814,14 @@ FILE FORMAT
format INR 1,00,00,000.00 format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi- 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. comma, followed by 0 or more decimal digits.
Default commodity Default commodity
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive. amounts, or until the next D directive.
; commodity-less amounts should be treated as dollars ; commodity-less amounts should be treated as dollars
@ -834,9 +836,9 @@ FILE FORMAT
a decimal point. a decimal point.
Market prices Market prices
The P directive declares a market price, which is an exchange rate be- 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 tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange, "historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market. cryptocurrency exchange, or the foreign exchange market.
Here is the format: Here is the format:
@ -847,16 +849,16 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced 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. 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: dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 EUR $1.35 P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40 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. commodity using these prices.
Declaring accounts Declaring accounts
@ -866,20 +868,20 @@ FILE FORMAT
o They can document your intended chart of accounts, providing a refer- o They can document your intended chart of accounts, providing a refer-
ence. ence.
o They can store extra information about accounts (account numbers, o They can store extra information about accounts (account numbers,
notes, etc.) notes, etc.)
o They can help hledger know your accounts' types (asset, liability, o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and equity, revenue, expense), useful for reports like balancesheet and
incomestatement. 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). 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. 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 name, eg:
account assets:bank:checking account assets:bank:checking
@ -887,7 +889,7 @@ FILE FORMAT
Account comments Account comments
Comments, beginning with a semicolon, can be added: 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) account names)
o on the next lines, indented o on the next lines, indented
@ -901,7 +903,7 @@ FILE FORMAT
Same-line comments are not supported by Ledger, or hledger <1.13. Same-line comments are not supported by Ledger, or hledger <1.13.
Account subdirectives Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.: for compatibility.:
account assets:bank:checking account assets:bank:checking
@ -914,18 +916,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED] [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types Account types
hledger recognises five types (or classes) of account: Asset, Liabil- hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow. reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types Auto-detected account types
If you name your top-level accounts with some variation of assets, lia- 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. detected automatically.
Account types declared with tags Account types declared with tags
More generally, you can declare an account's type with an account di- 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 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 words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive): ALERX (case insensitive):
@ -936,8 +938,8 @@ FILE FORMAT
account expenses ; type:Expenses account expenses ; type:Expenses
Account types declared with account type codes Account types declared with account type codes
Or, you can write one of those letters separated from the account name 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- by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13: cated as of hledger 1.13:
account assets A account assets A
@ -947,7 +949,7 @@ FILE FORMAT
account expenses X account expenses X
Overriding auto-detected types 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: names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
@ -958,8 +960,8 @@ FILE FORMAT
account - ; type:L account - ; type:L
Account display order Account display order
Account directives also set the order in which accounts are displayed, Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal: you have these account directives in the journal:
@ -981,20 +983,20 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order. Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently, each group of sibling accounts under the same parent). And currently,
this directive: this directive:
account other:zoo 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: 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- that you don't intend to post to, just to customize their display or-
der 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). a:b and a:c).
Rewriting accounts Rewriting accounts
@ -1012,14 +1014,14 @@ FILE FORMAT
o customising reports o customising reports
Account aliases also rewrite account names in account directives. They 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. web.
See also Rewrite account names. See also Rewrite account names.
Basic aliases Basic aliases
To set an account alias, use the alias directive in your journal file. 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 This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional: included files. The spaces around the = are optional:
alias OLD = NEW alias OLD = NEW
@ -1027,49 +1029,49 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This 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. affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will re- 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- place any occurrence of the old account name with the new one. Subac-
counts are also affected. Eg: counts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking 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" ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases Regex aliases
There is also a more powerful variant that uses a regular expression, There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes: indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'. or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE- inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref- MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg: erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command 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- line, to end of option argument), so it can contain trailing white-
space. space.
Combining aliases 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. and/or command line options.
Recursive aliases - where an account name is rewritten by one alias, Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases. effect of previously applied aliases.
In such cases it can be important to understand which aliases will be 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 applied and in which order. For (each account name in) each journal
entry, we apply: 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) 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). (left to right).
In other words, for (an account name in) a given journal entry: 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. o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro- This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde- vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order. 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. which aliases are being applied when.
end aliases 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: aliases directive:
end aliases end aliases
Default parent account Default parent account
You can specify a parent account which will be prepended to all ac- 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 counts within a section of the journal. Use the apply account and end
apply account directives like so: apply account directives like so:
apply account home apply account home
@ -1112,7 +1114,7 @@ FILE FORMAT
home:food $10 home:food $10
home:cash $-10 home:cash $-10
If end apply account is omitted, the effect lasts to the end of the If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg: file. Included files are also affected, eg:
apply account business apply account business
@ -1121,50 +1123,50 @@ FILE FORMAT
apply account personal apply account personal
include personal.journal include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup- Prior to hledger 1.0, legacy account and end spellings were also sup-
ported. ported.
A default parent account also affects account directives. It does not A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent account aliases are present, they are applied after the default parent
account. account.
Periodic transactions Periodic transactions
Periodic transaction rules describe transactions that recur. They al- Periodic transaction rules describe transactions that recur. They al-
low hledger to generate temporary future transactions to help with low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal, 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 and it's easy to try out different forecasts. Secondly, they are also
used to define the budgets shown in budget reports. 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: 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. read about this below.
2. For troubleshooting, show the generated transactions with hledger 2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast print --forecast tag:generated or hledger register --forecast
tag:generated. 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. 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. 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. provement, but is worth studying.
6. Some period expressions with a repeating interval must begin on a 6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE 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 must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
error. error.
7. Other period expressions with an interval are automatically expanded 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 reports, but it also affects periodic transactions. Yes, it's a bit
inconsistent with the above.) Eg: ~ 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, which is equivalent to ~ every 10th day of month from
2020/01/01, will be adjusted to start on 2019/12/10. 2020/01/01, will be adjusted to start on 2019/12/10.
Periodic rule syntax Periodic rule syntax
@ -1176,17 +1178,17 @@ FILE FORMAT
expenses:rent $2000 expenses:rent $2000
assets:bank:checking assets:bank:checking
There is an additional constraint on the period expression: the start There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg monthly from 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. 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 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 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 date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1. they will be relative to Y/1/1.
Two spaces between period expression and description! 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 these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden- where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example: tally alter their meaning, as in this example:
@ -1200,82 +1202,82 @@ FILE FORMAT
So, 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. 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. pression.
Forecasting with periodic transactions Forecasting with periodic transactions
With the --forecast flag, each periodic transaction rule generates fu- With the --forecast flag, each periodic transaction rule generates fu-
ture transactions recurring at the specified interval. These are not ture transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag: 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 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: appear in hledger's output:
o _generated-transaction:~ PERIODICEXPR 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. than generated in the past and saved to the journal.
Forecast transactions start on the first occurrence, and end on the Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The last occurrence, of their interval within the forecast period. The
forecast period: forecast period:
o begins on the later of o begins on the later of
o the report start date if specified with -b/-p/date: 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. 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. days from today.
where "today" means the current date at report time. The "later of" where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac- rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end. tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal means that forecasted transactions are automatically replaced by normal
transactions as you add those. transactions as you add those.
Forecasting can also help with data entry: describe most of your trans- 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. print --forecast to the journal.
You can generate one-time transactions too: just write a period expres- You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.) forecast transactions on previous dates.)
Budgeting with periodic transactions Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command, With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com- checking) every month. Goals and actual performance can then be com-
pared in budget reports. 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. casting.
Auto postings / transaction modifiers Auto postings / transaction modifiers
Transaction modifier rules, AKA auto posting rules, describe changes to Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become call "automated postings" or just "auto postings". These rules become
active when you use the --auto flag. active when you use the --auto flag.
A transaction modifier rule looks much like a normal transaction except 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- the first line is an equals sign followed by a query that matches cer-
tain postings (mnemonic: = suggests matching). And each "posting" is tain postings (mnemonic: = suggests matching). And each "posting" is
actually a posting-generating rule: actually a posting-generating rule:
= QUERY = QUERY
@ -1283,25 +1285,25 @@ FILE FORMAT
ACCT [AMT] 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: 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. as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post- o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this. 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 matched posting's amount (and total price, if any) will be multiplied
by N. 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 symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S. its commodity symbol will be replaced with S.
A query term containing spaces must be enclosed in single or double 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 quotes, as on the command line. Eg, note the quotes around the second
query term below: query term below:
= expenses:groceries 'expenses:dining out' = expenses:groceries 'expenses:dining out'
@ -1343,20 +1345,20 @@ FILE FORMAT
assets:checking $20 assets:checking $20
Auto postings and dates Auto postings and dates
A posting date (or secondary date) in the matched posting, or (taking A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also precedence) a posting date in the auto posting rule itself, will also
be used in the generated posting. be used in the generated posting.
Auto postings and transaction balancing / inferred amounts / balance asser- Auto postings and transaction balancing / inferred amounts / balance asser-
tions tions
Currently, transaction modifiers are applied / auto postings are added: 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, balancedness,
o but before balance assertions are checked. 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 after auto postings are added. This changed in hledger 1.12+; see #893
for background. for background.
@ -1366,11 +1368,11 @@ FILE FORMAT
o generated-posting:= QUERY - shows this was generated by an auto post- o generated-posting:= QUERY - shows this was generated by an auto post-
ing rule, and the query 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 hledger's output. This can be used to match postings generated "just
now", rather than generated in the past and saved to the journal. 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: rules will have these tags added:
o modified: - this transaction was modified o modified: - this transaction was modified
@ -1381,7 +1383,7 @@ FILE FORMAT
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -1395,7 +1397,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)

91
hledger/hledger.1
View File

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

358
hledger/hledger.info
View File

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

186
hledger/hledger.txt
View File

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