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

regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-02-20 13:15:41 -08:00
parent 861baadb2b
commit 8620e5414f
6 changed files with 697 additions and 479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
hledger-lib/hledger_journal.5
View File

@ -491,10 +491,10 @@ which is more correct and provides better error checking.
.SS Balance Assertions .SS Balance Assertions
.PP .PP
hledger supports Ledger\-style balance assertions in journal files. hledger supports Ledger\-style balance assertions in journal files.
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s These look like, for example, \f[C]=\ EXPECTEDBALANCE\f[] following a
amount. posting\[aq]s amount.
Eg in this example we assert the expected dollar balance in accounts a Eg here we assert the expected dollar balance in accounts a and b after
and b after each posting: each posting:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -513,7 +513,7 @@ and report an error if any of them fail.
Balance assertions can protect you from, eg, inadvertently disrupting Balance assertions can protect you from, eg, inadvertently disrupting
reconciled balances while cleaning up old entries. reconciled balances while cleaning up old entries.
You can disable them temporarily with the 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. troubleshooting or for reading Ledger files.
.SS Assertions and ordering .SS Assertions and ordering
.PP .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 To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity\[aq]s balance. write multiple postings, each asserting one commodity\[aq]s balance.
.PP .PP
You can make a stronger kind of balance assertion, by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (\f[C]==EXPECTEDBALANCE\f[]). equals sign (\f[C]==\ EXPECTEDBALANCE\f[]).
This "complete" balance assertion asserts the absence of other This asserts that there are no other unasserted commodities in the
commodities (or, that their balance is 0, which to hledger is account (or, that their balance is 0).
equivalent.)
.IP .IP
.nf .nf
\f[C] \f[C]
@ -619,29 +618,19 @@ generate balance assertions with prices), and because balance
\f[I]assignments\f[] do use them (see below). \f[I]assignments\f[] do use them (see below).
.SS Assertions and subaccounts .SS Assertions and subaccounts
.PP .PP
Balance assertions do not count the balance from subaccounts; they check The balance assertions above (\f[C]=\f[] and \f[C]==\f[]) do not count
the posted account\[aq]s exclusive balance. the balance from subaccounts; they check the account\[aq]s exclusive
For example: balance only.
You can assert the balance including subaccounts by writing \f[C]=*\f[]
or \f[C]==*\f[], eg:
.IP .IP
.nf .nf
\f[C] \f[C]
1/1 2019/1/1
\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1 \ \ equity:opening\ balances
\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1 \ \ checking:a\ \ \ \ \ \ \ 5
\ \ equity \ \ checking:b\ \ \ \ \ \ \ 5
\f[] \ \ checking\ \ \ \ \ \ \ \ \ 1\ \ ==*\ 11
.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
\f[] \f[]
.fi .fi
.SS Assertions and virtual postings .SS Assertions and virtual postings

194
hledger-lib/hledger_journal.info
View File

@ -449,9 +449,9 @@ File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignment
====================== ======================
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in These look like, for example, '= EXPECTEDBALANCE' following a posting's
this example we assert the expected dollar balance in accounts a and b amount. Eg here we assert the expected dollar balance in accounts a and
after each posting: b after each posting:
2013/1/1 2013/1/1
a $1 =$1 a $1 =$1
@ -465,8 +465,8 @@ after each posting:
assertions and report an error if any of them fail. Balance assertions assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with while cleaning up old entries. You can disable them temporarily with
the '--ignore-assertions' flag, which can be useful for troubleshooting the '-I/--ignore-assertions' flag, which can be useful for
or for reading Ledger files. troubleshooting or for reading Ledger files.
* Menu: * Menu:
* Assertions and ordering:: * 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 To assert the balance of more than one commodity in an account, you
can write multiple postings, each asserting one commodity's balance. can write multiple postings, each asserting one commodity's balance.
You can make a stronger kind of balance assertion, by writing a You can make a stronger "total" balance assertion by writing a double
double equals sign ('==EXPECTEDBALANCE'). This "complete" balance equals sign ('== EXPECTEDBALANCE'). This asserts that there are no
assertion asserts the absence of other commodities (or, that their other unasserted commodities in the account (or, that their balance is
balance is 0, which to hledger is equivalent.) 0).
2013/1/1 2013/1/1
a $1 a $1
@ -591,22 +591,16 @@ File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions
1.9.6 Assertions and subaccounts 1.9.6 Assertions and subaccounts
-------------------------------- --------------------------------
Balance assertions do not count the balance from subaccounts; they check The balance assertions above ('=' and '==') do not count the balance
the posted account's exclusive balance. For example: from subaccounts; they check the account's exclusive balance only. You
can assert the balance including subaccounts by writing '=*' or '==*',
eg:
1/1 2019/1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 equity:opening balances
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 checking:a 5
equity checking:b 5
checking 1 ==* 11
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
 
File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions 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 Ref: #virtual-postings15191
Node: Balance Assertions16411 Node: Balance Assertions16411
Ref: #balance-assertions16586 Ref: #balance-assertions16586
Node: Assertions and ordering17537 Node: Assertions and ordering17544
Ref: #assertions-and-ordering17723 Ref: #assertions-and-ordering17730
Node: Assertions and included files18423 Node: Assertions and included files18430
Ref: #assertions-and-included-files18664 Ref: #assertions-and-included-files18671
Node: Assertions and multiple -f options18997 Node: Assertions and multiple -f options19004
Ref: #assertions-and-multiple--f-options19251 Ref: #assertions-and-multiple--f-options19258
Node: Assertions and commodities19383 Node: Assertions and commodities19390
Ref: #assertions-and-commodities19613 Ref: #assertions-and-commodities19620
Node: Assertions and prices20801 Node: Assertions and prices20776
Ref: #assertions-and-prices21013 Ref: #assertions-and-prices20988
Node: Assertions and subaccounts21453 Node: Assertions and subaccounts21428
Ref: #assertions-and-subaccounts21680 Ref: #assertions-and-subaccounts21655
Node: Assertions and virtual postings22201 Node: Assertions and virtual postings21979
Ref: #assertions-and-virtual-postings22441 Ref: #assertions-and-virtual-postings22219
Node: Assertions and precision22583 Node: Assertions and precision22361
Ref: #assertions-and-precision22774 Ref: #assertions-and-precision22552
Node: Balance Assignments23041 Node: Balance Assignments22819
Ref: #balance-assignments23222 Ref: #balance-assignments23000
Node: Balance assignments and prices24386 Node: Balance assignments and prices24164
Ref: #balance-assignments-and-prices24558 Ref: #balance-assignments-and-prices24336
Node: Transaction prices24782 Node: Transaction prices24560
Ref: #transaction-prices24951 Ref: #transaction-prices24729
Node: Comments27219 Node: Comments26997
Ref: #comments27353 Ref: #comments27131
Node: Tags28523 Node: Tags28301
Ref: #tags28641 Ref: #tags28419
Node: Directives30043 Node: Directives29821
Ref: #directives30186 Ref: #directives29964
Node: Comment blocks35793 Node: Comment blocks35571
Ref: #comment-blocks35938 Ref: #comment-blocks35716
Node: Including other files36114 Node: Including other files35892
Ref: #including-other-files36294 Ref: #including-other-files36072
Node: Default year36702 Node: Default year36480
Ref: #default-year36871 Ref: #default-year36649
Node: Declaring commodities37294 Node: Declaring commodities37072
Ref: #declaring-commodities37477 Ref: #declaring-commodities37255
Node: Default commodity38704 Node: Default commodity38482
Ref: #default-commodity38880 Ref: #default-commodity38658
Node: Market prices39516 Node: Market prices39294
Ref: #market-prices39681 Ref: #market-prices39459
Node: Declaring accounts40522 Node: Declaring accounts40300
Ref: #declaring-accounts40698 Ref: #declaring-accounts40476
Node: Account comments41623 Node: Account comments41401
Ref: #account-comments41786 Ref: #account-comments41564
Node: Account subdirectives42181 Node: Account subdirectives41959
Ref: #account-subdirectives42376 Ref: #account-subdirectives42154
Node: Account types42689 Node: Account types42467
Ref: #account-types42873 Ref: #account-types42651
Node: Account display order44517 Node: Account display order44295
Ref: #account-display-order44687 Ref: #account-display-order44465
Node: Rewriting accounts45816 Node: Rewriting accounts45594
Ref: #rewriting-accounts46001 Ref: #rewriting-accounts45779
Node: Basic aliases46735 Node: Basic aliases46513
Ref: #basic-aliases46881 Ref: #basic-aliases46659
Node: Regex aliases47585 Node: Regex aliases47363
Ref: #regex-aliases47756 Ref: #regex-aliases47534
Node: Multiple aliases48474 Node: Multiple aliases48252
Ref: #multiple-aliases48649 Ref: #multiple-aliases48427
Node: end aliases49147 Node: end aliases48925
Ref: #end-aliases49294 Ref: #end-aliases49072
Node: Default parent account49395 Node: Default parent account49173
Ref: #default-parent-account49561 Ref: #default-parent-account49339
Node: Periodic transactions50445 Node: Periodic transactions50223
Ref: #periodic-transactions50627 Ref: #periodic-transactions50405
Node: Two spaces after the period expression51752 Node: Two spaces after the period expression51530
Ref: #two-spaces-after-the-period-expression51997 Ref: #two-spaces-after-the-period-expression51775
Node: Forecasting with periodic transactions52482 Node: Forecasting with periodic transactions52260
Ref: #forecasting-with-periodic-transactions52772 Ref: #forecasting-with-periodic-transactions52550
Node: Budgeting with periodic transactions54459 Node: Budgeting with periodic transactions54237
Ref: #budgeting-with-periodic-transactions54698 Ref: #budgeting-with-periodic-transactions54476
Node: Transaction modifiers55157 Node: Transaction modifiers54935
Ref: #transaction-modifiers55320 Ref: #transaction-modifiers55098
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57304 Node: Auto postings and transaction balancing / inferred amounts / balance assertions57082
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57605 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57383
Node: EDITOR SUPPORT57983 Node: EDITOR SUPPORT57761
Ref: #editor-support58101 Ref: #editor-support57879
 
End Tag Table End Tag Table

45
hledger-lib/hledger_journal.txt
View File

@ -358,9 +358,9 @@ FILE FORMAT
Balance Assertions Balance Assertions
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in These look like, for example, = EXPECTEDBALANCE following a posting's
this example we assert the expected dollar balance in accounts a and b amount. Eg here we assert the expected dollar balance in accounts a
after each posting: and b after each posting:
2013/1/1 2013/1/1
a $1 =$1 a $1 =$1
@ -374,7 +374,7 @@ FILE FORMAT
and report an error if any of them fail. Balance assertions can pro- and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the 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. for reading Ledger files.
Assertions and ordering Assertions and ordering
@ -412,10 +412,9 @@ FILE FORMAT
To assert the balance of more than one commodity in an account, you can To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance. write multiple postings, each asserting one commodity's balance.
You can make a stronger kind of balance assertion, by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (==EXPECTEDBALANCE). This "complete" balance assertion equals sign (== EXPECTEDBALANCE). This asserts that there are no other
asserts the absence of other commodities (or, that their balance is 0, unasserted commodities in the account (or, that their balance is 0).
which to hledger is equivalent.)
2013/1/1 2013/1/1
a $1 a $1
@ -460,22 +459,15 @@ FILE FORMAT
ments do use them (see below). ments do use them (see below).
Assertions and subaccounts Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they The balance assertions above (= and ==) do not count the balance from
check the posted account's exclusive balance. For example: subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg:
1/1 2019/1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 equity:opening balances
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 checking:a 5
equity checking:b 5
checking 1 ==* 11
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
Assertions and virtual postings Assertions and virtual postings
Balance assertions are checked against all postings, both real and vir- Balance assertions are checked against all postings, both real and vir-
@ -670,9 +662,6 @@ FILE FORMAT
links to more detailed docs. links to more detailed docs.
direc- end subdi- purpose can affect (as of direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06) tive directive rec- 2018/06)
tives tives
@ -680,6 +669,10 @@ FILE FORMAT
account any document account names, all entries in all account any document account names, all entries in all
text declare account types & dis- files, before or text declare account types & dis- files, before or
play order after play order after
alias end aliases rewrite account names following alias end aliases rewrite account names following
inline/included inline/included
entries until end entries until end

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

@ -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, \f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
For more about this see hledger(1), hledger_journal(5) etc. For more about this see hledger(1), hledger_journal(5) etc.
.PP .SH OPTIONS
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.
.PP .PP
Command\-line options and arguments may be used to set an initial filter Command\-line options and arguments may be used to set an initial filter
on the data. on the data.
This is not shown in the web UI, but it will be applied in addition to These filter options are not shown in the web UI, but it will be applied
any search query entered there. 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
.PP .PP
Note: if invoking hledger\-web as a hledger subcommand, write 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 .TP
.B \f[C]\-\-serve\f[] .B \f[C]\-\-serve\f[]
serve and log requests, don\[aq]t browse or auto\-exit 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. with this.
.RS .RS
.RE .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 .PP
hledger input options: hledger input options:
.TP .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 A \@FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. contain one command line option/argument per line.
(To prevent this, insert a \f[C]\-\-\f[] argument before.) (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 .SH ENVIRONMENT
.PP .PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with \f[B]LEDGER_FILE\f[] The journal file path when not specified with

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

@ -25,56 +25,26 @@ journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps '$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), 'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc. 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: * Menu:
* OPTIONS:: * 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 1 OPTIONS
********* *********
Note: if invoking hledger-web as a hledger subcommand, write '--' before Command-line options and arguments may be used to set an initial filter
options as shown above. 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' '--serve'
@ -96,6 +66,14 @@ options as shown above.
normally serves static files itself, but if you wanted to serve normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url with them from another server for efficiency, you would set the url with
this. 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: hledger input options:
@ -209,10 +187,129 @@ the last one takes precedence.
should contain one command line option/argument per line. (To prevent should contain one command line option/argument per line. (To prevent
this, insert a '--' argument before.) 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: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS3160 Node: OPTIONS1360
Ref: #options3245 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 End Tag Table

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

@ -35,45 +35,13 @@ DESCRIPTION
C:/Users/USER/.hledger.journal). For more about this see hledger(1), C:/Users/USER/.hledger.journal). For more about this see hledger(1),
hledger_journal(5) etc. 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 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 Note: if invoking hledger-web as a hledger subcommand, write -- before
options as shown above. options, as shown in the synopsis above.
--serve --serve
serve and log requests, don't browse or auto-exit 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 them from another server for efficiency, you would set the url
with this. 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: hledger input options:
-f FILE --file=FILE -f FILE --file=FILE
@ -203,6 +179,98 @@ OPTIONS
contain one command line option/argument per line. (To prevent this, contain one command line option/argument per line. (To prevent this,
insert a -- argument before.) 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 ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default: LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-