regen manuals
[ci skip]
This commit is contained in:
Simon Michael
parent
861baadb2b
commit
8620e5414f
@ -491,10 +491,10 @@ which is more correct and provides better error checking.
|
||||
.SS Balance Assertions
|
||||
.PP
|
||||
hledger supports Ledger\-style balance assertions in journal files.
|
||||
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
|
||||
amount.
|
||||
Eg in this example we assert the expected dollar balance in accounts a
|
||||
and b after each posting:
|
||||
These look like, for example, \f[C]=\ EXPECTEDBALANCE\f[] following a
|
||||
posting\[aq]s amount.
|
||||
Eg here we assert the expected dollar balance in accounts a and b after
|
||||
each posting:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
@ -513,7 +513,7 @@ and report an error if any of them fail.
|
||||
Balance assertions can protect you from, eg, inadvertently disrupting
|
||||
reconciled balances while cleaning up old entries.
|
||||
You can disable them temporarily with the
|
||||
\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for
|
||||
\f[C]\-I/\-\-ignore\-assertions\f[] flag, which can be useful for
|
||||
troubleshooting or for reading Ledger files.
|
||||
.SS Assertions and ordering
|
||||
.PP
|
||||
@ -558,11 +558,10 @@ We could call this a "partial" balance assertion.
|
||||
To assert the balance of more than one commodity in an account, you can
|
||||
write multiple postings, each asserting one commodity\[aq]s balance.
|
||||
.PP
|
||||
You can make a stronger kind of balance assertion, by writing a double
|
||||
equals sign (\f[C]==EXPECTEDBALANCE\f[]).
|
||||
This "complete" balance assertion asserts the absence of other
|
||||
commodities (or, that their balance is 0, which to hledger is
|
||||
equivalent.)
|
||||
You can make a stronger "total" balance assertion by writing a double
|
||||
equals sign (\f[C]==\ EXPECTEDBALANCE\f[]).
|
||||
This asserts that there are no other unasserted commodities in the
|
||||
account (or, that their balance is 0).
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
@ -619,29 +618,19 @@ generate balance assertions with prices), and because balance
|
||||
\f[I]assignments\f[] do use them (see below).
|
||||
.SS Assertions and subaccounts
|
||||
.PP
|
||||
Balance assertions do not count the balance from subaccounts; they check
|
||||
the posted account\[aq]s exclusive balance.
|
||||
For example:
|
||||
The balance assertions above (\f[C]=\f[] and \f[C]==\f[]) do not count
|
||||
the balance from subaccounts; they check the account\[aq]s exclusive
|
||||
balance only.
|
||||
You can assert the balance including subaccounts by writing \f[C]=*\f[]
|
||||
or \f[C]==*\f[], eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
1/1
|
||||
\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1
|
||||
\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1
|
||||
\ \ equity
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
The balance report\[aq]s flat mode shows these exclusive balances more
|
||||
clearly:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$\ hledger\ bal\ checking\ \-\-flat
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund
|
||||
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2
|
||||
2019/1/1
|
||||
\ \ equity:opening\ balances
|
||||
\ \ checking:a\ \ \ \ \ \ \ 5
|
||||
\ \ checking:b\ \ \ \ \ \ \ 5
|
||||
\ \ checking\ \ \ \ \ \ \ \ \ 1\ \ ==*\ 11
|
||||
\f[]
|
||||
.fi
|
||||
.SS Assertions and virtual postings
|
||||
|
||||
@ -449,9 +449,9 @@ File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignment
|
||||
======================
|
||||
|
||||
hledger supports Ledger-style balance assertions in journal files.
|
||||
These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in
|
||||
this example we assert the expected dollar balance in accounts a and b
|
||||
after each posting:
|
||||
These look like, for example, '= EXPECTEDBALANCE' following a posting's
|
||||
amount. Eg here we assert the expected dollar balance in accounts a and
|
||||
b after each posting:
|
||||
|
||||
2013/1/1
|
||||
a $1 =$1
|
||||
@ -465,8 +465,8 @@ after each posting:
|
||||
assertions and report an error if any of them fail. Balance assertions
|
||||
can protect you from, eg, inadvertently disrupting reconciled balances
|
||||
while cleaning up old entries. You can disable them temporarily with
|
||||
the '--ignore-assertions' flag, which can be useful for troubleshooting
|
||||
or for reading Ledger files.
|
||||
the '-I/--ignore-assertions' flag, which can be useful for
|
||||
troubleshooting or for reading Ledger files.
|
||||
* Menu:
|
||||
|
||||
* Assertions and ordering::
|
||||
@ -533,10 +533,10 @@ This is how assertions work in Ledger also. We could call this a
|
||||
To assert the balance of more than one commodity in an account, you
|
||||
can write multiple postings, each asserting one commodity's balance.
|
||||
|
||||
You can make a stronger kind of balance assertion, by writing a
|
||||
double equals sign ('==EXPECTEDBALANCE'). This "complete" balance
|
||||
assertion asserts the absence of other commodities (or, that their
|
||||
balance is 0, which to hledger is equivalent.)
|
||||
You can make a stronger "total" balance assertion by writing a double
|
||||
equals sign ('== EXPECTEDBALANCE'). This asserts that there are no
|
||||
other unasserted commodities in the account (or, that their balance is
|
||||
0).
|
||||
|
||||
2013/1/1
|
||||
a $1
|
||||
@ -591,22 +591,16 @@ File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions
|
||||
1.9.6 Assertions and subaccounts
|
||||
--------------------------------
|
||||
|
||||
Balance assertions do not count the balance from subaccounts; they check
|
||||
the posted account's exclusive balance. For example:
|
||||
The balance assertions above ('=' and '==') do not count the balance
|
||||
from subaccounts; they check the account's exclusive balance only. You
|
||||
can assert the balance including subaccounts by writing '=*' or '==*',
|
||||
eg:
|
||||
|
||||
1/1
|
||||
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
|
||||
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
|
||||
equity
|
||||
|
||||
The balance report's flat mode shows these exclusive balances more
|
||||
clearly:
|
||||
|
||||
$ hledger bal checking --flat
|
||||
1 checking
|
||||
1 checking:fund
|
||||
--------------------
|
||||
2
|
||||
2019/1/1
|
||||
equity:opening balances
|
||||
checking:a 5
|
||||
checking:b 5
|
||||
checking 1 ==* 11
|
||||
|
||||
|
||||
File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions
|
||||
@ -1619,81 +1613,81 @@ Node: Virtual Postings15032
|
||||
Ref: #virtual-postings15191
|
||||
Node: Balance Assertions16411
|
||||
Ref: #balance-assertions16586
|
||||
Node: Assertions and ordering17537
|
||||
Ref: #assertions-and-ordering17723
|
||||
Node: Assertions and included files18423
|
||||
Ref: #assertions-and-included-files18664
|
||||
Node: Assertions and multiple -f options18997
|
||||
Ref: #assertions-and-multiple--f-options19251
|
||||
Node: Assertions and commodities19383
|
||||
Ref: #assertions-and-commodities19613
|
||||
Node: Assertions and prices20801
|
||||
Ref: #assertions-and-prices21013
|
||||
Node: Assertions and subaccounts21453
|
||||
Ref: #assertions-and-subaccounts21680
|
||||
Node: Assertions and virtual postings22201
|
||||
Ref: #assertions-and-virtual-postings22441
|
||||
Node: Assertions and precision22583
|
||||
Ref: #assertions-and-precision22774
|
||||
Node: Balance Assignments23041
|
||||
Ref: #balance-assignments23222
|
||||
Node: Balance assignments and prices24386
|
||||
Ref: #balance-assignments-and-prices24558
|
||||
Node: Transaction prices24782
|
||||
Ref: #transaction-prices24951
|
||||
Node: Comments27219
|
||||
Ref: #comments27353
|
||||
Node: Tags28523
|
||||
Ref: #tags28641
|
||||
Node: Directives30043
|
||||
Ref: #directives30186
|
||||
Node: Comment blocks35793
|
||||
Ref: #comment-blocks35938
|
||||
Node: Including other files36114
|
||||
Ref: #including-other-files36294
|
||||
Node: Default year36702
|
||||
Ref: #default-year36871
|
||||
Node: Declaring commodities37294
|
||||
Ref: #declaring-commodities37477
|
||||
Node: Default commodity38704
|
||||
Ref: #default-commodity38880
|
||||
Node: Market prices39516
|
||||
Ref: #market-prices39681
|
||||
Node: Declaring accounts40522
|
||||
Ref: #declaring-accounts40698
|
||||
Node: Account comments41623
|
||||
Ref: #account-comments41786
|
||||
Node: Account subdirectives42181
|
||||
Ref: #account-subdirectives42376
|
||||
Node: Account types42689
|
||||
Ref: #account-types42873
|
||||
Node: Account display order44517
|
||||
Ref: #account-display-order44687
|
||||
Node: Rewriting accounts45816
|
||||
Ref: #rewriting-accounts46001
|
||||
Node: Basic aliases46735
|
||||
Ref: #basic-aliases46881
|
||||
Node: Regex aliases47585
|
||||
Ref: #regex-aliases47756
|
||||
Node: Multiple aliases48474
|
||||
Ref: #multiple-aliases48649
|
||||
Node: end aliases49147
|
||||
Ref: #end-aliases49294
|
||||
Node: Default parent account49395
|
||||
Ref: #default-parent-account49561
|
||||
Node: Periodic transactions50445
|
||||
Ref: #periodic-transactions50627
|
||||
Node: Two spaces after the period expression51752
|
||||
Ref: #two-spaces-after-the-period-expression51997
|
||||
Node: Forecasting with periodic transactions52482
|
||||
Ref: #forecasting-with-periodic-transactions52772
|
||||
Node: Budgeting with periodic transactions54459
|
||||
Ref: #budgeting-with-periodic-transactions54698
|
||||
Node: Transaction modifiers55157
|
||||
Ref: #transaction-modifiers55320
|
||||
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57304
|
||||
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57605
|
||||
Node: EDITOR SUPPORT57983
|
||||
Ref: #editor-support58101
|
||||
Node: Assertions and ordering17544
|
||||
Ref: #assertions-and-ordering17730
|
||||
Node: Assertions and included files18430
|
||||
Ref: #assertions-and-included-files18671
|
||||
Node: Assertions and multiple -f options19004
|
||||
Ref: #assertions-and-multiple--f-options19258
|
||||
Node: Assertions and commodities19390
|
||||
Ref: #assertions-and-commodities19620
|
||||
Node: Assertions and prices20776
|
||||
Ref: #assertions-and-prices20988
|
||||
Node: Assertions and subaccounts21428
|
||||
Ref: #assertions-and-subaccounts21655
|
||||
Node: Assertions and virtual postings21979
|
||||
Ref: #assertions-and-virtual-postings22219
|
||||
Node: Assertions and precision22361
|
||||
Ref: #assertions-and-precision22552
|
||||
Node: Balance Assignments22819
|
||||
Ref: #balance-assignments23000
|
||||
Node: Balance assignments and prices24164
|
||||
Ref: #balance-assignments-and-prices24336
|
||||
Node: Transaction prices24560
|
||||
Ref: #transaction-prices24729
|
||||
Node: Comments26997
|
||||
Ref: #comments27131
|
||||
Node: Tags28301
|
||||
Ref: #tags28419
|
||||
Node: Directives29821
|
||||
Ref: #directives29964
|
||||
Node: Comment blocks35571
|
||||
Ref: #comment-blocks35716
|
||||
Node: Including other files35892
|
||||
Ref: #including-other-files36072
|
||||
Node: Default year36480
|
||||
Ref: #default-year36649
|
||||
Node: Declaring commodities37072
|
||||
Ref: #declaring-commodities37255
|
||||
Node: Default commodity38482
|
||||
Ref: #default-commodity38658
|
||||
Node: Market prices39294
|
||||
Ref: #market-prices39459
|
||||
Node: Declaring accounts40300
|
||||
Ref: #declaring-accounts40476
|
||||
Node: Account comments41401
|
||||
Ref: #account-comments41564
|
||||
Node: Account subdirectives41959
|
||||
Ref: #account-subdirectives42154
|
||||
Node: Account types42467
|
||||
Ref: #account-types42651
|
||||
Node: Account display order44295
|
||||
Ref: #account-display-order44465
|
||||
Node: Rewriting accounts45594
|
||||
Ref: #rewriting-accounts45779
|
||||
Node: Basic aliases46513
|
||||
Ref: #basic-aliases46659
|
||||
Node: Regex aliases47363
|
||||
Ref: #regex-aliases47534
|
||||
Node: Multiple aliases48252
|
||||
Ref: #multiple-aliases48427
|
||||
Node: end aliases48925
|
||||
Ref: #end-aliases49072
|
||||
Node: Default parent account49173
|
||||
Ref: #default-parent-account49339
|
||||
Node: Periodic transactions50223
|
||||
Ref: #periodic-transactions50405
|
||||
Node: Two spaces after the period expression51530
|
||||
Ref: #two-spaces-after-the-period-expression51775
|
||||
Node: Forecasting with periodic transactions52260
|
||||
Ref: #forecasting-with-periodic-transactions52550
|
||||
Node: Budgeting with periodic transactions54237
|
||||
Ref: #budgeting-with-periodic-transactions54476
|
||||
Node: Transaction modifiers54935
|
||||
Ref: #transaction-modifiers55098
|
||||
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57082
|
||||
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57383
|
||||
Node: EDITOR SUPPORT57761
|
||||
Ref: #editor-support57879
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -358,9 +358,9 @@ FILE FORMAT
|
||||
|
||||
Balance Assertions
|
||||
hledger supports Ledger-style balance assertions in journal files.
|
||||
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
|
||||
this example we assert the expected dollar balance in accounts a and b
|
||||
after each posting:
|
||||
These look like, for example, = EXPECTEDBALANCE following a posting's
|
||||
amount. Eg here we assert the expected dollar balance in accounts a
|
||||
and b after each posting:
|
||||
|
||||
2013/1/1
|
||||
a $1 =$1
|
||||
@ -374,7 +374,7 @@ FILE FORMAT
|
||||
and report an error if any of them fail. Balance assertions can pro-
|
||||
tect you from, eg, inadvertently disrupting reconciled balances while
|
||||
cleaning up old entries. You can disable them temporarily with the
|
||||
--ignore-assertions flag, which can be useful for troubleshooting or
|
||||
-I/--ignore-assertions flag, which can be useful for troubleshooting or
|
||||
for reading Ledger files.
|
||||
|
||||
Assertions and ordering
|
||||
@ -412,10 +412,9 @@ FILE FORMAT
|
||||
To assert the balance of more than one commodity in an account, you can
|
||||
write multiple postings, each asserting one commodity's balance.
|
||||
|
||||
You can make a stronger kind of balance assertion, by writing a double
|
||||
equals sign (==EXPECTEDBALANCE). This "complete" balance assertion
|
||||
asserts the absence of other commodities (or, that their balance is 0,
|
||||
which to hledger is equivalent.)
|
||||
You can make a stronger "total" balance assertion by writing a double
|
||||
equals sign (== EXPECTEDBALANCE). This asserts that there are no other
|
||||
unasserted commodities in the account (or, that their balance is 0).
|
||||
|
||||
2013/1/1
|
||||
a $1
|
||||
@ -460,22 +459,15 @@ FILE FORMAT
|
||||
ments do use them (see below).
|
||||
|
||||
Assertions and subaccounts
|
||||
Balance assertions do not count the balance from subaccounts; they
|
||||
check the posted account's exclusive balance. For example:
|
||||
The balance assertions above (= and ==) do not count the balance from
|
||||
subaccounts; they check the account's exclusive balance only. You can
|
||||
assert the balance including subaccounts by writing =* or ==*, eg:
|
||||
|
||||
1/1
|
||||
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
|
||||
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
|
||||
equity
|
||||
|
||||
The balance report's flat mode shows these exclusive balances more
|
||||
clearly:
|
||||
|
||||
$ hledger bal checking --flat
|
||||
1 checking
|
||||
1 checking:fund
|
||||
--------------------
|
||||
2
|
||||
2019/1/1
|
||||
equity:opening balances
|
||||
checking:a 5
|
||||
checking:b 5
|
||||
checking 1 ==* 11
|
||||
|
||||
Assertions and virtual postings
|
||||
Balance assertions are checked against all postings, both real and vir-
|
||||
@ -670,9 +662,6 @@ FILE FORMAT
|
||||
links to more detailed docs.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
direc- end subdi- purpose can affect (as of
|
||||
tive directive rec- 2018/06)
|
||||
tives
|
||||
@ -680,6 +669,10 @@ FILE FORMAT
|
||||
account any document account names, all entries in all
|
||||
text declare account types & dis- files, before or
|
||||
play order after
|
||||
|
||||
|
||||
|
||||
|
||||
alias end aliases rewrite account names following
|
||||
inline/included
|
||||
entries until end
|
||||
|
||||
@ -41,54 +41,15 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
|
||||
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
|
||||
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
|
||||
For more about this see hledger(1), hledger_journal(5) etc.
|
||||
.PP
|
||||
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 \f[C]\-\-serve\f[], it just runs the web app without exiting, and
|
||||
logs requests to the console.
|
||||
.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[] to change this, eg
|
||||
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
|
||||
.PP
|
||||
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
|
||||
if you are running multiple hledger\-web instances.
|
||||
.PP
|
||||
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
|
||||
port and path that appear in hyperlinks, useful eg for integrating
|
||||
hledger\-web within a larger website.
|
||||
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
|
||||
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
|
||||
80).
|
||||
.PP
|
||||
With \f[C]\-\-file\-url\f[] you can set a different base url for static
|
||||
files, eg for better caching or cookie\-less serving on high performance
|
||||
websites.
|
||||
.PP
|
||||
Note there is no built\-in access control (aside from listening on
|
||||
127.0.0.1 by default).
|
||||
So you will need to hide hledger\-web behind an authenticating proxy
|
||||
(such as apache or nginx) if you want to restrict who can see and add
|
||||
entries to your journal.
|
||||
.SH OPTIONS
|
||||
.PP
|
||||
Command\-line options and arguments may be used to set an initial filter
|
||||
on the data.
|
||||
This is not shown in the web UI, but it will be applied in addition to
|
||||
any search query entered there.
|
||||
.PP
|
||||
With journal and timeclock files (but not CSV files, currently) the web
|
||||
app detects changes made by other means and will show the new data on
|
||||
the next request.
|
||||
If a change makes the file unparseable, hledger\-web will show an error
|
||||
until the file has been fixed.
|
||||
.SH OPTIONS
|
||||
These filter options are not shown in the web UI, but it will be applied
|
||||
in addition to any search query entered there.
|
||||
.PP
|
||||
Note: if invoking hledger\-web as a hledger subcommand, write
|
||||
\f[C]\-\-\f[] before options as shown above.
|
||||
\f[C]\-\-\f[] before options, as shown in the synopsis above.
|
||||
.TP
|
||||
.B \f[C]\-\-serve\f[]
|
||||
serve and log requests, don\[aq]t browse or auto\-exit
|
||||
@ -119,6 +80,17 @@ serve them from another server for efficiency, you would set the url
|
||||
with this.
|
||||
.RS
|
||||
.RE
|
||||
.TP
|
||||
.B \f[C]\-\-capabilities=CAP[,CAP..]\f[]
|
||||
enable the view, add, and/or manage capabilities (default: view,add)
|
||||
.RS
|
||||
.RE
|
||||
.TP
|
||||
.B \f[C]\-\-capabilities\-header=HTTPHEADER\f[]
|
||||
read capabilities to enable from a HTTP header, like
|
||||
X\-Sandstorm\-Permissions (default: disabled)
|
||||
.RS
|
||||
.RE
|
||||
.PP
|
||||
hledger input options:
|
||||
.TP
|
||||
@ -286,6 +258,111 @@ show debug output (levels 1\-9, default: 1)
|
||||
A \@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[] argument before.)
|
||||
.PP
|
||||
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 \f[C]\-\-serve\f[], it just runs the web app without exiting, and
|
||||
logs requests to the console.
|
||||
.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[] to change this, eg
|
||||
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
|
||||
.PP
|
||||
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
|
||||
if you are running multiple hledger\-web instances.
|
||||
.PP
|
||||
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
|
||||
port and path that appear in hyperlinks, useful eg for integrating
|
||||
hledger\-web within a larger website.
|
||||
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
|
||||
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
|
||||
80).
|
||||
.PP
|
||||
With \f[C]\-\-file\-url\f[] you can set a different base url for static
|
||||
files, eg for better caching or cookie\-less serving on high performance
|
||||
websites.
|
||||
.SH PERMISSIONS
|
||||
.PP
|
||||
By default, hledger\-web allows anyone who can reach it to view the
|
||||
journal and to add new transactions, but not to change existing data.
|
||||
.PP
|
||||
You can restrict who can reach it by
|
||||
.IP \[bu] 2
|
||||
setting the IP address it listens on (see \f[C]\-\-host\f[] above).
|
||||
By default it listens on 127.0.0.1, accessible to all users on the local
|
||||
machine.
|
||||
.IP \[bu] 2
|
||||
putting it behind an authenticating proxy, using eg apache or nginx
|
||||
.IP \[bu] 2
|
||||
custom firewall rules
|
||||
.PP
|
||||
You can restrict what the users who reach it can do, by
|
||||
.IP \[bu] 2
|
||||
using the \f[C]\-\-capabilities=CAP[,CAP..]\f[] flag when you start it,
|
||||
enabling one or more of the following capabilities.
|
||||
The default value is \f[C]view,add\f[]:
|
||||
.RS 2
|
||||
.IP \[bu] 2
|
||||
\f[C]view\f[] \- allows viewing the journal file and all included files
|
||||
.IP \[bu] 2
|
||||
\f[C]add\f[] \- allows adding new transactions to the main journal file
|
||||
.IP \[bu] 2
|
||||
\f[C]manage\f[] \- allows editing, uploading or downloading the main or
|
||||
included files
|
||||
.RE
|
||||
.IP \[bu] 2
|
||||
using the \f[C]\-\-capabilities\-header=HTTPHEADER\f[] flag to specify a
|
||||
HTTP header from which it will read capabilities to enable.
|
||||
hledger\-web on Sandstorm uses the X\-Sandstorm\-Permissions header to
|
||||
integrate with Sandstorm\[aq]s permissions.
|
||||
This is disabled by default.
|
||||
.SH EDITING, UPLOADING, DOWNLOADING
|
||||
.PP
|
||||
If you enable the \f[C]manage\f[] capability mentioned above, you\[aq]ll
|
||||
see a new "spanner" button to the right of the search form.
|
||||
Clicking this will let you edit, upload, or download the journal file or
|
||||
any files it includes.
|
||||
.PP
|
||||
Note, unlike any other hledger command, in this mode you (or any
|
||||
visitor) can alter or wipe the data files.
|
||||
.PP
|
||||
Normally whenever a file is changed in this way, hledger\-web saves a
|
||||
numbered backup (assuming file permissions allow it, the disk is not
|
||||
full, etc.) hledger\-web is not aware of version control systems,
|
||||
currently; if you use one, you\[aq]ll have to arrange to commit the
|
||||
changes yourself (eg with a cron job or a file watcher like entr).
|
||||
.PP
|
||||
Changes which would leave the journal file(s) unparseable or non\-valid
|
||||
(eg with failing balance assertions) are prevented.
|
||||
(Probably.
|
||||
This needs re\-testing.)
|
||||
.SH RELOADING
|
||||
.PP
|
||||
hledger\-web detects changes made to the files by other means (eg if you
|
||||
edit it directly, outside of hledger\-web), and it will show the new
|
||||
data when you reload the page or navigate to a new page.
|
||||
If a change makes a file unparseable, hledger\-web will display an error
|
||||
message until the file has been fixed.
|
||||
.SH JSON API
|
||||
.PP
|
||||
In addition to the web UI, hledger\-web provides some JSON API routes.
|
||||
These are similar to the API provided by the hledger\-api tool, but it
|
||||
may be convenient to have them in hledger\-web also.
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
/accountnames
|
||||
/transactions
|
||||
/prices
|
||||
/commodities
|
||||
/accounts
|
||||
/accounttransactions/#AccountName
|
||||
\f[]
|
||||
.fi
|
||||
.SH ENVIRONMENT
|
||||
.PP
|
||||
\f[B]LEDGER_FILE\f[] The journal file path when not specified with
|
||||
|
||||
@ -25,56 +25,26 @@ 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_journal(5) etc.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
||||
are running multiple hledger-web instances.
|
||||
|
||||
You can use '--base-url' to change the protocol, hostname, port and
|
||||
path that appear in hyperlinks, useful eg for integrating hledger-web
|
||||
within a larger website. The default is 'http://HOST:PORT/' using the
|
||||
server's configured host address and TCP port (or 'http://HOST' if PORT
|
||||
is 80).
|
||||
|
||||
With '--file-url' you can set a different base url for static files,
|
||||
eg for better caching or cookie-less serving on high performance
|
||||
websites.
|
||||
|
||||
Note there is no built-in access control (aside from listening on
|
||||
127.0.0.1 by default). So you will need to hide hledger-web behind an
|
||||
authenticating proxy (such as apache or nginx) if you want to restrict
|
||||
who can see and add entries to your journal.
|
||||
|
||||
Command-line options and arguments may be used to set an initial
|
||||
filter on the data. This is not shown in the web UI, but it will be
|
||||
applied in addition to any search query entered there.
|
||||
|
||||
With journal and timeclock files (but not CSV files, currently) the
|
||||
web app detects changes made by other means and will show the new data
|
||||
on the next request. If a change makes the file unparseable,
|
||||
hledger-web will show an error until the file has been fixed.
|
||||
* Menu:
|
||||
|
||||
* OPTIONS::
|
||||
* PERMISSIONS::
|
||||
* EDITING UPLOADING DOWNLOADING::
|
||||
* RELOADING::
|
||||
* JSON API::
|
||||
|
||||
|
||||
File: hledger-web.info, Node: OPTIONS, Prev: Top, Up: Top
|
||||
File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
|
||||
|
||||
1 OPTIONS
|
||||
*********
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write '--' before
|
||||
options as shown above.
|
||||
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
|
||||
will be applied in addition to any search query entered there.
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write '--'
|
||||
before options, as shown in the synopsis above.
|
||||
|
||||
'--serve'
|
||||
|
||||
@ -96,6 +66,14 @@ options as shown above.
|
||||
normally serves static files itself, but if you wanted to serve
|
||||
them from another server for efficiency, you would set the url with
|
||||
this.
|
||||
'--capabilities=CAP[,CAP..]'
|
||||
|
||||
enable the view, add, and/or manage capabilities (default:
|
||||
view,add)
|
||||
'--capabilities-header=HTTPHEADER'
|
||||
|
||||
read capabilities to enable from a HTTP header, like
|
||||
X-Sandstorm-Permissions (default: disabled)
|
||||
|
||||
hledger input options:
|
||||
|
||||
@ -209,10 +187,129 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
||||
are running multiple hledger-web instances.
|
||||
|
||||
You can use '--base-url' to change the protocol, hostname, port and
|
||||
path that appear in hyperlinks, useful eg for integrating hledger-web
|
||||
within a larger website. The default is 'http://HOST:PORT/' using the
|
||||
server's configured host address and TCP port (or 'http://HOST' if PORT
|
||||
is 80).
|
||||
|
||||
With '--file-url' you can set a different base url for static files,
|
||||
eg for better caching or cookie-less serving on high performance
|
||||
websites.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
|
||||
|
||||
2 PERMISSIONS
|
||||
*************
|
||||
|
||||
By default, hledger-web allows anyone who can reach it to view the
|
||||
journal and to add new transactions, but not to change existing data.
|
||||
|
||||
You can restrict who can reach it by
|
||||
|
||||
* setting the IP address it listens on (see '--host' above). By
|
||||
default it listens on 127.0.0.1, accessible to all users on the
|
||||
local machine.
|
||||
* putting it behind an authenticating proxy, using eg apache or nginx
|
||||
* custom firewall rules
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
|
||||
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
|
||||
enabling one or more of the following capabilities. The default
|
||||
value is 'view,add':
|
||||
* 'view' - allows viewing the journal file and all included
|
||||
files
|
||||
* 'add' - allows adding new transactions to the main journal
|
||||
file
|
||||
* 'manage' - allows editing, uploading or downloading the main
|
||||
or included files
|
||||
|
||||
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
|
||||
|
||||
3 EDITING, UPLOADING, DOWNLOADING
|
||||
*********************************
|
||||
|
||||
If you enable the 'manage' capability mentioned above, you'll see a new
|
||||
"spanner" button to the right of the search form. Clicking this will
|
||||
let you edit, upload, or download the journal file or any files it
|
||||
includes.
|
||||
|
||||
Note, unlike any other hledger command, in this mode you (or any
|
||||
visitor) can alter or wipe the data files.
|
||||
|
||||
Normally whenever a file is changed in this way, hledger-web saves a
|
||||
numbered backup (assuming file permissions allow it, the disk is not
|
||||
full, etc.) hledger-web is not aware of version control systems,
|
||||
currently; if you use one, you'll have to arrange to commit the changes
|
||||
yourself (eg with a cron job or a file watcher like entr).
|
||||
|
||||
Changes which would leave the journal file(s) unparseable or
|
||||
non-valid (eg with failing balance assertions) are prevented.
|
||||
(Probably. This needs re-testing.)
|
||||
|
||||
|
||||
File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOADING DOWNLOADING, Up: Top
|
||||
|
||||
4 RELOADING
|
||||
***********
|
||||
|
||||
hledger-web detects changes made to the files by other means (eg if you
|
||||
edit it directly, outside of hledger-web), and it will show the new data
|
||||
when you reload the page or navigate to a new page. If a change makes a
|
||||
file unparseable, hledger-web will display an error message until the
|
||||
file has been fixed.
|
||||
|
||||
|
||||
File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top
|
||||
|
||||
5 JSON API
|
||||
**********
|
||||
|
||||
In addition to the web UI, hledger-web provides some JSON API routes.
|
||||
These are similar to the API provided by the hledger-api tool, but it
|
||||
may be convenient to have them in hledger-web also.
|
||||
|
||||
/accountnames
|
||||
/transactions
|
||||
/prices
|
||||
/commodities
|
||||
/accounts
|
||||
/accounttransactions/#AccountName
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top72
|
||||
Node: OPTIONS3160
|
||||
Ref: #options3245
|
||||
Node: OPTIONS1360
|
||||
Ref: #options1465
|
||||
Node: PERMISSIONS6555
|
||||
Ref: #permissions6694
|
||||
Node: EDITING UPLOADING DOWNLOADING7906
|
||||
Ref: #editing-uploading-downloading8087
|
||||
Node: RELOADING8921
|
||||
Ref: #reloading9055
|
||||
Node: JSON API9365
|
||||
Ref: #json-api9459
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -35,45 +35,13 @@ DESCRIPTION
|
||||
C:/Users/USER/.hledger.journal). For more about this see hledger(1),
|
||||
hledger_journal(5) etc.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Similarly, use --port to set a TCP port other than 5000, eg if you are
|
||||
running multiple hledger-web instances.
|
||||
|
||||
You can use --base-url to change the protocol, hostname, port and path
|
||||
that appear in hyperlinks, useful eg for integrating hledger-web within
|
||||
a larger website. The default is http://HOST:PORT/ using the server's
|
||||
configured host address and TCP port (or http://HOST if PORT is 80).
|
||||
|
||||
With --file-url you can set a different base url for static files, eg
|
||||
for better caching or cookie-less serving on high performance websites.
|
||||
|
||||
Note there is no built-in access control (aside from listening on
|
||||
127.0.0.1 by default). So you will need to hide hledger-web behind an
|
||||
authenticating proxy (such as apache or nginx) if you want to restrict
|
||||
who can see and add entries to your journal.
|
||||
|
||||
Command-line options and arguments may be used to set an initial filter
|
||||
on the data. This is not shown in the web UI, but it will be applied
|
||||
in addition to any search query entered there.
|
||||
|
||||
With journal and timeclock files (but not CSV files, currently) the web
|
||||
app detects changes made by other means and will show the new data on
|
||||
the next request. If a change makes the file unparseable, hledger-web
|
||||
will show an error until the file has been fixed.
|
||||
|
||||
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
|
||||
will be applied in addition to any search query entered there.
|
||||
|
||||
Note: if invoking hledger-web as a hledger subcommand, write -- before
|
||||
options as shown above.
|
||||
options, as shown in the synopsis above.
|
||||
|
||||
--serve
|
||||
serve and log requests, don't browse or auto-exit
|
||||
@ -95,6 +63,14 @@ OPTIONS
|
||||
them from another server for efficiency, you would set the url
|
||||
with this.
|
||||
|
||||
--capabilities=CAP[,CAP..]
|
||||
enable the view, add, and/or manage capabilities (default:
|
||||
view,add)
|
||||
|
||||
--capabilities-header=HTTPHEADER
|
||||
read capabilities to enable from a HTTP header, like X-Sand-
|
||||
storm-Permissions (default: disabled)
|
||||
|
||||
hledger input options:
|
||||
|
||||
-f FILE --file=FILE
|
||||
@ -203,6 +179,98 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
Similarly, use --port to set a TCP port other than 5000, eg if you are
|
||||
running multiple hledger-web instances.
|
||||
|
||||
You can use --base-url to change the protocol, hostname, port and path
|
||||
that appear in hyperlinks, useful eg for integrating hledger-web within
|
||||
a larger website. The default is http://HOST:PORT/ using the server's
|
||||
configured host address and TCP port (or http://HOST if PORT is 80).
|
||||
|
||||
With --file-url you can set a different base url for static files, eg
|
||||
for better caching or cookie-less serving on high performance websites.
|
||||
|
||||
PERMISSIONS
|
||||
By default, hledger-web allows anyone who can reach it to view the
|
||||
journal and to add new transactions, but not to change existing data.
|
||||
|
||||
You can restrict who can reach it by
|
||||
|
||||
o setting the IP address it listens on (see --host above). By default
|
||||
it listens on 127.0.0.1, accessible to all users on the local
|
||||
machine.
|
||||
|
||||
o putting it behind an authenticating proxy, using eg apache or nginx
|
||||
|
||||
o custom firewall rules
|
||||
|
||||
You can restrict what the users who reach it can do, by
|
||||
|
||||
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
|
||||
one or more of the following capabilities. The default value is
|
||||
view,add:
|
||||
|
||||
o view - allows viewing the journal file and all included files
|
||||
|
||||
o add - allows adding new transactions to the main journal file
|
||||
|
||||
o manage - allows editing, uploading or downloading the main or
|
||||
included files
|
||||
|
||||
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
|
||||
header from which it will read capabilities to enable. hledger-web
|
||||
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
||||
with Sandstorm's permissions. This is disabled by default.
|
||||
|
||||
EDITING, UPLOADING, DOWNLOADING
|
||||
If you enable the manage capability mentioned above, you'll see a new
|
||||
"spanner" button to the right of the search form. Clicking this will
|
||||
let you edit, upload, or download the journal file or any files it
|
||||
includes.
|
||||
|
||||
Note, unlike any other hledger command, in this mode you (or any visi-
|
||||
tor) can alter or wipe the data files.
|
||||
|
||||
Normally whenever a file is changed in this way, hledger-web saves a
|
||||
numbered backup (assuming file permissions allow it, the disk is not
|
||||
full, etc.) hledger-web is not aware of version control systems, cur-
|
||||
rently; if you use one, you'll have to arrange to commit the changes
|
||||
yourself (eg with a cron job or a file watcher like entr).
|
||||
|
||||
Changes which would leave the journal file(s) unparseable or non-valid
|
||||
(eg with failing balance assertions) are prevented. (Probably. This
|
||||
needs re-testing.)
|
||||
|
||||
RELOADING
|
||||
hledger-web detects changes made to the files by other means (eg if you
|
||||
edit it directly, outside of hledger-web), and it will show the new
|
||||
data when you reload the page or navigate to a new page. If a change
|
||||
makes a file unparseable, hledger-web will display an error message
|
||||
until the file has been fixed.
|
||||
|
||||
JSON API
|
||||
In addition to the web UI, hledger-web provides some JSON API routes.
|
||||
These are similar to the API provided by the hledger-api tool, but it
|
||||
may be convenient to have them in hledger-web also.
|
||||
|
||||
/accountnames
|
||||
/transactions
|
||||
/prices
|
||||
/commodities
|
||||
/accounts
|
||||
/accounttransactions/#AccountName
|
||||
|
||||
ENVIRONMENT
|
||||
LEDGER_FILE The journal file path when not specified with -f. Default:
|
||||
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
|
||||
|
||||
Loading…
Reference in New Issue
Block a user