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

;update manuals

Browse Source
This commit is contained in:
Simon Michael 2021-05-18 10:35:43 -10:00
parent 701768765a
commit 0b15d5771a
3 changed files with 1471 additions and 1248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
hledger/hledger.1
View File

@ -656,9 +656,8 @@ Are all accounts posted to, declared with an \f[C]account\f[R] directive
Are all commodities declared with a \f[C]commodity\f[R] directive ? Are all commodities declared with a \f[C]commodity\f[R] directive ?
(Commodity error checking) (Commodity error checking)
.PP .PP
See also: https://hledger.org/checking-for-errors.html You can also use the check command to run these and some additional
.PP checks.
\f[I]experimental.\f[R]
.SH TIME PERIODS .SH TIME PERIODS
.SS Smart dates .SS Smart dates
.PP .PP
@ -830,12 +829,35 @@ T}
.SS Report intervals .SS Report intervals
.PP .PP
A report interval can be specified so that commands like register, A report interval can be specified so that commands like register,
balance and activity will divide their reports into multiple subperiods. balance and activity become multi-period, showing each subperiod as a
The basic intervals can be selected with one of \f[C]-D/--daily\f[R], separate row or column.
\f[C]-W/--weekly\f[R], \f[C]-M/--monthly\f[R], \f[C]-Q/--quarterly\f[R], .PP
or \f[C]-Y/--yearly\f[R]. The following \[dq]standard\[dq] report intervals can be enabled by
More complex intervals may be specified with a period expression. using their corresponding flag:
Report intervals can not be specified with a query. .PP
\f[C]-D/--daily\f[R], \f[C]-W/--weekly\f[R], \f[C]-M/--monthly\f[R],
\f[C]-Q/--quarterly\f[R], \f[C]-Y/--yearly\f[R].
.PP
These standard intervals always start on natural interval boundaries: eg
\f[C]--weekly\f[R] starts on mondays, \f[C]--monthly\f[R] starts on the
first of the month, \f[C]--yearly\f[R] always starts on January 1st,
etc.
.PP
Certain more complex intervals, and more flexible boundary dates, can be
specified by \f[C]-p/--period\f[R].
These are described in period expressions, below.
.PP
Report intervals can only be specified by the flags above, and not by
query arguments, currently.
.PP
Report intervals have another effect: multi-period reports are always
expanded to fill a whole number of subperiods.
So if you use a report interval (other than \f[C]--daily\f[R]), and you
have specified a start or end date, you may notice those dates being
overridden (ie, the report starts earlier than your requested start
date, or ends later than your requested end date).
This is done to ensure \[dq]full\[dq] first and last subperiods, so that
all subperiods\[aq] numbers are comparable.
.SS Period expressions .SS Period expressions
.PP .PP
The \f[C]-p/--period\f[R] option accepts period expressions, a shorthand The \f[C]-p/--period\f[R] option accepts period expressions, a shorthand
@ -2031,6 +2053,12 @@ $ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default) $ hledger print -o - # write to stdout (the default)
\f[R] \f[R]
.fi .fi
.PP
hledger can optionally produce debug output (if enabled with
\f[C]--debug=N\f[R]); this goes to stderr, and is not affected by
\f[C]-o/--output-file\f[R].
If you need to capture it, use shell redirects, eg:
\f[C]hledger bal --debug=3 >file 2>&1\f[R].
.SS Output format .SS Output format
.PP .PP
Some commands (print, register, the balance commands) offer a choice of Some commands (print, register, the balance commands) offer a choice of
@ -3612,7 +3640,8 @@ These checks can be run only by giving their names as arguments to
They are more specialised and not desirable for everyone, therefore They are more specialised and not desirable for everyone, therefore
optional: optional:
.IP \[bu] 2 .IP \[bu] 2
\f[B]ordereddates\f[R] - transactions are ordered by date in each file \f[B]ordereddates\f[R] - transactions are ordered by date within each
file
.IP \[bu] 2 .IP \[bu] 2
\f[B]payees\f[R] - all payees used by transactions have been declared \f[B]payees\f[R] - all payees used by transactions have been declared
.IP \[bu] 2 .IP \[bu] 2
@ -5440,23 +5469,15 @@ Amounts have a number (the \[dq]quantity\[dq]):
\f[R] \f[R]
.fi .fi
.PP .PP
\&..and usually a currency or commodity name (the \[dq]commodity\[dq]). \&..and usually a currency symbol or commodity name (more on this
This is a symbol, word, or phrase, to the left or right of the quantity, below), to the left or right of the quantity, with or without a
with or without a separating space: separating space:
.IP .IP
.nf .nf
\f[C] \f[C]
$1 $1
4000 AAPL 4000 AAPL
\f[R] 3 \[dq]green apples\[dq]
.fi
.PP
If the commodity name contains spaces, numbers, or punctuation, it must
be enclosed in double quotes:
.IP
.nf
\f[C]
3 \[dq]no. 42 green apples\[dq]
\f[R] \f[R]
.fi .fi
.PP .PP
@ -5526,14 +5547,49 @@ Are these digit group marks or decimal marks ?
.PP .PP
If you don\[aq]t tell it otherwise, hledger will assume both of the If you don\[aq]t tell it otherwise, hledger will assume both of the
above are decimal marks, parsing both numbers as 1. above are decimal marks, parsing both numbers as 1.
To prevent confusion and undetected typos, especially if your data To prevent confusion and undetected typos, we recommend adding
contains digit group marks, we recommend you explicitly declare the \f[C]commodity\f[R] directives at the top of your journal file to
decimal mark (and optionally a digit group mark), for each commodity, explicitly declare the decimal mark (and optionally a digit group mark)
using \f[C]commodity\f[R] directives (described below): for each commodity.
Read on for more about this.
.SS Commodity
.PP
Amounts in hledger have both a \[dq]quantity\[dq], which is a signed
decimal number, and a \[dq]commodity\[dq], which is a currency symbol,
stock ticker, or any word or phrase describing something you are
tracking.
.PP
If the commodity name contains non-letters (spaces, numbers, or
punctuation), you must always write it inside double quotes
(\f[C]\[dq]green apples\[dq]\f[R], \f[C]\[dq]ABC123\[dq]\f[R]).
.PP
If you write just a bare number, that too will have a commodity, with
name \f[C]\[dq]\[dq]\f[R]; we call that the \[dq]no-symbol
commodity\[dq].
.PP
Actually, hledger combines these single-commodity amounts into more
powerful multi-commodity amounts, which are what it works with most of
the time.
A multi-commodity amount could be, eg:
\f[C]1 USD, 2 EUR, 3.456 TSLA\f[R].
In practice, you will only see multi-commodity amounts in hledger\[aq]s
output; you can\[aq]t write them directly in the journal file.
.PP
(If you are writing scripts or working with hledger\[aq]s internals,
these are the \f[C]Amount\f[R] and \f[C]MixedAmount\f[R] types.)
.SS Commodity directives
.PP
You can add \f[C]commodity\f[R] directives to the journal, preferably at
the top, to declare your commodities and help with number parsing (see
above) and display (see below).
These are optional, but recommended.
They are described in more detail in JOURNAL FORMAT -> Declaring
commodities.
Here\[aq]s a quick example:
.IP .IP
.nf .nf
\f[C] \f[C]
# number formats for $, EUR, INR and the no-symbol commodity: # number format and display style for $, EUR, INR and the no-symbol commodity:
commodity $1,000.00 commodity $1,000.00
commodity EUR 1.000,00 commodity EUR 1.000,00
commodity INR 9,99,99,999.00 commodity INR 9,99,99,999.00
@ -5541,19 +5597,15 @@ commodity 1 000 000.9455
\f[R] \f[R]
.fi .fi
.PP .PP
Note, \f[C]commodity\f[R] directives declare both the number format for
parsing input, and the display style for showing output.
For the former, they are position-sensitive, affecting only following
amounts, so commodity directives should be at the top of your journal
file.
This is discussed more on #793.
.PP
.SS Commodity display style .SS Commodity display style
.PP .PP
For the amounts in each commodity, hledger chooses a consistent display For the amounts in each commodity, hledger chooses a consistent display
style to use in most reports. style to use in most reports.
(Except for price amounts, which are always displayed as written). (Exceptions: price amounts, and all amounts displayed by the
The display style is inferred as follows. \f[C]print\f[R] command, are displayed with all of their decimal digits
visible.)
.PP
A commodity\[aq]s display style is inferred as follows.
.PP .PP
First, if a default commodity is declared with \f[C]D\f[R], this First, if a default commodity is declared with \f[C]D\f[R], this
commodity and its style is applied to any no-symbol amounts in the commodity and its style is applied to any no-symbol amounts in the
@ -6206,47 +6258,54 @@ payee Whole Foods
.fi .fi
.SS Declaring commodities .SS Declaring commodities
.PP .PP
The \f[C]commodity\f[R] directive has several functions: You can use \f[C]commodity\f[R] directives to declare your commodities.
In fact the \f[C]commodity\f[R] directive performs several functions at
once:
.IP "1." 3 .IP "1." 3
It declares commodities which may be used in the journal. It declares commodities which may be used in the journal.
This is currently not enforced, but can serve as documentation. This can optionally be enforced, providing useful error checking.
(Cf Commodity error checking)
.IP "2." 3 .IP "2." 3
It declares what decimal mark character (period or comma) to expect when It declares which decimal mark character (period or comma), to expect
parsing input - useful to disambiguate international number formats in when parsing input - useful to disambiguate international number formats
your data. in your data.
(Without this, hledger will parse both \f[C]1,000\f[R] and Without this, hledger will parse both \f[C]1,000\f[R] and
\f[C]1.000\f[R] as 1). \f[C]1.000\f[R] as 1.
(Cf Amounts)
.IP "3." 3 .IP "3." 3
It declares a commodity\[aq]s display style in output - decimal and It declares how to render the commodity\[aq]s amounts when displaying
digit group marks, number of decimal places, symbol placement etc. output - the decimal mark, any digit group marks, the number of decimal
places, symbol placement and so on.
(Cf Commodity display style)
.PP .PP
You are likely to run into one of the problems solved by commodity You will run into one of the problems solved by commodity directives
directives, sooner or later, so it\[aq]s a good idea to just always use sooner or later, so we recommend using them, for robust and predictable
them to declare your commodities. parsing and display.
.PP .PP
A commodity directive is just the word \f[C]commodity\f[R] followed by Generally you should put them at the top of your journal file (since for
an amount. function 2, they affect only following amounts, cf #793).
It may be written on a single line, like this: .PP
A commodity directive is just the word \f[C]commodity\f[R] followed by a
sample amount, like this:
.IP .IP
.nf .nf
\f[C] \f[C]
; commodity EXAMPLEAMOUNT ;commodity SAMPLEAMOUNT
; display AAAA amounts with the symbol on the right, space-separated, commodity $1000.00
; using period as decimal point, with four decimal places, and commodity 1,000.0000 AAAA ; optional same-line comment
; separating thousands with comma.
commodity 1,000.0000 AAAA
\f[R] \f[R]
.fi .fi
.PP .PP
or on multiple lines, using the \[dq]format\[dq] subdirective. It may also be written on multiple lines, and use the \f[C]format\f[R]
(In this case the commodity symbol appears twice and should be the same subdirective, as in Ledger.
in both places.): Note in this case the commodity symbol appears twice; it must be the
same in both places:
.IP .IP
.nf .nf
\f[C] \f[C]
; commodity SYMBOL ;commodity SYMBOL
; format EXAMPLEAMOUNT ; format SAMPLEAMOUNT
; display indian rupees with currency name on the left, ; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated, ; thousands, lakhs and crores comma-separated,
@ -6256,10 +6315,25 @@ commodity INR
\f[R] \f[R]
.fi .fi
.PP .PP
The quantity of the amount does not matter; only the format is Remember that if the commodity symbol contains spaces, numbers, or
punctuation, it must be enclosed in double quotes (cf Commodity).
.PP
The amount\[aq]s quantity does not matter; only the format is
significant. significant.
The number must include a decimal mark: either a period or a comma, It must include a decimal mark - either a period or a comma - followed
followed by 0 or more decimal digits. by 0 or more decimal digits.
.PP
A few more examples:
.IP
.nf
\f[C]
# number formats for $, EUR, INR and the no-symbol commodity:
commodity $1,000.00
commodity EUR 1.000,00
commodity INR 9,99,99,999.0
commodity 1 000 000.
\f[R]
.fi
.PP .PP
Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with
zero decimal digits is \[dq]0\[dq]. zero decimal digits is \[dq]0\[dq].
@ -6273,19 +6347,20 @@ This works similarly to account error checking, see the notes there for
more details. more details.
.SS Default commodity .SS Default commodity
.PP .PP
The \f[C]D\f[R] directive sets a default commodity, to be used for The \f[C]D\f[R] directive sets a default commodity, to be used for any
amounts without a commodity symbol (ie, plain numbers). subsequent commodityless amounts (ie, plain numbers) seen while parsing
This commodity will be applied to all subsequent commodity-less amounts, the journal.
or until the next \f[C]D\f[R] directive. This effect lasts until the next \f[C]D\f[R] directive, or the end of
(Note, this is different from Ledger\[aq]s \f[C]D\f[R].) the journal.
.PP .PP
For compatibility/historical reasons, \f[C]D\f[R] also acts like a For compatibility/historical reasons, \f[C]D\f[R] also acts like a
\f[C]commodity\f[R] directive, setting the commodity\[aq]s display style \f[C]commodity\f[R] directive (setting the commodity\[aq]s decimal mark
(for output) and decimal mark (for parsing input). for parsing and display style for output).
As with \f[C]commodity\f[R], the amount must always be written with a .PP
decimal mark (period or comma). As with \f[C]commodity\f[R], the amount must include a decimal mark
If both directives are used, \f[C]commodity\f[R]\[aq]s style takes (either period or comma).
precedence. If both \f[C]commodity\f[R] and \f[C]D\f[R] directives are used for the
same commodity, the \f[C]commodity\f[R] style takes precedence.
.PP .PP
The syntax is \f[C]D AMOUNT\f[R]. The syntax is \f[C]D AMOUNT\f[R].
Eg: Eg:
@ -6494,7 +6569,7 @@ using the following rules:
tab(@); tab(@);
l l. l l.
T{ T{
If name matches regular expression: If name matches this regular expression:
T}@T{ T}@T{
account type is: account type is:
T} T}
@ -6528,10 +6603,10 @@ T}
.PP .PP
.TS .TS
tab(@); tab(@);
lw(56.9n) lw(13.1n). lw(57.6n) lw(12.4n).
T{ T{
If account type is \f[C]Asset\f[R] and name does not contain regular If account type is \f[C]Asset\f[R] and name does not contain this
expression: regular expression:
T}@T{ T}@T{
account type is: account type is:
T} T}
@ -7789,13 +7864,13 @@ REGEX
\f[R] \f[R]
.fi .fi
.PP .PP
REGEX is a case-insensitive regular expression which tries to match REGEX is a case-insensitive regular expression that tries to match
anywhere within the CSV record. anywhere within the CSV record.
It is a POSIX ERE (extended regular expression) that also supports GNU It is a POSIX ERE (extended regular expression) that also supports GNU
word boundaries (\f[C]\[rs]b\f[R], \f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R], word boundaries (\f[C]\[rs]b\f[R], \f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R],
\f[C]\[rs]>\f[R]), and nothing else. \f[C]\[rs]>\f[R]), and nothing else.
If you have trouble, be sure to check our If you have trouble, be sure to check our doc:
https://hledger.org/hledger.html#regular-expressions doc. https://hledger.org/hledger.html#regular-expressions
.PP .PP
Important note: the record that is matched is not the original record, Important note: the record that is matched is not the original record,
but a synthetic one, with any enclosing double quotes (but not enclosing but a synthetic one, with any enclosing double quotes (but not enclosing

1053
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

229
hledger/hledger.txt
View File

@ -497,9 +497,8 @@ DATA FILES
o Are all commodities declared with a commodity directive ? (Commodity o Are all commodities declared with a commodity directive ? (Commodity
error checking) error checking)
See also: https://hledger.org/checking-for-errors.html You can also use the check command to run these and some additional
checks.
experimental.
TIME PERIODS TIME PERIODS
Smart dates Smart dates
@ -576,11 +575,32 @@ TIME PERIODS
Report intervals Report intervals
A report interval can be specified so that commands like register, bal- A report interval can be specified so that commands like register, bal-
ance and activity will divide their reports into multiple subperiods. ance and activity become multi-period, showing each subperiod as a sep-
The basic intervals can be selected with one of -D/--daily, arate row or column.
-W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com-
plex intervals may be specified with a period expression. Report The following "standard" report intervals can be enabled by using their
intervals can not be specified with a query. corresponding flag:
-D/--daily, -W/--weekly, -M/--monthly, -Q/--quarterly, -Y/--yearly.
These standard intervals always start on natural interval boundaries:
eg --weekly starts on mondays, --monthly starts on the first of the
month, --yearly always starts on January 1st, etc.
Certain more complex intervals, and more flexible boundary dates, can
be specified by -p/--period. These are described in period expres-
sions, below.
Report intervals can only be specified by the flags above, and not by
query arguments, currently.
Report intervals have another effect: multi-period reports are always
expanded to fill a whole number of subperiods. So if you use a report
interval (other than --daily), and you have specified a start or end
date, you may notice those dates being overridden (ie, the report
starts earlier than your requested start date, or ends later than your
requested end date). This is done to ensure "full" first and last sub-
periods, so that all subperiods' numbers are comparable.
Period expressions Period expressions
The -p/--period option accepts period expressions, a shorthand way of The -p/--period option accepts period expressions, a shorthand way of
@ -606,7 +626,6 @@ TIME PERIODS
-p "1/1 4/1" -p "1/1 4/1"
-p "january-apr" -p "january-apr"
-p "this year to 4/1" -p "this year to 4/1"
@ -1162,8 +1181,6 @@ VALUATION
posting cost value at value at posting value at value at posting cost value at value at posting value at value at
amounts report end date report or DATE/today amounts report end date report or DATE/today
or today journal end or today journal end
summary post- summarised value at sum of postings value at value at summary post- summarised value at sum of postings value at value at
ing amounts cost period ends in interval, val- period ends DATE/today ing amounts cost period ends in interval, val- period ends DATE/today
with report ued at interval with report ued at interval
@ -1201,6 +1218,12 @@ VALUATION
is, bs postings in period at respec- each period, sums of post- is, bs postings in period at respec- each period, sums of post-
--change, cf period tive posting valued at ings --change, cf period tive posting valued at ings
--change) dates period ends --change) dates period ends
end balances sums of same as sums of values of period end value at end balances sums of same as sums of values of period end value at
(bal -H, is costs of --value=end postings from balances, DATE/today of (bal -H, is costs of --value=end postings from balances, DATE/today of
--H, bs, cf) postings before period valued at sums of post- --H, bs, cf) postings before period valued at sums of post-
@ -1322,6 +1345,11 @@ OUTPUT
$ hledger print -o foo.txt $ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default) $ hledger print -o - # write to stdout (the default)
hledger can optionally produce debug output (if enabled with
--debug=N); this goes to stderr, and is not affected by -o/--output-
file. If you need to capture it, use shell redirects, eg: hledger bal
--debug=3 >file 2>&1.
Output format Output format
Some commands (print, register, the balance commands) offer a choice of Some commands (print, register, the balance commands) offer a choice of
output format. In addition to the usual plain text format (txt), there output format. In addition to the usual plain text format (txt), there
@ -2588,7 +2616,7 @@ COMMANDS
check. They are more specialised and not desirable for everyone, check. They are more specialised and not desirable for everyone,
therefore optional: therefore optional:
o ordereddates - transactions are ordered by date in each file o ordereddates - transactions are ordered by date within each file
o payees - all payees used by transactions have been declared o payees - all payees used by transactions have been declared
@ -3964,17 +3992,13 @@ JOURNAL FORMAT
1 1
..and usually a currency or commodity name (the "commodity"). This is ..and usually a currency symbol or commodity name (more on this below),
a symbol, word, or phrase, to the left or right of the quantity, with to the left or right of the quantity, with or without a separating
or without a separating space: space:
$1 $1
4000 AAPL 4000 AAPL
3 "green apples"
If the commodity name contains spaces, numbers, or punctuation, it must
be enclosed in double quotes:
3 "no. 42 green apples"
Amounts can be preceded by a minus sign (or a plus sign, though plus is Amounts can be preceded by a minus sign (or a plus sign, though plus is
the default), The sign can be written before or after a left-side com- the default), The sign can be written before or after a left-side com-
@ -4017,29 +4041,53 @@ JOURNAL FORMAT
If you don't tell it otherwise, hledger will assume both of the above If you don't tell it otherwise, hledger will assume both of the above
are decimal marks, parsing both numbers as 1. To prevent confusion and are decimal marks, parsing both numbers as 1. To prevent confusion and
undetected typos, especially if your data contains digit group marks, undetected typos, we recommend adding commodity directives at the top
we recommend you explicitly declare the decimal mark (and optionally a of your journal file to explicitly declare the decimal mark (and
digit group mark), for each commodity, using commodity directives optionally a digit group mark) for each commodity. Read on for more
(described below): about this.
# number formats for $, EUR, INR and the no-symbol commodity: Commodity
Amounts in hledger have both a "quantity", which is a signed decimal
number, and a "commodity", which is a currency symbol, stock ticker, or
any word or phrase describing something you are tracking.
If the commodity name contains non-letters (spaces, numbers, or punctu-
ation), you must always write it inside double quotes ("green apples",
"ABC123").
If you write just a bare number, that too will have a commodity, with
name ""; we call that the "no-symbol commodity".
Actually, hledger combines these single-commodity amounts into more
powerful multi-commodity amounts, which are what it works with most of
the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456
TSLA. In practice, you will only see multi-commodity amounts in
hledger's output; you can't write them directly in the journal file.
(If you are writing scripts or working with hledger's internals, these
are the Amount and MixedAmount types.)
Commodity directives
You can add commodity directives to the journal, preferably at the top,
to declare your commodities and help with number parsing (see above)
and display (see below). These are optional, but recommended. They
are described in more detail in JOURNAL FORMAT -> Declaring commodi-
ties. Here's a quick example:
# number format and display style for $, EUR, INR and the no-symbol commodity:
commodity $1,000.00 commodity $1,000.00
commodity EUR 1.000,00 commodity EUR 1.000,00
commodity INR 9,99,99,999.00 commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
Note, commodity directives declare both the number format for parsing
input, and the display style for showing output. For the former, they
are position-sensitive, affecting only following amounts, so commodity
directives should be at the top of your journal file. This is dis-
cussed more on #793.
Commodity display style Commodity display style
For the amounts in each commodity, hledger chooses a consistent display For the amounts in each commodity, hledger chooses a consistent display
style to use in most reports. (Except for price amounts, which are style to use in most reports. (Exceptions: price amounts, and all
always displayed as written). The display style is inferred as fol- amounts displayed by the print command, are displayed with all of their
lows. decimal digits visible.)
A commodity's display style is inferred as follows.
First, if a default commodity is declared with D, this commodity and First, if a default commodity is declared with D, this commodity and
its style is applied to any no-symbol amounts in the journal. its style is applied to any no-symbol amounts in the journal.
@ -4342,9 +4390,6 @@ JOURNAL FORMAT
tive directive rec- 2018/06) tive directive rec- 2018/06)
tives tives
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
account any document account names, all entries in all account any document account names, all entries in all
text declare account types & dis- files, before or text declare account types & dis- files, before or
play order after play order after
@ -4360,6 +4405,11 @@ JOURNAL FORMAT
ment until end of cur- ment until end of cur-
rent file or end rent file or end
directive directive
commod- format declare a commodity and its number notation: commod- format declare a commodity and its number notation:
ity number notation & display following entries ity number notation & display following entries
style in that commodity style in that commodity
@ -4494,39 +4544,44 @@ JOURNAL FORMAT
payee Whole Foods payee Whole Foods
Declaring commodities Declaring commodities
The commodity directive has several functions: You can use commodity directives to declare your commodities. In fact
the commodity directive performs several functions at once:
1. It declares commodities which may be used in the journal. This is 1. It declares commodities which may be used in the journal. This can
currently not enforced, but can serve as documentation. optionally be enforced, providing useful error checking. (Cf Com-
modity error checking)
2. It declares what decimal mark character (period or comma) to expect 2. It declares which decimal mark character (period or comma), to
when parsing input - useful to disambiguate international number expect when parsing input - useful to disambiguate international
formats in your data. (Without this, hledger will parse both 1,000 number formats in your data. Without this, hledger will parse both
and 1.000 as 1). 1,000 and 1.000 as 1. (Cf Amounts)
3. It declares a commodity's display style in output - decimal and 3. It declares how to render the commodity's amounts when displaying
digit group marks, number of decimal places, symbol placement etc. output - the decimal mark, any digit group marks, the number of dec-
imal places, symbol placement and so on. (Cf Commodity display
style)
You are likely to run into one of the problems solved by commodity You will run into one of the problems solved by commodity directives
directives, sooner or later, so it's a good idea to just always use sooner or later, so we recommend using them, for robust and predictable
them to declare your commodities. parsing and display.
A commodity directive is just the word commodity followed by an amount. Generally you should put them at the top of your journal file (since
It may be written on a single line, like this: for function 2, they affect only following amounts, cf #793).
; commodity EXAMPLEAMOUNT A commodity directive is just the word commodity followed by a sample
amount, like this:
; display AAAA amounts with the symbol on the right, space-separated, ;commodity SAMPLEAMOUNT
; 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 commodity $1000.00
the commodity symbol appears twice and should be the same in both commodity 1,000.0000 AAAA ; optional same-line comment
places.):
; commodity SYMBOL It may also be written on multiple lines, and use the format subdirec-
; format EXAMPLEAMOUNT tive, as in Ledger. Note in this case the commodity symbol appears
twice; it must be the same in both places:
;commodity SYMBOL
; format SAMPLEAMOUNT
; display indian rupees with currency name on the left, ; display indian rupees with currency name on the left,
; thousands, lakhs and crores comma-separated, ; thousands, lakhs and crores comma-separated,
@ -4534,9 +4589,20 @@ JOURNAL FORMAT
commodity INR commodity INR
format INR 1,00,00,000.00 format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi- Remember that if the commodity symbol contains spaces, numbers, or
cant. The number must include a decimal mark: either a period or a punctuation, it must be enclosed in double quotes (cf Commodity).
comma, followed by 0 or more decimal digits.
The amount's quantity does not matter; only the format is significant.
It must include a decimal mark - either a period or a comma - followed
by 0 or more decimal digits.
A few more examples:
# number formats for $, EUR, INR and the no-symbol commodity:
commodity $1,000.00
commodity EUR 1.000,00
commodity INR 9,99,99,999.0
commodity 1 000 000.
Note hledger normally uses banker's rounding, so 0.5 displayed with Note hledger normally uses banker's rounding, so 0.5 displayed with
zero decimal digits is "0". (More at Commodity display style.) zero decimal digits is "0". (More at Commodity display style.)
@ -4548,16 +4614,18 @@ JOURNAL FORMAT
see the notes there for more details. see the notes there for more details.
Default commodity Default commodity
The D directive sets a default commodity, to be used for amounts with- The D directive sets a default commodity, to be used for any subsequent
out a commodity symbol (ie, plain numbers). This commodity will be commodityless amounts (ie, plain numbers) seen while parsing the jour-
applied to all subsequent commodity-less amounts, or until the next D nal. This effect lasts until the next D directive, or the end of the
directive. (Note, this is different from Ledger's D.) journal.
For compatibility/historical reasons, D also acts like a commodity For compatibility/historical reasons, D also acts like a commodity
directive, setting the commodity's display style (for output) and deci- directive (setting the commodity's decimal mark for parsing and display
mal mark (for parsing input). As with commodity, the amount must style for output).
always be written with a decimal mark (period or comma). If both
directives are used, commodity's style takes precedence. As with commodity, the amount must include a decimal mark (either
period or comma). If both commodity and D directives are used for the
same commodity, the commodity style takes precedence.
The syntax is D AMOUNT. Eg: The syntax is D AMOUNT. Eg:
@ -4718,8 +4786,8 @@ JOURNAL FORMAT
cally using the following rules: cally using the following rules:
If name matches regular account type is: If name matches this regu- account type is:
expression: lar expression:
---------------------------------------------- ----------------------------------------------
^assets?(:|$) Asset ^assets?(:|$) Asset
^(debts?|lia- Liability ^(debts?|lia- Liability
@ -4729,10 +4797,9 @@ JOURNAL FORMAT
^expenses?(:|$) Expense ^expenses?(:|$) Expense
If account type is Asset and name does not contain regu- account type If account type is Asset and name does not contain this account type
lar expression: is: regular expression: is:
-------------------------------------------------------------------------- --------------------------------------------------------------------------
(investment|receivable|:A/R|:fixed) Cash (investment|receivable|:A/R|:fixed) Cash
Even so, explicit declarations may be a good idea, for clarity and pre- Even so, explicit declarations may be a good idea, for clarity and pre-
@ -5695,11 +5762,11 @@ CSV FORMAT
REGEX REGEX
REGEX is a case-insensitive regular expression which tries to match REGEX is a case-insensitive regular expression that tries to match any-
anywhere within the CSV record. It is a POSIX ERE (extended regular where within the CSV record. It is a POSIX ERE (extended regular
expression) that also supports GNU word boundaries (\b, \B, \<, \>), expression) that also supports GNU word boundaries (\b, \B, \<, \>),
and nothing else. If you have trouble, be sure to check our and nothing else. If you have trouble, be sure to check our doc:
https://hledger.org/hledger.html#regular-expressions doc. https://hledger.org/hledger.html#regular-expressions
Important note: the record that is matched is not the original record, Important note: the record that is matched is not the original record,
but a synthetic one, with any enclosing double quotes (but not enclos- but a synthetic one, with any enclosing double quotes (but not enclos-