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. historical exchange rates between two commodities.
(Ledger calls them historical prices.) For example, the prices published (Ledger calls them historical prices.) For example, the prices published
by a stock exchange or the foreign exchange market. by a stock exchange or the foreign exchange market.
Some commands (balance, currently) can use this information to show the hledger can use these prices to show the market value of things at a
market value of things at a given date. given date, see market value.
.PP .PP
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. 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 Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. (Ledger calls them historical exchange rates between two commodities. (Ledger calls them
historical prices.) For example, the prices published by a stock historical prices.) For example, the prices published by a stock
exchange or the foreign exchange market. Some commands (balance, exchange or the foreign exchange market. hledger can use these prices
currently) can use this information to show the market value of things to show the market value of things at a given date, see market value.
at a given date.
To record market prices, use P directives in the main journal or in To record market prices, use P directives in the main journal or in
an included file. Their format is: an included file. Their format is:
@ -1005,39 +1004,39 @@ Node: Transaction prices18256
Ref: #transaction-prices18401 Ref: #transaction-prices18401
Node: Market prices19978 Node: Market prices19978
Ref: #market-prices20113 Ref: #market-prices20113
Node: Comments21086 Node: Comments21073
Ref: #comments21208 Ref: #comments21195
Node: Tags22321 Node: Tags22308
Ref: #tags22441 Ref: #tags22428
Node: Implicit tags23870 Node: Implicit tags23857
Ref: #implicit-tags23978 Ref: #implicit-tags23965
Node: Directives24495 Node: Directives24482
Ref: #directives24610 Ref: #directives24597
Node: Account aliases24803 Node: Account aliases24790
Ref: #account-aliases24949 Ref: #account-aliases24936
Node: Basic aliases25553 Node: Basic aliases25540
Ref: #basic-aliases25698 Ref: #basic-aliases25685
Node: Regex aliases26388 Node: Regex aliases26375
Ref: #regex-aliases26558 Ref: #regex-aliases26545
Node: Multiple aliases27329 Node: Multiple aliases27316
Ref: #multiple-aliases27503 Ref: #multiple-aliases27490
Node: end aliases28001 Node: end aliases27988
Ref: #end-aliases28143 Ref: #end-aliases28130
Node: account directive28244 Node: account directive28231
Ref: #account-directive28426 Ref: #account-directive28413
Node: apply account directive28722 Node: apply account directive28709
Ref: #apply-account-directive28920 Ref: #apply-account-directive28907
Node: Multi-line comments29579 Node: Multi-line comments29566
Ref: #multi-line-comments29771 Ref: #multi-line-comments29758
Node: commodity directive29899 Node: commodity directive29886
Ref: #commodity-directive30085 Ref: #commodity-directive30072
Node: Default commodity30957 Node: Default commodity30944
Ref: #default-commodity31132 Ref: #default-commodity31119
Node: Default year31669 Node: Default year31656
Ref: #default-year31836 Ref: #default-year31823
Node: Including other files32259 Node: Including other files32246
Ref: #including-other-files32418 Ref: #including-other-files32405
Node: EDITOR SUPPORT32815 Node: EDITOR SUPPORT32802
Ref: #editor-support32935 Ref: #editor-support32922
 
End Tag Table 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.) (Ledger calls them historical prices.)
For example, the prices published by a [stock exchange](https://en.wikipedia.org/wiki/Stock_exchange) 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). 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 To record market prices, use P directives in the main journal or
in an [included](#including-other-files) file. Their format is: 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 Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. (Ledger calls them historical exchange rates between two commodities. (Ledger calls them
historical prices.) For example, the prices published by a stock historical prices.) For example, the prices published by a stock
exchange or the foreign exchange market. Some commands (balance, cur- exchange or the foreign exchange market. hledger can use these prices
rently) can use this information to show the market value of things at to show the market value of things at a given date, see market value.
a given date.
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: included file. Their format is:
P DATE COMMODITYBEINGPRICED UNITPRICE P DATE COMMODITYBEINGPRICED UNITPRICE
DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of
the commodity being priced. UNITPRICE is an ordinary amount (symbol the commodity being priced. UNITPRICE is an ordinary amount (symbol
and quantity) in a second commodity, specifying the unit price or con- 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 version rate for the first commodity in terms of the second, on the
given date. 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: US dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35 P 2009/1/1 $1.35
P 2010/1/1 $1.40 P 2010/1/1 $1.40
Comments Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or Lines in the journal beginning with a semicolon (;) or hash (#) or
asterisk (*) are comments, and will be ignored. (Asterisk comments asterisk (*) are comments, and will be ignored. (Asterisk comments
make it easy to treat your journal like an org-mode outline in emacs.) make it easy to treat your journal like an org-mode outline in emacs.)
Also, anything between comment and end comment directives is a Also, anything between comment and end comment directives is a
(multi-line) comment. If there is no end comment, the comment extends (multi-line) comment. If there is no end comment, the comment extends
to the end of the file. to the end of the file.
You can attach comments to a transaction by writing them after the You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post- description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines. writing them after the amount and/or indented on the following lines.
Some examples: Some examples:
@ -468,20 +467,20 @@ FILE FORMAT
; a journal comment (because not indented) ; a journal comment (because not indented)
Tags Tags
Tags are a way to add extra labels or labelled data to postings and Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on. transactions, which you can then search or pivot on.
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: colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag: 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: next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value 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 lines. Ending at commas means you can write multiple short tags on one
line, comma separated: line, comma separated:
@ -495,16 +494,16 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..." o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting. postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag): third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2: 1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value ; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag: (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. are simple strings.
Implicit tags Implicit tags
@ -518,14 +517,14 @@ FILE FORMAT
o note - the part of description after |, or all of it 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- 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. same as description.
Directives Directives
Account aliases 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 the journal, before generating reports). hledger's account aliases can
be useful for: be useful for:
@ -542,8 +541,8 @@ FILE FORMAT
See also Cookbook: rewrite account names. See also Cookbook: rewrite account names.
Basic aliases Basic aliases
To set an account alias, use the alias directive in your journal file. To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional: included files. The spaces around the = are optional:
alias OLD = NEW alias OLD = NEW
@ -551,53 +550,53 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively. affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are full account names. hledger will replace any occur- 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 rence of the old account name with the new one. Subaccounts are also
affected. Eg: affected. Eg:
alias checking = assets:bank:wells fargo:checking alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases Regex aliases
There is also a more powerful variant that uses a regular expression, There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes. (This was the default behaviour in indicated by the forward slashes. (This was the default behaviour in
hledger 0.24-0.25): hledger 0.24-0.25):
alias /REGEX/ = REPLACEMENT alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'. or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE- inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref- MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Note, cur- 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: (And if you use Ledger on your hledger file, they will be ignored.) Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Multiple aliases Multiple aliases
You can define as many aliases as you like using directives or com- You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol- aliases are non-recursive by default). Aliases are applied in the fol-
lowing order: 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) precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line 2. alias options, in the order they appear on the command line
end aliases 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 directive:
end aliases end aliases
account directive account directive
The account directive predefines account names, as in Ledger and Bean- The account directive predefines account names, as in Ledger and Bean-
count. This may be useful for your own documentation; hledger doesn't count. This may be useful for your own documentation; hledger doesn't
make use of it yet. make use of it yet.
; account ACCT ; account ACCT
@ -612,8 +611,8 @@ FILE FORMAT
; etc. ; etc.
apply account directive apply account directive
You can specify a parent account which will be prepended to all You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and accounts within a section of the journal. Use the apply account and
end apply account directives like so: end apply account directives like so:
apply account home apply account home
@ -630,7 +629,7 @@ FILE FORMAT
home:food $10 home:food $10
home:cash $-10 home:cash $-10
If end apply account is omitted, the effect lasts to the end of the If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg: file. Included files are also affected, eg:
apply account business apply account business
@ -639,16 +638,16 @@ FILE FORMAT
apply account personal apply account personal
include personal.journal include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup- Prior to hledger 1.0, legacy account and end spellings were also sup-
ported. ported.
Multi-line comments 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. containing just end comment ends it. See comments.
commodity directive commodity directive
The commodity directive predefines commodities (currently this is just The commodity directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format). in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this: It may be written on a single line, like this:
@ -660,8 +659,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places: places:
; commodity SYMBOL ; commodity SYMBOL
@ -674,10 +673,10 @@ FILE FORMAT
format INR 9,99,99,999.00 format INR 9,99,99,999.00
Default commodity Default commodity
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive. amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars # commodity-less amounts should be treated as dollars
@ -689,8 +688,8 @@ FILE FORMAT
b b
Default year Default year
You can set a default year to be used for subsequent dates which don't You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -710,24 +709,24 @@ FILE FORMAT
assets assets
Including other files 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 directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported. 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. include journal, timeclock or timedot files, but not CSV files.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. 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: files:
@ -744,7 +743,7 @@ EDITOR SUPPORT
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -758,7 +757,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)

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 ### 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

126
hledger/doc/hledger.1
View File

@ -840,6 +840,71 @@ $\ hledger\ balance\ \-\-pivot\ member\ acct:.
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\f[] \f[]
.fi .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 .SS Regular expressions
.PP .PP
hledger uses regular expressions in a number of places: 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 #\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
\f[] \f[]
.fi .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 .SS Custom balance output
.PP .PP
In simple (non\-multi\-column) balance reports, you can customise the 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:: * Period expressions::
* Depth limiting:: * Depth limiting::
* Pivoting:: * Pivoting::
* Cost::
* Market value::
* Regular expressions:: * 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. 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 2.11 Pivoting
============= =============
@ -568,9 +570,67 @@ $ hledger balance --pivot member acct:.
-2 EUR -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: hledger uses regular expressions in a number of places:
@ -999,7 +1059,6 @@ $ hledger balance -p 2008/6 expenses --no-total
* Flat mode:: * Flat mode::
* Depth limited balance reports:: * Depth limited balance reports::
* Multicolumn balance reports:: * Multicolumn balance reports::
* Market value::
* Custom balance output:: * Custom balance output::
* Output destination:: * Output destination::
* CSV output:: * CSV output::
@ -1038,7 +1097,7 @@ $ hledger balance -N --depth 1
$1 liabilities $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 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 # 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 4.4.4 Custom balance output
------------------
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
--------------------------- ---------------------------
In simple (non-multi-column) balance reports, you can customise the 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 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 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 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. The balance, print and register commands can write their output as CSV.
@ -2094,121 +2104,123 @@ Node: EXAMPLES1886
Ref: #examples1988 Ref: #examples1988
Node: OPTIONS3634 Node: OPTIONS3634
Ref: #options3738 Ref: #options3738
Node: General options3993 Node: General options4019
Ref: #general-options4120 Ref: #general-options4146
Node: Command options6643 Node: Command options6669
Ref: #command-options6796 Ref: #command-options6822
Node: Command arguments7194 Node: Command arguments7220
Ref: #command-arguments7354 Ref: #command-arguments7380
Node: Special characters7475 Node: Special characters7501
Ref: #special-characters7633 Ref: #special-characters7659
Node: Input files8801 Node: Input files8827
Ref: #input-files8939 Ref: #input-files8965
Node: Smart dates10902 Node: Smart dates10928
Ref: #smart-dates11045 Ref: #smart-dates11071
Node: Report start & end date12024 Node: Report start & end date12050
Ref: #report-start-end-date12196 Ref: #report-start-end-date12222
Node: Report intervals13262 Node: Report intervals13288
Ref: #report-intervals13427 Ref: #report-intervals13453
Node: Period expressions13828 Node: Period expressions13854
Ref: #period-expressions13988 Ref: #period-expressions14014
Node: Depth limiting16328 Node: Depth limiting16354
Ref: #depth-limiting16474 Ref: #depth-limiting16500
Node: Pivoting16675 Node: Pivoting16701
Ref: #pivoting16810 Ref: #pivoting16821
Node: Regular expressions18581 Node: Cost18592
Ref: #regular-expressions18715 Ref: #cost18702
Node: QUERIES20076 Node: Market value18820
Ref: #queries20180 Ref: #market-value18957
Node: COMMANDS23826 Node: Regular expressions20257
Ref: #commands23940 Ref: #regular-expressions20395
Node: accounts24613 Node: QUERIES21756
Ref: #accounts24713 Ref: #queries21860
Node: activity25695 Node: COMMANDS25506
Ref: #activity25807 Ref: #commands25620
Node: add26166 Node: accounts26293
Ref: #add26267 Ref: #accounts26393
Node: balance28925 Node: activity27375
Ref: #balance29038 Ref: #activity27487
Node: Flat mode31980 Node: add27846
Ref: #flat-mode32107 Ref: #add27947
Node: Depth limited balance reports32527 Node: balance30605
Ref: #depth-limited-balance-reports32730 Ref: #balance30718
Node: Multicolumn balance reports33150 Node: Flat mode33643
Ref: #multicolumn-balance-reports33352 Ref: #flat-mode33770
Node: Market value38000 Node: Depth limited balance reports34190
Ref: #market-value38164 Ref: #depth-limited-balance-reports34393
Node: Custom balance output39464 Node: Multicolumn balance reports34813
Ref: #custom-balance-output39637 Ref: #multicolumn-balance-reports35024
Node: Output destination41730 Node: Custom balance output39672
Ref: #output-destination41895 Ref: #custom-balance-output39860
Node: CSV output42165 Node: Output destination41953
Ref: #csv-output42284 Ref: #output-destination42118
Node: balancesheet42681 Node: CSV output42388
Ref: #balancesheet42809 Ref: #csv-output42507
Node: cashflow44716 Node: balancesheet42904
Ref: #cashflow44833 Ref: #balancesheet43032
Node: help46701 Node: cashflow44939
Ref: #help46813 Ref: #cashflow45056
Node: incomestatement47651 Node: help46924
Ref: #incomestatement47781 Ref: #help47036
Node: info49673 Node: incomestatement47874
Ref: #info49780 Ref: #incomestatement48004
Node: man50144 Node: info49896
Ref: #man50241 Ref: #info50003
Node: print50646 Node: man50367
Ref: #print50751 Ref: #man50464
Node: register54507 Node: print50869
Ref: #register54620 Ref: #print50974
Node: Custom register output59116 Node: register54730
Ref: #custom-register-output59247 Ref: #register54843
Node: stats60544 Node: Custom register output59339
Ref: #stats60650 Ref: #custom-register-output59470
Node: test61531 Node: stats60767
Ref: #test61618 Ref: #stats60873
Node: ADD-ON COMMANDS61986 Node: test61754
Ref: #add-on-commands62098 Ref: #test61841
Node: Official add-ons63385 Node: ADD-ON COMMANDS62209
Ref: #official-add-ons63527 Ref: #add-on-commands62321
Node: api63614 Node: Official add-ons63608
Ref: #api63705 Ref: #official-add-ons63750
Node: ui63757 Node: api63837
Ref: #ui63858 Ref: #api63928
Node: web63916 Node: ui63980
Ref: #web64007 Ref: #ui64081
Node: Third party add-ons64053 Node: web64139
Ref: #third-party-add-ons64230 Ref: #web64230
Node: diff64365 Node: Third party add-ons64276
Ref: #diff64464 Ref: #third-party-add-ons64453
Node: iadd64563 Node: diff64588
Ref: #iadd64679 Ref: #diff64687
Node: interest64762 Node: iadd64786
Ref: #interest64885 Ref: #iadd64902
Node: irr64980 Node: interest64985
Ref: #irr65080 Ref: #interest65108
Node: Experimental add-ons65158 Node: irr65203
Ref: #experimental-add-ons65312 Ref: #irr65303
Node: autosync65705 Node: Experimental add-ons65381
Ref: #autosync65819 Ref: #experimental-add-ons65535
Node: budget66058 Node: autosync65928
Ref: #budget66182 Ref: #autosync66042
Node: chart66248 Node: budget66281
Ref: #chart66367 Ref: #budget66405
Node: check66438 Node: chart66471
Ref: #check66562 Ref: #chart66590
Node: check-dates66629 Node: check66661
Ref: #check-dates66771 Ref: #check66785
Node: check-dupes66844 Node: check-dates66852
Ref: #check-dupes66987 Ref: #check-dates66994
Node: equity67064 Node: check-dupes67067
Ref: #equity67192 Ref: #check-dupes67210
Node: prices67311 Node: equity67287
Ref: #prices67440 Ref: #equity67415
Node: print-unique67495 Node: prices67534
Ref: #print-unique67644 Ref: #prices67663
Node: register-match67737 Node: print-unique67718
Ref: #register-match67893 Ref: #print-unique67867
Node: rewrite67991 Node: register-match67960
Ref: #rewrite68112 Ref: #register-match68116
Node: rewrite68214
Ref: #rewrite68335
 
End Tag Table End Tag Table

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

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

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

@ -315,6 +315,58 @@ $ hledger balance --pivot member acct:.
-2 EUR -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 ## Regular expressions
hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places: hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places: