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

doc: move cost/market value into general options section

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2017-03-31 19:17:56 -07:00
parent 2f5c9df0de
commit d9488ea01b
9 changed files with 581 additions and 558 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
hledger-lib/doc/hledger_journal.5
View File

@ -540,8 +540,8 @@ Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities.
(Ledger calls them historical prices.) For example, the prices published
by a stock exchange or the foreign exchange market.
Some commands (balance, currently) can use this information to show the
market value of things at a given date.
hledger can use these prices to show the market value of things at a
given date, see market value.
.PP
To record market prices, use P directives in the main journal or in an
included file.

73
hledger-lib/doc/hledger_journal.5.info
View File

@ -540,9 +540,8 @@ File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices,
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. (Ledger calls them
historical prices.) For example, the prices published by a stock
exchange or the foreign exchange market. Some commands (balance,
currently) can use this information to show the market value of things
at a given date.
exchange or the foreign exchange market. hledger can use these prices
to show the market value of things at a given date, see market value.
To record market prices, use P directives in the main journal or in
an included file. Their format is:
@ -1005,39 +1004,39 @@ Node: Transaction prices18256
Ref: #transaction-prices18401
Node: Market prices19978
Ref: #market-prices20113
Node: Comments21086
Ref: #comments21208
Node: Tags22321
Ref: #tags22441
Node: Implicit tags23870
Ref: #implicit-tags23978
Node: Directives24495
Ref: #directives24610
Node: Account aliases24803
Ref: #account-aliases24949
Node: Basic aliases25553
Ref: #basic-aliases25698
Node: Regex aliases26388
Ref: #regex-aliases26558
Node: Multiple aliases27329
Ref: #multiple-aliases27503
Node: end aliases28001
Ref: #end-aliases28143
Node: account directive28244
Ref: #account-directive28426
Node: apply account directive28722
Ref: #apply-account-directive28920
Node: Multi-line comments29579
Ref: #multi-line-comments29771
Node: commodity directive29899
Ref: #commodity-directive30085
Node: Default commodity30957
Ref: #default-commodity31132
Node: Default year31669
Ref: #default-year31836
Node: Including other files32259
Ref: #including-other-files32418
Node: EDITOR SUPPORT32815
Ref: #editor-support32935
Node: Comments21073
Ref: #comments21195
Node: Tags22308
Ref: #tags22428
Node: Implicit tags23857
Ref: #implicit-tags23965
Node: Directives24482
Ref: #directives24597
Node: Account aliases24790
Ref: #account-aliases24936
Node: Basic aliases25540
Ref: #basic-aliases25685
Node: Regex aliases26375
Ref: #regex-aliases26545
Node: Multiple aliases27316
Ref: #multiple-aliases27490
Node: end aliases27988
Ref: #end-aliases28130
Node: account directive28231
Ref: #account-directive28413
Node: apply account directive28709
Ref: #apply-account-directive28907
Node: Multi-line comments29566
Ref: #multi-line-comments29758
Node: commodity directive29886
Ref: #commodity-directive30072
Node: Default commodity30944
Ref: #default-commodity31119
Node: Default year31656
Ref: #default-year31823
Node: Including other files32246
Ref: #including-other-files32405
Node: EDITOR SUPPORT32802
Ref: #editor-support32922

End Tag Table

2
hledger-lib/doc/hledger_journal.5.m4.md
View File

@ -442,7 +442,7 @@ Market prices are not tied to a particular transaction; they represent historica
(Ledger calls them historical prices.)
For example, the prices published by a [stock exchange](https://en.wikipedia.org/wiki/Stock_exchange)
or the [foreign exchange market](https://en.wikipedia.org/wiki/Foreign_exchange_market).
Some commands ([balance](hledger.html#market-value), currently) can use this information to show the market value of things at a given date.
hledger can use these prices to show the market value of things at a given date, see [market value](#market-value).
To record market prices, use P directives in the main journal or
in an [included](#including-other-files) file. Their format is:

133
hledger-lib/doc/hledger_journal.5.txt
View File

@ -411,39 +411,38 @@ FILE FORMAT
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. (Ledger calls them
historical prices.) For example, the prices published by a stock
exchange or the foreign exchange market. Some commands (balance, cur-
rently) can use this information to show the market value of things at
a given date.
exchange or the foreign exchange market. hledger can use these prices
to show the market value of things at a given date, see market value.
To record market prices, use P directives in the main journal or in an
To record market prices, use P directives in the main journal or in an
included file. Their format is:
P DATE COMMODITYBEINGPRICED UNITPRICE
DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of
the commodity being priced. UNITPRICE is an ordinary amount (symbol
and quantity) in a second commodity, specifying the unit price or con-
version rate for the first commodity in terms of the second, on the
DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of
the commodity being priced. UNITPRICE is an ordinary amount (symbol
and quantity) in a second commodity, specifying the unit price or con-
version rate for the first commodity in terms of the second, on the
given date.
For example, the following directives say that one euro was worth 1.35
For example, the following directives say that one euro was worth 1.35
US dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35
P 2010/1/1 $1.40
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.)
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends
to the end of the file.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Some examples:
@ -468,20 +467,20 @@ FILE FORMAT
; a journal comment (because not indented)
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.
A simple tag is a word (which may contain hyphens) followed by a full
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
Tags can have a value, which is the text after the colon, up to the
Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@ -495,16 +494,16 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Implicit tags
@ -518,14 +517,14 @@ FILE FORMAT
o note - the part of description after |, or all of it
payee and note support descriptions written in a special PAYEE | NOTE
payee and note support descriptions written in a special PAYEE | NOTE
format, accessing the parts before and after the pipe character respec-
tively. For descriptions not containing a pipe character they are the
tively. For descriptions not containing a pipe character they are the
same as description.
Directives
Account aliases
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
be useful for:
@ -542,8 +541,8 @@ FILE FORMAT
See also Cookbook: rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -551,53 +550,53 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are full account names. hledger will replace any occur-
rence of the old account name with the new one. Subaccounts are also
OLD and NEW are full account names. hledger will replace any occur-
rence 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"
Regex aliases
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in
hledger 0.24-0.25):
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Note, cur-
rently regular expression aliases may cause noticeable slow-downs.
rently regular expression aliases may cause noticeable slow-downs.
(And if you use Ledger on your hledger file, they will be ignored.) Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Multiple aliases
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
You can define as many aliases as you like using directives or com-
mand-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 fol-
lowing order:
1. alias directives, most recently seen first (recent directives take
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
end aliases
You can clear (forget) all currently defined aliases with the
You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
account directive
The account directive predefines account names, as in Ledger and Bean-
count. This may be useful for your own documentation; hledger doesn't
The account directive predefines account names, as in Ledger and Bean-
count. This may be useful for your own documentation; hledger doesn't
make use of it yet.
; account ACCT
@ -612,8 +611,8 @@ FILE FORMAT
; etc.
apply account directive
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@ -630,7 +629,7 @@ FILE FORMAT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -639,16 +638,16 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
Multi-line comments
A line containing just comment starts a multi-line comment, and a line
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 predefines commodities (currently this is just
informational), and also it may define the display format for amounts
The commodity directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this:
@ -660,8 +659,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
@ -674,10 +673,10 @@ FILE FORMAT
format INR 9,99,99,999.00
Default commodity
The D directive sets a default commodity (and display format), to be
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
@ -689,8 +688,8 @@ FILE FORMAT
b
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -710,24 +709,24 @@ FILE FORMAT
assets
Including other files
You can pull in the content of additional journal files by writing an
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
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
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger
These were written with Ledger in mind, but also work with hledger
files:
@ -744,7 +743,7 @@ EDITOR SUPPORT
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -758,7 +757,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

47
hledger/doc/balance.m4.md
View File

@ -233,53 +233,6 @@ Balance changes in 2008:
```
### Market value
The `-V/--value` flag converts the reported amounts to their market value
on the report end date, using the most recent applicable market prices,
when known.
Specifically, when there is a [market price](journal.html#market-prices) (P directive)
for the amount's commodity, dated on or before the
[report end date](hledger.html#report-start-end-date) (see hledger -> Report start & end date),
the amount will be converted to the price's commodity.
If multiple applicable prices are defined, the latest-dated one is used
(and if dates are equal, the one last parsed).
For example:
```journal
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros €100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 € $1.03
```
How many euros do I have ?
```
$ hledger -f t.j bal euros
€100 assets:euros
```
What are they worth on nov 3 ? (no report end date specified, defaults to the last date in the journal)
```
$ hledger -f t.j bal euros -V
$110.00 assets:euros
```
What are they worth on dec 21 ?
```
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
```
Currently, hledger's -V only uses market prices recorded with P directives,
not [transaction prices](journal.html#transaction-prices) (unlike Ledger).
Using -B and -V together is allowed.
### Custom balance output
In simple (non-multi-column) balance reports, you can customise the

126
hledger/doc/hledger.1
View File

@ -840,6 +840,71 @@ $\ hledger\ balance\ \-\-pivot\ member\ acct:.
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\f[]
.fi
.SS Cost
.PP
The \f[C]\-B/\-\-cost\f[] flag converts amounts to their cost at
transaction time, if they have a transaction price specified.
.SS Market value
.PP
The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their
market value on the report end date, using the most recent applicable
market prices, when known.
Specifically, when there is a market price (P directive) for the
amount\[aq]s commodity, dated on or before the report end date (see
hledger \-> Report start & end date), the amount will be converted to
the price\[aq]s commodity.
If multiple applicable prices are defined, the latest\-dated one is used
(and if dates are equal, the one last parsed).
.PP
For example:
.IP
.nf
\f[C]
#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1
P\ 2016/11/01\ €\ $1.10
#\ purchase\ some\ euros\ on\ nov\ 3
2016/11/3
\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100
\ \ \ \ assets:checking
#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21
P\ 2016/12/21\ €\ $1.03
\f[]
.fi
.PP
How many euros do I have ?
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.j\ bal\ euros
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
\f[]
.fi
.PP
What are they worth on nov 3 ?
(no report end date specified, defaults to the last date in the journal)
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.j\ bal\ euros\ \-V
\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros
\f[]
.fi
.PP
What are they worth on dec 21 ?
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21
\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros
\f[]
.fi
.PP
Currently, hledger\[aq]s \-V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
.PP
Using \-B and \-V together is allowed.
.SS Regular expressions
.PP
hledger uses regular expressions in a number of places:
@ -1494,67 +1559,6 @@ Balance\ changes\ in\ 2008:
#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
\f[]
.fi
.SS Market value
.PP
The \f[C]\-V/\-\-value\f[] flag converts the reported amounts to their
market value on the report end date, using the most recent applicable
market prices, when known.
Specifically, when there is a market price (P directive) for the
amount\[aq]s commodity, dated on or before the report end date (see
hledger \-> Report start & end date), the amount will be converted to
the price\[aq]s commodity.
If multiple applicable prices are defined, the latest\-dated one is used
(and if dates are equal, the one last parsed).
.PP
For example:
.IP
.nf
\f[C]
#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1
P\ 2016/11/01\ €\ $1.10
#\ purchase\ some\ euros\ on\ nov\ 3
2016/11/3
\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100
\ \ \ \ assets:checking
#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21
P\ 2016/12/21\ €\ $1.03
\f[]
.fi
.PP
How many euros do I have ?
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.j\ bal\ euros
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
\f[]
.fi
.PP
What are they worth on nov 3 ?
(no report end date specified, defaults to the last date in the journal)
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.j\ bal\ euros\ \-V
\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros
\f[]
.fi
.PP
What are they worth on dec 21 ?
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21
\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros
\f[]
.fi
.PP
Currently, hledger\[aq]s \-V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
.PP
Using \-B and \-V together is allowed.
.SS Custom balance output
.PP
In simple (non\-multi\-column) balance reports, you can customise the

360
hledger/doc/hledger.1.info
View File

@ -126,6 +126,8 @@ File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Period expressions::
* Depth limiting::
* Pivoting::
* Cost::
* Market value::
* Regular expressions::

@ -508,7 +510,7 @@ will show only the uppermost accounts in the account tree, down to level
N. Use this when you want a summary with less detail.

File: hledger.1.info, Node: Pivoting, Next: Regular expressions, Prev: Depth limiting, Up: OPTIONS
File: hledger.1.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS
2.11 Pivoting
=============
@ -568,9 +570,67 @@ $ hledger balance --pivot member acct:.
-2 EUR

File: hledger.1.info, Node: Regular expressions, Prev: Pivoting, Up: OPTIONS
File: hledger.1.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS
2.12 Regular expressions
2.12 Cost
=========
The '-B/--cost' flag converts amounts to their cost at transaction time,
if they have a transaction price specified.

File: hledger.1.info, Node: Market value, Next: Regular expressions, Prev: Cost, Up: OPTIONS
2.13 Market value
=================
The '-V/--value' flag converts the reported amounts to their market
value on the report end date, using the most recent applicable market
prices, when known. Specifically, when there is a market price (P
directive) for the amount's commodity, dated on or before the report end
date (see hledger -> Report start & end date), the amount will be
converted to the price's commodity. If multiple applicable prices are
defined, the latest-dated one is used (and if dates are equal, the one
last parsed).
For example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros €100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 € $1.03
How many euros do I have ?
$ hledger -f t.j bal euros
€100 assets:euros
What are they worth on nov 3 ? (no report end date specified,
defaults to the last date in the journal)
$ hledger -f t.j bal euros -V
$110.00 assets:euros
What are they worth on dec 21 ?
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
Using -B and -V together is allowed.

File: hledger.1.info, Node: Regular expressions, Prev: Market value, Up: OPTIONS
2.14 Regular expressions
========================
hledger uses regular expressions in a number of places:
@ -999,7 +1059,6 @@ $ hledger balance -p 2008/6 expenses --no-total
* Flat mode::
* Depth limited balance reports::
* Multicolumn balance reports::
* Market value::
* Custom balance output::
* Output destination::
* CSV output::
@ -1038,7 +1097,7 @@ $ hledger balance -N --depth 1
$1 liabilities

File: hledger.1.info, Node: Multicolumn balance reports, Next: Market value, Prev: Depth limited balance reports, Up: balance
File: hledger.1.info, Node: Multicolumn balance reports, Next: Custom balance output, Prev: Depth limited balance reports, Up: balance
4.4.3 Multicolumn balance reports
---------------------------------
@ -1138,58 +1197,9 @@ Balance changes in 2008:
# Average is rounded to the dollar here since all journal amounts are

File: hledger.1.info, Node: Market value, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance
File: hledger.1.info, Node: Custom balance output, Next: Output destination, Prev: Multicolumn balance reports, Up: balance
4.4.4 Market value
------------------
The '-V/--value' flag converts the reported amounts to their market
value on the report end date, using the most recent applicable market
prices, when known. Specifically, when there is a market price (P
directive) for the amount's commodity, dated on or before the report end
date (see hledger -> Report start & end date), the amount will be
converted to the price's commodity. If multiple applicable prices are
defined, the latest-dated one is used (and if dates are equal, the one
last parsed).
For example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros €100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 € $1.03
How many euros do I have ?
$ hledger -f t.j bal euros
€100 assets:euros
What are they worth on nov 3 ? (no report end date specified,
defaults to the last date in the journal)
$ hledger -f t.j bal euros -V
$110.00 assets:euros
What are they worth on dec 21 ?
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
Using -B and -V together is allowed.

File: hledger.1.info, Node: Custom balance output, Next: Output destination, Prev: Market value, Up: balance
4.4.5 Custom balance output
4.4.4 Custom balance output
---------------------------
In simple (non-multi-column) balance reports, you can customise the
@ -1249,7 +1259,7 @@ may be needed to get pleasing results.

File: hledger.1.info, Node: Output destination, Next: CSV output, Prev: Custom balance output, Up: balance
4.4.6 Output destination
4.4.5 Output destination
------------------------
The balance, print, register and stats commands can write their output
@ -1262,7 +1272,7 @@ $ hledger balance -o FILE # write to FILE

File: hledger.1.info, Node: CSV output, Prev: Output destination, Up: balance
4.4.7 CSV output
4.4.6 CSV output
----------------
The balance, print and register commands can write their output as CSV.
@ -2094,121 +2104,123 @@ Node: EXAMPLES1886
Ref: #examples1988
Node: OPTIONS3634
Ref: #options3738
Node: General options3993
Ref: #general-options4120
Node: Command options6643
Ref: #command-options6796
Node: Command arguments7194
Ref: #command-arguments7354
Node: Special characters7475
Ref: #special-characters7633
Node: Input files8801
Ref: #input-files8939
Node: Smart dates10902
Ref: #smart-dates11045
Node: Report start & end date12024
Ref: #report-start-end-date12196
Node: Report intervals13262
Ref: #report-intervals13427
Node: Period expressions13828
Ref: #period-expressions13988
Node: Depth limiting16328
Ref: #depth-limiting16474
Node: Pivoting16675
Ref: #pivoting16810
Node: Regular expressions18581
Ref: #regular-expressions18715
Node: QUERIES20076
Ref: #queries20180
Node: COMMANDS23826
Ref: #commands23940
Node: accounts24613
Ref: #accounts24713
Node: activity25695
Ref: #activity25807
Node: add26166
Ref: #add26267
Node: balance28925
Ref: #balance29038
Node: Flat mode31980
Ref: #flat-mode32107
Node: Depth limited balance reports32527
Ref: #depth-limited-balance-reports32730
Node: Multicolumn balance reports33150
Ref: #multicolumn-balance-reports33352
Node: Market value38000
Ref: #market-value38164
Node: Custom balance output39464
Ref: #custom-balance-output39637
Node: Output destination41730
Ref: #output-destination41895
Node: CSV output42165
Ref: #csv-output42284
Node: balancesheet42681
Ref: #balancesheet42809
Node: cashflow44716
Ref: #cashflow44833
Node: help46701
Ref: #help46813
Node: incomestatement47651
Ref: #incomestatement47781
Node: info49673
Ref: #info49780
Node: man50144
Ref: #man50241
Node: print50646
Ref: #print50751
Node: register54507
Ref: #register54620
Node: Custom register output59116
Ref: #custom-register-output59247
Node: stats60544
Ref: #stats60650
Node: test61531
Ref: #test61618
Node: ADD-ON COMMANDS61986
Ref: #add-on-commands62098
Node: Official add-ons63385
Ref: #official-add-ons63527
Node: api63614
Ref: #api63705
Node: ui63757
Ref: #ui63858
Node: web63916
Ref: #web64007
Node: Third party add-ons64053
Ref: #third-party-add-ons64230
Node: diff64365
Ref: #diff64464
Node: iadd64563
Ref: #iadd64679
Node: interest64762
Ref: #interest64885
Node: irr64980
Ref: #irr65080
Node: Experimental add-ons65158
Ref: #experimental-add-ons65312
Node: autosync65705
Ref: #autosync65819
Node: budget66058
Ref: #budget66182
Node: chart66248
Ref: #chart66367
Node: check66438
Ref: #check66562
Node: check-dates66629
Ref: #check-dates66771
Node: check-dupes66844
Ref: #check-dupes66987
Node: equity67064
Ref: #equity67192
Node: prices67311
Ref: #prices67440
Node: print-unique67495
Ref: #print-unique67644
Node: register-match67737
Ref: #register-match67893
Node: rewrite67991
Ref: #rewrite68112
Node: General options4019
Ref: #general-options4146
Node: Command options6669
Ref: #command-options6822
Node: Command arguments7220
Ref: #command-arguments7380
Node: Special characters7501
Ref: #special-characters7659
Node: Input files8827
Ref: #input-files8965
Node: Smart dates10928
Ref: #smart-dates11071
Node: Report start & end date12050
Ref: #report-start-end-date12222
Node: Report intervals13288
Ref: #report-intervals13453
Node: Period expressions13854
Ref: #period-expressions14014
Node: Depth limiting16354
Ref: #depth-limiting16500
Node: Pivoting16701
Ref: #pivoting16821
Node: Cost18592
Ref: #cost18702
Node: Market value18820
Ref: #market-value18957
Node: Regular expressions20257
Ref: #regular-expressions20395
Node: QUERIES21756
Ref: #queries21860
Node: COMMANDS25506
Ref: #commands25620
Node: accounts26293
Ref: #accounts26393
Node: activity27375
Ref: #activity27487
Node: add27846
Ref: #add27947
Node: balance30605
Ref: #balance30718
Node: Flat mode33643
Ref: #flat-mode33770
Node: Depth limited balance reports34190
Ref: #depth-limited-balance-reports34393
Node: Multicolumn balance reports34813
Ref: #multicolumn-balance-reports35024
Node: Custom balance output39672
Ref: #custom-balance-output39860
Node: Output destination41953
Ref: #output-destination42118
Node: CSV output42388
Ref: #csv-output42507
Node: balancesheet42904
Ref: #balancesheet43032
Node: cashflow44939
Ref: #cashflow45056
Node: help46924
Ref: #help47036
Node: incomestatement47874
Ref: #incomestatement48004
Node: info49896
Ref: #info50003
Node: man50367
Ref: #man50464
Node: print50869
Ref: #print50974
Node: register54730
Ref: #register54843
Node: Custom register output59339
Ref: #custom-register-output59470
Node: stats60767
Ref: #stats60873
Node: test61754
Ref: #test61841
Node: ADD-ON COMMANDS62209
Ref: #add-on-commands62321
Node: Official add-ons63608
Ref: #official-add-ons63750
Node: api63837
Ref: #api63928
Node: ui63980
Ref: #ui64081
Node: web64139
Ref: #web64230
Node: Third party add-ons64276
Ref: #third-party-add-ons64453
Node: diff64588
Ref: #diff64687
Node: iadd64786
Ref: #iadd64902
Node: interest64985
Ref: #interest65108
Node: irr65203
Ref: #irr65303
Node: Experimental add-ons65381
Ref: #experimental-add-ons65535
Node: autosync65928
Ref: #autosync66042
Node: budget66281
Ref: #budget66405
Node: chart66471
Ref: #chart66590
Node: check66661
Ref: #check66785
Node: check-dates66852
Ref: #check-dates66994
Node: check-dupes67067
Ref: #check-dupes67210
Node: equity67287
Ref: #equity67415
Node: prices67534
Ref: #prices67663
Node: print-unique67718
Ref: #print-unique67867
Node: register-match67960
Ref: #register-match68116
Node: rewrite68214
Ref: #rewrite68335

End Tag Table

342
hledger/doc/hledger.1.txt
View File

@ -518,6 +518,53 @@ OPTIONS
--------------------
-2 EUR
Cost
The -B/--cost flag converts amounts to their cost at transaction time,
if they have a transaction price specified.
Market value
The -V/--value flag converts the reported amounts to their market value
on the report end date, using the most recent applicable market prices,
when known. Specifically, when there is a market price (P directive)
for the amount's commodity, dated on or before the report end date (see
hledger -> Report start & end date), the amount will be converted to
the price's commodity. If multiple applicable prices are defined, the
latest-dated one is used (and if dates are equal, the one last parsed).
For example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros 100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 $1.03
How many euros do I have ?
$ hledger -f t.j bal euros
100 assets:euros
What are they worth on nov 3 ? (no report end date specified, defaults
to the last date in the journal)
$ hledger -f t.j bal euros -V
$110.00 assets:euros
What are they worth on dec 21 ?
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P direc-
tives, not transaction prices (unlike Ledger).
Using -B and -V together is allowed.
Regular expressions
hledger uses regular expressions in a number of places:
@ -1022,51 +1069,8 @@ COMMANDS
# Average is rounded to the dollar here since all journal amounts are
Market value
The -V/--value flag converts the reported amounts to their market value
on the report end date, using the most recent applicable market prices,
when known. Specifically, when there is a market price (P directive)
for the amount's commodity, dated on or before the report end date (see
hledger -> Report start & end date), the amount will be converted to
the price's commodity. If multiple applicable prices are defined, the
latest-dated one is used (and if dates are equal, the one last parsed).
For example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros 100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 $1.03
How many euros do I have ?
$ hledger -f t.j bal euros
100 assets:euros
What are they worth on nov 3 ? (no report end date specified, defaults
to the last date in the journal)
$ hledger -f t.j bal euros -V
$110.00 assets:euros
What are they worth on dec 21 ?
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P direc-
tives, not transaction prices (unlike Ledger).
Using -B and -V together is allowed.
Custom balance output
In simple (non-multi-column) balance reports, you can customise the
In simple (non-multi-column) balance reports, you can customise the
output with --format FMT:
$ hledger balance --format "%20(account) %12(total)"
@ -1084,7 +1088,7 @@ COMMANDS
0
The FMT format string (plus a newline) specifies the formatting applied
to each account/balance pair. It may contain any suitable text, with
to each account/balance pair. It may contain any suitable text, with
data fields interpolated like so:
%[MIN][.MAX](FIELDNAME)
@ -1095,14 +1099,14 @@ COMMANDS
o FIELDNAME must be enclosed in parentheses, and can be one of:
o depth_spacer - a number of spaces equal to the account's depth, or
o depth_spacer - a number of spaces equal to the account's depth, or
if MIN is specified, MIN * depth spaces.
o account - the account's name
o total - the account's balance/posted total, right justified
Also, FMT can begin with an optional prefix to control how multi-com-
Also, FMT can begin with an optional prefix to control how multi-com-
modity amounts are rendered:
o %_ - render on multiple lines, bottom-aligned (the default)
@ -1111,7 +1115,7 @@ COMMANDS
o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results.
@ -1119,19 +1123,19 @@ COMMANDS
o %(total) - the account's total
o %-20.20(account) - the account's name, left justified, padded to 20
o %-20.20(account) - the account's name, left justified, padded to 20
characters and clipped at 20 characters
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
one line
o %20(total) %2(depth_spacer)%-(account) - the default format for the
o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report
Output destination
The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the
The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the
-o/--output-file option.
$ hledger balance -o - # write to stdout (the default)
@ -1139,8 +1143,8 @@ COMMANDS
CSV output
The balance, print and register commands can write their output as CSV.
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the -O/--output-format
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the -O/--output-format
option, or by specifying a .csv file extension with -o/--output-file.
$ hledger balance -O csv # write CSV to stdout
@ -1154,7 +1158,7 @@ COMMANDS
balances
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of historical ending balances
-H --historical
@ -1185,8 +1189,8 @@ COMMANDS
--format=LINEFORMAT
in single-column balance reports: use this custom line format
This command displays a simple balance sheet. It currently assumes
that you have top-level accounts named asset and liability (plural
This command displays a simple balance sheet. It currently assumes
that you have top-level accounts named asset and liability (plural
forms also allowed.)
$ hledger balancesheet
@ -1209,9 +1213,9 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
cashflow
@ -1221,7 +1225,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1252,9 +1256,9 @@ COMMANDS
--format=LINEFORMAT
in single-column balance reports: use this custom line format
This command displays a simple cashflow statement It shows the change
in all "cash" (ie, liquid assets) accounts for the period. It cur-
rently assumes that cash accounts are under a top-level account named
This command displays a simple cashflow statement It shows the change
in all "cash" (ie, liquid assets) accounts for the period. It cur-
rently assumes that cash accounts are under a top-level account named
asset and do not contain receivable or A/R (plural forms also allowed.)
$ hledger cashflow
@ -1272,18 +1276,18 @@ COMMANDS
$-1
With a reporting interval, multiple columns will be shown, one for each
report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report
report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical.
help
Show any of the hledger manuals.
The help command displays any of the main hledger man pages. (Unlike
hledger --help, which displays only the hledger man page.) Run it with
no arguments to list available topics (their names are shortened for
easier typing), and run hledger help TOPIC to select one. The output
is similar to a man page, but fixed width. It may be long, so you may
The help command displays any of the main hledger man pages. (Unlike
hledger --help, which displays only the hledger man page.) Run it with
no arguments to list available topics (their names are shortened for
easier typing), and run hledger help TOPIC to select one. The output
is similar to a man page, but fixed width. It may be long, so you may
wish to pipe it into a pager. See also info and man.
$ hledger help
@ -1311,7 +1315,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@ -1342,8 +1346,8 @@ COMMANDS
--format=LINEFORMAT
in single-column balance reports: use this custom line format
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@ -1368,30 +1372,30 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
info
Show any of the hledger manuals using info.
The info command displays any of the hledger reference manuals using
the info hypertextual documentation viewer. This can be a very effi-
cient way to browse large manuals. It requires the "info" program to
The info command displays any of the hledger reference manuals using
the info hypertextual documentation viewer. This can be a very effi-
cient way to browse large manuals. It requires the "info" program to
be available in your PATH.
As with help, run it with no arguments to list available topics (manu-
As with help, run it with no arguments to list available topics (manu-
als).
man
Show any of the hledger manuals using man.
The man command displays any of the hledger reference manuals using
man, the standard documentation viewer on unix systems. This will fit
the text to your terminal width, and probably invoke a pager automati-
The man command displays any of the hledger reference manuals using
man, the standard documentation viewer on unix systems. This will fit
the text to your terminal width, and probably invoke a pager automati-
cally. It requires the "man" program to be available in your PATH.
As with help, run it with no arguments to list available topics (manu-
As with help, run it with no arguments to list available topics (manu-
als).
print
@ -1401,14 +1405,14 @@ COMMANDS
show all amounts explicitly
-m STR --match=STR
show the transaction whose description is most similar to STR,
show the transaction whose description is most similar to STR,
and is most recent
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger print
@ -1436,23 +1440,23 @@ COMMANDS
The print command displays full journal entries (transactions) from the
journal file, tidily formatted.
As of hledger 1.2, print's output is always a valid hledger journal.
However it may not preserve all original content, eg it does not print
As of hledger 1.2, print's output is always a valid hledger journal.
However it may not preserve all original content, eg it does not print
directives or inter-transaction comments.
Normally, transactions' implicit/explicit amount style is preserved:
when an amount is omitted in the journal, it will be omitted in the
output. You can use the -x/--explicit flag to make all amounts
explicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors. Note, in
this mode postings with a multi-commodity amount (possible with an
implicit amount in a multi-commodity transaction) will be split into
Normally, transactions' implicit/explicit amount style is preserved:
when an amount is omitted in the journal, it will be omitted in the
output. You can use the -x/--explicit flag to make all amounts
explicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors. Note, in
this mode postings with a multi-commodity amount (possible with an
implicit amount in a multi-commodity transaction) will be split into
multiple single-commodity postings, for valid journal output.
With -B/--cost, amounts with transaction prices are converted to cost
With -B/--cost, amounts with transaction prices are converted to cost
(using the transaction price).
The print command also supports output destination and CSV output.
The print command also supports output destination and CSV output.
Here's an example of print's CSV output:
$ hledger print -Ocsv
@ -1469,20 +1473,20 @@ COMMANDS
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
o There is one CSV record per posting, with the parent transaction's
o There is one CSV record per posting, with the parent transaction's
fields repeated.
o The "txnidx" (transaction index) field shows which postings belong to
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different
order, etc.)
o The amount is separated into "commodity" (the symbol) and "amount"
o The amount is separated into "commodity" (the symbol) and "amount"
(numeric quantity) fields.
o The numeric amount is repeated in either the "credit" or "debit" col-
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or
greater amounts under debit.)
register
@ -1492,7 +1496,7 @@ COMMANDS
show running total from report start date (default)
-H --historical
show historical running total/balance (includes postings before
show historical running total/balance (includes postings before
report start date)
-A --average
@ -1503,18 +1507,18 @@ COMMANDS
show postings' siblings instead
-w N --width=N
set output width (default: terminal width or COLUMNS. -wN,M
set output width (default: terminal width or COLUMNS. -wN,M
sets description width as well)
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
The register command displays postings, one per line, and their running
total. This is typically used with a query selecting a particular
total. This is typically used with a query selecting a particular
account, to see that account's activity:
$ hledger register checking
@ -1523,8 +1527,8 @@ COMMANDS
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical
@ -1534,23 +1538,23 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead
The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one
the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one
account and one commodity.
The --related/-r flag shows the other postings in the transactions of
The --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown.
With a reporting interval, register shows summary postings, one per
With a reporting interval, register shows summary postings, one per
interval, aggregating the postings to each account:
$ hledger register --monthly income
2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are
Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E
@ -1567,7 +1571,7 @@ COMMANDS
2008/11 0 $-2
2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth
Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@ -1575,19 +1579,19 @@ COMMANDS
2008/06 assets $-1 0
2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report.
Custom register output
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a
description width as part of --width's argument, comma-separated:
--width W,D . Here's a diagram:
<--------------------------------- width (W) ---------------------------------->
@ -1603,14 +1607,14 @@ COMMANDS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
The register command also supports the -o/--output-file and -O/--out-
The register command also supports the -o/--output-file and -O/--out-
put-format options for controlling output destination and CSV output.
stats
Show some journal statistics.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger stats
@ -1625,8 +1629,8 @@ COMMANDS
Accounts : 8 (depth 3)
Commodities : 1 ($)
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
The stats command also supports -o/--output-file for controlling output
@ -1638,34 +1642,34 @@ COMMANDS
$ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
This command runs hledger's built-in unit tests and displays a quick
This command runs hledger's built-in unit tests and displays a quick
report. With a regular expression argument, it selects only tests with
matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.
ADD-ON COMMANDS
hledger also searches for external add-on commands, and will include
hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten-
whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
Add-ons can be invoked like any hledger command, but there are a few
Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred:
o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
@ -1683,7 +1687,7 @@ ADD-ON COMMANDS
hledger-web provides a simple web interface.
Third party add-ons
These are maintained separately, and usually updated shortly after a
These are maintained separately, and usually updated shortly after a
hledger release.
diff
@ -1691,7 +1695,7 @@ ADD-ON COMMANDS
journal file and another.
iadd
hledger-iadd is a curses-style, more interactive replacement for the
hledger-iadd is a curses-style, more interactive replacement for the
add command.
interest
@ -1699,19 +1703,19 @@ ADD-ON COMMANDS
ing to various schemes.
irr
hledger-irr calculates the internal rate of return of an investment
hledger-irr calculates the internal rate of return of an investment
account.
Experimental add-ons
These are available in source form in the hledger repo's bin/ direc-
These are available in source form in the hledger repo's bin/ direc-
tory; installing them is pretty easy. They may be less mature and doc-
umented than built-in commands. Reading and tweaking these is a good
umented than built-in commands. Reading and tweaking these is a good
way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
if installed. ledger-autosync does deduplicating conversion of OFX
data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
budget
@ -1727,18 +1731,18 @@ ADD-ON COMMANDS
hledger-check-dates.hs checks that journal entries are ordered by date.
check-dupes
hledger-check-dupes.hs checks for account names sharing the same leaf
hledger-check-dupes.hs checks for account names sharing the same leaf
name.
equity
hledger-equity.hs prints balance-resetting transactions, useful for
hledger-equity.hs prints balance-resetting transactions, useful for
bringing account balances across file boundaries.
prices
hledger-prices.hs prints all prices from the journal.
print-unique
hledger-print-unique.hs prints transactions which do not reuse an
hledger-print-unique.hs prints transactions which do not reuse an
already-seen description.
register-match
@ -1750,21 +1754,21 @@ ADD-ON COMMANDS
tions.
ENVIRONMENT
COLUMNS The screen width used by the register command. Default: the
COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede addon command options with -- when invoked from
The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@ -1777,33 +1781,33 @@ BUGS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
Not all of Ledger's journal file syntax is supported. See file format
Not all of Ledger's journal file syntax is supported. See file format
differences.
On large data files, hledger is slower and uses more memory than
On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
Here are some issues you might encounter when you run hledger (and
remember you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command 'hledger' found"
stack and cabal install binaries into a special directory, which should
be added to your PATH environment variable. Eg on unix-like systems,
be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu
@ -1822,7 +1826,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
If we preferred to use eg fr_FR.utf8, we might have to install that
If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr
@ -1843,7 +1847,7 @@ TROUBLESHOOTING
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -1857,7 +1861,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

52
hledger/doc/options.m4.md
View File

@ -315,6 +315,58 @@ $ hledger balance --pivot member acct:.
-2 EUR
```
## Cost
The `-B/--cost` flag converts amounts to their cost at transaction time,
if they have a [transaction price](/journal.html#transaction-prices) specified.
## Market value
The `-V/--value` flag converts the reported amounts to their market value
on the report end date, using the most recent applicable market prices,
when known.
Specifically, when there is a [market price](journal.html#market-prices) (P directive)
for the amount's commodity, dated on or before the
[report end date](hledger.html#report-start-end-date) (see hledger -> Report start & end date),
the amount will be converted to the price's commodity.
If multiple applicable prices are defined, the latest-dated one is used
(and if dates are equal, the one last parsed).
For example:
```journal
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros €100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 € $1.03
```
How many euros do I have ?
```
$ hledger -f t.j bal euros
€100 assets:euros
```
What are they worth on nov 3 ? (no report end date specified, defaults to the last date in the journal)
```
$ hledger -f t.j bal euros -V
$110.00 assets:euros
```
What are they worth on dec 21 ?
```
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
```
Currently, hledger's -V only uses market prices recorded with P directives,
not [transaction prices](journal.html#transaction-prices) (unlike Ledger).
Using -B and -V together is allowed.
## Regular expressions
hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places: