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

regen manuals

Browse Source
This commit is contained in:
Simon Michael 2018-04-29 18:04:59 -07:00
parent 59c804dac4
commit 290ea1891a
6 changed files with 1039 additions and 1018 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

398
hledger-lib/hledger_journal.5
View File

@ -758,11 +758,6 @@ Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
(Star comments cause org\-mode nodes to be ignored, allowing emacs users
to fold and navigate their journals with org\-mode or orgstruct\-mode.)
.PP
Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[]
directives is a (multi\-line) comment.
If there is no \f[C]end\ comment\f[], the comment extends to the end of
the file.
.PP
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the
postings).
@ -795,6 +790,9 @@ end\ comment
;\ a\ file\ comment\ (because\ not\ indented)
\f[]
.fi
.PP
You can also comment larger regions of a file using \f[C]comment\f[] and
\f[C]end\ comment\f[] directives.
.SS Tags
.PP
Tags are a way to add extra labels or labelled data to postings and
@ -855,7 +853,173 @@ For example, the following transaction has three tags (\f[C]A\f[],
Tags are like Ledger's metadata feature, except hledger's tag values are
simple strings.
.SS Directives
.SS Account aliases
.SS Comment blocks
.PP
A line containing just \f[C]comment\f[] starts a commented region of the
file, and a line containing just \f[C]end\ comment\f[] (or the end of
the current file) ends it.
See also comments.
.SS Including other files
.PP
You can pull in the content of additional files by writing an include
directive, like this:
.IP
.nf
\f[C]
include\ path/to/file.journal
\f[]
.fi
.PP
If the path does not begin with a slash, it is relative to the current
file.
Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SS Default year
.PP
You can set a default year to be used for subsequent dates which don't
specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year.
Eg:
.IP
.nf
\f[C]
Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009
12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15
\ \ expenses\ \ 1
\ \ assets
Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010
2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected
\ \ expenses\ \ 1
\ \ assets
1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31
\ \ expenses\ \ 1
\ \ assets
\f[]
.fi
.SS Declaring commodities
.PP
The \f[C]commodity\f[] directive declares commodities which may be used
in the journal (though currently we do not enforce this).
It may be written on a single line, like this:
.IP
.nf
\f[C]
;\ commodity\ EXAMPLEAMOUNT
;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated,
;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and
;\ separating\ thousands\ with\ comma.
commodity\ 1,000.0000\ AAAA
\f[]
.fi
.PP
or on multiple lines, using the \[lq]format\[rq] subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
.nf
\f[C]
;\ commodity\ SYMBOL
;\ \ \ format\ EXAMPLEAMOUNT
;\ display\ indian\ rupees\ with\ currency\ name\ on\ the\ left,
;\ thousands,\ lakhs\ and\ crores\ comma\-separated,
;\ period\ as\ decimal\ point,\ and\ two\ decimal\ places.
commodity\ INR
\ \ format\ INR\ 9,99,99,999.00
\f[]
.fi
.PP
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity.
Normally the display format is inferred from journal entries, but this
can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity.
Towards this end, amounts in commodity directives must always be written
with a decimal point (a period or comma, followed by 0 or more decimal
digits).
.SS Default commodity
.PP
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers).
(Note this differs from Ledger's default commodity directive.) The
commodity and display format will be applied to all subsequent
commodity\-less amounts, or until the next D directive.
.IP
.nf
\f[C]
#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars
#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places)
D\ $1,000.00
1/1
\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1
\ \ b
\f[]
.fi
.PP
As with the \f[C]commodity\f[] directive, the amount must always be
written with a decimal point.
.SS Declaring accounts
.PP
The \f[C]account\f[] directive predeclares account names.
The simplest form is \f[C]account\ ACCTNAME\f[], eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\f[]
.fi
.PP
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
.PD 0
.P
.PD
In future it will also help detect misspelled accounts.
.PP
Account names can be followed by a numeric account code:
.IP
.nf
\f[C]
account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
account\ assets:bank:checking\ \ \ \ 1110
account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
\f[]
.fi
.PP
This affects account display order in reports: accounts with codes are
listed before accounts without codes, in increasing code order.
(Otherwise, accounts are listed alphabetically.) Account codes should be
all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces).
By convention, often the first digit indicates the type of account, as
in this numbering scheme and the example above.
In future, we might use this to recognize account types.
.PP
An account directive can also have indented subdirectives following it,
which are currently ignored.
Here is the full syntax:
.IP
.nf
\f[C]
;\ account\ ACCTNAME\ \ [OPTIONALCODE]
;\ \ \ [OPTIONALSUBDIRECTIVES]
account\ assets:bank:checking\ \ \ 1110
\ \ a\ comment
\ \ some\-tag:12345
\f[]
.fi
.SS Rewriting accounts
.PP
You can define aliases which rewrite your account names (after reading
the journal, before generating reports).
@ -871,7 +1035,7 @@ combining two accounts into one
.IP \[bu] 2
customising reports
.PP
See also Cookbook: rewrite account names.
See also Cookbook: Rewrite account names.
.SS Basic aliases
.PP
To set an account alias, use the \f[C]alias\f[] directive in your
@ -946,7 +1110,7 @@ alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
.IP "2." 3
alias options, in the order they appear on the command line
.SS end aliases
.SS \f[C]end\ aliases\f[]
.PP
You can clear (forget) all currently defined aliases with the
\f[C]end\ aliases\f[] directive:
@ -956,60 +1120,7 @@ You can clear (forget) all currently defined aliases with the
end\ aliases
\f[]
.fi
.SS account directive
.PP
The \f[C]account\f[] directive predeclares account names.
The simplest form is \f[C]account\ ACCTNAME\f[], eg:
.IP
.nf
\f[C]
account\ assets:bank:checking
\f[]
.fi
.PP
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
.PD 0
.P
.PD
In future it will also help detect misspelled accounts.
.PP
Account names can be followed by a numeric account code:
.IP
.nf
\f[C]
account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
account\ assets:bank:checking\ \ \ \ 1110
account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
\f[]
.fi
.PP
This affects account display order in reports: accounts with codes are
listed before accounts without codes, in increasing code order.
(Otherwise, accounts are listed alphabetically.) Account codes should be
all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces).
By convention, often the first digit indicates the type of account, as
in this numbering scheme and the example above.
In future, we might use this to recognize account types.
.PP
An account directive can also have indented subdirectives following it,
which are currently ignored.
Here is the full syntax:
.IP
.nf
\f[C]
;\ account\ ACCTNAME\ \ [OPTIONALCODE]
;\ \ \ [OPTIONALSUBDIRECTIVES]
account\ assets:bank:checking\ \ \ 1110
\ \ a\ comment
\ \ some\-tag:12345
\f[]
.fi
.SS apply account directive
.SS Default parent account
.PP
You can specify a parent account which will be prepended to all accounts
within a section of the journal.
@ -1054,125 +1165,13 @@ include\ personal.journal
.PP
Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported.
.SS Multi\-line comments
.SS Periodic transactions
.PP
A line containing just \f[C]comment\f[] starts a multi\-line comment,
and a line containing just \f[C]end\ comment\f[] ends it.
See comments.
.SS commodity directive
.PP
The \f[C]commodity\f[] directive declares commodities which may be used
in the journal (though currently we do not enforce this).
It may be written on a single line, like this:
.IP
.nf
\f[C]
;\ commodity\ EXAMPLEAMOUNT
;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated,
;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and
;\ separating\ thousands\ with\ comma.
commodity\ 1,000.0000\ AAAA
\f[]
.fi
.PP
or on multiple lines, using the \[lq]format\[rq] subdirective.
In this case the commodity symbol appears twice and should be the same
in both places:
.IP
.nf
\f[C]
;\ commodity\ SYMBOL
;\ \ \ format\ EXAMPLEAMOUNT
;\ display\ indian\ rupees\ with\ currency\ name\ on\ the\ left,
;\ thousands,\ lakhs\ and\ crores\ comma\-separated,
;\ period\ as\ decimal\ point,\ and\ two\ decimal\ places.
commodity\ INR
\ \ format\ INR\ 9,99,99,999.00
\f[]
.fi
.PP
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity.
Normally the display format is inferred from journal entries, but this
can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity.
Towards this end, amounts in commodity directives must always be written
with a decimal point (a period or comma, followed by 0 or more decimal
digits).
.SS Default commodity
.PP
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers).
(Note this differs from Ledger's default commodity directive.) The
commodity and display format will be applied to all subsequent
commodity\-less amounts, or until the next D directive.
.IP
.nf
\f[C]
#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars
#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places)
D\ $1,000.00
1/1
\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1
\ \ b
\f[]
.fi
.PP
As with the \f[C]commodity\f[] directive, the amount must always be
written with a decimal point.
.SS Default year
.PP
You can set a default year to be used for subsequent dates which don't
specify a year.
This is a line beginning with \f[C]Y\f[] followed by the year.
Eg:
.IP
.nf
\f[C]
Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009
12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15
\ \ expenses\ \ 1
\ \ assets
Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010
2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected
\ \ expenses\ \ 1
\ \ assets
1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31
\ \ expenses\ \ 1
\ \ assets
\f[]
.fi
.SS Including other files
.PP
You can pull in the content of additional journal files by writing an
include directive, like this:
.IP
.nf
\f[C]
include\ path/to/file.journal
\f[]
.fi
.PP
If the path does not begin with a slash, it is relative to the current
file.
Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SH Periodic transactions
.PP
Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with \f[C]\-\-forecast\f[]), or
budget goals (with \f[C]\-\-budget\f[]).
They look a bit like a transaction, except the first line is a tilde
(\f[C]~\f[]) followed by a period expression:
Periodic transaction rules (enabled by \f[C]\-\-forecast\f[] or
\f[C]\-\-budget\f[]) describe recurring transactions.
They look like a transaction where the first line is a tilde
(\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] is
like a recurring sine wave):
.IP
.nf
\f[C]
@ -1182,25 +1181,34 @@ They look a bit like a transaction, except the first line is a tilde
\f[]
.fi
.PP
Periodic transactions have a dual purpose:
.IP \[bu] 2
With \f[C]\-\-forecast\f[], each periodic transaction rule generates
recurring \[lq]forecast\[rq] transactions at the specified interval,
beginning the day after the latest recorded journal transaction (or
today, if there are no transactions) and ending 6 months from today (or
at the report end date, if specified).
.PP
With \f[C]balance\ \-\-budget\f[], each periodic transaction declares
recurring budget goals for the specified accounts.
future transactions, recurring at the specified interval, which can be
seen in reports.
Forecast transactions begin the day after the latest recorded journal
transaction (or today, if there are no transactions) and end 6 months
from today (or at the report end date, if specified).
.IP \[bu] 2
With \f[C]\-\-budget\f[] (supported by the balance command), each
periodic transaction rule declares recurring budget goals for the
specified accounts, which can be seen in budget reports.
Eg the example above declares the goal of receiving $400 from
\f[C]income:acme\ inc\f[] (and also, depositing $400 into
\f[C]assets:bank:checking\f[]) every week.
.PP
For more details, see: balance: Budgeting and Budgeting and Forecasting.
.SH Automated postings
(Actually, you can generate one\-off transactions too, by writing a
period expression with no report interval.)
.PP
Automated postings are postings added automatically by rule to certain
transactions (with \f[C]\-\-auto\f[]).
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
.SS Automated postings
.PP
Automated postings (enabled by \f[C]\-\-auto\f[]) are postings added
automatically by rule to certain transactions.
An automated posting rule looks like a transaction where the first line
is an equal sign (\f[C]=\f[]) followed by a query:
is an equal sign (\f[C]=\f[]) followed by a query (mnemonic: \f[C]=\f[]
tests for matching transactions, and also looks like posting lines):
.IP
.nf
\f[C]
@ -1240,10 +1248,8 @@ $\ hledger\ print\ \-\-auto
\f[]
.fi
.PP
Automated postings would not be distinguishable from equivalent postings
written by hand.
In particular, they would affect [amount inference|#postings] and
[balance assertion|#balance\-assertions] checks in the usual way.
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with

652
hledger-lib/hledger_journal.info
View File

@ -57,12 +57,10 @@ assisted by the helper modes for emacs or vim.
* Menu:
* FILE FORMAT::
* Periodic transactions::
* Automated postings::
* EDITOR SUPPORT::

File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top
File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top
1 FILE FORMAT
*************
@ -83,6 +81,8 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, P
* Comments::
* Tags::
* Directives::
* Periodic transactions::
* Automated postings::

File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
@ -713,10 +713,6 @@ star ('*') are comments, and will be ignored. (Star comments cause
org-mode nodes to be ignored, allowing emacs users to fold and navigate
their journals with org-mode or orgstruct-mode.)
Also, anything between 'comment' and 'end comment' directives is a
(multi-line) comment. If there is no 'end comment', the comment extends
to the end of the file.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual posting
@ -744,6 +740,9 @@ end comment
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using 'comment' and
'end comment' directives.

File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
@ -788,128 +787,142 @@ example, the following transaction has three tags ('A', 'TAG2',
are simple strings.

File: hledger_journal.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Tags, Up: FILE FORMAT
1.14 Directives
===============
* Menu:
* Account aliases::
* account directive::
* apply account directive::
* Multi-line comments::
* commodity directive::
* Default commodity::
* Default year::
* Comment blocks::
* Including other files::
* Default year::
* Declaring commodities::
* Default commodity::
* Declaring accounts::
* Rewriting accounts::
* Default parent account::

File: hledger_journal.info, Node: Account aliases, Next: account directive, Up: Directives
File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives
1.14.1 Account aliases
----------------------
1.14.1 Comment blocks
---------------------
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
* expanding shorthand account names to their full form, allowing
easier data entry and a less verbose journal
* adapting old journals to your current chart of accounts
* experimenting with new account organisations, like a new hierarchy
or combining two accounts into one
* customising reports
See also Cookbook: rewrite account names.
* Menu:
* Basic aliases::
* Regex aliases::
* Multiple aliases::
* end aliases::
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.

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives
1.14.1.1 Basic aliases
......................
1.14.2 Including other files
----------------------------
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:
You can pull in the content of additional files by writing an include
directive, like this:
alias OLD = NEW
include path/to/file.journal
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.
If the path does not begin with a slash, it is relative to the
current file. Glob patterns ('*') are not currently supported.
OLD and NEW are full account names. hledger will replace any
occurrence of the old account name with the new one. Subaccounts are
also affected. Eg:
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"
The 'include' directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives
1.14.1.2 Regex aliases
......................
1.14.3 Default year
-------------------
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
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:
alias /REGEX/ = REPLACEMENT
Y2009 ; set default year to 2009
or '--alias '/REGEX/=REPLACEMENT''.
12/15 ; equivalent to 2009/12/15
expenses 1
assets
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by
REPLACEMENT. If REGEX contains parenthesised match groups, these can be
referenced by the usual numeric backreferences in REPLACEMENT. Eg:
Y2010 ; change default year to 2010
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
2009/1/30 ; specifies the year, not affected
expenses 1
assets
Also note that REPLACEMENT continues to the end of line (or on
command line, to end of option argument), so it can contain trailing
whitespace.
1/31 ; equivalent to 2010/1/31
expenses 1
assets

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives
1.14.1.3 Multiple aliases
.........................
1.14.4 Declaring commodities
----------------------------
You can define as many aliases as you like using directives or
command-line options. Aliases are recursive - each alias sees the
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
The 'commodity' directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written on
a single line, like this:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
; commodity EXAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated,
; using period as decimal point, with four decimal places, and
; 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
places:
; commodity SYMBOL
; format EXAMPLEAMOUNT
; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated,
; period as decimal point, and two decimal places.
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display
format is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0
or more decimal digits).

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
File: hledger_journal.info, Node: Default commodity, Next: Declaring accounts, Prev: Declaring commodities, Up: Directives
1.14.1.4 end aliases
....................
You can clear (forget) all currently defined aliases with the 'end
aliases' directive:
end aliases

File: hledger_journal.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
1.14.2 account directive
1.14.5 Default commodity
------------------------
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
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
b
As with the 'commodity' directive, the amount must always be written
with a decimal point.

File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Default commodity, Up: Directives
1.14.6 Declaring accounts
-------------------------
The 'account' directive predeclares account names. The simplest form is
'account ACCTNAME', eg:
@ -947,10 +960,110 @@ account assets:bank:checking 1110
some-tag:12345

File: hledger_journal.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
1.14.3 apply account directive
------------------------------
1.14.7 Rewriting accounts
-------------------------
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
* expanding shorthand account names to their full form, allowing
easier data entry and a less verbose journal
* adapting old journals to your current chart of accounts
* experimenting with new account organisations, like a new hierarchy
or combining two accounts into one
* customising reports
See also Cookbook: Rewrite account names.
* Menu:
* Basic aliases::
* Regex aliases::
* Multiple aliases::
* end aliases::

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
1.14.7.1 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
included files. The spaces around the = are optional:
alias OLD = NEW
Or, you can use the '--alias 'OLD=NEW'' option on the command line.
This affects all entries. It's useful for trying out aliases
interactively.
OLD and NEW are full account names. hledger will replace any
occurrence of the old account name with the new one. Subaccounts are
also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts
1.14.7.2 Regex aliases
......................
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
REPLACEMENT. If REGEX contains parenthesised match groups, these can be
referenced 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
whitespace.

File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
1.14.7.3 Multiple aliases
.........................
You can define as many aliases as you like using directives or
command-line options. Aliases are recursive - each alias sees the
result of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the
following order:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line

File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts
1.14.7.4 'end aliases'
......................
You can clear (forget) all currently defined aliases with the 'end
aliases' directive:
end aliases

File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
1.14.8 Default parent account
-----------------------------
You can specify a parent account which will be prepended to all accounts
within a section of the journal. Use the 'apply account' and 'end apply
@ -983,157 +1096,52 @@ include personal.journal
supported.

File: hledger_journal.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: Directives, Up: FILE FORMAT
1.14.4 Multi-line comments
--------------------------
1.15 Periodic transactions
==========================
A line containing just 'comment' starts a multi-line comment, and a line
containing just 'end comment' ends it. See comments.

File: hledger_journal.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
1.14.5 commodity directive
--------------------------
The 'commodity' directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written on
a single line, like this:
; commodity EXAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated,
; using period as decimal point, with four decimal places, and
; 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
places:
; commodity SYMBOL
; format EXAMPLEAMOUNT
; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated,
; period as decimal point, and two decimal places.
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display
format is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0
or more decimal digits).

File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
1.14.6 Default commodity
------------------------
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
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
b
As with the 'commodity' directive, the amount must always be written
with a decimal point.

File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
1.14.7 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.
Eg:
Y2009 ; set default year to 2009
12/15 ; equivalent to 2009/12/15
expenses 1
assets
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
expenses 1
assets

File: hledger_journal.info, Node: Including other files, Prev: Default year, Up: Directives
1.14.8 Including other files
----------------------------
You can pull in the content of additional journal files by writing an
include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the
current file. Glob patterns ('*') are not currently supported.
The 'include' directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: FILE FORMAT, Up: Top
2 Periodic transactions
***********************
Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with '--forecast'), or budget
goals (with '--budget'). They look a bit like a transaction, except the
first line is a tilde ('~') followed by a period expression:
Periodic transaction rules (enabled by '--forecast' or '--budget')
describe recurring transactions. They look like a transaction where the
first line is a tilde ('~') followed by a period expression (mnemonic:
'~' is like a recurring sine wave):
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
With '--forecast', each periodic transaction rule generates recurring
"forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are no
transactions) and ending 6 months from today (or at the report end date,
if specified).
Periodic transactions have a dual purpose:
With 'balance --budget', each periodic transaction declares recurring
budget goals for the specified accounts. Eg the example above declares
the goal of receiving $400 from 'income:acme inc' (and also, depositing
$400 into 'assets:bank:checking') every week.
* With '--forecast', each periodic transaction rule generates future
transactions, recurring at the specified interval, which can be
seen in reports. Forecast transactions begin the day after the
latest recorded journal transaction (or today, if there are no
transactions) and end 6 months from today (or at the report end
date, if specified).
For more details, see: balance: Budgeting and Budgeting and
Forecasting.
* With '--budget' (supported by the balance command), each periodic
transaction rule declares recurring budget goals for the specified
accounts, which can be seen in budget reports. Eg the example
above declares the goal of receiving $400 from 'income:acme inc'
(and also, depositing $400 into 'assets:bank:checking') every week.
(Actually, you can generate one-off transactions too, by writing a
period expression with no report interval.)
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.

File: hledger_journal.info, Node: Automated postings, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top
File: hledger_journal.info, Node: Automated postings, Prev: Periodic transactions, Up: FILE FORMAT
3 Automated postings
********************
1.16 Automated postings
=======================
Automated postings are postings added automatically by rule to certain
transactions (with '--auto'). An automated posting rule looks like a
transaction where the first line is an equal sign ('=') followed by a
query:
Automated postings (enabled by '--auto') are postings added
automatically by rule to certain transactions. An automated posting
rule looks like a transaction where the first line is an equal sign
('=') followed by a query (mnemonic: '=' tests for matching
transactions, and also looks like posting lines):
= expenses:gifts
budget:gifts *-1
@ -1161,15 +1169,13 @@ $ hledger print --auto
(budget:gifts) $-20
assets
Automated postings would not be distinguishable from equivalent
postings written by hand. In particular, they would affect [amount
inference|#postings] and [balance assertion|#balance-assertions] checks
in the usual way.
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.

File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated postings, Up: Top
File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
4 EDITOR SUPPORT
2 EDITOR SUPPORT
****************
Add-on modes exist for various text editors, to make working with
@ -1196,89 +1202,89 @@ Code

Tag Table:
Node: Top76
Node: FILE FORMAT2425
Ref: #file-format2556
Node: Transactions2779
Ref: #transactions2900
Node: Postings3584
Ref: #postings3711
Node: Dates4706
Ref: #dates4821
Node: Simple dates4886
Ref: #simple-dates5012
Node: Secondary dates5378
Ref: #secondary-dates5532
Node: Posting dates7095
Ref: #posting-dates7224
Node: Status8598
Ref: #status8718
Node: Description10426
Ref: #description10564
Node: Payee and note10883
Ref: #payee-and-note10997
Node: Account names11239
Ref: #account-names11382
Node: Amounts11869
Ref: #amounts12005
Node: Virtual Postings15020
Ref: #virtual-postings15179
Node: Balance Assertions16399
Ref: #balance-assertions16574
Node: Assertions and ordering17470
Ref: #assertions-and-ordering17656
Node: Assertions and included files18356
Ref: #assertions-and-included-files18597
Node: Assertions and multiple -f options18930
Ref: #assertions-and-multiple--f-options19184
Node: Assertions and commodities19316
Ref: #assertions-and-commodities19551
Node: Assertions and subaccounts20247
Ref: #assertions-and-subaccounts20479
Node: Assertions and virtual postings21000
Ref: #assertions-and-virtual-postings21207
Node: Balance Assignments21349
Ref: #balance-assignments21518
Node: Prices22638
Ref: #prices22771
Node: Transaction prices22822
Ref: #transaction-prices22967
Node: Market prices25123
Ref: #market-prices25258
Node: Comments26218
Ref: #comments26340
Node: Tags27582
Ref: #tags27700
Node: Directives29102
Ref: #directives29215
Node: Account aliases29408
Ref: #account-aliases29552
Node: Basic aliases30156
Ref: #basic-aliases30299
Node: Regex aliases30989
Ref: #regex-aliases31157
Node: Multiple aliases31875
Ref: #multiple-aliases32047
Node: end aliases32545
Ref: #end-aliases32685
Node: account directive32786
Ref: #account-directive32966
Node: apply account directive34313
Ref: #apply-account-directive34509
Node: Multi-line comments35168
Ref: #multi-line-comments35358
Node: commodity directive35486
Ref: #commodity-directive35670
Node: Default commodity36897
Ref: #default-commodity37070
Node: Default year37702
Ref: #default-year37867
Node: Including other files38290
Ref: #including-other-files38447
Node: Periodic transactions38844
Ref: #periodic-transactions39010
Node: Automated postings39999
Ref: #automated-postings40162
Node: EDITOR SUPPORT41290
Ref: #editor-support41415
Node: FILE FORMAT2376
Ref: #file-format2500
Node: Transactions2772
Ref: #transactions2893
Node: Postings3577
Ref: #postings3704
Node: Dates4699
Ref: #dates4814
Node: Simple dates4879
Ref: #simple-dates5005
Node: Secondary dates5371
Ref: #secondary-dates5525
Node: Posting dates7088
Ref: #posting-dates7217
Node: Status8591
Ref: #status8711
Node: Description10419
Ref: #description10557
Node: Payee and note10876
Ref: #payee-and-note10990
Node: Account names11232
Ref: #account-names11375
Node: Amounts11862
Ref: #amounts11998
Node: Virtual Postings15013
Ref: #virtual-postings15172
Node: Balance Assertions16392
Ref: #balance-assertions16567
Node: Assertions and ordering17463
Ref: #assertions-and-ordering17649
Node: Assertions and included files18349
Ref: #assertions-and-included-files18590
Node: Assertions and multiple -f options18923
Ref: #assertions-and-multiple--f-options19177
Node: Assertions and commodities19309
Ref: #assertions-and-commodities19544
Node: Assertions and subaccounts20240
Ref: #assertions-and-subaccounts20472
Node: Assertions and virtual postings20993
Ref: #assertions-and-virtual-postings21200
Node: Balance Assignments21342
Ref: #balance-assignments21511
Node: Prices22631
Ref: #prices22764
Node: Transaction prices22815
Ref: #transaction-prices22960
Node: Market prices25116
Ref: #market-prices25251
Node: Comments26211
Ref: #comments26333
Node: Tags27503
Ref: #tags27621
Node: Directives29023
Ref: #directives29166
Node: Comment blocks29359
Ref: #comment-blocks29504
Node: Including other files29680
Ref: #including-other-files29860
Node: Default year30249
Ref: #default-year30418
Node: Declaring commodities30841
Ref: #declaring-commodities31024
Node: Default commodity32251
Ref: #default-commodity32432
Node: Declaring accounts33064
Ref: #declaring-accounts33244
Node: Rewriting accounts34591
Ref: #rewriting-accounts34776
Node: Basic aliases35380
Ref: #basic-aliases35526
Node: Regex aliases36216
Ref: #regex-aliases36387
Node: Multiple aliases37105
Ref: #multiple-aliases37280
Node: end aliases37778
Ref: #end-aliases37925
Node: Default parent account38026
Ref: #default-parent-account38192
Node: Periodic transactions38851
Ref: #periodic-transactions39030
Node: Automated postings40329
Ref: #automated-postings40483
Node: EDITOR SUPPORT41616
Ref: #editor-support41734

End Tag Table

320
hledger-lib/hledger_journal.txt
View File

@ -553,10 +553,6 @@ FILE FORMAT
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
to the end of the file.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
@ -584,6 +580,9 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using comment and
end comment directives.
Tags
Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
@ -625,7 +624,133 @@ FILE FORMAT
are simple strings.
Directives
Account aliases
Comment blocks
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
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported.
The include directive can only be used in journal files. It can
include 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.
Eg:
Y2009 ; set default year to 2009
12/15 ; equivalent to 2009/12/15
expenses 1
assets
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
expenses 1
assets
Declaring commodities
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated,
; using period as decimal point, with four decimal places, and
; 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
places:
; commodity SYMBOL
; format EXAMPLEAMOUNT
; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated,
; period as decimal point, and two decimal places.
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
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
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
b
As with the commodity directive, the amount must always be written with
a decimal point.
Declaring accounts
The account directive predeclares account names. The simplest form is
account ACCTNAME, eg:
account assets:bank:checking
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger-iadd, hledger-web, and ledger-mode.
In future it will also help detect misspelled accounts.
Account names can be followed by a numeric account code:
account assets 1000
account assets:bank:checking 1110
account liabilities 2000
account revenues 4000
account expenses 6000
This affects account display order in reports: accounts with codes are
listed before accounts without codes, in increasing code order. (Oth-
erwise, accounts are listed alphabetically.) Account codes should be
all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces). By
convention, often the first digit indicates the type of account, as in
this numbering scheme and the example above. In future, we might use
this to recognize account types.
An account directive can also have indented subdirectives following it,
which are currently ignored. Here is the full syntax:
; account ACCTNAME [OPTIONALCODE]
; [OPTIONALSUBDIRECTIVES]
account assets:bank:checking 1110
a comment
some-tag:12345
Rewriting accounts
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
@ -640,7 +765,7 @@ FILE FORMAT
o customising reports
See also Cookbook: rewrite account names.
See also Cookbook: Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
@ -697,44 +822,7 @@ FILE FORMAT
end aliases
account directive
The account directive predeclares account names. The simplest form is
account ACCTNAME, eg:
account assets:bank:checking
Currently this mainly helps with account name autocompletion in eg
hledger add, hledger-iadd, hledger-web, and ledger-mode.
In future it will also help detect misspelled accounts.
Account names can be followed by a numeric account code:
account assets 1000
account assets:bank:checking 1110
account liabilities 2000
account revenues 4000
account expenses 6000
This affects account display order in reports: accounts with codes are
listed before accounts without codes, in increasing code order. (Oth-
erwise, accounts are listed alphabetically.) Account codes should be
all numeric digits, unique, and separated from the account name by at
least two spaces (since account names may contain single spaces). By
convention, often the first digit indicates the type of account, as in
this numbering scheme and the example above. In future, we might use
this to recognize account types.
An account directive can also have indented subdirectives following it,
which are currently ignored. Here is the full syntax:
; account ACCTNAME [OPTIONALCODE]
; [OPTIONALSUBDIRECTIVES]
account assets:bank:checking 1110
a comment
some-tag:12345
apply account directive
Default parent account
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
@ -765,123 +853,43 @@ FILE FORMAT
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
Multi-line comments
A line containing just comment starts a multi-line comment, and a line
containing just end comment ends it. See comments.
commodity directive
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated,
; using period as decimal point, with four decimal places, and
; 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
places:
; commodity SYMBOL
; format EXAMPLEAMOUNT
; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated,
; period as decimal point, and two decimal places.
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
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
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
# (and displayed with symbol on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
b
As with the commodity directive, the amount must always be written with
a decimal point.
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.
Eg:
Y2009 ; set default year to 2009
12/15 ; equivalent to 2009/12/15
expenses 1
assets
Y2010 ; change default year to 2010
2009/1/30 ; specifies the year, not affected
expenses 1
assets
1/31 ; equivalent to 2010/1/31
expenses 1
assets
Including other files
You can pull in the content of additional journal files by writing an
include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported.
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Periodic transactions
Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with --forecast), or budget
goals (with --budget). They look a bit like a transaction, except the
first line is a tilde (~) followed by a period expression:
Periodic transactions
Periodic transaction rules (enabled by --forecast or --budget) describe
recurring transactions. They look like a transaction where the first
line is a tilde (~) followed by a period expression (mnemonic: ~ is
like a recurring sine wave):
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
With --forecast, each periodic transaction rule generates recurring
"forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are
no transactions) and ending 6 months from today (or at the report end
date, if specified).
Periodic transactions have a dual purpose:
With balance --budget, each periodic transaction declares recurring
budget goals for the specified accounts. Eg the example above declares
the goal of receiving $400 from income:acme inc (and also, depositing
$400 into assets:bank:checking) every week.
o With --forecast, each periodic transaction rule generates future
transactions, recurring at the specified interval, which can be seen
in reports. Forecast transactions begin the day after the latest
recorded journal transaction (or today, if there are no transactions)
and end 6 months from today (or at the report end date, if speci-
fied).
For more details, see: balance: Budgeting and Budgeting and Forecast-
ing.
o With --budget (supported by the balance command), each periodic
transaction rule declares recurring budget goals for the specified
accounts, which can be seen in budget reports. Eg the example above
declares the goal of receiving $400 from income:acme inc (and also,
depositing $400 into assets:bank:checking) every week.
Automated postings
Automated postings are postings added automatically by rule to certain
transactions (with --auto). An automated posting rule looks like a
transaction where the first line is an equal sign (=) followed by a
query:
(Actually, you can generate one-off transactions too, by writing a
period expression with no report interval.)
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
Automated postings
Automated postings (enabled by --auto) are postings added automatically
by rule to certain transactions. An automated posting rule looks like
a transaction where the first line is an equal sign (=) followed by a
query (mnemonic: = tests for matching transactions, and also looks like
posting lines):
= expenses:gifts
budget:gifts *-1
@ -909,10 +917,8 @@ Automated postings
(budget:gifts) $-20
assets
Automated postings would not be distinguishable from equivalent post-
ings written by hand. In particular, they would affect [amount infer-
ence|#postings] and [balance assertion|#balance-assertions] checks in
the usual way.
Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-

3
hledger/hledger.1
View File

@ -1607,7 +1607,8 @@ Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount.
\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more
compact output.
Use \f[C]\-\-no\-elide\f[] to prevent this.
(Eg above, the \[lq]liabilities\[rq] account.) Use
\f[C]\-\-no\-elide\f[] to prevent this.
.PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts.

161
hledger/hledger.info
View File

@ -1212,7 +1212,8 @@ sorted by account code if any, then by account name. Or with
"Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more
compact output. Use '--no-elide' to prevent this.
compact output. (Eg above, the "liabilities" account.) Use
'--no-elide' to prevent this.
Account balances are "inclusive" - they include the balances of any
subaccounts.
@ -2485,84 +2486,84 @@ Node: balance35737
Ref: #balance35848
Node: Classic balance report38931
Ref: #classic-balance-report39104
Node: Customising the classic balance report40433
Ref: #customising-the-classic-balance-report40661
Node: Colour support42735
Ref: #colour-support42902
Node: Flat mode43075
Ref: #flat-mode43223
Node: Depth limited balance reports43636
Ref: #depth-limited-balance-reports43836
Node: Multicolumn balance report44292
Ref: #multicolumn-balance-report44490
Node: Budget report49670
Ref: #budget-report49813
Ref: #output-format-152847
Node: balancesheet52925
Ref: #balancesheet53061
Node: balancesheetequity55372
Ref: #balancesheetequity55521
Node: cashflow56058
Ref: #cashflow56186
Node: check-dates58309
Ref: #check-dates58436
Node: check-dupes58553
Ref: #check-dupes58677
Node: close58814
Ref: #close58921
Node: help59251
Ref: #help59351
Node: import60425
Ref: #import60539
Node: incomestatement61269
Ref: #incomestatement61403
Node: prices63807
Ref: #prices63922
Node: print63965
Ref: #print64075
Node: print-unique68969
Ref: #print-unique69095
Node: register69163
Ref: #register69290
Node: Custom register output73791
Ref: #custom-register-output73920
Node: register-match75150
Ref: #register-match75284
Node: rewrite75467
Ref: #rewrite75584
Node: stats75653
Ref: #stats75756
Node: tags76626
Ref: #tags76724
Node: test76960
Ref: #test77044
Node: ADD-ON COMMANDS77412
Ref: #add-on-commands77522
Node: Official add-ons78809
Ref: #official-add-ons78949
Node: api79036
Ref: #api79125
Node: ui79177
Ref: #ui79276
Node: web79334
Ref: #web79423
Node: Third party add-ons79469
Ref: #third-party-add-ons79644
Node: diff79779
Ref: #diff79876
Node: iadd79975
Ref: #iadd80089
Node: interest80172
Ref: #interest80293
Node: irr80388
Ref: #irr80486
Node: Experimental add-ons80564
Ref: #experimental-add-ons80716
Node: autosync80996
Ref: #autosync81107
Node: chart81346
Ref: #chart81465
Node: check81536
Ref: #check81638
Node: Customising the classic balance report40473
Ref: #customising-the-classic-balance-report40701
Node: Colour support42775
Ref: #colour-support42942
Node: Flat mode43115
Ref: #flat-mode43263
Node: Depth limited balance reports43676
Ref: #depth-limited-balance-reports43876
Node: Multicolumn balance report44332
Ref: #multicolumn-balance-report44530
Node: Budget report49710
Ref: #budget-report49853
Ref: #output-format-152887
Node: balancesheet52965
Ref: #balancesheet53101
Node: balancesheetequity55412
Ref: #balancesheetequity55561
Node: cashflow56098
Ref: #cashflow56226
Node: check-dates58349
Ref: #check-dates58476
Node: check-dupes58593
Ref: #check-dupes58717
Node: close58854
Ref: #close58961
Node: help59291
Ref: #help59391
Node: import60465
Ref: #import60579
Node: incomestatement61309
Ref: #incomestatement61443
Node: prices63847
Ref: #prices63962
Node: print64005
Ref: #print64115
Node: print-unique69009
Ref: #print-unique69135
Node: register69203
Ref: #register69330
Node: Custom register output73831
Ref: #custom-register-output73960
Node: register-match75190
Ref: #register-match75324
Node: rewrite75507
Ref: #rewrite75624
Node: stats75693
Ref: #stats75796
Node: tags76666
Ref: #tags76764
Node: test77000
Ref: #test77084
Node: ADD-ON COMMANDS77452
Ref: #add-on-commands77562
Node: Official add-ons78849
Ref: #official-add-ons78989
Node: api79076
Ref: #api79165
Node: ui79217
Ref: #ui79316
Node: web79374
Ref: #web79463
Node: Third party add-ons79509
Ref: #third-party-add-ons79684
Node: diff79819
Ref: #diff79916
Node: iadd80015
Ref: #iadd80129
Node: interest80212
Ref: #interest80333
Node: irr80428
Ref: #irr80526
Node: Experimental add-ons80604
Ref: #experimental-add-ons80756
Node: autosync81036
Ref: #autosync81147
Node: chart81386
Ref: #chart81505
Node: check81576
Ref: #check81678

End Tag Table

3
hledger/hledger.txt
View File

@ -1099,7 +1099,8 @@ COMMANDS
"Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com-
pact output. Use --no-elide to prevent this.
pact output. (Eg above, the "liabilities" account.) Use --no-elide to
prevent this.
Account balances are "inclusive" - they include the balances of any
subaccounts.