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

doc: document new --pivot

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2017-01-16 15:53:32 -08:00
parent e51bb6944a
commit 91dbeedee4
17 changed files with 803 additions and 590 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/lib.m4
View File

@ -147,12 +147,8 @@ m4_define({{_reportingoptions_}}, {{
: convert amounts to their cost at transaction time
(using the [transaction price](journal.html#transaction-prices), if any)
`--pivot TAG`
: will transform the journal before any other processing by replacing
the account name of every posting having the tag TAG with content VALUE
by the account name "TAG:VALUE". The TAG will only match if it is a full-length match.
The pivot will only happen if the TAG is on a posting, not if it is on the transaction.
If the tag value is a multi:level:account:name the new account name will be "TAG:multi:level:account:name".
`--pivot TAGNAME`
: organize reports by some tag's value instead of by account
`--anon`
: show anonymized accounts and payees

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

@ -617,7 +617,11 @@ A \f[I]tag\f[] is a word followed by a full colon inside a transaction
or posting comment.
You can write multiple tags, comma separated.
Eg: \f[C];\ a\ comment\ containing\ sometag:,\ anothertag:\f[].
You can search for tags with the \f[C]tag:\f[] query.
.PD 0
.P
.PD
You can search for tags with the \f[C]tag:\f[] query, or pivot on them
with \f[C]\-\-pivot\ TAG\f[].
.PP
A tag can also have a value, which is any text between the colon and the
next comma or newline, excluding leading/trailing whitespace.
@ -639,6 +643,24 @@ posting\-tag):
.PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are simple strings.
.SS Implicit tags
.PP
Some predefined "implicit" tags are also provided:
.IP \[bu] 2
\f[C]code\f[] \- the transaction\[aq]s code field
.IP \[bu] 2
\f[C]description\f[] \- the transaction\[aq]s description
.IP \[bu] 2
\f[C]payee\f[] \- the part of description before \f[C]|\f[], or all of
it
.IP \[bu] 2
\f[C]note\f[] \- the part of description after \f[C]|\f[], or all of it
.PP
\f[C]payee\f[] and \f[C]note\f[] support descriptions written in a
special \f[C]PAYEE\ |\ NOTE\f[] format, accessing the parts before and
after the pipe character respectively.
For descriptions not containing a pipe character they are the same as
\f[C]description\f[].
.SS Directives
.SS Account aliases
.PP

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

@ -640,8 +640,9 @@ File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments,
A _tag_ is a word followed by a full colon inside a transaction or
posting comment. You can write multiple tags, comma separated. Eg: `; a
comment containing sometag:, anothertag:'. You can search for tags with
the `tag:' query.
comment containing sometag:, anothertag:'.
You can search for tags with the `tag:' query, or pivot on them with
`--pivot TAG'.
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace. (So
@ -660,6 +661,31 @@ and the posting has four (A, TAG2, third-tag, posting-tag):
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
* Menu:
* Implicit tags::

File: hledger_journal.5.info, Node: Implicit tags, Up: Tags
1.10.1 Implicit tags
--------------------
Some predefined "implicit" tags are also provided:
* `code' - the transaction's code field
* `description' - the transaction's description
* `payee' - the part of description before `|', or all of it
* `note' - the part of description after `|', or all of it
`payee' and `note' support descriptions written in a special `PAYEE
| NOTE' format, accessing the parts before and after the pipe character
respectively. For descriptions not containing a pipe character they are
the same as `description'.

File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
@ -1025,33 +1051,35 @@ Node: Comments21085
Ref: #comments21207
Node: Tags22319
Ref: #tags22439
Node: Directives23362
Ref: #directives23477
Node: Account aliases23670
Ref: #account-aliases23816
Node: Basic aliases24418
Ref: #basic-aliases24563
Node: Regex aliases25251
Ref: #regex-aliases25421
Node: Multiple aliases26191
Ref: #multiple-aliases26365
Node: end aliases26861
Ref: #end-aliases27003
Node: account directive27105
Ref: #account-directive27287
Node: apply account directive27583
Ref: #apply-account-directive27781
Node: Multi-line comments28441
Ref: #multi-line-comments28633
Node: commodity directive28760
Ref: #commodity-directive28946
Node: Default commodity29819
Ref: #default-commodity29994
Node: Default year30530
Ref: #default-year30697
Node: Including other files31120
Ref: #including-other-files31279
Node: EDITOR SUPPORT31675
Ref: #editor-support31795
Node: Implicit tags23427
Ref: #implicit-tags23535
Node: Directives24054
Ref: #directives24169
Node: Account aliases24362
Ref: #account-aliases24508
Node: Basic aliases25110
Ref: #basic-aliases25255
Node: Regex aliases25943
Ref: #regex-aliases26113
Node: Multiple aliases26883
Ref: #multiple-aliases27057
Node: end aliases27553
Ref: #end-aliases27695
Node: account directive27797
Ref: #account-directive27979
Node: apply account directive28275
Ref: #apply-account-directive28473
Node: Multi-line comments29133
Ref: #multi-line-comments29325
Node: commodity directive29452
Ref: #commodity-directive29638
Node: Default commodity30511
Ref: #default-commodity30686
Node: Default year31222
Ref: #default-year31389
Node: Including other files31812
Ref: #including-other-files31971
Node: EDITOR SUPPORT32367
Ref: #editor-support32487

End Tag Table

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

@ -504,8 +504,9 @@ end comment
A *tag* is a word followed by a full colon inside a transaction or
posting [comment](#comments). You can write multiple tags, comma
separated. Eg: `; a comment containing sometag:, anothertag:`. You can search for tags
with the [`tag:` query](manual#queries).
separated. Eg: `; a comment containing sometag:, anothertag:`.
You can search for tags with the [`tag:` query](/hledger.html#queries),
or pivot on them with [`--pivot TAG`](/hledger.html#pivoting).
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace.
@ -526,6 +527,19 @@ Tags are like Ledger's
[metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are simple strings.
### Implicit tags
Some predefined "implicit" tags are also provided:
- `code` - the transaction's code field
- `description` - the transaction's description
- `payee` - the part of description before `|`, or all of it
- `note` - the part of description after `|`, or all of it
`payee` and `note` support descriptions written in a special `PAYEE | NOTE` format,
accessing the parts before and after the pipe character respectively.
For descriptions not containing a pipe character they are the same as `description`.
## Directives
### Account aliases

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

@ -470,8 +470,9 @@ FILE FORMAT
Tags
A tag is a word followed by a full colon inside a transaction or post-
ing comment. You can write multiple tags, comma separated. Eg:
; a comment containing sometag:, anothertag:. You can search for tags
with the tag: query.
; a comment containing sometag:, anothertag:.
You can search for tags with the tag: query, or pivot on them with
--pivot TAG.
A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace. (So
@ -489,9 +490,25 @@ FILE FORMAT
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Implicit tags
Some predefined "implicit" tags are also provided:
o code - the transaction's code field
o description - the transaction's description
o payee - the part of description before |, 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
format, accessing the parts before and after the pipe character respec-
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:
@ -508,8 +525,8 @@ FILE FORMAT
See also How to use account aliases.
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
@ -517,53 +534,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
@ -578,8 +595,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
@ -596,7 +613,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
@ -605,16 +622,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:
@ -626,8 +643,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
@ -640,10 +657,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
@ -655,8 +672,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
@ -676,24 +693,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:
@ -710,7 +727,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)
@ -724,7 +741,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)

11
hledger-ui/doc/hledger-ui.1
View File

@ -208,15 +208,8 @@ price, if any)
.RS
.RE
.TP
.B \f[C]\-\-pivot\ TAG\f[]
will transform the journal before any other processing by replacing the
account name of every posting having the tag TAG with content VALUE by
the account name "TAG:VALUE".
The TAG will only match if it is a full\-length match.
The pivot will only happen if the TAG is on a posting, not if it is on
the transaction.
If the tag value is a multi:level:account:name the new account name will
be "TAG:multi:level:account:name".
.B \f[C]\-\-pivot\ TAGNAME\f[]
organize reports by some tag\[aq]s value instead of by account
.RS
.RE
.TP

34
hledger-ui/doc/hledger-ui.1.info
View File

@ -142,14 +142,8 @@ the data.
convert amounts to their cost at transaction time (using the
transaction price, if any)
`--pivot TAG'
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG will
only match if it is a full-length match. The pivot will only
happen if the TAG is on a posting, not if it is on the
transaction. If the tag value is a multi:level:account:name the
new account name will be "TAG:multi:level:account:name".
`--pivot TAGNAME'
organize reports by some tag's value instead of by account
`--anon'
show anonymized accounts and payees
@ -361,17 +355,17 @@ Tag Table:
Node: Top88
Node: OPTIONS823
Ref: #options922
Node: KEYS4001
Ref: #keys4098
Node: SCREENS6668
Ref: #screens6755
Node: Accounts screen6845
Ref: #accounts-screen6975
Node: Register screen9013
Ref: #register-screen9170
Node: Transaction screen11058
Ref: #transaction-screen11218
Node: Error screen12085
Ref: #error-screen12209
Node: KEYS3611
Ref: #keys3708
Node: SCREENS6278
Ref: #screens6365
Node: Accounts screen6455
Ref: #accounts-screen6585
Node: Register screen8623
Ref: #register-screen8780
Node: Transaction screen10668
Ref: #transaction-screen10828
Node: Error screen11695
Ref: #error-screen11819

End Tag Table

10
hledger-ui/doc/hledger-ui.1.txt
View File

@ -136,14 +136,8 @@ OPTIONS
convert amounts to their cost at transaction time (using the
transaction price, if any)
--pivot TAG
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG
will only match if it is a full-length match. The pivot will
only happen if the TAG is on a posting, not if it is on the
transaction. If the tag value is a multi:level:account:name the
new account name will be "TAG:multi:level:account:name".
--pivot TAGNAME
organize reports by some tag's value instead of by account
--anon show anonymized accounts and payees

11
hledger-web/doc/hledger-web.1
View File

@ -270,15 +270,8 @@ price, if any)
.RS
.RE
.TP
.B \f[C]\-\-pivot\ TAG\f[]
will transform the journal before any other processing by replacing the
account name of every posting having the tag TAG with content VALUE by
the account name "TAG:VALUE".
The TAG will only match if it is a full\-length match.
The pivot will only happen if the TAG is on a posting, not if it is on
the transaction.
If the tag value is a multi:level:account:name the new account name will
be "TAG:multi:level:account:name".
.B \f[C]\-\-pivot\ TAGNAME\f[]
organize reports by some tag\[aq]s value instead of by account
.RS
.RE
.TP

10
hledger-web/doc/hledger-web.1.info
View File

@ -190,14 +190,8 @@ before options as shown above.
convert amounts to their cost at transaction time (using the
transaction price, if any)
`--pivot TAG'
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG will
only match if it is a full-length match. The pivot will only
happen if the TAG is on a posting, not if it is on the
transaction. If the tag value is a multi:level:account:name the
new account name will be "TAG:multi:level:account:name".
`--pivot TAGNAME'
organize reports by some tag's value instead of by account
`--anon'
show anonymized accounts and payees

10
hledger-web/doc/hledger-web.1.txt
View File

@ -186,14 +186,8 @@ OPTIONS
convert amounts to their cost at transaction time (using the
transaction price, if any)
--pivot TAG
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG
will only match if it is a full-length match. The pivot will
only happen if the TAG is on a posting, not if it is on the
transaction. If the tag value is a multi:level:account:name the
new account name will be "TAG:multi:level:account:name".
--pivot TAGNAME
organize reports by some tag's value instead of by account
--anon show anonymized accounts and payees

2
hledger/Hledger/Cli/CliOptions.hs
View File

@ -120,7 +120,7 @@ inputflags = [
,flagReq ["rules-file"] (\s opts -> Right $ setopt "rules-file" s opts) "RFILE" "CSV conversion rules file (default: FILE.rules)"
,flagReq ["alias"] (\s opts -> Right $ setopt "alias" s opts) "OLD=NEW" "display accounts named OLD as NEW"
,flagNone ["ignore-assertions","I"] (setboolopt "ignore-assertions") "ignore any balance assertions in the journal"
,flagReq ["pivot"] (\s opts -> Right $ setopt "pivot" s opts) "TAG" "Replace the accounts of postings with TAG by TAG:<value>"
,flagReq ["pivot"] (\s opts -> Right $ setopt "pivot" s opts) "TAGNAME" "organize reports by some tag's value, not by account"
]
-- | Common report-related flags: --period, --cost, etc.

17
hledger/doc/examples.m4.md
View File

@ -68,20 +68,3 @@ $ hledger reg 'assets:some bank:checking' # show postings to/from this checking
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
```
With the journal
```journal
2016/02/16 Member Fee Payment John Doe
assets:bank account 2 EUR
income:member fees -2 EUR
; member: John Doe
```
the --pivot comand will output the following:
```shells
$ hledger bal --pivot member
2 EUR assets:bank account
-2 EUR member:John Doe
```

123
hledger/doc/hledger.1
View File

@ -147,27 +147,6 @@ $\ hledger\ print\ desc:shop\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transacti
$\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
\f[]
.fi
.PP
With the journal
.IP
.nf
\f[C]
2016/02/16\ Member\ Fee\ Payment\ John\ Doe
\ \ \ \ assets:bank\ account\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
\ \ \ \ income:member\ fees\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\ \ \ \ \ \ ;\ member:\ John\ Doe
\f[]
.fi
.PP
the \-\-pivot comand will output the following:
.IP
.nf
\f[C]
$\ hledger\ bal\ \-\-pivot\ member
\ \ \ \ 2\ EUR\ \ assets:bank\ account
\ \ \ \-2\ EUR\ \ member:John\ Doe
\f[]
.fi
.SH OPTIONS
.PP
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just
@ -378,15 +357,8 @@ price, if any)
.RS
.RE
.TP
.B \f[C]\-\-pivot\ TAG\f[]
will transform the journal before any other processing by replacing the
account name of every posting having the tag TAG with content VALUE by
the account name "TAG:VALUE".
The TAG will only match if it is a full\-length match.
The pivot will only happen if the TAG is on a posting, not if it is on
the transaction.
If the tag value is a multi:level:account:name the new account name will
be "TAG:multi:level:account:name".
.B \f[C]\-\-pivot\ TAGNAME\f[]
organize reports by some tag\[aq]s value instead of by account
.RS
.RE
.TP
@ -498,12 +470,6 @@ balance assertions will not see any account balances from previous files
.PP
If you need those, either use the include directive, or concatenate the
files, eg: \f[C]cat\ a.journal\ b.journal\ |\ hledger\ \-f\-\ CMD\f[].
.SS Depth limiting
.PP
With the \f[C]\-\-depth\ N\f[] option, commands like account, balance
and register will show only the uppermost accounts in the account tree,
down to level N.
Use this when you want a summary with less detail.
.SS Smart dates
.PP
hledger\[aq]s user interfaces accept a flexible "smart date" syntax
@ -789,6 +755,91 @@ Group postings from start of wednesday to end of next tuesday (N is
start date and exclusive end date):
.PP
\f[C]hledger\ register\ checking\ \-p\ "every\ 3rd\ day\ of\ week"\f[]
.SS Depth limiting
.PP
With the \f[C]\-\-depth\ N\f[] option, commands like account, balance
and register will show only the uppermost accounts in the account tree,
down to level N.
Use this when you want a summary with less detail.
.SS Pivoting
.PP
Normally hledger sums amounts, and organizes them in a hierarchy, based
on account name.
The \f[C]\-\-pivot\ TAGNAME\f[] option causes it to sum and organize
hierarchy based on some other field instead.
.PP
TAGNAME is the full, case\-insensitive name of a tag you have defined,
or one of the built\-in implicit tags (like \f[C]code\f[] or
\f[C]payee\f[]).
As with account names, when tag values have
\f[C]multiple:colon\-separated:parts\f[] hledger will build hierarchy,
displayed in tree\-mode reports, summarisable with a depth limit, and so
on.
.PP
\f[C]\-\-pivot\f[] affects all reports, and is one of those options you
can write before the command name if you wish.
You can think of hledger transforming the journal before any other
processing, replacing every posting\[aq]s account name with the value of
the specified tag on that posting, inheriting it from the transaction or
using a blank value if it\[aq]s not present.
.PP
An example:
.IP
.nf
\f[C]
2016/02/16\ Member\ Fee\ Payment
\ \ \ \ assets:bank\ account\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
\ \ \ \ income:member\ fees\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ ;\ member:\ John\ Doe
\f[]
.fi
.PP
Normal balance report showing account names:
.IP
.nf
\f[C]
$\ hledger\ balance
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR\ \ assets:bank\ account
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ income:member\ fees
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
\f[]
.fi
.PP
Pivoted balance report, using member: tag values instead:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-\-pivot\ member
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
\f[]
.fi
.PP
One way to show only amounts with a member: value (using a query,
described below):
.IP
.nf
\f[C]
$\ hledger\ balance\ \-\-pivot\ member\ tag:member=.
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\f[]
.fi
.PP
Another way (the acct: query matches against the pivoted "account
name"):
.IP
.nf
\f[C]
$\ hledger\ balance\ \-\-pivot\ member\ acct:.
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR
\f[]
.fi
.SS Regular expressions
.PP
hledger uses regular expressions in a number of places:

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

@ -117,21 +117,6 @@ $ hledger reg 'assets:some bank:checking' # show postings to/from this checking
$ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart
With the journal
2016/02/16 Member Fee Payment John Doe
assets:bank account 2 EUR
income:member fees -2 EUR
; member: John Doe
the -pivot comand will output the following:
$ hledger bal --pivot member
2 EUR assets:bank account
-2 EUR member:John Doe

File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
@ -200,11 +185,12 @@ cur:\\\\$'.
* General options::
* Reporting options::
* Input files::
* Depth limiting::
* Smart dates::
* Report start & end date::
* Report intervals::
* Period expressions::
* Depth limiting::
* Pivoting::
* Regular expressions::

@ -304,14 +290,8 @@ Common reporting options, must be written after COMMAND.
convert amounts to their cost at transaction time (using the
transaction price, if any)
`--pivot TAG'
will transform the journal before any other processing by
replacing the account name of every posting having the tag TAG
with content VALUE by the account name "TAG:VALUE". The TAG will
only match if it is a full-length match. The pivot will only
happen if the TAG is on a posting, not if it is on the
transaction. If the tag value is a multi:level:account:name the
new account name will be "TAG:multi:level:account:name".
`--pivot TAGNAME'
organize reports by some tag's value instead of by account
`--anon'
show anonymized accounts and payees
@ -320,7 +300,7 @@ Common reporting options, must be written after COMMAND.
last one takes precedence. Eg -p jan -p feb is equivalent to -p feb.

File: hledger.1.info, Node: Input files, Next: Depth limiting, Prev: Reporting options, Up: OPTIONS
File: hledger.1.info, Node: Input files, Next: Smart dates, Prev: Reporting options, Up: OPTIONS
2.3 Input files
===============
@ -380,19 +360,9 @@ as one big journal. There are some limitations with this:
the files, eg: `cat a.journal b.journal | hledger -f- CMD'.

File: hledger.1.info, Node: Depth limiting, Next: Smart dates, Prev: Input files, Up: OPTIONS
File: hledger.1.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS
2.4 Depth limiting
==================
With the `--depth N' option, commands like account, balance and
register 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: Smart dates, Next: Report start & end date, Prev: Depth limiting, Up: OPTIONS
2.5 Smart dates
2.4 Smart dates
===============
hledger's user interfaces accept a flexible "smart date" syntax (unlike
@ -415,7 +385,7 @@ omitted (defaulting to 1).

File: hledger.1.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS
2.6 Report start & end date
2.5 Report start & end date
===========================
Most hledger reports show the full span of time represented by the
@ -444,7 +414,7 @@ you need to write the date _after_ the last day you want to include.

File: hledger.1.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS
2.7 Report intervals
2.6 Report intervals
====================
A report interval can be specified so that commands like register,
@ -455,9 +425,9 @@ complex intervals may be specified with a period expression. Report
intervals can not be specified with a query, currently.

File: hledger.1.info, Node: Period expressions, Next: Regular expressions, Prev: Report intervals, Up: OPTIONS
File: hledger.1.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS
2.8 Period expressions
2.7 Period expressions
======================
The `-p/--period' option accepts period expressions, a shorthand way of
@ -530,10 +500,87 @@ start date and exclusive end date):
`hledger register checking -p "every 3rd day of week"'

File: hledger.1.info, Node: Regular expressions, Prev: Period expressions, Up: OPTIONS
File: hledger.1.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS
2.9 Regular expressions
=======================
2.8 Depth limiting
==================
With the `--depth N' option, commands like account, balance and
register 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
2.9 Pivoting
============
Normally hledger sums amounts, and organizes them in a hierarchy, based
on account name. The `--pivot TAGNAME' option causes it to sum and
organize hierarchy based on some other field instead.
TAGNAME is the full, case-insensitive name of a tag you have
defined, or one of the built-in implicit tags (like `code' or `payee').
As with account names, when tag values have
`multiple:colon-separated:parts' hledger will build hierarchy,
displayed in tree-mode reports, summarisable with a depth limit, and so
on.
`--pivot' affects all reports, and is one of those options you can
write before the command name if you wish. You can think of hledger
transforming the journal before any other processing, replacing every
posting's account name with the value of the specified tag on that
posting, inheriting it from the transaction or using a blank value if
it's not present.
An example:
2016/02/16 Member Fee Payment
assets:bank account 2 EUR
income:member fees -2 EUR ; member: John Doe
Normal balance report showing account names:
$ hledger balance
2 EUR assets:bank account
-2 EUR income:member fees
--------------------
0
Pivoted balance report, using member: tag values instead:
$ hledger balance --pivot member
2 EUR
-2 EUR John Doe
--------------------
0
One way to show only amounts with a member: value (using a query,
described below):
$ hledger balance --pivot member tag:member=.
-2 EUR John Doe
--------------------
-2 EUR
Another way (the acct: query matches against the pivoted "account
name"):
$ hledger balance --pivot member acct:.
-2 EUR John Doe
--------------------
-2 EUR

File: hledger.1.info, Node: Regular expressions, Prev: Pivoting, Up: OPTIONS
2.10 Regular expressions
========================
hledger uses regular expressions in a number of places:
@ -2282,101 +2329,103 @@ Tag Table:
Node: Top82
Node: EXAMPLES1873
Ref: #examples1975
Node: OPTIONS3979
Ref: #options4083
Node: General options6711
Ref: #general-options6840
Node: Reporting options7611
Ref: #reporting-options7764
Node: Input files9587
Ref: #input-files9727
Node: Depth limiting11768
Ref: #depth-limiting11908
Node: Smart dates12109
Ref: #smart-dates12255
Node: Report start & end date13252
Ref: #report-start-end-date13424
Node: Report intervals14500
Ref: #report-intervals14665
Node: Period expressions15064
Ref: #period-expressions15229
Node: Regular expressions17564
Ref: #regular-expressions17706
Node: QUERIES19189
Ref: #queries19293
Node: COMMANDS22932
Ref: #commands23046
Node: accounts23719
Ref: #accounts23819
Node: activity24801
Ref: #activity24913
Node: add25272
Ref: #add25373
Node: balance28036
Ref: #balance28149
Node: Flat mode31162
Ref: #flat-mode31289
Node: Depth limited balance reports31708
Ref: #depth-limited-balance-reports31911
Node: Multicolumn balance reports32332
Ref: #multicolumn-balance-reports32534
Node: Market value37183
Ref: #market-value37347
Node: Custom balance output38648
Ref: #custom-balance-output38821
Node: Output destination40925
Ref: #output-destination41090
Node: CSV output41360
Ref: #csv-output41479
Node: balancesheet41876
Ref: #balancesheet42004
Node: cashflow42656
Ref: #cashflow42773
Node: help43463
Ref: #help43575
Node: incomestatement44412
Ref: #incomestatement44542
Node: info45269
Ref: #info45376
Node: man45738
Ref: #man45835
Node: print46238
Ref: #print46343
Node: register50092
Ref: #register50205
Node: Custom register output54697
Ref: #custom-register-output54828
Node: stats56125
Ref: #stats56231
Node: test57111
Ref: #test57198
Node: ADD-ON COMMANDS57565
Ref: #add-on-commands57701
Node: api58989
Ref: #api59081
Node: autosync59115
Ref: #autosync59230
Node: diff61545
Ref: #diff61655
Node: equity62319
Ref: #equity62433
Node: interest63761
Ref: #interest63878
Node: irr66962
Ref: #irr67075
Node: print-unique69450
Ref: #print-unique69580
Node: rewrite69838
Ref: #rewrite69957
Node: ui70486
Ref: #ui70586
Node: web70627
Ref: #web70715
Node: TROUBLESHOOTING70748
Ref: #troubleshooting70867
Node: Run-time problems70921
Ref: #run-time-problems71064
Node: Known limitations73008
Ref: #known-limitations73151
Node: OPTIONS3627
Ref: #options3731
Node: General options6372
Ref: #general-options6501
Node: Reporting options7272
Ref: #reporting-options7425
Node: Input files8858
Ref: #input-files8995
Node: Smart dates11036
Ref: #smart-dates11179
Node: Report start & end date12176
Ref: #report-start-end-date12348
Node: Report intervals13424
Ref: #report-intervals13589
Node: Period expressions13988
Ref: #period-expressions14148
Node: Depth limiting16483
Ref: #depth-limiting16627
Node: Pivoting16828
Ref: #pivoting16961
Node: Regular expressions18792
Ref: #regular-expressions18926
Node: QUERIES20409
Ref: #queries20513
Node: COMMANDS24152
Ref: #commands24266
Node: accounts24939
Ref: #accounts25039
Node: activity26021
Ref: #activity26133
Node: add26492
Ref: #add26593
Node: balance29256
Ref: #balance29369
Node: Flat mode32382
Ref: #flat-mode32509
Node: Depth limited balance reports32928
Ref: #depth-limited-balance-reports33131
Node: Multicolumn balance reports33552
Ref: #multicolumn-balance-reports33754
Node: Market value38403
Ref: #market-value38567
Node: Custom balance output39868
Ref: #custom-balance-output40041
Node: Output destination42145
Ref: #output-destination42310
Node: CSV output42580
Ref: #csv-output42699
Node: balancesheet43096
Ref: #balancesheet43224
Node: cashflow43876
Ref: #cashflow43993
Node: help44683
Ref: #help44795
Node: incomestatement45632
Ref: #incomestatement45762
Node: info46489
Ref: #info46596
Node: man46958
Ref: #man47055
Node: print47458
Ref: #print47563
Node: register51312
Ref: #register51425
Node: Custom register output55917
Ref: #custom-register-output56048
Node: stats57345
Ref: #stats57451
Node: test58331
Ref: #test58418
Node: ADD-ON COMMANDS58785
Ref: #add-on-commands58921
Node: api60209
Ref: #api60301
Node: autosync60335
Ref: #autosync60450
Node: diff62765
Ref: #diff62875
Node: equity63539
Ref: #equity63653
Node: interest64981
Ref: #interest65098
Node: irr68182
Ref: #irr68295
Node: print-unique70670
Ref: #print-unique70800
Node: rewrite71058
Ref: #rewrite71177
Node: ui71706
Ref: #ui71806
Node: web71847
Ref: #web71935
Node: TROUBLESHOOTING71968
Ref: #troubleshooting72087
Node: Run-time problems72141
Ref: #run-time-problems72284
Node: Known limitations74228
Ref: #known-limitations74371

End Tag Table

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

File diff suppressed because it is too large Load Diff

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

@ -121,12 +121,6 @@ There are some limitations with this:
If you need those, either use the [include directive](/journal.html#including-other-files),
or concatenate the files, eg: `cat a.journal b.journal | hledger -f- CMD`.
## Depth limiting
With the `--depth N` option, commands like [account](#account), [balance](#balance)
and [register](#register) will show only the uppermost accounts in the account
tree, down to level N. Use this when you want a summary with less detail.
## Smart dates
hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file).
@ -269,6 +263,65 @@ Group postings from start of wednesday to end of next tuesday (N is start date a
`hledger register checking -p "every 3rd day of week"`
## Depth limiting
With the `--depth N` option, commands like [account](#account), [balance](#balance)
and [register](#register) will show only the uppermost accounts in the account
tree, down to level N. Use this when you want a summary with less detail.
## Pivoting
Normally hledger sums amounts, and organizes them in a hierarchy, based on account name.
The `--pivot TAGNAME` option causes it to sum and organize hierarchy based on some other field instead.
TAGNAME is the full, case-insensitive name of a [tag](/journal.html#tags) you have defined,
or one of the built-in implicit tags (like `code` or `payee`).
As with account names, when tag values have `multiple:colon-separated:parts` hledger will build hierarchy,
displayed in tree-mode reports, summarisable with a depth limit, and so on.
`--pivot` affects all reports, and is one of those options you can write before the command name if you wish.
You can think of hledger transforming the journal before any other processing,
replacing every posting's account name with the value of the specified tag on that posting,
inheriting it from the transaction or using a blank value if it's not present.
An example:
```journal
2016/02/16 Member Fee Payment
assets:bank account 2 EUR
income:member fees -2 EUR ; member: John Doe
```
Normal balance report showing account names:
```shell
$ hledger balance
2 EUR assets:bank account
-2 EUR income:member fees
--------------------
0
```
Pivoted balance report, using member: tag values instead:
```shell
$ hledger balance --pivot member
2 EUR
-2 EUR John Doe
--------------------
0
```
One way to show only amounts with a member: value (using a [query](#queries), described below):
```shell
$ hledger balance --pivot member tag:member=.
-2 EUR John Doe
--------------------
-2 EUR
```
Another way (the acct: query matches against the pivoted "account name"):
```
$ hledger balance --pivot member acct:.
-2 EUR John Doe
--------------------
-2 EUR
```
## Regular expressions
hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places: