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 : convert amounts to their cost at transaction time
(using the [transaction price](journal.html#transaction-prices), if any) (using the [transaction price](journal.html#transaction-prices), if any)
`--pivot TAG` `--pivot TAGNAME`
: will transform the journal before any other processing by replacing : organize reports by some tag's value instead of by account
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".
`--anon` `--anon`
: show anonymized accounts and payees : 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. or posting comment.
You can write multiple tags, comma separated. You can write multiple tags, comma separated.
Eg: \f[C];\ a\ comment\ containing\ sometag:,\ anothertag:\f[]. 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 .PP
A tag can also have a value, which is any text between the colon and the A tag can also have a value, which is any text between the colon and the
next comma or newline, excluding leading/trailing whitespace. next comma or newline, excluding leading/trailing whitespace.
@ -639,6 +643,24 @@ posting\-tag):
.PP .PP
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
values are simple strings. 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 Directives
.SS Account aliases .SS Account aliases
.PP .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 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 posting comment. You can write multiple tags, comma separated. Eg: `; a
comment containing sometag:, anothertag:'. You can search for tags with comment containing sometag:, anothertag:'.
the `tag:' query. 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 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 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 Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings. 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 File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
@ -1025,33 +1051,35 @@ Node: Comments21085
Ref: #comments21207 Ref: #comments21207
Node: Tags22319 Node: Tags22319
Ref: #tags22439 Ref: #tags22439
Node: Directives23362 Node: Implicit tags23427
Ref: #directives23477 Ref: #implicit-tags23535
Node: Account aliases23670 Node: Directives24054
Ref: #account-aliases23816 Ref: #directives24169
Node: Basic aliases24418 Node: Account aliases24362
Ref: #basic-aliases24563 Ref: #account-aliases24508
Node: Regex aliases25251 Node: Basic aliases25110
Ref: #regex-aliases25421 Ref: #basic-aliases25255
Node: Multiple aliases26191 Node: Regex aliases25943
Ref: #multiple-aliases26365 Ref: #regex-aliases26113
Node: end aliases26861 Node: Multiple aliases26883
Ref: #end-aliases27003 Ref: #multiple-aliases27057
Node: account directive27105 Node: end aliases27553
Ref: #account-directive27287 Ref: #end-aliases27695
Node: apply account directive27583 Node: account directive27797
Ref: #apply-account-directive27781 Ref: #account-directive27979
Node: Multi-line comments28441 Node: apply account directive28275
Ref: #multi-line-comments28633 Ref: #apply-account-directive28473
Node: commodity directive28760 Node: Multi-line comments29133
Ref: #commodity-directive28946 Ref: #multi-line-comments29325
Node: Default commodity29819 Node: commodity directive29452
Ref: #default-commodity29994 Ref: #commodity-directive29638
Node: Default year30530 Node: Default commodity30511
Ref: #default-year30697 Ref: #default-commodity30686
Node: Including other files31120 Node: Default year31222
Ref: #including-other-files31279 Ref: #default-year31389
Node: EDITOR SUPPORT31675 Node: Including other files31812
Ref: #editor-support31795 Ref: #including-other-files31971
Node: EDITOR SUPPORT32367
Ref: #editor-support32487
 
End Tag Table 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 A *tag* is a word followed by a full colon inside a transaction or
posting [comment](#comments). You can write multiple tags, comma posting [comment](#comments). You can write multiple tags, comma
separated. Eg: `; a comment containing sometag:, anothertag:`. You can search for tags separated. Eg: `; a comment containing sometag:, anothertag:`.
with the [`tag:` query](manual#queries). 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 A tag can also have a value, which is any text between the colon and
the next comma or newline, excluding leading/trailing whitespace. 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) [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
feature, except hledger's tag values are simple strings. 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 ## Directives
### Account aliases ### Account aliases

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

@ -470,8 +470,9 @@ FILE FORMAT
Tags Tags
A tag is a word followed by a full colon inside a transaction or post- 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: ing comment. You can write multiple tags, comma separated. Eg:
; a comment containing sometag:, anothertag:. You can search for tags ; a comment containing sometag:, anothertag:.
with the tag: query. 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 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 the next comma or newline, excluding leading/trailing whitespace. (So
@ -489,6 +490,22 @@ FILE FORMAT
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
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 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

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

@ -208,15 +208,8 @@ price, if any)
.RS .RS
.RE .RE
.TP .TP
.B \f[C]\-\-pivot\ TAG\f[] .B \f[C]\-\-pivot\ TAGNAME\f[]
will transform the journal before any other processing by replacing the organize reports by some tag\[aq]s value instead of by account
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".
.RS .RS
.RE .RE
.TP .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 convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
`--pivot TAG' `--pivot TAGNAME'
will transform the journal before any other processing by organize reports by some tag's value instead of by account
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".
`--anon' `--anon'
show anonymized accounts and payees show anonymized accounts and payees
@ -361,17 +355,17 @@ Tag Table:
Node: Top88 Node: Top88
Node: OPTIONS823 Node: OPTIONS823
Ref: #options922 Ref: #options922
Node: KEYS4001 Node: KEYS3611
Ref: #keys4098 Ref: #keys3708
Node: SCREENS6668 Node: SCREENS6278
Ref: #screens6755 Ref: #screens6365
Node: Accounts screen6845 Node: Accounts screen6455
Ref: #accounts-screen6975 Ref: #accounts-screen6585
Node: Register screen9013 Node: Register screen8623
Ref: #register-screen9170 Ref: #register-screen8780
Node: Transaction screen11058 Node: Transaction screen10668
Ref: #transaction-screen11218 Ref: #transaction-screen10828
Node: Error screen12085 Node: Error screen11695
Ref: #error-screen12209 Ref: #error-screen11819
 
End Tag Table 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 convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
--pivot TAG --pivot TAGNAME
will transform the journal before any other processing by organize reports by some tag's value instead of by account
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".
--anon show anonymized accounts and payees --anon show anonymized accounts and payees

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

@ -270,15 +270,8 @@ price, if any)
.RS .RS
.RE .RE
.TP .TP
.B \f[C]\-\-pivot\ TAG\f[] .B \f[C]\-\-pivot\ TAGNAME\f[]
will transform the journal before any other processing by replacing the organize reports by some tag\[aq]s value instead of by account
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".
.RS .RS
.RE .RE
.TP .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 convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
`--pivot TAG' `--pivot TAGNAME'
will transform the journal before any other processing by organize reports by some tag's value instead of by account
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".
`--anon' `--anon'
show anonymized accounts and payees 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 convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
--pivot TAG --pivot TAGNAME
will transform the journal before any other processing by organize reports by some tag's value instead of by account
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".
--anon show anonymized accounts and payees --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 ["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" ,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" ,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. -- | 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 print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart $ 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 $\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart
\f[] \f[]
.fi .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 .SH OPTIONS
.PP .PP
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just To see general usage and the command list: \f[C]hledger\ \-h\f[] or just
@ -378,15 +357,8 @@ price, if any)
.RS .RS
.RE .RE
.TP .TP
.B \f[C]\-\-pivot\ TAG\f[] .B \f[C]\-\-pivot\ TAGNAME\f[]
will transform the journal before any other processing by replacing the organize reports by some tag\[aq]s value instead of by account
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".
.RS .RS
.RE .RE
.TP .TP
@ -498,12 +470,6 @@ balance assertions will not see any account balances from previous files
.PP .PP
If you need those, either use the include directive, or concatenate the 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[]. 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 .SS Smart dates
.PP .PP
hledger\[aq]s user interfaces accept a flexible "smart date" syntax 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): start date and exclusive end date):
.PP .PP
\f[C]hledger\ register\ checking\ \-p\ "every\ 3rd\ day\ of\ week"\f[] \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 .SS Regular expressions
.PP .PP
hledger uses regular expressions in a number of places: 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 print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart $ 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 File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
@ -200,11 +185,12 @@ cur:\\\\$'.
* General options:: * General options::
* Reporting options:: * Reporting options::
* Input files:: * Input files::
* Depth limiting::
* Smart dates:: * Smart dates::
* Report start & end date:: * Report start & end date::
* Report intervals:: * Report intervals::
* Period expressions:: * Period expressions::
* Depth limiting::
* Pivoting::
* Regular expressions:: * Regular expressions::
 
@ -304,14 +290,8 @@ Common reporting options, must be written after COMMAND.
convert amounts to their cost at transaction time (using the convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
`--pivot TAG' `--pivot TAGNAME'
will transform the journal before any other processing by organize reports by some tag's value instead of by account
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".
`--anon' `--anon'
show anonymized accounts and payees 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. 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 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'. 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 2.4 Smart dates
==================
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
=============== ===============
hledger's user interfaces accept a flexible "smart date" syntax (unlike 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 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 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 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, 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. 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 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"' `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: hledger uses regular expressions in a number of places:
@ -2282,101 +2329,103 @@ Tag Table:
Node: Top82 Node: Top82
Node: EXAMPLES1873 Node: EXAMPLES1873
Ref: #examples1975 Ref: #examples1975
Node: OPTIONS3979 Node: OPTIONS3627
Ref: #options4083 Ref: #options3731
Node: General options6711 Node: General options6372
Ref: #general-options6840 Ref: #general-options6501
Node: Reporting options7611 Node: Reporting options7272
Ref: #reporting-options7764 Ref: #reporting-options7425
Node: Input files9587 Node: Input files8858
Ref: #input-files9727 Ref: #input-files8995
Node: Depth limiting11768 Node: Smart dates11036
Ref: #depth-limiting11908 Ref: #smart-dates11179
Node: Smart dates12109 Node: Report start & end date12176
Ref: #smart-dates12255 Ref: #report-start-end-date12348
Node: Report start & end date13252 Node: Report intervals13424
Ref: #report-start-end-date13424 Ref: #report-intervals13589
Node: Report intervals14500 Node: Period expressions13988
Ref: #report-intervals14665 Ref: #period-expressions14148
Node: Period expressions15064 Node: Depth limiting16483
Ref: #period-expressions15229 Ref: #depth-limiting16627
Node: Regular expressions17564 Node: Pivoting16828
Ref: #regular-expressions17706 Ref: #pivoting16961
Node: QUERIES19189 Node: Regular expressions18792
Ref: #queries19293 Ref: #regular-expressions18926
Node: COMMANDS22932 Node: QUERIES20409
Ref: #commands23046 Ref: #queries20513
Node: accounts23719 Node: COMMANDS24152
Ref: #accounts23819 Ref: #commands24266
Node: activity24801 Node: accounts24939
Ref: #activity24913 Ref: #accounts25039
Node: add25272 Node: activity26021
Ref: #add25373 Ref: #activity26133
Node: balance28036 Node: add26492
Ref: #balance28149 Ref: #add26593
Node: Flat mode31162 Node: balance29256
Ref: #flat-mode31289 Ref: #balance29369
Node: Depth limited balance reports31708 Node: Flat mode32382
Ref: #depth-limited-balance-reports31911 Ref: #flat-mode32509
Node: Multicolumn balance reports32332 Node: Depth limited balance reports32928
Ref: #multicolumn-balance-reports32534 Ref: #depth-limited-balance-reports33131
Node: Market value37183 Node: Multicolumn balance reports33552
Ref: #market-value37347 Ref: #multicolumn-balance-reports33754
Node: Custom balance output38648 Node: Market value38403
Ref: #custom-balance-output38821 Ref: #market-value38567
Node: Output destination40925 Node: Custom balance output39868
Ref: #output-destination41090 Ref: #custom-balance-output40041
Node: CSV output41360 Node: Output destination42145
Ref: #csv-output41479 Ref: #output-destination42310
Node: balancesheet41876 Node: CSV output42580
Ref: #balancesheet42004 Ref: #csv-output42699
Node: cashflow42656 Node: balancesheet43096
Ref: #cashflow42773 Ref: #balancesheet43224
Node: help43463 Node: cashflow43876
Ref: #help43575 Ref: #cashflow43993
Node: incomestatement44412 Node: help44683
Ref: #incomestatement44542 Ref: #help44795
Node: info45269 Node: incomestatement45632
Ref: #info45376 Ref: #incomestatement45762
Node: man45738 Node: info46489
Ref: #man45835 Ref: #info46596
Node: print46238 Node: man46958
Ref: #print46343 Ref: #man47055
Node: register50092 Node: print47458
Ref: #register50205 Ref: #print47563
Node: Custom register output54697 Node: register51312
Ref: #custom-register-output54828 Ref: #register51425
Node: stats56125 Node: Custom register output55917
Ref: #stats56231 Ref: #custom-register-output56048
Node: test57111 Node: stats57345
Ref: #test57198 Ref: #stats57451
Node: ADD-ON COMMANDS57565 Node: test58331
Ref: #add-on-commands57701 Ref: #test58418
Node: api58989 Node: ADD-ON COMMANDS58785
Ref: #api59081 Ref: #add-on-commands58921
Node: autosync59115 Node: api60209
Ref: #autosync59230 Ref: #api60301
Node: diff61545 Node: autosync60335
Ref: #diff61655 Ref: #autosync60450
Node: equity62319 Node: diff62765
Ref: #equity62433 Ref: #diff62875
Node: interest63761 Node: equity63539
Ref: #interest63878 Ref: #equity63653
Node: irr66962 Node: interest64981
Ref: #irr67075 Ref: #interest65098
Node: print-unique69450 Node: irr68182
Ref: #print-unique69580 Ref: #irr68295
Node: rewrite69838 Node: print-unique70670
Ref: #rewrite69957 Ref: #print-unique70800
Node: ui70486 Node: rewrite71058
Ref: #ui70586 Ref: #rewrite71177
Node: web70627 Node: ui71706
Ref: #web70715 Ref: #ui71806
Node: TROUBLESHOOTING70748 Node: web71847
Ref: #troubleshooting70867 Ref: #web71935
Node: Run-time problems70921 Node: TROUBLESHOOTING71968
Ref: #run-time-problems71064 Ref: #troubleshooting72087
Node: Known limitations73008 Node: Run-time problems72141
Ref: #known-limitations73151 Ref: #run-time-problems72284
Node: Known limitations74228
Ref: #known-limitations74371
 
End Tag Table End Tag Table

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

@ -107,19 +107,6 @@ EXAMPLES
$ hledger print desc:shop # show transactions with shop in the description $ hledger print desc:shop # show transactions with shop in the description
$ hledger activity -W # show transaction counts per week as a bar chart $ 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
OPTIONS OPTIONS
To see general usage and the command list: hledger -h or just hledger. To see general usage and the command list: hledger -h or just hledger.
To see usage for a specific command: hledger COMMAND -h. To see usage for a specific command: hledger COMMAND -h.
@ -261,14 +248,8 @@ OPTIONS
convert amounts to their cost at transaction time (using the convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
--pivot TAG --pivot TAGNAME
will transform the journal before any other processing by organize reports by some tag's value instead of by account
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".
--anon show anonymized accounts and payees --anon show anonymized accounts and payees
@ -327,11 +308,6 @@ OPTIONS
If you need those, either use the include directive, or concatenate the If you need those, either use the include directive, or concatenate the
files, eg: cat a.journal b.journal | hledger -f- CMD. files, eg: cat a.journal b.journal | hledger -f- CMD.
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.
Smart dates Smart dates
hledger's user interfaces accept a flexible "smart date" syntax (unlike hledger's user interfaces accept a flexible "smart date" syntax (unlike
dates in the journal file). Smart dates allow some english words, can dates in the journal file). Smart dates allow some english words, can
@ -429,6 +405,7 @@ OPTIONS
earliest or latest transaction in your journal: earliest or latest transaction in your journal:
-p "from 2009/1/1" everything after january -p "from 2009/1/1" everything after january
1, 2009 1, 2009
-p "from 2009/1" the same -p "from 2009/1" the same
@ -480,6 +457,67 @@ OPTIONS
hledger register checking -p "every 3rd day of week" hledger register checking -p "every 3rd day of week"
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.
Pivoting
Normally hledger sums amounts, and organizes them in a hierarchy, based
on account name. The --pivot TAGNAME option causes it to sum and orga-
nize 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, summaris-
able 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 trans-
forming the journal before any other processing, replacing every post-
ing'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
Regular expressions Regular expressions
hledger uses regular expressions in a number of places: hledger uses regular expressions in a number of places:

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), 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`. 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 ## Smart dates
hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file). 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"` `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 ## 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: