slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions 2 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 (Star comments cause org\-mode nodes to be ignored, allowing emacs users
to fold and navigate their journals with org\-mode or orgstruct\-mode.) to fold and navigate their journals with org\-mode or orgstruct\-mode.)
.PP .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 You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the description and/or indented on the following lines (before the
postings). postings).
@ -795,6 +790,9 @@ end\ comment
;\ a\ file\ comment\ (because\ not\ indented) ;\ a\ file\ comment\ (because\ not\ indented)
\f[] \f[]
.fi .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 .SS Tags
.PP .PP
Tags are a way to add extra labels or labelled data to postings and Tags are a way to add extra labels or labelled data to postings and
@ -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 Tags are like Ledger's metadata feature, except hledger's tag values are
simple strings. simple strings.
.SS Directives .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 .PP
You can define aliases which rewrite your account names (after reading You can define aliases which rewrite your account names (after reading
the journal, before generating reports). the journal, before generating reports).
@ -871,7 +1035,7 @@ combining two accounts into one
.IP \[bu] 2 .IP \[bu] 2
customising reports customising reports
.PP .PP
See also Cookbook: rewrite account names. See also Cookbook: Rewrite account names.
.SS Basic aliases .SS Basic aliases
.PP .PP
To set an account alias, use the \f[C]alias\f[] directive in your 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) precedence over earlier ones; directives not yet seen are ignored)
.IP "2." 3 .IP "2." 3
alias options, in the order they appear on the command line alias options, in the order they appear on the command line
.SS end aliases .SS \f[C]end\ aliases\f[]
.PP .PP
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases with the
\f[C]end\ aliases\f[] directive: \f[C]end\ aliases\f[] directive:
@ -956,60 +1120,7 @@ You can clear (forget) all currently defined aliases with the
end\ aliases end\ aliases
\f[] \f[]
.fi .fi
.SS account directive .SS Default parent account
.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
.PP .PP
You can specify a parent account which will be prepended to all accounts You can specify a parent account which will be prepended to all accounts
within a section of the journal. within a section of the journal.
@ -1054,125 +1165,13 @@ include\ personal.journal
.PP .PP
Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported. were also supported.
.SS Multi\-line comments .SS Periodic transactions
.PP .PP
A line containing just \f[C]comment\f[] starts a multi\-line comment, Periodic transaction rules (enabled by \f[C]\-\-forecast\f[] or
and a line containing just \f[C]end\ comment\f[] ends it. \f[C]\-\-budget\f[]) describe recurring transactions.
See comments. They look like a transaction where the first line is a tilde
.SS commodity directive (\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] is
.PP like a recurring sine wave):
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:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1182,25 +1181,34 @@ They look a bit like a transaction, except the first line is a tilde
\f[] \f[]
.fi .fi
.PP .PP
Periodic transactions have a dual purpose:
.IP \[bu] 2
With \f[C]\-\-forecast\f[], each periodic transaction rule generates With \f[C]\-\-forecast\f[], each periodic transaction rule generates
recurring \[lq]forecast\[rq] transactions at the specified interval, future transactions, recurring at the specified interval, which can be
beginning the day after the latest recorded journal transaction (or seen in reports.
today, if there are no transactions) and ending 6 months from today (or Forecast transactions begin the day after the latest recorded journal
at the report end date, if specified). transaction (or today, if there are no transactions) and end 6 months
.PP from today (or at the report end date, if specified).
With \f[C]balance\ \-\-budget\f[], each periodic transaction declares .IP \[bu] 2
recurring budget goals for the specified accounts. 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 Eg the example above declares the goal of receiving $400 from
\f[C]income:acme\ inc\f[] (and also, depositing $400 into \f[C]income:acme\ inc\f[] (and also, depositing $400 into
\f[C]assets:bank:checking\f[]) every week. \f[C]assets:bank:checking\f[]) every week.
.PP .PP
For more details, see: balance: Budgeting and Budgeting and Forecasting. (Actually, you can generate one\-off transactions too, by writing a
.SH Automated postings period expression with no report interval.)
.PP .PP
Automated postings are postings added automatically by rule to certain For more details, see: balance: Budget report and Cookbook: Budgeting
transactions (with \f[C]\-\-auto\f[]). 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 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 .IP
.nf .nf
\f[C] \f[C]
@ -1240,10 +1248,8 @@ $\ hledger\ print\ \-\-auto
\f[] \f[]
.fi .fi
.PP .PP
Automated postings would not be distinguishable from equivalent postings Like postings recorded by hand, automated postings participate in
written by hand. transaction balancing, missing amount inference and balance assertions.
In particular, they would affect [amount inference|#postings] and
[balance assertion|#balance\-assertions] checks in the usual way.
.SH EDITOR SUPPORT .SH EDITOR SUPPORT
.PP .PP
Add\-on modes exist for various text editors, to make working with 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: * Menu:
* FILE FORMAT:: * FILE FORMAT::
* Periodic transactions::
* Automated postings::
* EDITOR SUPPORT:: * 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 1 FILE FORMAT
************* *************
@ -83,6 +81,8 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, P
* Comments:: * Comments::
* Tags:: * Tags::
* Directives:: * Directives::
* Periodic transactions::
* Automated postings::
 
File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT 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 org-mode nodes to be ignored, allowing emacs users to fold and navigate
their journals with org-mode or orgstruct-mode.) 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 You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual posting postings). Similarly, you can attach comments to an individual posting
@ -744,6 +740,9 @@ end comment
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; 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 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. 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 1.14 Directives
=============== ===============
* Menu: * Menu:
* Account aliases:: * Comment blocks::
* account directive::
* apply account directive::
* Multi-line comments::
* commodity directive::
* Default commodity::
* Default year::
* Including other files:: * 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 A line containing just 'comment' starts a commented region of the file,
the journal, before generating reports). hledger's account aliases can and a line containing just 'end comment' (or the end of the current
be useful for: file) ends it. See also comments.
* 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: 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. You can pull in the content of additional files by writing an include
This affects all subsequent journal entries in the current file or its directive, like this:
included files. The spaces around the = are optional:
alias OLD = NEW include path/to/file.journal
Or, you can use the '--alias 'OLD=NEW'' option on the command line. If the path does not begin with a slash, it is relative to the
This affects all entries. It's useful for trying out aliases current file. Glob patterns ('*') are not currently supported.
interactively.
OLD and NEW are full account names. hledger will replace any The 'include' directive can only be used in journal files. It can
occurrence of the old account name with the new one. Subaccounts are include journal, timeclock or timedot files, but not CSV files.
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: 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, You can set a default year to be used for subsequent dates which don't
indicated by the forward slashes: 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 Y2010 ; change default year to 2010
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 2009/1/30 ; specifies the year, not affected
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" expenses 1
assets
Also note that REPLACEMENT continues to the end of line (or on 1/31 ; equivalent to 2010/1/31
command line, to end of option argument), so it can contain trailing expenses 1
whitespace. 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 The 'commodity' directive declares commodities which may be used in the
command-line options. Aliases are recursive - each alias sees the journal (though currently we do not enforce this). It may be written on
result of applying previous ones. (This is different from Ledger, where a single line, like this:
aliases are non-recursive by default). Aliases are applied in the
following order:
1. alias directives, most recently seen first (recent directives take ; commodity EXAMPLEAMOUNT
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line ; 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 1.14.5 Default commodity
....................
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
------------------------ ------------------------
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 The 'account' directive predeclares account names. The simplest form is
'account ACCTNAME', eg: 'account ACCTNAME', eg:
@ -947,10 +960,110 @@ account assets:bank:checking 1110
some-tag:12345 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 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 within a section of the journal. Use the 'apply account' and 'end apply
@ -983,157 +1096,52 @@ include personal.journal
supported. 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 Periodic transaction rules (enabled by '--forecast' or '--budget')
containing just 'end comment' ends it. See comments. 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):
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:
~ weekly ~ weekly
assets:bank:checking $400 ; paycheck assets:bank:checking $400 ; paycheck
income:acme inc income:acme inc
With '--forecast', each periodic transaction rule generates recurring Periodic transactions have a dual purpose:
"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).
With 'balance --budget', each periodic transaction declares recurring * With '--forecast', each periodic transaction rule generates future
budget goals for the specified accounts. Eg the example above declares transactions, recurring at the specified interval, which can be
the goal of receiving $400 from 'income:acme inc' (and also, depositing seen in reports. Forecast transactions begin the day after the
$400 into 'assets:bank:checking') every week. 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 * With '--budget' (supported by the balance command), each periodic
Forecasting. 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 Automated postings (enabled by '--auto') are postings added
transactions (with '--auto'). An automated posting rule looks like a automatically by rule to certain transactions. An automated posting
transaction where the first line is an equal sign ('=') followed by a rule looks like a transaction where the first line is an equal sign
query: ('=') followed by a query (mnemonic: '=' tests for matching
transactions, and also looks like posting lines):
= expenses:gifts = expenses:gifts
budget:gifts *-1 budget:gifts *-1
@ -1161,15 +1169,13 @@ $ hledger print --auto
(budget:gifts) $-20 (budget:gifts) $-20
assets assets
Automated postings would not be distinguishable from equivalent Like postings recorded by hand, automated postings participate in
postings written by hand. In particular, they would affect [amount transaction balancing, missing amount inference and balance assertions.
inference|#postings] and [balance assertion|#balance-assertions] checks
in the usual way.
 
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 Add-on modes exist for various text editors, to make working with
@ -1196,89 +1202,89 @@ Code
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT2425 Node: FILE FORMAT2376
Ref: #file-format2556 Ref: #file-format2500
Node: Transactions2779 Node: Transactions2772
Ref: #transactions2900 Ref: #transactions2893
Node: Postings3584 Node: Postings3577
Ref: #postings3711 Ref: #postings3704
Node: Dates4706 Node: Dates4699
Ref: #dates4821 Ref: #dates4814
Node: Simple dates4886 Node: Simple dates4879
Ref: #simple-dates5012 Ref: #simple-dates5005
Node: Secondary dates5378 Node: Secondary dates5371
Ref: #secondary-dates5532 Ref: #secondary-dates5525
Node: Posting dates7095 Node: Posting dates7088
Ref: #posting-dates7224 Ref: #posting-dates7217
Node: Status8598 Node: Status8591
Ref: #status8718 Ref: #status8711
Node: Description10426 Node: Description10419
Ref: #description10564 Ref: #description10557
Node: Payee and note10883 Node: Payee and note10876
Ref: #payee-and-note10997 Ref: #payee-and-note10990
Node: Account names11239 Node: Account names11232
Ref: #account-names11382 Ref: #account-names11375
Node: Amounts11869 Node: Amounts11862
Ref: #amounts12005 Ref: #amounts11998
Node: Virtual Postings15020 Node: Virtual Postings15013
Ref: #virtual-postings15179 Ref: #virtual-postings15172
Node: Balance Assertions16399 Node: Balance Assertions16392
Ref: #balance-assertions16574 Ref: #balance-assertions16567
Node: Assertions and ordering17470 Node: Assertions and ordering17463
Ref: #assertions-and-ordering17656 Ref: #assertions-and-ordering17649
Node: Assertions and included files18356 Node: Assertions and included files18349
Ref: #assertions-and-included-files18597 Ref: #assertions-and-included-files18590
Node: Assertions and multiple -f options18930 Node: Assertions and multiple -f options18923
Ref: #assertions-and-multiple--f-options19184 Ref: #assertions-and-multiple--f-options19177
Node: Assertions and commodities19316 Node: Assertions and commodities19309
Ref: #assertions-and-commodities19551 Ref: #assertions-and-commodities19544
Node: Assertions and subaccounts20247 Node: Assertions and subaccounts20240
Ref: #assertions-and-subaccounts20479 Ref: #assertions-and-subaccounts20472
Node: Assertions and virtual postings21000 Node: Assertions and virtual postings20993
Ref: #assertions-and-virtual-postings21207 Ref: #assertions-and-virtual-postings21200
Node: Balance Assignments21349 Node: Balance Assignments21342
Ref: #balance-assignments21518 Ref: #balance-assignments21511
Node: Prices22638 Node: Prices22631
Ref: #prices22771 Ref: #prices22764
Node: Transaction prices22822 Node: Transaction prices22815
Ref: #transaction-prices22967 Ref: #transaction-prices22960
Node: Market prices25123 Node: Market prices25116
Ref: #market-prices25258 Ref: #market-prices25251
Node: Comments26218 Node: Comments26211
Ref: #comments26340 Ref: #comments26333
Node: Tags27582 Node: Tags27503
Ref: #tags27700 Ref: #tags27621
Node: Directives29102 Node: Directives29023
Ref: #directives29215 Ref: #directives29166
Node: Account aliases29408 Node: Comment blocks29359
Ref: #account-aliases29552 Ref: #comment-blocks29504
Node: Basic aliases30156 Node: Including other files29680
Ref: #basic-aliases30299 Ref: #including-other-files29860
Node: Regex aliases30989 Node: Default year30249
Ref: #regex-aliases31157 Ref: #default-year30418
Node: Multiple aliases31875 Node: Declaring commodities30841
Ref: #multiple-aliases32047 Ref: #declaring-commodities31024
Node: end aliases32545 Node: Default commodity32251
Ref: #end-aliases32685 Ref: #default-commodity32432
Node: account directive32786 Node: Declaring accounts33064
Ref: #account-directive32966 Ref: #declaring-accounts33244
Node: apply account directive34313 Node: Rewriting accounts34591
Ref: #apply-account-directive34509 Ref: #rewriting-accounts34776
Node: Multi-line comments35168 Node: Basic aliases35380
Ref: #multi-line-comments35358 Ref: #basic-aliases35526
Node: commodity directive35486 Node: Regex aliases36216
Ref: #commodity-directive35670 Ref: #regex-aliases36387
Node: Default commodity36897 Node: Multiple aliases37105
Ref: #default-commodity37070 Ref: #multiple-aliases37280
Node: Default year37702 Node: end aliases37778
Ref: #default-year37867 Ref: #end-aliases37925
Node: Including other files38290 Node: Default parent account38026
Ref: #including-other-files38447 Ref: #default-parent-account38192
Node: Periodic transactions38844 Node: Periodic transactions38851
Ref: #periodic-transactions39010 Ref: #periodic-transactions39030
Node: Automated postings39999 Node: Automated postings40329
Ref: #automated-postings40162 Ref: #automated-postings40483
Node: EDITOR SUPPORT41290 Node: EDITOR SUPPORT41616
Ref: #editor-support41415 Ref: #editor-support41734
 
End Tag Table End Tag Table

316
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 nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.) 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 You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post- description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by ings). Similarly, you can attach comments to an individual posting by
@ -584,6 +580,9 @@ FILE FORMAT
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; a file comment (because not indented)
You can also comment larger regions of a file using comment and
end comment directives.
Tags Tags
Tags are a way to add extra labels or labelled data to postings and Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on. transactions, which you can then search or pivot on.
@ -625,7 +624,133 @@ FILE FORMAT
are simple strings. are simple strings.
Directives 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 You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can the journal, before generating reports). hledger's account aliases can
be useful for: be useful for:
@ -640,7 +765,7 @@ FILE FORMAT
o customising reports o customising reports
See also Cookbook: rewrite account names. See also Cookbook: 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.
@ -697,44 +822,7 @@ FILE FORMAT
end aliases end aliases
account directive Default parent account
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
You can specify a parent account which will be prepended to all You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and accounts within a section of the journal. Use the apply account and
end apply account directives like so: 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- Prior to hledger 1.0, legacy account and end spellings were also sup-
ported. 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
Periodic transactions are a kind of rule with a dual purpose: they can Periodic transaction rules (enabled by --forecast or --budget) describe
specify recurring future transactions (with --forecast), or budget recurring transactions. They look like a transaction where the first
goals (with --budget). They look a bit like a transaction, except the line is a tilde (~) followed by a period expression (mnemonic: ~ is
first line is a tilde (~) followed by a period expression: like a recurring sine wave):
~ weekly ~ weekly
assets:bank:checking $400 ; paycheck assets:bank:checking $400 ; paycheck
income:acme inc income:acme inc
With --forecast, each periodic transaction rule generates recurring Periodic transactions have a dual purpose:
"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).
With balance --budget, each periodic transaction declares recurring o With --forecast, each periodic transaction rule generates future
budget goals for the specified accounts. Eg the example above declares transactions, recurring at the specified interval, which can be seen
the goal of receiving $400 from income:acme inc (and also, depositing in reports. Forecast transactions begin the day after the latest
$400 into assets:bank:checking) every week. 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- o With --budget (supported by the balance command), each periodic
ing. 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.
Automated postings Automated postings
Automated postings are postings added automatically by rule to certain Automated postings (enabled by --auto) are postings added automatically
transactions (with --auto). An automated posting rule looks like a by rule to certain transactions. An automated posting rule looks like
transaction where the first line is an equal sign (=) followed by a a transaction where the first line is an equal sign (=) followed by a
query: query (mnemonic: = tests for matching transactions, and also looks like
posting lines):
= expenses:gifts = expenses:gifts
budget:gifts *-1 budget:gifts *-1
@ -909,10 +917,8 @@ Automated postings
(budget:gifts) $-20 (budget:gifts) $-20
assets assets
Automated postings would not be distinguishable from equivalent post- Like postings recorded by hand, automated postings participate in
ings written by hand. In particular, they would affect [amount infer- transaction balancing, missing amount inference and balance assertions.
ence|#postings] and [balance assertion|#balance-assertions] checks in
the usual way.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- 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 \[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more and no balance of their own, are elided into the following line for more
compact output. 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 .PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts. 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 "Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more 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 Account balances are "inclusive" - they include the balances of any
subaccounts. subaccounts.
@ -2485,84 +2486,84 @@ Node: balance35737
Ref: #balance35848 Ref: #balance35848
Node: Classic balance report38931 Node: Classic balance report38931
Ref: #classic-balance-report39104 Ref: #classic-balance-report39104
Node: Customising the classic balance report40433 Node: Customising the classic balance report40473
Ref: #customising-the-classic-balance-report40661 Ref: #customising-the-classic-balance-report40701
Node: Colour support42735 Node: Colour support42775
Ref: #colour-support42902 Ref: #colour-support42942
Node: Flat mode43075 Node: Flat mode43115
Ref: #flat-mode43223 Ref: #flat-mode43263
Node: Depth limited balance reports43636 Node: Depth limited balance reports43676
Ref: #depth-limited-balance-reports43836 Ref: #depth-limited-balance-reports43876
Node: Multicolumn balance report44292 Node: Multicolumn balance report44332
Ref: #multicolumn-balance-report44490 Ref: #multicolumn-balance-report44530
Node: Budget report49670 Node: Budget report49710
Ref: #budget-report49813 Ref: #budget-report49853
Ref: #output-format-152847 Ref: #output-format-152887
Node: balancesheet52925 Node: balancesheet52965
Ref: #balancesheet53061 Ref: #balancesheet53101
Node: balancesheetequity55372 Node: balancesheetequity55412
Ref: #balancesheetequity55521 Ref: #balancesheetequity55561
Node: cashflow56058 Node: cashflow56098
Ref: #cashflow56186 Ref: #cashflow56226
Node: check-dates58309 Node: check-dates58349
Ref: #check-dates58436 Ref: #check-dates58476
Node: check-dupes58553 Node: check-dupes58593
Ref: #check-dupes58677 Ref: #check-dupes58717
Node: close58814 Node: close58854
Ref: #close58921 Ref: #close58961
Node: help59251 Node: help59291
Ref: #help59351 Ref: #help59391
Node: import60425 Node: import60465
Ref: #import60539 Ref: #import60579
Node: incomestatement61269 Node: incomestatement61309
Ref: #incomestatement61403 Ref: #incomestatement61443
Node: prices63807 Node: prices63847
Ref: #prices63922 Ref: #prices63962
Node: print63965 Node: print64005
Ref: #print64075 Ref: #print64115
Node: print-unique68969 Node: print-unique69009
Ref: #print-unique69095 Ref: #print-unique69135
Node: register69163 Node: register69203
Ref: #register69290 Ref: #register69330
Node: Custom register output73791 Node: Custom register output73831
Ref: #custom-register-output73920 Ref: #custom-register-output73960
Node: register-match75150 Node: register-match75190
Ref: #register-match75284 Ref: #register-match75324
Node: rewrite75467 Node: rewrite75507
Ref: #rewrite75584 Ref: #rewrite75624
Node: stats75653 Node: stats75693
Ref: #stats75756 Ref: #stats75796
Node: tags76626 Node: tags76666
Ref: #tags76724 Ref: #tags76764
Node: test76960 Node: test77000
Ref: #test77044 Ref: #test77084
Node: ADD-ON COMMANDS77412 Node: ADD-ON COMMANDS77452
Ref: #add-on-commands77522 Ref: #add-on-commands77562
Node: Official add-ons78809 Node: Official add-ons78849
Ref: #official-add-ons78949 Ref: #official-add-ons78989
Node: api79036 Node: api79076
Ref: #api79125 Ref: #api79165
Node: ui79177 Node: ui79217
Ref: #ui79276 Ref: #ui79316
Node: web79334 Node: web79374
Ref: #web79423 Ref: #web79463
Node: Third party add-ons79469 Node: Third party add-ons79509
Ref: #third-party-add-ons79644 Ref: #third-party-add-ons79684
Node: diff79779 Node: diff79819
Ref: #diff79876 Ref: #diff79916
Node: iadd79975 Node: iadd80015
Ref: #iadd80089 Ref: #iadd80129
Node: interest80172 Node: interest80212
Ref: #interest80293 Ref: #interest80333
Node: irr80388 Node: irr80428
Ref: #irr80486 Ref: #irr80526
Node: Experimental add-ons80564 Node: Experimental add-ons80604
Ref: #experimental-add-ons80716 Ref: #experimental-add-ons80756
Node: autosync80996 Node: autosync81036
Ref: #autosync81107 Ref: #autosync81147
Node: chart81346 Node: chart81386
Ref: #chart81465 Ref: #chart81505
Node: check81536 Node: check81576
Ref: #check81638 Ref: #check81678
 
End Tag Table End Tag Table

3
hledger/hledger.txt
View File

@ -1099,7 +1099,8 @@ COMMANDS
"Boring" accounts, which contain a single interesting subaccount and no "Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com- 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 Account balances are "inclusive" - they include the balances of any
subaccounts. subaccounts.