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 2022-11-03 08:31:47 -10:00
parent 14c31cc23d
commit 80eb461063
12 changed files with 2862 additions and 2656 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER-UI" "1" "October 2022" "hledger-ui-1.27.99 " "hledger User Manuals"
.TH "HLEDGER-UI" "1" "November 2022" "hledger-ui-1.27.99 " "hledger User Manuals"

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

@ -574,4 +574,4 @@ SEE ALSO
hledger-ui-1.27.99 October 2022 HLEDGER-UI(1)
hledger-ui-1.27.99 November 2022 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

53
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER-WEB" "1" "October 2022" "hledger-web-1.27.99 " "hledger User Manuals"
.TH "HLEDGER-WEB" "1" "November 2022" "hledger-web-1.27.99 " "hledger User Manuals"
@ -9,11 +9,18 @@ hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.27.99.
.SH SYNOPSIS
.PP
\f[C]hledger-web [OPTIONS]\f[R]
\f[C]hledger-web [OPTIONS] # run temporarily & browse\f[R]
.PD 0
.P
.PD
\f[C]hledger-web --serve [OPTIONS] # run without stopping\f[R]
.PD 0
.P
.PD
\f[C]hledger-web --serve-api [OPTIONS] # run JSON server only\f[R]
.PD 0
.P
.PD
\f[C]hledger web -- [OPTIONS]\f[R]
.SH DESCRIPTION
.PP
hledger is a reliable, cross-platform set of programs for tracking
@ -21,27 +28,41 @@ money, time, or any other commodity, using double-entry accounting and a
simple, editable file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger-web is hledger\[aq]s web interface.
It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible.
hledger-web is a simple web application for browsing and adding
transactions.
It provides a more user-friendly UI than the hledger CLI or hledger-ui
interface, showing more at once (accounts, the current account register,
TUI, showing more at once (accounts, the current account register,
balance charts) and allowing history-aware data entry, interactive
searching, and bookmarking.
.PP
hledger-web also lets you share a ledger with multiple users, or even
hledger-web also lets you share a journal with multiple users, or even
the public web.
There is no access control, so if you need that you should put it behind
a suitable web proxy.
As a small protection against data loss when running an unprotected
instance, it writes a numbered backup of the main journal file (only ?)
on every edit.
instance, it writes a numbered backup of the main journal file (only) on
every edit.
.PP
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1).
.PP
hledger-web can be run in three modes:
.IP \[bu] 2
Transient mode (the default): your default web browser will be opened to
show the app if possible, and the app exits automatically after two
minutes of inactivity (no requests received and no open browser windows
viewing it).
.IP \[bu] 2
With \f[C]--serve\f[R]: the app runs without stopping, and without
opening a browser.
.IP \[bu] 2
With \f[C]--serve-api\f[R]: only the JSON API is served.
.PP
In all cases hledger-web runs as a foreground process, logging requests
to stdout.
.SH OPTIONS
.PP
Command-line options and arguments may be used to set an initial filter
@ -53,7 +74,7 @@ Note: if invoking hledger-web as a hledger subcommand, write
\f[C]--\f[R] before options, as shown in the synopsis above.
.TP
\f[B]\f[CB]--serve\f[B]\f[R]
serve and log requests, don\[aq]t browse or auto-exit
serve and log requests, don\[aq]t browse or auto-exit after timeout
.TP
\f[B]\f[CB]--serve-api\f[B]\f[R]
like --serve, but serve only the JSON web API, without the server-side
@ -249,16 +270,6 @@ A \[at]FILE argument will be expanded to the contents of FILE, which
should contain one command line option/argument per line.
(To prevent this, insert a \f[C]--\f[R] argument before.)
.PP
By default, hledger-web starts the web app in \[dq]transient mode\[dq]
and also opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
With \f[C]--serve\f[R], it just runs the web app without exiting, and
logs requests to the console.
With \f[C]--serve-api\f[R], only the JSON web api (see below) is served,
with the usual HTML server-side web UI disabled.
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[C]--host\f[R] to change this, eg \f[C]--host 0.0.0.0\f[R]

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

@ -14,33 +14,47 @@ hledger-web(1)
hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.27.99.
'hledger-web [OPTIONS]'
'hledger web -- [OPTIONS]'
'hledger-web [OPTIONS] # run temporarily & browse'
'hledger-web --serve [OPTIONS] # run without stopping'
'hledger-web --serve-api [OPTIONS] # run JSON server only'
hledger is a reliable, cross-platform set of programs for tracking
money, time, or any other commodity, using double-entry accounting and a
simple, editable file format. hledger is inspired by and largely
compatible with ledger(1).
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens
it in a web browser window if possible. It provides a more
user-friendly UI than the hledger CLI or hledger-ui interface, showing
more at once (accounts, the current account register, balance charts)
and allowing history-aware data entry, interactive searching, and
bookmarking.
hledger-web is a simple web application for browsing and adding
transactions. It provides a more user-friendly UI than the hledger CLI
or hledger-ui TUI, showing more at once (accounts, the current account
register, balance charts) and allowing history-aware data entry,
interactive searching, and bookmarking.
hledger-web also lets you share a ledger with multiple users, or even
the public web. There is no access control, so if you need that you
should put it behind a suitable web proxy. As a small protection
hledger-web also lets you share a journal with multiple users, or
even the public web. There is no access control, so if you need that
you should put it behind a suitable web proxy. As a small protection
against data loss when running an unprotected instance, it writes a
numbered backup of the main journal file (only ?) on every edit.
numbered backup of the main journal file (only) on every edit.
Like hledger, it reads data from one or more files in hledger
journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1).
hledger-web can be run in three modes:
* Transient mode (the default): your default web browser will be
opened to show the app if possible, and the app exits automatically
after two minutes of inactivity (no requests received and no open
browser windows viewing it).
* With '--serve': the app runs without stopping, and without opening
a browser.
* With '--serve-api': only the JSON API is served.
In all cases hledger-web runs as a foreground process, logging
requests to stdout.
* Menu:
* OPTIONS::
@ -67,7 +81,7 @@ before options, as shown in the synopsis above.
'--serve'
serve and log requests, don't browse or auto-exit
serve and log requests, don't browse or auto-exit after timeout
'--serve-api'
like -serve, but serve only the JSON web API, without the
@ -264,15 +278,6 @@ the last one takes precedence.
should contain one command line option/argument per line. (To prevent
this, insert a '--' argument before.)
By default, hledger-web starts the web app in "transient mode" and
also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console. With
'--serve-api', only the JSON web api (see below) is served, with the
usual HTML server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
0.0.0.0' to listen on all configured addresses.
@ -632,22 +637,22 @@ awkward.

Tag Table:
Node: Top223
Node: OPTIONS1889
Ref: #options1994
Node: PERMISSIONS9905
Ref: #permissions10044
Node: EDITING UPLOADING DOWNLOADING11256
Ref: #editing-uploading-downloading11437
Node: RELOADING12271
Ref: #reloading12405
Node: JSON API12838
Ref: #json-api12952
Node: ENVIRONMENT18442
Ref: #environment18558
Node: FILES19869
Ref: #files19969
Node: BUGS20182
Ref: #bugs20260
Node: OPTIONS2419
Ref: #options2524
Node: PERMISSIONS9923
Ref: #permissions10062
Node: EDITING UPLOADING DOWNLOADING11274
Ref: #editing-uploading-downloading11455
Node: RELOADING12289
Ref: #reloading12423
Node: JSON API12856
Ref: #json-api12970
Node: ENVIRONMENT18460
Ref: #environment18576
Node: FILES19887
Ref: #files19987
Node: BUGS20200
Ref: #bugs20278

End Tag Table

48
hledger-web/hledger-web.txt
View File

@ -8,8 +8,9 @@ NAME
This manual is for hledger-web 1.27.99.
SYNOPSIS
hledger-web [OPTIONS]
hledger web -- [OPTIONS]
hledger-web [OPTIONS] # run temporarily & browse
hledger-web --serve [OPTIONS] # run without stopping
hledger-web --serve-api [OPTIONS] # run JSON server only
DESCRIPTION
hledger is a reliable, cross-platform set of programs for tracking
@ -17,24 +18,38 @@ DESCRIPTION
a simple, editable file format. hledger is inspired by and largely
compatible with ledger(1).
hledger-web is hledger's web interface. It starts a simple web appli-
cation for browsing and adding transactions, and optionally opens it in
a web browser window if possible. It provides a more user-friendly UI
than the hledger CLI or hledger-ui interface, showing more at once
(accounts, the current account register, balance charts) and allowing
history-aware data entry, interactive searching, and bookmarking.
hledger-web is a simple web application for browsing and adding trans-
actions. It provides a more user-friendly UI than the hledger CLI or
hledger-ui TUI, showing more at once (accounts, the current account
register, balance charts) and allowing history-aware data entry, inter-
active searching, and bookmarking.
hledger-web also lets you share a ledger with multiple users, or even
hledger-web also lets you share a journal with multiple users, or even
the public web. There is no access control, so if you need that you
should put it behind a suitable web proxy. As a small protection
against data loss when running an unprotected instance, it writes a
numbered backup of the main journal file (only ?) on every edit.
numbered backup of the main journal file (only) on every edit.
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
or $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). For more about this see hledger(1).
hledger-web can be run in three modes:
o Transient mode (the default): your default web browser will be opened
to show the app if possible, and the app exits automatically after
two minutes of inactivity (no requests received and no open browser
windows viewing it).
o With --serve: the app runs without stopping, and without opening a
browser.
o With --serve-api: only the JSON API is served.
In all cases hledger-web runs as a foreground process, logging requests
to stdout.
OPTIONS
Command-line options and arguments may be used to set an initial filter
on the data. These filter options are not shown in the web UI, but it
@ -44,7 +59,7 @@ OPTIONS
options, as shown in the synopsis above.
--serve
serve and log requests, don't browse or auto-exit
serve and log requests, don't browse or auto-exit after timeout
--serve-api
like --serve, but serve only the JSON web API, without the
@ -234,15 +249,6 @@ OPTIONS
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML
server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host
0.0.0.0 to listen on all configured addresses.
@ -586,4 +592,4 @@ SEE ALSO
hledger-web-1.27.99 October 2022 HLEDGER-WEB(1)
hledger-web-1.27.99 November 2022 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{October 2022}})m4_dnl
m4_define({{_monthyear_}}, {{November 2022}})m4_dnl

639
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "HLEDGER" "1" "October 2022" "hledger-1.27.99 " "hledger User Manuals"
.TH "HLEDGER" "1" "November 2022" "hledger-1.27.99 " "hledger User Manuals"
@ -563,7 +563,7 @@ Default: the full terminal width.
\f[B]NO_COLOR\f[R] If this variable exists with any value, hledger will
not use ANSI color codes in terminal output.
This is overriden by the --color/--colour option.
.SH DATA FILES
.SH INPUT
.PP
hledger reads transactions from one or more data files.
The default data file is \f[C]$HOME/.hledger.journal\f[R] (or on
@ -710,6 +710,283 @@ Are all commodity conversions declared explicitly ?
.PP
You can use the check command to run individual checks -- the ones
listed above and some more.
.SH OUTPUT
.PP
Some of this section may refer to things explained further below.
.SS Output destination
.PP
hledger commands send their output to the terminal by default.
You can of course redirect this, eg into a file, using standard shell
syntax:
.IP
.nf
\f[C]
$ hledger print > foo.txt
\f[R]
.fi
.PP
Some commands (print, register, stats, the balance commands) also
provide the \f[C]-o/--output-file\f[R] option, which does the same thing
without needing the shell.
Eg:
.IP
.nf
\f[C]
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
\f[R]
.fi
.SS Output styling
.PP
hledger commands can produce colour output when the terminal supports
it.
This is controlled by the \f[C]--color/--colour\f[R] option: - if the
\f[C]--color/--colour\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), colour will (or
will not) be used; - otherwise, if the \f[C]NO_COLOR\f[R] environment
variable is set, colour will not be used; - otherwise, colour will be
used if the output (terminal or file) supports it.
.PP
hledger commands can also use unicode box-drawing characters to produce
prettier tables and output.
This is controlled by the \f[C]--pretty\f[R] option: - if the
\f[C]--pretty\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), unicode
characters will (or will not) be used; - otherwise, unicode characters
will not be used.
.SS Output format
.PP
Some commands offer additional output formats, other than the usual
plain text terminal output.
Here are those commands and the formats currently supported:
.PP
.TS
tab(@);
l l l l l l.
T{
-
T}@T{
txt
T}@T{
csv
T}@T{
html
T}@T{
json
T}@T{
sql
T}
_
T{
aregister
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
T{
balance
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1,2\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheet
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheetequity
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
cashflow
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
incomestatement
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
print
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
Y
T}
T{
register
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
.TE
.IP \[bu] 2
\f[I]1 Also affected by the balance commands\[aq] \f[CI]--layout\f[I]
option.\f[R]
.IP \[bu] 2
\f[I]2 \f[CI]balance\f[I] does not support html output without a report
interval or with \f[CI]--budget\f[I].\f[R]
.PP
The output format is selected by the \f[C]-O/--output-format=FMT\f[R]
option:
.IP
.nf
\f[C]
$ hledger print -O csv # print CSV on stdout
\f[R]
.fi
.PP
or by the filename extension of an output file specified with the
\f[C]-o/--output-file=FILE.FMT\f[R] option:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
\f[R]
.fi
.PP
The \f[C]-O\f[R] option can be combined with \f[C]-o\f[R] to override
the file extension, if needed:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
\f[R]
.fi
.SS CSV output
.IP \[bu] 2
In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
.SS HTML output
.IP \[bu] 2
HTML output can be styled by an optional \f[C]hledger.css\f[R] file in
the same directory.
.SS JSON output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
Our JSON is rather large and verbose, as it is quite a faithful
representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are
mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
.IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals.
Such numbers can arise in practice (from automatically-calculated
transaction prices), and would break most JSON consumers.
So in JSON, we show quantities as simple Numbers with at most 10 decimal
places.
We don\[aq]t limit the number of integer digits, but that part is under
your control.
We hope this approach will not cause problems in practice; if you find
otherwise, please let us know.
(Cf #1195)
.SS SQL output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
SQL output is expected to work with sqlite, MySQL and PostgreSQL
.IP \[bu] 2
SQL output is structured with the expectations that statements will be
executed in the empty database.
If you already have tables created via SQL output of hledger, you would
probably want to either clear tables of existing data (via
\f[C]delete\f[R] or \f[C]truncate\f[R] SQL statements) or drop tables
completely as otherwise your postings will be duped.
.SS Commodity styles
.PP
The display style of a commodity/currency is inferred according to the
rules described in Commodity display style.
The inferred display style can be overridden by an optional
\f[C]-c/--commodity-style\f[R] option (Exceptions: as is the case for
inferred styles, price amounts, and all amounts displayed by the
\f[C]print\f[R] command, will be displayed with all of their decimal
digits visible, regardless of the specified precision).
For example, the following will override the display style for dollars.
.IP
.nf
\f[C]
$ hledger print -c \[aq]$1.000,0\[aq]
\f[R]
.fi
.PP
The format specification of the style is identical to the commodity
display style specification for the commodity directive.
The command line option can be supplied repeatedly to override the
display style for multiple commodity/currency symbols.
.SS Debug output
.PP
We aim for hledger to be relatively easy to troubleshoot, introspect and
develop.
You can add \f[C]--debug[=N]\f[R] to any hledger command line to see
additional debug output.
N ranges from 1 (least output, the default) to 9 (maximum output).
Typically you would start with 1 and increase until you are seeing
enough.
Debug output goes to stderr, and is not affected by
\f[C]-o/--output-file\f[R] (unless you redirect stderr to stdout, eg:
\f[C]2>&1\f[R]).
It will be interleaved with normal output, which can help reveal when
parts of the code are evaluated.
To capture debug output in a log file instead, you can usually redirect
stderr, eg:
.PD 0
.P
.PD
\f[C]hledger bal --debug=3 2>hledger.log\f[R].
.SH TIME PERIODS
.SS Smart dates
.PP
@ -2790,267 +3067,6 @@ $ hledger balance --pivot member acct:.
-2 EUR
\f[R]
.fi
.SH OUTPUT
.SS Output destination
.PP
hledger commands send their output to the terminal by default.
You can of course redirect this, eg into a file, using standard shell
syntax:
.IP
.nf
\f[C]
$ hledger print > foo.txt
\f[R]
.fi
.PP
Some commands (print, register, stats, the balance commands) also
provide the \f[C]-o/--output-file\f[R] option, which does the same thing
without needing the shell.
Eg:
.IP
.nf
\f[C]
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
\f[R]
.fi
.PP
hledger can optionally produce debug output (if enabled with
\f[C]--debug=N\f[R]); this goes to stderr, and is not affected by
\f[C]-o/--output-file\f[R].
If you need to capture it, use shell redirects, eg:
\f[C]hledger bal --debug=3 >file 2>&1\f[R].
.SS Output styling
.PP
hledger commands can produce colour output when the terminal supports
it.
This is controlled by the \f[C]--color/--colour\f[R] option: - if the
\f[C]--color/--colour\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), colour will (or
will not) be used; - otherwise, if the \f[C]NO_COLOR\f[R] environment
variable is set, colour will not be used; - otherwise, colour will be
used if the output (terminal or file) supports it.
.PP
hledger commands can also use unicode box-drawing characters to produce
prettier tables and output.
This is controlled by the \f[C]--pretty\f[R] option: - if the
\f[C]--pretty\f[R] option is given a value of \f[C]yes\f[R] or
\f[C]always\f[R] (or \f[C]no\f[R] or \f[C]never\f[R]), unicode
characters will (or will not) be used; - otherwise, unicode characters
will not be used.
.SS Output format
.PP
Some commands offer additional output formats, other than the usual
plain text terminal output.
Here are those commands and the formats currently supported:
.PP
.TS
tab(@);
l l l l l l.
T{
-
T}@T{
txt
T}@T{
csv
T}@T{
html
T}@T{
json
T}@T{
sql
T}
_
T{
aregister
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
T{
balance
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1,2\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheet
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
balancesheetequity
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
cashflow
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
incomestatement
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y \f[I]1\f[R]
T}@T{
Y
T}@T{
T}
T{
print
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
Y
T}
T{
register
T}@T{
Y
T}@T{
Y
T}@T{
T}@T{
Y
T}@T{
T}
.TE
.IP \[bu] 2
\f[I]1 Also affected by the balance commands\[aq] \f[CI]--layout\f[I]
option.\f[R]
.IP \[bu] 2
\f[I]2 \f[CI]balance\f[I] does not support html output without a report
interval or with \f[CI]--budget\f[I].\f[R]
.PP
The output format is selected by the \f[C]-O/--output-format=FMT\f[R]
option:
.IP
.nf
\f[C]
$ hledger print -O csv # print CSV on stdout
\f[R]
.fi
.PP
or by the filename extension of an output file specified with the
\f[C]-o/--output-file=FILE.FMT\f[R] option:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
\f[R]
.fi
.PP
The \f[C]-O\f[R] option can be combined with \f[C]-o\f[R] to override
the file extension, if needed:
.IP
.nf
\f[C]
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
\f[R]
.fi
.SS CSV output
.IP \[bu] 2
In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
.SS HTML output
.IP \[bu] 2
HTML output can be styled by an optional \f[C]hledger.css\f[R] file in
the same directory.
.SS JSON output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
Our JSON is rather large and verbose, as it is quite a faithful
representation of hledger\[aq]s internal data types.
To understand the JSON, read the Haskell type definitions, which are
mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
.IP \[bu] 2
hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals.
Such numbers can arise in practice (from automatically-calculated
transaction prices), and would break most JSON consumers.
So in JSON, we show quantities as simple Numbers with at most 10 decimal
places.
We don\[aq]t limit the number of integer digits, but that part is under
your control.
We hope this approach will not cause problems in practice; if you find
otherwise, please let us know.
(Cf #1195)
.SS SQL output
.IP \[bu] 2
Not yet much used; real-world feedback is welcome.
.IP \[bu] 2
SQL output is expected to work with sqlite, MySQL and PostgreSQL
.IP \[bu] 2
SQL output is structured with the expectations that statements will be
executed in the empty database.
If you already have tables created via SQL output of hledger, you would
probably want to either clear tables of existing data (via
\f[C]delete\f[R] or \f[C]truncate\f[R] SQL statements) or drop tables
completely as otherwise your postings will be duped.
.SS Commodity styles
.PP
The display style of a commodity/currency is inferred according to the
rules described in Commodity display style.
The inferred display style can be overridden by an optional
\f[C]-c/--commodity-style\f[R] option (Exceptions: as is the case for
inferred styles, price amounts, and all amounts displayed by the
\f[C]print\f[R] command, will be displayed with all of their decimal
digits visible, regardless of the specified precision).
For example, the following will override the display style for dollars.
.IP
.nf
\f[C]
$ hledger print -c \[aq]$1.000,0\[aq]
\f[R]
.fi
.PP
The format specification of the style is identical to the commodity
display style specification for the commodity directive.
The command line option can be supplied repeatedly to override the
display style for multiple commodity/currency symbols.
.SH COMMANDS
.PP
hledger provides a number of commands for producing reports and managing
@ -3165,11 +3181,19 @@ accounts
.PD
Show account names.
.PP
This command lists account names, either declared with account
directives (--declared), posted to (--used), or both (the default).
This command lists account names.
By default it shows all known accounts, either used in transactions or
declared with account directives.
.PP
With query arguments, only matched account names and account names
referenced by matched postings are shown.
.PP
Or it can show just the used accounts (\f[C]--used\f[R]/\f[C]-u\f[R]),
the declared accounts (\f[C]--declared\f[R]/\f[C]-d\f[R]), the accounts
declared but not used (\f[C]--unused\f[R]), the accounts used but not
declared (\f[C]--undeclared\f[R]), or the first account matched by an
account name pattern, if any (\f[C]--find\f[R]).
.PP
It shows a flat list by default.
With \f[C]--tree\f[R], it uses indentation to show the account
hierarchy.
@ -3190,6 +3214,13 @@ display order.
With \f[C]--directives\f[R], it adds the \f[C]account\f[R] keyword,
showing valid account directives which can be pasted into a journal
file.
This is useful together with \f[C]--undeclared\f[R] when updating your
account declarations to satisfy \f[C]hledger check accounts\f[R].
.PP
The \f[C]--find\f[R] flag can be used to look up a single account name,
in the same way that the \f[C]aregister\f[R] command does.
It returns the alphanumerically-first matched account name, or if none
can be found, it fails with a non-zero exit code.
.PP
Examples:
.IP
@ -3206,6 +3237,13 @@ income:salary
liabilities:debts
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger accounts --undeclared --directives >> $LEDGER_FILE
$ hledger check accounts
\f[R]
.fi
.SS activity
.PP
activity
@ -8979,7 +9017,14 @@ T}
T{
\f[B]\f[CB]newest-first\f[B]\f[R]
T}@T{
disambiguate record order when there\[aq]s only one date
improve txn order when there are multiple records, newest first, all
with the same date
T}
T{
\f[B]\f[CB]intra-day-reversed\f[B]\f[R]
T}@T{
improve txn order when each day\[aq]s txns are reverse of the overall
date order
T}
T{
\f[B]\f[CB]include\f[B]\f[R]
@ -9842,7 +9887,7 @@ the TZ environment variable, eg:
.IP
.nf
\f[C]
$ TZ=HST hledger print -f foo.csv # or TZ=HST hledger import foo.csv
$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv
\f[R]
.fi
.PP
@ -9874,29 +9919,55 @@ thousand-separating commas, you should declare the decimal mark
explicitly with this rule, to avoid misparsed numbers.
.SS \f[C]newest-first\f[R]
.PP
hledger always sorts the generated transactions by date.
Transactions on the same date should appear in the same order as their
CSV records, as hledger can usually auto-detect whether the CSV\[aq]s
normal order is oldest first or newest first.
But if all of the following are true:
.IP \[bu] 2
the CSV might sometimes contain just one day of data (all records having
the same date)
.IP \[bu] 2
the CSV records are normally in reverse chronological order (newest at
the top)
.IP \[bu] 2
and you care about preserving the order of same-day transactions
.PP
then, you should add the \f[C]newest-first\f[R] rule as a hint.
Eg:
hledger tries to ensure that the generated transactions will be ordered
chronologically, including intra-day transactions.
Usually it can auto-detect how the CSV records are ordered.
But if it encounters CSV where all records are on the same date, it
assumes that the records are oldest first.
If in fact the CSV\[aq]s records are normally newest first, like:
.IP
.nf
\f[C]
# tell hledger explicitly that the CSV is normally newest first
2022-10-01, txn 3...
2022-10-01, txn 2...
2022-10-01, txn 1...
\f[R]
.fi
.PP
you can add the \f[C]newest-first\f[R] rule to help hledger generate the
transactions in correct order.
.IP
.nf
\f[C]
# same-day CSV records are newest first
newest-first
\f[R]
.fi
.SS \f[C]intra-day-reversed\f[R]
.PP
CSV records for each day are sometimes ordered in reverse compared to
the overall date order.
Eg, here dates are newest first, but the transactions on each date are
oldest first:
.IP
.nf
\f[C]
2022-10-02, txn 3...
2022-10-02, txn 4...
2022-10-01, txn 1...
2022-10-01, txn 2...
\f[R]
.fi
.PP
In this situation, add the \f[C]intra-day-reversed\f[R] rule, and
hledger will compensate, improving the order of transactions.
.IP
.nf
\f[C]
# transactions within each day are reversed with respect to the overall date order
intra-day-reversed
\f[R]
.fi
.SS \f[C]include\f[R]
.IP
.nf

1686
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

357
hledger/hledger.txt
View File

@ -446,7 +446,7 @@ ENVIRONMENT
ANSI color codes in terminal output. This is overriden by the
--color/--colour option.
DATA FILES
INPUT
hledger reads transactions from one or more data files. The default
data file is $HOME/.hledger.journal (or on Windows, something like
C:\Users\YOURNAME\.hledger.journal).
@ -539,6 +539,141 @@ DATA FILES
You can use the check command to run individual checks -- the ones
listed above and some more.
OUTPUT
Some of this section may refer to things explained further below.
Output destination
hledger commands send their output to the terminal by default. You can
of course redirect this, eg into a file, using standard shell syntax:
$ hledger print > foo.txt
Some commands (print, register, stats, the balance commands) also pro-
vide the -o/--output-file option, which does the same thing without
needing the shell. Eg:
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
Output styling
hledger commands can produce colour output when the terminal supports
it. This is controlled by the --color/--colour option: - if the
--color/--colour option is given a value of yes or always (or no or
never), colour will (or will not) be used; - otherwise, if the NO_COLOR
environment variable is set, colour will not be used; - otherwise,
colour will be used if the output (terminal or file) supports it.
hledger commands can also use unicode box-drawing characters to produce
prettier tables and output. This is controlled by the --pretty option:
- if the --pretty option is given a value of yes or always (or no or
never), unicode characters will (or will not) be used; - otherwise,
unicode characters will not be used.
Output format
Some commands offer additional output formats, other than the usual
plain text terminal output. Here are those commands and the formats
currently supported:
- txt csv html json sql
---------------------------------------------
aregister Y Y Y
balance Y 1 Y 1 Y 1,2 Y
bal- Y 1 Y 1 Y 1 Y
ancesheet
bal- Y 1 Y 1 Y 1 Y
ancesheete-
quity
cashflow Y 1 Y 1 Y 1 Y
incomes- Y 1 Y 1 Y 1 Y
tatement
print Y Y Y Y
register Y Y Y
o 1 Also affected by the balance commands' --layout option.
o 2 balance does not support html output without a report interval or
with --budget.
The output format is selected by the -O/--output-format=FMT option:
$ hledger print -O csv # print CSV on stdout
or by the filename extension of an output file specified with the
-o/--output-file=FILE.FMT option:
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
The -O option can be combined with -o to override the file extension,
if needed:
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
CSV output
o In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
HTML output
o HTML output can be styled by an optional hledger.css file in the same
directory.
JSON output
o Not yet much used; real-world feedback is welcome.
o Our JSON is rather large and verbose, as it is quite a faithful rep-
resentation of hledger's internal data types. To understand the
JSON, read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-
lib/Hledger/Data/Types.hs.
o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
arise in practice (from automatically-calculated transaction prices),
and would break most JSON consumers. So in JSON, we show quantities
as simple Numbers with at most 10 decimal places. We don't limit the
number of integer digits, but that part is under your control. We
hope this approach will not cause problems in practice; if you find
otherwise, please let us know. (Cf #1195)
SQL output
o Not yet much used; real-world feedback is welcome.
o SQL output is expected to work with sqlite, MySQL and PostgreSQL
o SQL output is structured with the expectations that statements will
be executed in the empty database. If you already have tables cre-
ated via SQL output of hledger, you would probably want to either
clear tables of existing data (via delete or truncate SQL statements)
or drop tables completely as otherwise your postings will be duped.
Commodity styles
The display style of a commodity/currency is inferred according to the
rules described in Commodity display style. The inferred display style
can be overridden by an optional -c/--commodity-style option (Excep-
tions: as is the case for inferred styles, price amounts, and all
amounts displayed by the print command, will be displayed with all of
their decimal digits visible, regardless of the specified precision).
For example, the following will override the display style for dollars.
$ hledger print -c '$1.000,0'
The format specification of the style is identical to the commodity
display style specification for the commodity directive. The command
line option can be supplied repeatedly to override the display style
for multiple commodity/currency symbols.
Debug output
We aim for hledger to be relatively easy to troubleshoot, introspect
and develop. You can add --debug[=N] to any hledger command line to
see additional debug output. N ranges from 1 (least output, the
default) to 9 (maximum output). Typically you would start with 1 and
increase until you are seeing enough. Debug output goes to stderr, and
is not affected by -o/--output-file (unless you redirect stderr to std-
out, eg: 2>&1). It will be interleaved with normal output, which can
help reveal when parts of the code are evaluated. To capture debug
output in a log file instead, you can usually redirect stderr, eg:
hledger bal --debug=3 2>hledger.log.
TIME PERIODS
Smart dates
hledger's user interfaces accept a flexible "smart date" syntax. Smart
@ -550,6 +685,7 @@ TIME PERIODS
2004/10/1, 2004-01-01, exact date, several separators allowed. Year
2004.9.1 is 4+ digits, month is 1-12, day is 1-31
2004 start of year
2004/10 start of month
10/1 month and day in current year
@ -618,6 +754,7 @@ TIME PERIODS
Examples:
-b 2016/3/17 begin on St. Patrick's day 2016
-e 12/1 end at the start of december 1st of the current year
(11/30 will be the last date included)
@ -822,10 +959,9 @@ TIME PERIODS
Examples:
-p "every 2nd day of periods will go from Tue to Tue
week"
-p "every Tue" same
-p "every 15th day" period boundaries will be on 15th of each
month
@ -1721,8 +1857,6 @@ VALUATION
ments
register
starting bal- cost value at valued at day value at value at
ance (-H) report or each historical report or DATE/today
journal end posting was made journal end
@ -1731,6 +1865,8 @@ VALUATION
with report report or posting was made report or
interval journal journal
start start
posting cost value at value at posting value at value at
amounts report or date report or DATE/today
journal end journal end
@ -1878,132 +2014,6 @@ PIVOTING
--------------------
-2 EUR
OUTPUT
Output destination
hledger commands send their output to the terminal by default. You can
of course redirect this, eg into a file, using standard shell syntax:
$ hledger print > foo.txt
Some commands (print, register, stats, the balance commands) also pro-
vide the -o/--output-file option, which does the same thing without
needing the shell. Eg:
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
hledger can optionally produce debug output (if enabled with
--debug=N); this goes to stderr, and is not affected by -o/--output-
file. If you need to capture it, use shell redirects, eg: hledger bal
--debug=3 >file 2>&1.
Output styling
hledger commands can produce colour output when the terminal supports
it. This is controlled by the --color/--colour option: - if the
--color/--colour option is given a value of yes or always (or no or
never), colour will (or will not) be used; - otherwise, if the NO_COLOR
environment variable is set, colour will not be used; - otherwise,
colour will be used if the output (terminal or file) supports it.
hledger commands can also use unicode box-drawing characters to produce
prettier tables and output. This is controlled by the --pretty option:
- if the --pretty option is given a value of yes or always (or no or
never), unicode characters will (or will not) be used; - otherwise,
unicode characters will not be used.
Output format
Some commands offer additional output formats, other than the usual
plain text terminal output. Here are those commands and the formats
currently supported:
- txt csv html json sql
---------------------------------------------
aregister Y Y Y
balance Y 1 Y 1 Y 1,2 Y
bal- Y 1 Y 1 Y 1 Y
ancesheet
bal- Y 1 Y 1 Y 1 Y
ancesheete-
quity
cashflow Y 1 Y 1 Y 1 Y
incomes- Y 1 Y 1 Y 1 Y
tatement
print Y Y Y Y
register Y Y Y
o 1 Also affected by the balance commands' --layout option.
o 2 balance does not support html output without a report interval or
with --budget.
The output format is selected by the -O/--output-format=FMT option:
$ hledger print -O csv # print CSV on stdout
or by the filename extension of an output file specified with the
-o/--output-file=FILE.FMT option:
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
The -O option can be combined with -o to override the file extension,
if needed:
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
CSV output
o In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
HTML output
o HTML output can be styled by an optional hledger.css file in the same
directory.
JSON output
o Not yet much used; real-world feedback is welcome.
o Our JSON is rather large and verbose, as it is quite a faithful rep-
resentation of hledger's internal data types. To understand the
JSON, read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/master/hledger-
lib/Hledger/Data/Types.hs.
o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
arise in practice (from automatically-calculated transaction prices),
and would break most JSON consumers. So in JSON, we show quantities
as simple Numbers with at most 10 decimal places. We don't limit the
number of integer digits, but that part is under your control. We
hope this approach will not cause problems in practice; if you find
otherwise, please let us know. (Cf #1195)
SQL output
o Not yet much used; real-world feedback is welcome.
o SQL output is expected to work with sqlite, MySQL and PostgreSQL
o SQL output is structured with the expectations that statements will
be executed in the empty database. If you already have tables cre-
ated via SQL output of hledger, you would probably want to either
clear tables of existing data (via delete or truncate SQL statements)
or drop tables completely as otherwise your postings will be duped.
Commodity styles
The display style of a commodity/currency is inferred according to the
rules described in Commodity display style. The inferred display style
can be overridden by an optional -c/--commodity-style option (Excep-
tions: as is the case for inferred styles, price amounts, and all
amounts displayed by the print command, will be displayed with all of
their decimal digits visible, regardless of the specified precision).
For example, the following will override the display style for dollars.
$ hledger print -c '$1.000,0'
The format specification of the style is identical to the commodity
display style specification for the commodity directive. The command
line option can be supplied repeatedly to override the display style
for multiple commodity/currency symbols.
COMMANDS
hledger provides a number of commands for producing reports and manag-
ing your data. Run hledger with no arguments to list the commands
@ -2111,10 +2121,17 @@ COMMANDS
accounts
Show account names.
This command lists account names, either declared with account direc-
tives (--declared), posted to (--used), or both (the default). With
query arguments, only matched account names and account names refer-
enced by matched postings are shown.
This command lists account names. By default it shows all known
accounts, either used in transactions or declared with account direc-
tives.
With query arguments, only matched account names and account names ref-
erenced by matched postings are shown.
Or it can show just the used accounts (--used/-u), the declared
accounts (--declared/-d), the accounts declared but not used
(--unused), the accounts used but not declared (--undeclared), or the
first account matched by an account name pattern, if any (--find).
It shows a flat list by default. With --tree, it uses indentation to
show the account hierarchy. In flat mode you can add --drop N to omit
@ -2129,7 +2146,14 @@ COMMANDS
order; these may be useful when troubleshooting account display order.
With --directives, it adds the account keyword, showing valid account
directives which can be pasted into a journal file.
directives which can be pasted into a journal file. This is useful
together with --undeclared when updating your account declarations to
satisfy hledger check accounts.
The --find flag can be used to look up a single account name, in the
same way that the aregister command does. It returns the alphanumeri-
cally-first matched account name, or if none can be found, it fails
with a non-zero exit code.
Examples:
@ -2143,6 +2167,9 @@ COMMANDS
income:salary
liabilities:debts
$ hledger accounts --undeclared --directives >> $LEDGER_FILE
$ hledger check accounts
activity
activity
Show an ascii barchart of posting counts per interval.
@ -2875,6 +2902,7 @@ COMMANDS
--change change in period sum of posting- period-end DATE-value of
date market val- value of change change in
ues in period in period period
--cumu- change from sum of posting- period-end DATE-value of
lative report start to date market val- value of change change from
period end ues from report from report report start
@ -4808,6 +4836,8 @@ JOURNAL FORMAT
status meaning
--------------------------------------------------------------------------
uncleared recorded but not yet reconciled; needs review
pending tentatively reconciled (if needed, eg during a big reconcil-
iation)
cleared complete, reconciled as far as possible, and considered cor-
@ -5477,6 +5507,9 @@ JOURNAL FORMAT
~ Declares a periodic transaction rule that generates future
(tilde) transactions with --forecast and budget goals with balance
--budget.
= Declares an auto posting rule that generates extra postings partly
(equals) on matched transactions with --auto, in current, parent, and
child files (but not sibling files, see #1212).
@ -6448,8 +6481,11 @@ CSV FORMAT
date-format how to parse dates in CSV records
decimal-mark the decimal mark used in CSV amounts, if
ambiguous
newest-first disambiguate record order when there's only
one date
newest-first improve txn order when there are multiple
records, newest first, all with the same
date
intra-day-reversed improve txn order when each day's txns are
reverse of the overall date order
include inline another CSV rules file
balance-type choose which type of balance assignments to
use
@ -7116,7 +7152,7 @@ CSV FORMAT
can (on unix at least) set the output timezone with the TZ environment
variable, eg:
$ TZ=HST hledger print -f foo.csv # or TZ=HST hledger import foo.csv
$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv
timezone currently does not understand timezone names, except "UTC",
"GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For
@ -7136,24 +7172,39 @@ CSV FORMAT
misparsed numbers.
newest-first
hledger always sorts the generated transactions by date. Transactions
on the same date should appear in the same order as their CSV records,
as hledger can usually auto-detect whether the CSV's normal order is
oldest first or newest first. But if all of the following are true:
hledger tries to ensure that the generated transactions will be ordered
chronologically, including intra-day transactions. Usually it can
auto-detect how the CSV records are ordered. But if it encounters CSV
where all records are on the same date, it assumes that the records are
oldest first. If in fact the CSV's records are normally newest first,
like:
o the CSV might sometimes contain just one day of data (all records
having the same date)
2022-10-01, txn 3...
2022-10-01, txn 2...
2022-10-01, txn 1...
o the CSV records are normally in reverse chronological order (newest
at the top)
you can add the newest-first rule to help hledger generate the transac-
tions in correct order.
o and you care about preserving the order of same-day transactions
then, you should add the newest-first rule as a hint. Eg:
# tell hledger explicitly that the CSV is normally newest first
# same-day CSV records are newest first
newest-first
intra-day-reversed
CSV records for each day are sometimes ordered in reverse compared to
the overall date order. Eg, here dates are newest first, but the
transactions on each date are oldest first:
2022-10-02, txn 3...
2022-10-02, txn 4...
2022-10-01, txn 1...
2022-10-01, txn 2...
In this situation, add the intra-day-reversed rule, and hledger will
compensate, improving the order of transactions.
# transactions within each day are reversed with respect to the overall date order
intra-day-reversed
include
include RULESFILE
@ -8171,4 +8222,4 @@ SEE ALSO
hledger-1.27.99 October 2022 HLEDGER(1)
hledger-1.27.99 November 2022 HLEDGER(1)