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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2021-07-29 20:40:47 -10:00
parent 085b7d4b88
commit 4451d68a63
7 changed files with 1759 additions and 1164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
hledger-ui/hledger-ui.1
View File

@ -302,12 +302,6 @@ There\[aq]s not yet any visual reminder when cost or value mode is
active; for now pressing \f[C]b\f[R] \f[C]b\f[R] \f[C]v\f[R] should active; for now pressing \f[C]b\f[R] \f[C]b\f[R] \f[C]v\f[R] should
reliably reset to normal mode. reliably reset to normal mode.
.PP .PP
With \f[C]--watch\f[R] active, if you save an edit to the journal file
while viewing the transaction screen in cost or value mode, the
\f[C]B\f[R]/\f[C]V\f[R] keys will stop working.
To work around, press \f[C]g\f[R] to force a manual reload, or exit the
transaction screen.
.PP
\f[C]q\f[R] quits the application. \f[C]q\f[R] quits the application.
.PP .PP
Additional screen-specific keys are described below. Additional screen-specific keys are described below.
@ -439,6 +433,58 @@ when you press g to reload.
Once you have fixed the problem, press g again to reload and resume Once you have fixed the problem, press g again to reload and resume
normal operation. normal operation.
(Or, you can press escape to cancel the reload attempt.) (Or, you can press escape to cancel the reload attempt.)
.SH TIPS
.SS Watch mode
.PP
One of hledger-ui\[aq]s best features is the auto-reloading
\f[C]--watch\f[R] mode.
With this flag, it will update the display automatically whenever
changes are saved to the data files.
.PP
This is very useful when reconciling.
A good workflow is to have your bank\[aq]s online register open in a
browser window, for reference; the journal file open in an editor
window; and hledger-ui in watch mode in a terminal window, eg:
.IP
.nf
\f[C]
$ hledger-ui --watch --register checking -C
\f[R]
.fi
.PP
As you mark things cleared in the editor, you can see the effect
immediately without having to context switch.
This leaves more mental bandwidth for your accounting.
Of course you can still interact with hledger-ui when needed, eg to
toggle cleared mode, or to explore the history.
.SS Watch mode limitations
.PP
There are situations in which it won\[aq]t work, ie the display will not
update when you save a change (because the underlying \f[C]inotify\f[R]
library does not support it).
Here are some that we know of:
.IP \[bu] 2
Certain editors: saving with \f[C]gedit\f[R], and perhaps any Gnome
application, won\[aq]t be detected (#1617).
Jetbrains IDEs, such as IDEA, also may not work (#911).
.IP \[bu] 2
Certain unusual filesystems might not be supported.
(All the usual ones on unix, mac and windows are supported.)
.PP
In such cases, the workaround is to switch to the hledger-ui window and
press \f[C]g\f[R] each time you want it to reload.
(Actually, see #1617 for another workaround, and let us know if it works
for you.)
.PP
If you leave \f[C]hledger-ui --watch\f[R] running for days, on certain
platforms (?), perhaps with many transactions in your journal (?),
perhaps with large numbers of other files present (?), you may see it
gradually using more and more memory and CPU over time, as seen in
\f[C]top\f[R] or Activity Monitor or Task Manager.
.PP
A workaround is to \f[C]q\f[R]uit and restart it, or to suspend it
(\f[C]CTRL-z\f[R]) and restart it (\f[C]fg\f[R]) if your shell supports
that.
.SH ENVIRONMENT .SH ENVIRONMENT
.PP .PP
\f[B]COLUMNS\f[R] The screen width to use. \f[B]COLUMNS\f[R] The screen width to use.

132
hledger-ui/hledger-ui.info
View File

@ -3,7 +3,7 @@ from stdin.
INFO-DIR-SECTION User Applications INFO-DIR-SECTION User Applications
START-INFO-DIR-ENTRY START-INFO-DIR-ENTRY
* hledger-ui: (hledger-ui/hledger-ui). Terminal UI for the hledger accounting tool. * hledger-ui: (hledger-ui). Terminal UI for the hledger accounting tool.
END-INFO-DIR-ENTRY END-INFO-DIR-ENTRY
 
@ -45,6 +45,7 @@ enable "forecast mode".
* OPTIONS:: * OPTIONS::
* KEYS:: * KEYS::
* SCREENS:: * SCREENS::
* TIPS::
* ENVIRONMENT:: * ENVIRONMENT::
* FILES:: * FILES::
* BUGS:: * BUGS::
@ -308,17 +309,12 @@ screen, press `/', and add `date:-7/30' to the query.
active; for now pressing `b' `b' `v' should reliably reset to normal active; for now pressing `b' `b' `v' should reliably reset to normal
mode. mode.
With `--watch' active, if you save an edit to the journal file while
viewing the transaction screen in cost or value mode, the `B'/`V' keys
will stop working. To work around, press `g' to force a manual reload,
or exit the transaction screen.
`q' quits the application. `q' quits the application.
Additional screen-specific keys are described below. Additional screen-specific keys are described below.
 
File: hledger-ui.info, Node: SCREENS, Next: ENVIRONMENT, Prev: KEYS, Up: Top File: hledger-ui.info, Node: SCREENS, Next: TIPS, Prev: KEYS, Up: Top
3 SCREENS 3 SCREENS
********* *********
@ -463,9 +459,75 @@ again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.) to cancel the reload attempt.)
 
File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: SCREENS, Up: Top File: hledger-ui.info, Node: TIPS, Next: ENVIRONMENT, Prev: SCREENS, Up: Top
4 ENVIRONMENT 4 TIPS
******
* Menu:
* Watch mode::
* Watch mode limitations::

File: hledger-ui.info, Node: Watch mode, Next: Watch mode limitations, Up: TIPS
4.1 Watch mode
==============
One of hledger-ui's best features is the auto-reloading `--watch' mode.
With this flag, it will update the display automatically whenever
changes are saved to the data files.
This is very useful when reconciling. A good workflow is to have your
bank's online register open in a browser window, for reference; the
journal file open in an editor window; and hledger-ui in watch mode in a
terminal window, eg:
$ hledger-ui --watch --register checking -C
As you mark things cleared in the editor, you can see the effect
immediately without having to context switch. This leaves more mental
bandwidth for your accounting. Of course you can still interact with
hledger-ui when needed, eg to toggle cleared mode, or to explore the
history.

File: hledger-ui.info, Node: Watch mode limitations, Prev: Watch mode, Up: TIPS
4.2 Watch mode limitations
==========================
There are situations in which it won't work, ie the display will not
update when you save a change (because the underlying `inotify' library
does not support it). Here are some that we know of:
* Certain editors: saving with `gedit', and perhaps any Gnome
application, won't be detected (#1617). Jetbrains IDEs, such as
IDEA, also may not work (#911).
* Certain unusual filesystems might not be supported. (All the usual
ones on unix, mac and windows are supported.)
In such cases, the workaround is to switch to the hledger-ui window
and press `g' each time you want it to reload. (Actually, see #1617 for
another workaround, and let us know if it works for you.)
If you leave `hledger-ui --watch' running for days, on certain
platforms (?), perhaps with many transactions in your journal (?),
perhaps with large numbers of other files present (?), you may see it
gradually using more and more memory and CPU over time, as seen in
`top' or Activity Monitor or Task Manager.
A workaround is to `q'uit and restart it, or to suspend it
(`CTRL-z') and restart it (`fg') if your shell supports that.

File: hledger-ui.info, Node: ENVIRONMENT, Next: FILES, Prev: TIPS, Up: Top
5 ENVIRONMENT
************* *************
*COLUMNS* The screen width to use. Default: the full terminal width. *COLUMNS* The screen width to use. Default: the full terminal width.
@ -494,7 +556,7 @@ GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a
 
File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top File: hledger-ui.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top
5 FILES 6 FILES
******* *******
Reads data from one or more files in hledger journal, timeclock, Reads data from one or more files in hledger journal, timeclock,
@ -505,7 +567,7 @@ timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or
 
File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top File: hledger-ui.info, Node: BUGS, Prev: FILES, Up: Top
6 BUGS 7 BUGS
****** ******
The need to precede options with `--' when invoked from hledger is The need to precede options with `--' when invoked from hledger is
@ -533,26 +595,32 @@ program is restarted.
 
Tag Table: Tag Table:
Node: Top243 Node: Top232
Node: OPTIONS1636 Node: OPTIONS1634
Ref: #options1733 Ref: #options1731
Node: KEYS6128 Node: KEYS6126
Ref: #keys6223 Ref: #keys6221
Node: SCREENS10519 Node: SCREENS10270
Ref: #screens10624 Ref: #screens10368
Node: Accounts screen10714 Node: Accounts screen10458
Ref: #accounts-screen10842 Ref: #accounts-screen10586
Node: Register screen13046 Node: Register screen12790
Ref: #register-screen13201 Ref: #register-screen12945
Node: Transaction screen15196 Node: Transaction screen14940
Ref: #transaction-screen15354 Ref: #transaction-screen15098
Node: Error screen16221 Node: Error screen15965
Ref: #error-screen16343 Ref: #error-screen16087
Node: ENVIRONMENT16585 Node: TIPS16329
Ref: #environment16699 Ref: #tips16428
Node: FILES17504 Node: Watch mode16480
Ref: #files17603 Ref: #watch-mode16597
Node: BUGS17816 Node: Watch mode limitations17341
Ref: #bugs17893 Ref: #watch-mode-limitations17482
Node: ENVIRONMENT18615
Ref: #environment18726
Node: FILES19531
Ref: #files19630
Node: BUGS19843
Ref: #bugs19920
 
End Tag Table End Tag Table

49
hledger-ui/hledger-ui.txt
View File

@ -276,11 +276,6 @@ KEYS
There's not yet any visual reminder when cost or value mode is active; There's not yet any visual reminder when cost or value mode is active;
for now pressing b b v should reliably reset to normal mode. for now pressing b b v should reliably reset to normal mode.
With --watch active, if you save an edit to the journal file while
viewing the transaction screen in cost or value mode, the B/V keys will
stop working. To work around, press g to force a manual reload, or
exit the transaction screen.
q quits the application. q quits the application.
Additional screen-specific keys are described below. Additional screen-specific keys are described below.
@ -393,6 +388,50 @@ SCREENS
again to reload and resume normal operation. (Or, you can press escape again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.) to cancel the reload attempt.)
TIPS
Watch mode
One of hledger-ui's best features is the auto-reloading --watch mode.
With this flag, it will update the display automatically whenever
changes are saved to the data files.
This is very useful when reconciling. A good workflow is to have your
bank's online register open in a browser window, for reference; the
journal file open in an editor window; and hledger-ui in watch mode in
a terminal window, eg:
$ hledger-ui --watch --register checking -C
As you mark things cleared in the editor, you can see the effect imme-
diately without having to context switch. This leaves more mental
bandwidth for your accounting. Of course you can still interact with
hledger-ui when needed, eg to toggle cleared mode, or to explore the
history.
Watch mode limitations
There are situations in which it won't work, ie the display will not
update when you save a change (because the underlying inotify library
does not support it). Here are some that we know of:
o Certain editors: saving with gedit, and perhaps any Gnome applica-
tion, won't be detected (#1617). Jetbrains IDEs, such as IDEA, also
may not work (#911).
o Certain unusual filesystems might not be supported. (All the usual
ones on unix, mac and windows are supported.)
In such cases, the workaround is to switch to the hledger-ui window and
press g each time you want it to reload. (Actually, see #1617 for
another workaround, and let us know if it works for you.)
If you leave hledger-ui --watch running for days, on certain platforms
(?), perhaps with many transactions in your journal (?), perhaps with
large numbers of other files present (?), you may see it gradually
using more and more memory and CPU over time, as seen in top or Activ-
ity Monitor or Task Manager.
A workaround is to quit and restart it, or to suspend it (CTRL-z) and
restart it (fg) if your shell supports that.
ENVIRONMENT ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width. COLUMNS The screen width to use. Default: the full terminal width.

36
hledger-web/hledger-web.info
View File

@ -3,7 +3,7 @@ from stdin.
INFO-DIR-SECTION User Applications INFO-DIR-SECTION User Applications
START-INFO-DIR-ENTRY START-INFO-DIR-ENTRY
* hledger-web: (hledger-web/hledger-web). Web UI/API for the hledger accounting tool. * hledger-web: (hledger-web). Web UI/API for the hledger accounting tool.
END-INFO-DIR-ENTRY END-INFO-DIR-ENTRY
 
@ -612,22 +612,22 @@ awkward.
 
Tag Table: Tag Table:
Node: Top247 Node: Top235
Node: OPTIONS1887 Node: OPTIONS1875
Ref: #options1992 Ref: #options1980
Node: PERMISSIONS9405 Node: PERMISSIONS9393
Ref: #permissions9544 Ref: #permissions9532
Node: EDITING UPLOADING DOWNLOADING10756 Node: EDITING UPLOADING DOWNLOADING10744
Ref: #editing-uploading-downloading10937 Ref: #editing-uploading-downloading10925
Node: RELOADING11768 Node: RELOADING11756
Ref: #reloading11902 Ref: #reloading11890
Node: JSON API12334 Node: JSON API12322
Ref: #json-api12448 Ref: #json-api12436
Node: ENVIRONMENT17937 Node: ENVIRONMENT17925
Ref: #environment18053 Ref: #environment18041
Node: FILES18785 Node: FILES18773
Ref: #files18885 Ref: #files18873
Node: BUGS19098 Node: BUGS19086
Ref: #bugs19176 Ref: #bugs19164
 
End Tag Table End Tag Table

362
hledger/hledger.1
View File

@ -296,6 +296,11 @@ or:
$ hledger register credit\[rs] card $ hledger register credit\[rs] card
\f[R] \f[R]
.fi .fi
.PP
Windows users should keep in mind that \f[C]cmd\f[R] treats single quote
as a regular character, so you should be using double quotes
exclusively.
PowerShell treats both single and double quotes as quotes.
.SS Double escaping (regular expression metacharacters) .SS Double escaping (regular expression metacharacters)
.PP .PP
Characters significant in regular expressions (described below) - such Characters significant in regular expressions (described below) - such
@ -657,6 +662,8 @@ Are all accounts posted to, declared with an \f[C]account\f[R] directive
.IP \[bu] 2 .IP \[bu] 2
Are all commodities declared with a \f[C]commodity\f[R] directive ? Are all commodities declared with a \f[C]commodity\f[R] directive ?
(Commodity error checking) (Commodity error checking)
.IP \[bu] 2
Are all commodity conversions declared explicitly ?
.PP .PP
You can also use the check command to run these and some additional You can also use the check command to run these and some additional
checks. checks.
@ -754,6 +761,7 @@ T}@T{
9+ digits beginning with a valid YYYYMMDD gives an error 9+ digits beginning with a valid YYYYMMDD gives an error
T} T}
.TE .TE
.PP
.SS Report start & end date .SS Report start & end date
.PP .PP
By default, most hledger reports will show the full span of time By default, most hledger reports will show the full span of time
@ -1140,18 +1148,171 @@ This flag has the same effect as a \f[C]depth:\f[R] query argument (so
\f[C]-2\f[R], \f[C]--depth=2\f[R] or \f[C]depth:2\f[R] are equivalent). \f[C]-2\f[R], \f[C]--depth=2\f[R] or \f[C]depth:2\f[R] are equivalent).
.SH QUERIES .SH QUERIES
.PP .PP
One of hledger\[aq]s strengths is being able to quickly report on One of hledger\[aq]s strengths is being able to quickly report on a
precise subsets of your data. precise subset of your data.
Most commands accept an optional query expression, written as arguments Most hledger commands accept optional query arguments to restrict their
after the command name, to filter the data by date, account name or scope.
other criteria. The syntax is as follows:
The syntax is similar to a web search: one or more space-separated .IP \[bu] 2
search terms, quotes to enclose whitespace, prefixes to match specific Zero or more space-separated query terms.
fields, a not: prefix to negate the match. These are most often account name substrings:
.RS 2
.PP .PP
We do not yet support arbitrary boolean combinations of search terms; \f[C]utilities food:groceries\f[R]
instead most commands show transactions/postings/accounts which match .RE
(or negatively match): .IP \[bu] 2
Terms with spaces or other special characters should be enclosed in
quotes:
.RS 2
.PP
\f[C]\[dq]personal care\[dq]\f[R]
.RE
.IP \[bu] 2
Regular expressions are also supported:
.RS 2
.PP
\f[C]\[dq]\[ha]expenses\[rs]b\[dq] \[dq]accounts (payable|receivable)\[dq]\f[R]
.RE
.IP \[bu] 2
Add a query type prefix to match other parts of the data:
.RS 2
.PP
\f[C]date:202012- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R]
.RE
.IP \[bu] 2
Add a \f[C]not:\f[R] prefix to negate a term:
.RS 2
.PP
\f[C]not:cur:USD\f[R]
.RE
.SS Query types
.PP
Here are the types of query term available.
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R] to
convert them into a negative match.
.PP
\f[B]\f[CB]acct:REGEX\f[B], \f[CB]REGEX\f[B]\f[R]
.PD 0
.P
.PD
Match account names containing this (case insensitive) regular
expression.
This is the default query type when there is no prefix, and regular
expression syntax is typically not needed, so usually we just write an
account name substring, like \f[C]expenses\f[R] or \f[C]food\f[R].
.PP
\f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[B]\f[R]
.PD 0
.P
.PD
Match postings with a single-commodity amount equal to, less than, or
greater than N.
(Postings with multi-commodity amounts are not tested and will always
match.) The comparison has two modes: if N is preceded by a + or - sign
(or is 0), the two signed numbers are compared.
Otherwise, the absolute magnitudes are compared, ignoring sign.
.PP
\f[B]\f[CB]code:REGEX\f[B]\f[R]
.PD 0
.P
.PD
Match by transaction code (eg check number).
.PP
\f[B]\f[CB]cur:REGEX\f[B]\f[R]
.PD 0
.P
.PD
Match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX.
(For a partial match, use \f[C].*REGEX.*\f[R]).
Note, to match special characters which are regex-significant, you need
to escape them with \f[C]\[rs]\f[R].
And for characters which are significant to your shell you may need one
more level of escaping.
So eg to match the dollar sign:
.PD 0
.P
.PD
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
.PP
\f[B]\f[CB]desc:REGEX\f[B]\f[R]
.PD 0
.P
.PD
Match transaction descriptions.
.PP
\f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]
.PD 0
.P
.PD
Match dates (or with the \f[C]--date2\f[R] flag, secondary dates) within
the specified period.
PERIODEXPR is a period expression with no report interval.
Examples:
.PD 0
.P
.PD
\f[C]date:2016\f[R], \f[C]date:thismonth\f[R], \f[C]date:2/1-2/15\f[R],
\f[C]date:2021-07-27..nextquarter\f[R].
.PP
\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]
.PD 0
.P
.PD
Match secondary dates within the specified period (independent of the
\f[C]--date2\f[R] flag).
.PP
\f[B]\f[CB]depth:N\f[B]\f[R]
.PD 0
.P
.PD
Match (or display, depending on command) accounts at or above this
depth.
.PP
\f[B]\f[CB]note:REGEX\f[B]\f[R]
.PD 0
.P
.PD
Match transaction notes (the part of the description right of
\f[C]|\f[R], or the whole description if there\[aq]s no \f[C]|\f[R]).
.PP
\f[B]\f[CB]payee:REGEX\f[B]\f[R]
.PD 0
.P
.PD
Match transaction payee/payer names (the part of the description left of
\f[C]|\f[R], or the whole description if there\[aq]s no \f[C]|\f[R]).
.PP
\f[B]\f[CB]real:, real:0\f[B]\f[R]
.PD 0
.P
.PD
Match real or virtual postings respectively.
.PP
\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]
.PD 0
.P
.PD
Match unmarked, pending, or cleared transactions respectively.
.PP
\f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]
.PD 0
.P
.PD
Match by tag name, and optionally also by tag value.
(To match only by value, use \f[C]tag:.=REGEX\f[R].) Note that postings
also inherit tags from their transaction, and transactions also acquire
tags from their postings, when querying.
.PP
(\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]
.PD 0
.P
.PD
A special query term used automatically in hledger-web only: tells
hledger-web to show the transaction register for an account.)
.SS Combining query terms
.PP
Most commands select things which match:
.IP \[bu] 2 .IP \[bu] 2
any of the description terms AND any of the description terms AND
.IP \[bu] 2 .IP \[bu] 2
@ -1161,7 +1322,7 @@ any of the status terms AND
.IP \[bu] 2 .IP \[bu] 2
all the other terms. all the other terms.
.PP .PP
The print command instead shows transactions which: while the print command shows transactions which:
.IP \[bu] 2 .IP \[bu] 2
match any of the description terms AND match any of the description terms AND
.IP \[bu] 2 .IP \[bu] 2
@ -1171,89 +1332,49 @@ have no postings matching any of the negative account terms AND
.IP \[bu] 2 .IP \[bu] 2
match all the other terms. match all the other terms.
.PP .PP
The following kinds of search terms can be used. You can do more powerful queries (such as AND-ing two like terms) by
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg running a first query with \f[C]print\f[R], and piping the result into a
to exclude a particular subaccount. second hledger command.
.TP Eg: how much of food expenses was paid with cash ?
\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R] .IP
match account names by this regular expression. .nf
(With no prefix, \f[C]acct:\f[R] is assumed.) \f[C]
same as above $ hledger print assets:cash | hledger f- -I balance expenses:food
.TP \f[R]
\f[B]\f[R]\f[C]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[R]\f[B]\f[R] .fi
match postings with a single-commodity amount that is equal to, less
than, or greater than N.
(Multi-commodity amounts are not tested, and will always match.) The
comparison has two modes: if N is preceded by a + or - sign (or is 0),
the two signed numbers are compared.
Otherwise, the absolute magnitudes are compared, ignoring sign.
.TP
\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R]
match by transaction code (eg check number)
.TP
\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R]
match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX.
(For a partial match, use \f[C].*REGEX.*\f[R]).
Note, to match characters which are regex-significant, like the dollar
sign (\f[C]$\f[R]), you need to prepend \f[C]\[rs]\f[R].
And when using the command line you need to add one more level of
quoting to hide it from the shell, so eg do:
\f[C]hledger print cur:\[aq]\[rs]$\[aq]\f[R] or
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
.TP
\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R]
match transaction descriptions.
.TP
\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R]
match dates within the specified period.
PERIODEXPR is a period expression (with no report interval).
Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
\f[C]date:2000/2/1-2/15\f[R], \f[C]date:lastweek-\f[R].
If the \f[C]--date2\f[R] command line flag is present, this matches
secondary dates instead.
(Report intervals will adjust start/end dates to preceding/following
subperiod boundaries.)
.TP
\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R]
match secondary dates within the specified period.
.TP
\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R]
match (or display, depending on command) accounts at or above this depth
.TP
\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R]
match transaction notes (part of description right of \f[C]|\f[R], or
whole description when there\[aq]s no \f[C]|\f[R])
.TP
\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R]
match transaction payee/payer names (part of description left of
\f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R])
.TP
\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R]
match real or virtual postings respectively
.TP
\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R]
match unmarked, pending, or cleared transactions respectively
.TP
\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R]
match by tag name, and optionally also by tag value.
Note a tag: query is considered to match a transaction if it matches any
of the postings.
Also remember that postings inherit the tags of their parent
transaction.
.PP .PP
The following special search term is used automatically in hledger-web, If you are interested in full boolean expressions for queries, see #203.
only: .SS Queries and command options
.TP
\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R]
tells hledger-web to show the transaction register for this account.
Can be filtered further with \f[C]acct\f[R] etc.
.PP .PP
Some of these can also be expressed as command-line options (eg Some queries can also be expressed as command-line options:
\f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R]). \f[C]depth:2\f[R] is equivalent to \f[C]--depth 2\f[R],
Generally you can mix options and query arguments, and the resulting \f[C]date:2020\f[R] is equivalent to \f[C]-p 2020\f[R], etc.
query will be their intersection (perhaps excluding the When you mix command options and query arguments, generally the
\f[C]-p/--period\f[R] option). resulting query is their intersection.
.SS Queries and account aliases
.PP
When account names are rewritten with \f[C]--alias\f[R] or
\f[C]alias\f[R], \f[C]acct:\f[R] will match either the old or the new
account name.
.SS Queries and valuation
.PP
When amounts are converted to other commodities in cost or value
reports, \f[C]cur:\f[R] and \f[C]amt:\f[R] match the old commodity
symbol and the old amount quantity, not the new ones (except in hledger
1.22.0 where it\[aq]s reversed, see #1625).
.SS Querying with account aliases
.PP
When account names are rewritten with \f[C]--alias\f[R] or
\f[C]alias\f[R], note that \f[C]acct:\f[R] will match either the old or
the new account name.
.SS Querying with cost or value
.PP
When amounts are converted to other commodities in cost or value
reports, note that \f[C]cur:\f[R] matches the new commodity symbol, and
not the old one, and \f[C]amt:\f[R] matches the new quantity, and not
the old one.
Note: this changed in hledger 1.22, previously it was the reverse, see
the discussion at #1625.
.SH COSTING .SH COSTING
.PP .PP
The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale
@ -2783,6 +2904,9 @@ With \f[C]-S/--sort-amount\f[R], accounts with the largest (most
positive) balances are shown first. positive) balances are shown first.
Eg: \f[C]hledger bal expenses -MAS\f[R] shows your biggest averaged Eg: \f[C]hledger bal expenses -MAS\f[R] shows your biggest averaged
monthly expenses first. monthly expenses first.
When more than one commodity is present, they will be sorted by the
alphabetically earliest commodity first, and then by subsequent
commodities (if an amount is missing a commodity, it is treated as 0).
.PP .PP
Revenues and liability balances are typically negative, however, so Revenues and liability balances are typically negative, however, so
\f[C]-S\f[R] shows these in reverse order. \f[C]-S\f[R] shows these in reverse order.
@ -3255,7 +3379,7 @@ Budget performance in 2020-01-01..2020-01-15:
|| $400 [80% of $500] || $400 [80% of $500]
\f[R] \f[R]
.fi .fi
.SS Nested budgets .SS Budgets and subaccounts
.PP .PP
You can add budgets to any account in your account hierarchy. You can add budgets to any account in your account hierarchy.
If you have budgets on both parent account and some of its children, If you have budgets on both parent account and some of its children,
@ -3357,6 +3481,34 @@ Budget performance in 2019/01:
|| 0 [ 0] || 0 [ 0]
\f[R] \f[R]
.fi .fi
.SS Selecting budget goals
.PP
The budget report evaluates periodic transaction rules to generate
special \[dq]goal transactions\[dq], which generate the goal amounts for
each account in each report subperiod.
When troubleshooting, you can use the print command to show these as
forecasted transactions:
.IP
.nf
\f[C]
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
\f[R]
.fi
.PP
By default, the budget report uses all available periodic transaction
rules to generate goals.
This includes rules with a different report interval from your report.
Eg if you have daily, weekly and monthly periodic rules, all of these
will contribute to the goals in a monthly budget report.
.PP
You can select a subset of periodic rules by providing an argument to
the \f[C]--budget\f[R] flag.
\f[C]--budget=DESCPAT\f[R] will match all periodic rules whose
description contains DESCPAT, a case-insensitive substring (not a
regular expression or query).
This means you can give your periodic rules descriptions (remember that
two spaces are needed), and then select from multiple budgets defined in
your journal.
.SS Customising single-period balance reports .SS Customising single-period balance reports
.PP .PP
For single-period balance reports displayed in the terminal (only), you For single-period balance reports displayed in the terminal (only), you
@ -4871,6 +5023,28 @@ Using roi to compute total return of investment in stocks:
https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger
.IP \[bu] 2 .IP \[bu] 2
Cookbook -> Return on Investment Cookbook -> Return on Investment
.SS Spaces and special characters in \f[C]--inv\f[R] and \f[C]--pnl\f[R]
.PP
Note that \f[C]--inv\f[R] and \f[C]--pnl\f[R]\[aq]s argument is a query,
and queries could have several space-separated terms (see QUERIES).
.PP
To indicate that all search terms form single command-line argument, you
will need to put them in quotes (see Special characters):
.IP
.nf
\f[C]
$ hledger roi --inv \[aq]term1 term2 term3 ...\[aq]
\f[R]
.fi
.PP
If any query terms contain spaces themselves, you will need an extra
level of nested quoting, eg:
.IP
.nf
\f[C]
$ hledger roi --inv=\[dq]\[aq]Assets:Test 1\[aq]\[dq] --pnl=\[dq]\[aq]Equity:Unrealized Profit and Loss\[aq]\[dq]
\f[R]
.fi
.SS Semantics of \f[C]--inv\f[R] and \f[C]--pnl\f[R] .SS Semantics of \f[C]--inv\f[R] and \f[C]--pnl\f[R]
.PP .PP
Query supplied to \f[C]--inv\f[R] has to match all transactions that are Query supplied to \f[C]--inv\f[R] has to match all transactions that are

1288
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

272
hledger/hledger.txt
View File

@ -251,6 +251,10 @@ OPTIONS
$ hledger register credit\ card $ hledger register credit\ card
Windows users should keep in mind that cmd treats single quote as a
regular character, so you should be using double quotes exclusively.
PowerShell treats both single and double quotes as quotes.
Double escaping (regular expression metacharacters) Double escaping (regular expression metacharacters)
Characters significant in regular expressions (described below) - such Characters significant in regular expressions (described below) - such
as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
@ -499,6 +503,8 @@ DATA FILES
o Are all commodities declared with a commodity directive ? (Commodity o Are all commodities declared with a commodity directive ? (Commodity
error checking) error checking)
o Are all commodity conversions declared explicitly ?
You can also use the check command to run these and some additional You can also use the check command to run these and some additional
checks. checks.
@ -537,6 +543,7 @@ TIME PERIODS
20181232 8 digits with an invalid day gives an error 20181232 8 digits with an invalid day gives an error
201801012 9+ digits beginning with a valid YYYYMMDD gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error
Report start & end date Report start & end date
By default, most hledger reports will show the full span of time repre- By default, most hledger reports will show the full span of time repre-
sented by the journal data. The report start date will be the earliest sented by the journal data. The report start date will be the earliest
@ -630,8 +637,8 @@ TIME PERIODS
also be written as: also be written as:
-p "1/1 4/1" -p "1/1 4/1"
-p "january-apr" -p "january-apr"
-p "this year to 4/1" -p "this year to 4/1"
@ -751,17 +758,104 @@ DEPTH
-2, --depth=2 or depth:2 are equivalent). -2, --depth=2 or depth:2 are equivalent).
QUERIES QUERIES
One of hledger's strengths is being able to quickly report on precise One of hledger's strengths is being able to quickly report on a precise
subsets of your data. Most commands accept an optional query expres- subset of your data. Most hledger commands accept optional query argu-
sion, written as arguments after the command name, to filter the data ments to restrict their scope. The syntax is as follows:
by date, account name or other criteria. The syntax is similar to a
web search: one or more space-separated search terms, quotes to enclose
whitespace, prefixes to match specific fields, a not: prefix to negate
the match.
We do not yet support arbitrary boolean combinations of search terms; o Zero or more space-separated query terms. These are most often
instead most commands show transactions/postings/accounts which match account name substrings:
(or negatively match):
utilities food:groceries
o Terms with spaces or other special characters should be enclosed in
quotes:
"personal care"
o Regular expressions are also supported:
"^expenses\b" "accounts (payable|receivable)"
o Add a query type prefix to match other parts of the data:
date:202012- desc:amazon cur:USD amt:">100" status:
o Add a not: prefix to negate a term:
not:cur:USD
Query types
Here are the types of query term available. Remember these can also be
prefixed with not: to convert them into a negative match.
acct:REGEX, REGEX
Match account names containing this (case insensitive) regular expres-
sion. This is the default query type when there is no prefix, and reg-
ular expression syntax is typically not needed, so usually we just
write an account name substring, like expenses or food.
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
Match postings with a single-commodity amount equal to, less than, or
greater than N. (Postings with multi-commodity amounts are not tested
and will always match.) The comparison has two modes: if N is preceded
by a + or - sign (or is 0), the two signed numbers are compared. Oth-
erwise, the absolute magnitudes are compared, ignoring sign.
code:REGEX
Match by transaction code (eg check number).
cur:REGEX
Match postings or transactions including any amounts whose cur-
rency/commodity symbol is fully matched by REGEX. (For a partial
match, use .*REGEX.*). Note, to match special characters which are
regex-significant, you need to escape them with \. And for characters
which are significant to your shell you may need one more level of
escaping. So eg to match the dollar sign:
hledger print cur:\\$.
desc:REGEX
Match transaction descriptions.
date:PERIODEXPR
Match dates (or with the --date2 flag, secondary dates) within the
specified period. PERIODEXPR is a period expression with no report
interval. Examples:
date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter.
date2:PERIODEXPR
Match secondary dates within the specified period (independent of the
--date2 flag).
depth:N
Match (or display, depending on command) accounts at or above this
depth.
note:REGEX
Match transaction notes (the part of the description right of |, or the
whole description if there's no |).
payee:REGEX
Match transaction payee/payer names (the part of the description left
of |, or the whole description if there's no |).
real:, real:0
Match real or virtual postings respectively.
status:, status:!, status:*
Match unmarked, pending, or cleared transactions respectively.
tag:REGEX[=REGEX]
Match by tag name, and optionally also by tag value. (To match only by
value, use tag:.=REGEX.) Note that postings also inherit tags from
their transaction, and transactions also acquire tags from their post-
ings, when querying.
(inacct:ACCTNAME
A special query term used automatically in hledger-web only: tells
hledger-web to show the transaction register for an account.)
Combining query terms
Most commands select things which match:
o any of the description terms AND o any of the description terms AND
@ -771,7 +865,7 @@ QUERIES
o all the other terms. o all the other terms.
The print command instead shows transactions which: while the print command shows transactions which:
o match any of the description terms AND o match any of the description terms AND
@ -781,82 +875,41 @@ QUERIES
o match all the other terms. o match all the other terms.
The following kinds of search terms can be used. Remember these can You can do more powerful queries (such as AND-ing two like terms) by
also be prefixed with not:, eg to exclude a particular subaccount. running a first query with print, and piping the result into a second
hledger command. Eg: how much of food expenses was paid with cash ?
REGEX, acct:REGEX $ hledger print assets:cash | hledger f- -I balance expenses:food
match account names by this regular expression. (With no pre-
fix, acct: is assumed.) same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N If you are interested in full boolean expressions for queries, see
match postings with a single-commodity amount that is equal to, #203.
less than, or greater than N. (Multi-commodity amounts are not
tested, and will always match.) The comparison has two modes: if
N is preceded by a + or - sign (or is 0), the two signed numbers
are compared. Otherwise, the absolute magnitudes are compared,
ignoring sign.
code:REGEX Queries and command options
match by transaction code (eg check number) Some queries can also be expressed as command-line options: depth:2 is
equivalent to --depth 2, date:2020 is equivalent to -p 2020, etc. When
you mix command options and query arguments, generally the resulting
query is their intersection.
cur:REGEX Queries and account aliases
match postings or transactions including any amounts whose cur- When account names are rewritten with --alias or alias, acct: will
rency/commodity symbol is fully matched by REGEX. (For a par- match either the old or the new account name.
tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend
\. And when using the command line you need to add one more
level of quoting to hide it from the shell, so eg do: hledger
print cur:'\$' or hledger print cur:\\$.
desc:REGEX Queries and valuation
match transaction descriptions. When amounts are converted to other commodities in cost or value
reports, cur: and amt: match the old commodity symbol and the old
amount quantity, not the new ones (except in hledger 1.22.0 where it's
reversed, see #1625).
date:PERIODEXPR Querying with account aliases
match dates within the specified period. PERIODEXPR is a period When account names are rewritten with --alias or alias, note that acct:
expression (with no report interval). Examples: date:2016, will match either the old or the new account name.
date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
--date2 command line flag is present, this matches secondary
dates instead. (Report intervals will adjust start/end dates to
preceding/following subperiod boundaries.)
date2:PERIODEXPR Querying with cost or value
match secondary dates within the specified period. When amounts are converted to other commodities in cost or value
reports, note that cur: matches the new commodity symbol, and not the
depth:N old one, and amt: matches the new quantity, and not the old one. Note:
match (or display, depending on command) accounts at or above this changed in hledger 1.22, previously it was the reverse, see the
this depth discussion at #1625.
note:REGEX
match transaction notes (part of description right of |, or
whole description when there's no |)
payee:REGEX
match transaction payee/payer names (part of description left of
|, or whole description when there's no |)
real:, real:0
match real or virtual postings respectively
status:, status:!, status:*
match unmarked, pending, or cleared transactions respectively
tag:REGEX[=REGEX]
match by tag name, and optionally also by tag value. Note a
tag: query is considered to match a transaction if it matches
any of the postings. Also remember that postings inherit the
tags of their parent transaction.
The following special search term is used automatically in hledger-web,
only:
inacct:ACCTNAME
tells hledger-web to show the transaction register for this
account. Can be filtered further with acct etc.
Some of these can also be expressed as command-line options (eg depth:2
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
excluding the -p/--period option).
COSTING COSTING
The -B/--cost flag converts amounts to their cost or sale amount at The -B/--cost flag converts amounts to their cost or sale amount at
@ -1196,6 +1249,8 @@ VALUATION
total/average of displayed of displayed displayed values of displayed of displayed total/average of displayed of displayed displayed values of displayed of displayed
values values values values values values values values
balance (bs, balance (bs,
bse, cf, is) bse, cf, is)
balance sums of value at value at posting value at value at balance sums of value at value at posting value at value at
@ -1203,8 +1258,6 @@ VALUATION
or today of journal end sums of post- or today of journal end sums of post-
sums of of sums of ings sums of of sums of ings
postings postings postings postings
budget like balance like balance like balance like bal- like balance budget like balance like balance like balance like bal- like balance
amounts changes changes changes ances changes amounts changes changes changes ances changes
(--budget) (--budget)
@ -1951,7 +2004,10 @@ COMMANDS
Sorting by amount Sorting by amount
With -S/--sort-amount, accounts with the largest (most positive) bal- With -S/--sort-amount, accounts with the largest (most positive) bal-
ances are shown first. Eg: hledger bal expenses -MAS shows your big- ances are shown first. Eg: hledger bal expenses -MAS shows your big-
gest averaged monthly expenses first. gest averaged monthly expenses first. When more than one commodity is
present, they will be sorted by the alphabetically earliest commodity
first, and then by subsequent commodities (if an amount is missing a
commodity, it is treated as 0).
Revenues and liability balances are typically negative, however, so -S Revenues and liability balances are typically negative, however, so -S
shows these in reverse order. To work around this, you can add shows these in reverse order. To work around this, you can add
@ -2300,7 +2356,7 @@ COMMANDS
---------------++------------------------ ---------------++------------------------
|| $400 [80% of $500] || $400 [80% of $500]
Nested budgets Budgets and subaccounts
You can add budgets to any account in your account hierarchy. If you You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud- have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their get(s) of the child account(s) would be added to the budget of their
@ -2383,6 +2439,27 @@ COMMANDS
----------------------------------------++------------------------------- ----------------------------------------++-------------------------------
|| 0 [ 0] || 0 [ 0]
Selecting budget goals
The budget report evaluates periodic transaction rules to generate spe-
cial "goal transactions", which generate the goal amounts for each
account in each report subperiod. When troubleshooting, you can use
the print command to show these as forecasted transactions:
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
By default, the budget report uses all available periodic transaction
rules to generate goals. This includes rules with a different report
interval from your report. Eg if you have daily, weekly and monthly
periodic rules, all of these will contribute to the goals in a monthly
budget report.
You can select a subset of periodic rules by providing an argument to
the --budget flag. --budget=DESCPAT will match all periodic rules
whose description contains DESCPAT, a case-insensitive substring (not a
regular expression or query). This means you can give your periodic
rules descriptions (remember that two spaces are needed), and then
select from multiple budgets defined in your journal.
Customising single-period balance reports Customising single-period balance reports
For single-period balance reports displayed in the terminal (only), you For single-period balance reports displayed in the terminal (only), you
can use --format FMT to customise the format and content of each line. can use --format FMT to customise the format and content of each line.
@ -3542,6 +3619,20 @@ COMMANDS
o Cookbook -> Return on Investment o Cookbook -> Return on Investment
Spaces and special characters in --inv and --pnl
Note that --inv and --pnl's argument is a query, and queries could have
several space-separated terms (see QUERIES).
To indicate that all search terms form single command-line argument,
you will need to put them in quotes (see Special characters):
$ hledger roi --inv 'term1 term2 term3 ...'
If any query terms contain spaces themselves, you will need an extra
level of nested quoting, eg:
$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
Semantics of --inv and --pnl Semantics of --inv and --pnl
Query supplied to --inv has to match all transactions that are related Query supplied to --inv has to match all transactions that are related
to your investment. Transactions not matching --inv will be ignored. to your investment. Transactions not matching --inv will be ignored.
@ -4502,10 +4593,6 @@ JOURNAL FORMAT
aliases until end of cur- aliases until end of cur-
rent file or end rent file or end
directive directive
apply end apply prepend a common parent to following entries apply end apply prepend a common parent to following entries
account account account names until end of cur- account account account names until end of cur-
rent file or end rent file or end
@ -4514,6 +4601,13 @@ JOURNAL FORMAT
ment until end of cur- ment until end of cur-
rent file or end rent file or end
directive directive
commod- format declare a commodity and its number notation: commod- format declare a commodity and its number notation:
ity number notation & display following entries ity number notation & display following entries
style until end of cur- style until end of cur-