diff options
| -rw-r--r-- | CHANGES.md | 4 | ||||
| -rw-r--r-- | hledger-web.1 | 2 | ||||
| -rw-r--r-- | hledger-web.cabal | 14 | ||||
| -rw-r--r-- | hledger-web.info | 332 | ||||
| -rw-r--r-- | hledger-web.txt | 118 |
5 files changed, 242 insertions, 228 deletions
@@ -1,6 +1,10 @@ User-visible changes in hledger-web. See also the hledger changelog. +# 1.20.4 2021-01-29 + +- Use hledger 1.20.4. + # 1.20.3 2021-01-14 - Use hledger 1.20.3. diff --git a/hledger-web.1 b/hledger-web.1 index ba12e29..2d4e762 100644 --- a/hledger-web.1 +++ b/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.3 " "hledger User Manuals" +.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.4 " "hledger User Manuals" diff --git a/hledger-web.cabal b/hledger-web.cabal index 095a65b..9ca6836 100644 --- a/hledger-web.cabal +++ b/hledger-web.cabal @@ -4,10 +4,10 @@ cabal-version: 1.12 -- -- see: https://github.com/sol/hpack -- --- hash: 348251d2065835646436e6115f6c0245cab922dba5119b9c476376c784f2194a +-- hash: 4d6a3569da376b1fdb1d8a7bbd69b24d6c64f28a67423fb84318b64a36282cbe name: hledger-web -version: 1.20.3 +version: 1.20.4 synopsis: Web-based user interface for the hledger accounting system description: A simple web-based user interface for the hledger accounting system, providing a more modern UI than the command-line or terminal interfaces. @@ -152,7 +152,7 @@ library hs-source-dirs: ./. ghc-options: -Wall -fwarn-tabs -Wcompat -Wincomplete-uni-patterns -Wincomplete-record-updates -Wredundant-constraints - cpp-options: -DVERSION="1.20.3" + cpp-options: -DVERSION="1.20.4" build-depends: Decimal >=0.5.1 , aeson >=1 @@ -171,8 +171,8 @@ library , extra >=1.6.3 , filepath , hjsmin - , hledger >=1.20.3 && <1.21 - , hledger-lib >=1.20.3 && <1.21 + , hledger >=1.20.4 && <1.21 + , hledger-lib >=1.20.4 && <1.21 , hspec , http-client , http-conduit @@ -212,7 +212,7 @@ executable hledger-web hs-source-dirs: app ghc-options: -Wall -fwarn-tabs -Wcompat -Wincomplete-uni-patterns -Wincomplete-record-updates -Wredundant-constraints - cpp-options: -DVERSION="1.20.3" + cpp-options: -DVERSION="1.20.4" build-depends: base , hledger-web @@ -232,7 +232,7 @@ test-suite test hs-source-dirs: test ghc-options: -Wall -fwarn-tabs -Wcompat -Wincomplete-uni-patterns -Wincomplete-record-updates -Wredundant-constraints - cpp-options: -DVERSION="1.20.3" + cpp-options: -DVERSION="1.20.4" build-depends: base , hledger diff --git a/hledger-web.info b/hledger-web.info index 24832db..dafdd72 100644 --- a/hledger-web.info +++ b/hledger-web.info @@ -1,39 +1,39 @@ -This is hledger-web.info, produced by makeinfo version 6.7 from stdin. +This is hledger-web/hledger-web.info, produced by makeinfo version 4.8 +from stdin. -File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) +File: hledger-web.info, Node: Top, Up: (dir) hledger-web(1) ************** A web interface (WUI) for the hledger accounting tool. - 'hledger-web [OPTIONS]' -'hledger web -- [OPTIONS]' + `hledger-web [OPTIONS]' +`hledger web -- [OPTIONS]' 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 +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 + 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. +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 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 -against data loss when running an unprotected instance, it writes a -numbered backup of the main journal file (only ?) on every edit. +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. 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), +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. * Menu: @@ -54,165 +54,162 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top ********* 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 +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 '--' + Note: if invoking hledger-web as a hledger subcommand, write `--' before options, as shown in the synopsis above. -'--serve' - +`--serve' serve and log requests, don't browse or auto-exit -'--serve-api' +`--serve-api' like -serve, but serve only the JSON web API, without the server-side web UI -'--host=IPADDR' +`--host=IPADDR' listen on this IP address (default: 127.0.0.1) -'--port=PORT' +`--port=PORT' listen on this TCP port (default: 5000) -'--socket=SOCKETFILE' +`--socket=SOCKETFILE' use a unix domain socket file to listen for requests instead of a - TCP socket. Implies '--serve'. It can only be used if the - operating system can provide this type of socket. -'--base-url=URL' + TCP socket. Implies `--serve'. It can only be used if the operating + system can provide this type of socket. +`--base-url=URL' set the base url (default: http://IPADDR:PORT). You would change this when sharing over the network, or integrating within a larger website. -'--file-url=URL' - set the static files url (default: BASEURL/static). hledger-web +`--file-url=URL' + set the static files url (default: BASEURL/static). hledger-web 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..]' + 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' +`--capabilities-header=HTTPHEADER' read capabilities to enable from a HTTP header, like X-Sandstorm-Permissions (default: disabled) -'--test' - run hledger-web's tests and exit. hspec test runner args may +`--test' + run hledger-web's tests and exit. hspec test runner args may follow a -, eg: hledger-web -test - -help hledger input options: -'-f FILE --file=FILE' - - use a different input file. For stdin, use - (default: - '$LEDGER_FILE' or '$HOME/.hledger.journal') -'--rules-file=RULESFILE' +`-f FILE --file=FILE' + use a different input file. For stdin, use - (default: + `$LEDGER_FILE' or `$HOME/.hledger.journal') +`--rules-file=RULESFILE' Conversion rules file to use when reading CSV (default: FILE.rules) -'--separator=CHAR' +`--separator=CHAR' Field separator to expect when reading CSV (default: ',') -'--alias=OLD=NEW' +`--alias=OLD=NEW' rename accounts named OLD to NEW -'--anon' +`--anon' anonymize accounts and payees -'--pivot FIELDNAME' +`--pivot FIELDNAME' use some other field or tag for the account name -'-I --ignore-assertions' +`-I --ignore-assertions' disable balance assertion checks (note: does not disable balance assignments) -'-s --strict' +`-s --strict' do extra error checking (check that all posted accounts are declared) hledger reporting options: -'-b --begin=DATE' - +`-b --begin=DATE' include postings/txns on or after this date -'-e --end=DATE' +`-e --end=DATE' include postings/txns before this date -'-D --daily' +`-D --daily' multiperiod/multicolumn report by day -'-W --weekly' +`-W --weekly' multiperiod/multicolumn report by week -'-M --monthly' +`-M --monthly' multiperiod/multicolumn report by month -'-Q --quarterly' +`-Q --quarterly' multiperiod/multicolumn report by quarter -'-Y --yearly' +`-Y --yearly' multiperiod/multicolumn report by year -'-p --period=PERIODEXP' +`-p --period=PERIODEXP' set start date, end date, and/or reporting interval all at once using period expressions syntax -'--date2' +`--date2' match the secondary date instead (see command help for other effects) -'-U --unmarked' +`-U --unmarked' include only unmarked postings/txns (can combine with -P or -C) -'-P --pending' +`-P --pending' include only pending postings/txns -'-C --cleared' +`-C --cleared' include only cleared postings/txns -'-R --real' +`-R --real' include only non-virtual postings -'-NUM --depth=NUM' +`-NUM --depth=NUM' hide/aggregate accounts or postings more than NUM levels deep -'-E --empty' +`-E --empty' show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -'-B --cost' +`-B --cost' convert amounts to their cost/selling amount at transaction time -'-V --market' +`-V --market' convert amounts to their market value in default valuation commodities -'-X --exchange=COMM' +`-X --exchange=COMM' convert amounts to their market value in commodity COMM -'--value' +`--value' convert amounts to cost or market value, more flexibly than -B/-V/-X -'--infer-value' +`--infer-value' with -V/-X/-value, also infer market prices from transactions -'--auto' +`--auto' apply automated posting rules to modify transactions. -'--forecast' +`--forecast' generate future transactions from periodic transaction rules, for - the next 6 months or till report end date. In hledger-ui, also + the next 6 months or till report end date. In hledger-ui, also make ordinary future transactions visible. -'--color=WHEN (or --colour=WHEN)' +`--color=WHEN (or --colour=WHEN)' Should color-supporting commands use ANSI color codes in text output. 'auto' (default): whenever stdout seems to be a color-supporting terminal. 'always' or 'yes': always, useful eg - when piping output into 'less -R'. 'never' or 'no': never. A + when piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. When a reporting option appears more than once in the command line, @@ -222,56 +219,56 @@ the last one takes precedence. hledger help options: -'-h --help' - +`-h --help' show general usage (or after COMMAND, command usage) -'--version' +`--version' show version -'--debug[=N]' +`--debug[=N]' 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 '--' argument before.) +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 +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 +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 +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 + Similarly, use `--port' to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. - Both of these options are ignored when '--socket' is used. In this -case, it creates an 'AF_UNIX' socket file at the supplied path and uses -that for communication. This is an alternative way of running multiple -hledger-web instances behind a reverse proxy that handles authentication -for different users. The path can be derived in a predictable way, eg -by using the username within the path. As an example, 'nginx' as -reverse proxy can use the variable '$remote_user' to derive a path from -the username used in a HTTP basic authentication. The following -'proxy_pass' directive allows access to all 'hledger-web' instances that -created a socket in '/tmp/hledger/': + Both of these options are ignored when `--socket' is used. In this +case, it creates an `AF_UNIX' socket file at the supplied path and uses +that for communication. This is an alternative way of running multiple +hledger-web instances behind a reverse proxy that handles +authentication for different users. The path can be derived in a +predictable way, eg by using the username within the path. As an +example, `nginx' as reverse proxy can use the variable `$remote_user' +to derive a path from the username used in a HTTP basic authentication. +The following `proxy_pass' directive allows access to all `hledger-web' +instances that created a socket in `/tmp/hledger/': + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; - You can use '--base-url' to change the protocol, hostname, port and + 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 +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, + 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. @@ -286,28 +283,32 @@ 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 + * 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 + * 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 + + * `add' - allows adding new transactions to the main journal file - * 'manage' - allows editing, uploading or downloading the main + + * `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 + * 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. + with Sandstorm's permissions. This is disabled by default. File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top @@ -315,8 +316,8 @@ File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, 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 +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. @@ -325,13 +326,13 @@ 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, +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.) +(Probably. This needs re-testing.) File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOADING DOWNLOADING, Up: Top @@ -341,7 +342,7 @@ File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOAD 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 +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. @@ -355,14 +356,16 @@ File: hledger-web.info, Node: JSON API, Next: ENVIRONMENT, Prev: RELOADING, ********** In addition to the web UI, hledger-web also serves a JSON API that can -be used to get data or add new transactions. If you want the JSON API -only, you can use the '--serve-api' flag. Eg: +be used to get data or add new transactions. If you want the JSON API +only, you can use the `--serve-api' flag. Eg: + $ hledger-web -f examples/sample.journal --serve-api ... You can get JSON data from these routes: + /version /accountnames /transactions @@ -375,6 +378,7 @@ $ hledger-web -f examples/sample.journal --serve-api command). (hledger-web's JSON does not include newlines, here we use python to prettify it): + $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool [ "assets", @@ -394,6 +398,7 @@ $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool Or all transactions: + $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool [ { @@ -415,24 +420,25 @@ $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool Most of the JSON corresponds to hledger's data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click -on the various data types, eg Transaction. And for a higher level +on the various data types, eg Transaction. And for a higher level understanding, see the journal manual. In some cases there is outer JSON corresponding to a "Report" type. -To understand that, go to the Hledger.Web.Handler.MiscR haddock and look -at the source for the appropriate handler to see what it returns. Eg -for '/accounttransactions' it's getAccounttransactionsR, returning a -"'accountTransactionsReport ...'". Looking up the haddock for that we +To understand that, go to the Hledger.Web.Handler.MiscR haddock and +look at the source for the appropriate handler to see what it returns. +Eg for `/accounttransactions' it's getAccounttransactionsR, returning a +"`accountTransactionsReport ...'". Looking up the haddock for that we can see that /accounttransactions returns an AccountTransactionsReport, which consists of a report title and a list of AccountTransactionsReportItem (etc). You can add a new transaction to the journal with a PUT request to -'/add', if hledger-web was started with the 'add' capability (enabled by -default). The payload must be the full, exact JSON representation of a -hledger transaction (partial data won't do). You can get sample JSON -from hledger-web's '/transactions' or '/accounttransactions', or you can -export it with hledger-lib, eg like so: +`/add', if hledger-web was started with the `add' capability (enabled +by default). The payload must be the full, exact JSON representation of +a hledger transaction (partial data won't do). You can get sample JSON +from hledger-web's `/transactions' or `/accounttransactions', or you +can export it with hledger-lib, eg like so: + .../hledger$ stack ghci hledger-lib >>> writeJsonFile "txn.json" (head $ jtxns samplejournal) @@ -441,6 +447,7 @@ export it with hledger-lib, eg like so: Here's how it looks as of hledger-1.17 (remember, this JSON corresponds to hledger's Transaction and related data types): + { "tcomment": "", "tpostings": [ @@ -527,9 +534,10 @@ corresponds to hledger's Transaction and related data types): "tstatus": "Unmarked" } - And here's how to test adding it with curl. This should add a new + And here's how to test adding it with curl. This should add a new entry to your journal: + $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json @@ -538,25 +546,26 @@ File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up: 6 ENVIRONMENT ************* -*LEDGER_FILE* The journal file path when not specified with '-f'. -Default: '~/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). +*LEDGER_FILE* The journal file path when not specified with `-f'. +Default: `~/.hledger.journal' (on windows, perhaps +`C:/Users/USER/.hledger.journal'). - A typical value is '~/DIR/YYYY.journal', where DIR is a -version-controlled finance directory and YYYY is the current year. Or -'~/DIR/current.journal', where current.journal is a symbolic link to + A typical value is `~/DIR/YYYY.journal', where DIR is a +version-controlled finance directory and YYYY is the current year. Or +`~/DIR/current.journal', where current.journal is a symbolic link to YYYY.journal. - On Mac computers, you can set this and other environment variables in -a more thorough way that also affects applications started from the GUI -(say, an Emacs dock icon). Eg on MacOS Catalina I have a -'~/.MacOSX/environment.plist' file containing + On Mac computers, you can set this and other environment variables +in a more thorough way that also affects applications started from the +GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a +`~/.MacOSX/environment.plist' file containing + { "LEDGER_FILE" : "~/finance/current.journal" } - To see the effect you may need to 'killall Dock', or reboot. + To see the effect you may need to `killall Dock', or reboot. File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top @@ -565,9 +574,9 @@ File: hledger-web.info, Node: FILES, Next: BUGS, Prev: ENVIRONMENT, Up: Top ******* 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'). +timedot, or CSV format specified with `-f', or `$LEDGER_FILE', or +`$HOME/.hledger.journal' (on windows, perhaps +`C:/Users/USER/.hledger.journal'). File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top @@ -575,10 +584,10 @@ File: hledger-web.info, Node: BUGS, Prev: FILES, Up: Top 8 BUGS ****** -The need to precede options with '--' when invoked from hledger is +The need to precede options with `--' when invoked from hledger is awkward. - '-f-' doesn't work (hledger-web can't read from stdin). + `-f-' doesn't work (hledger-web can't read from stdin). Query arguments and some hledger options are ignored. @@ -586,24 +595,25 @@ awkward. Does not work well on small screens. + Tag Table: -Node: Top72 -Node: OPTIONS1707 -Ref: #options1812 -Node: PERMISSIONS8911 -Ref: #permissions9050 -Node: EDITING UPLOADING DOWNLOADING10262 -Ref: #editing-uploading-downloading10443 -Node: RELOADING11277 -Ref: #reloading11411 -Node: JSON API11844 -Ref: #json-api11958 -Node: ENVIRONMENT17448 -Ref: #environment17564 -Node: FILES18297 -Ref: #files18397 -Node: BUGS18610 -Ref: #bugs18688 +Node: Top84 +Node: OPTIONS1696 +Ref: #options1801 +Node: PERMISSIONS8880 +Ref: #permissions9019 +Node: EDITING UPLOADING DOWNLOADING10231 +Ref: #editing-uploading-downloading10412 +Node: RELOADING11243 +Ref: #reloading11377 +Node: JSON API11809 +Ref: #json-api11923 +Node: ENVIRONMENT17412 +Ref: #environment17528 +Node: FILES18260 +Ref: #files18360 +Node: BUGS18573 +Ref: #bugs18651 End Tag Table diff --git a/hledger-web.txt b/hledger-web.txt index 73d2d23..ea808a4 100644 --- a/hledger-web.txt +++ b/hledger-web.txt @@ -19,9 +19,9 @@ DESCRIPTION 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 (ac- - counts, the current account register, balance charts) and allowing his- - tory-aware data entry, interactive searching, and bookmarking. + 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 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 @@ -58,8 +58,8 @@ OPTIONS --socket=SOCKETFILE use a unix domain socket file to listen for requests instead of - a TCP socket. Implies --serve. It can only be used if the op- - erating system can provide this type of socket. + a TCP socket. Implies --serve. It can only be used if the + operating system can provide this type of socket. --base-url=URL set the base url (default: http://IPADDR:PORT). You would @@ -109,8 +109,8 @@ OPTIONS assignments) -s --strict - do extra error checking (check that all posted accounts are de- - clared) + do extra error checking (check that all posted accounts are + declared) hledger reporting options: @@ -140,8 +140,8 @@ OPTIONS using period expressions syntax --date2 - match the secondary date instead (see command help for other ef- - fects) + match the secondary date instead (see command help for other + effects) -U --unmarked include only unmarked postings/txns (can combine with -P or -C) @@ -166,14 +166,14 @@ OPTIONS convert amounts to their cost/selling amount at transaction time -V --market - convert amounts to their market value in default valuation com- + convert amounts to their market value in default valuation com- modities -X --exchange=COMM convert amounts to their market value in commodity COMM --value - convert amounts to cost or market value, more flexibly than + convert amounts to cost or market value, more flexibly than -B/-V/-X --infer-value @@ -182,15 +182,15 @@ OPTIONS --auto apply automated posting rules to modify transactions. --forecast - generate future transactions from periodic transaction rules, - for the next 6 months or till report end date. In hledger-ui, + generate future transactions from periodic transaction rules, + for the next 6 months or till report end date. In hledger-ui, also make ordinary future transactions visible. --color=WHEN (or --colour=WHEN) - Should color-supporting commands use ANSI color codes in text - output. 'auto' (default): whenever stdout seems to be a color- - supporting terminal. 'always' or 'yes': always, useful eg when - piping output into 'less -R'. 'never' or 'no': never. A + Should color-supporting commands use ANSI color codes in text + output. 'auto' (default): whenever stdout seems to be a color- + supporting terminal. 'always' or 'yes': always, useful eg when + piping output into 'less -R'. 'never' or 'no': never. A NO_COLOR environment variable overrides this. When a reporting option appears more than once in the command line, the @@ -210,44 +210,44 @@ OPTIONS 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, + 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 + 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 + 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 + Similarly, use --port to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. Both of these options are ignored when --socket is used. In this case, - it creates an AF_UNIX socket file at the supplied path and uses that - for communication. This is an alternative way of running multiple - hledger-web instances behind a reverse proxy that handles authentica- - tion for different users. The path can be derived in a predictable + it creates an AF_UNIX socket file at the supplied path and uses that + for communication. This is an alternative way of running multiple + hledger-web instances behind a reverse proxy that handles authentica- + tion for different users. The path can be derived in a predictable way, eg by using the username within the path. As an example, nginx as - reverse proxy can use the variable $remote_user to derive a path from - the username used in a HTTP basic authentication. The following - proxy_pass directive allows access to all hledger-web instances that + reverse proxy can use the variable $remote_user to derive a path from + the username used in a HTTP basic authentication. The following + proxy_pass directive allows access to all hledger-web instances that created a socket in /tmp/hledger/: proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; - You can use --base-url to change the protocol, hostname, port and path + 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 + 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 + 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 @@ -257,8 +257,8 @@ PERMISSIONS 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 ma- - chine. + 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 @@ -274,8 +274,8 @@ PERMISSIONS o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or in- - cluded files + 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 @@ -285,8 +285,8 @@ PERMISSIONS 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 in- - cludes. + 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. @@ -305,8 +305,8 @@ 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 un- - til the file has been fixed. + makes a file unparseable, hledger-web will display an error message + until the file has been fixed. (Note: if you are viewing files mounted from another machine, make sure that both machine clocks are roughly in step.) @@ -373,15 +373,15 @@ JSON API Most of the JSON corresponds to hledger's data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click - on the various data types, eg Transaction. And for a higher level un- - derstanding, see the journal manual. + on the various data types, eg Transaction. And for a higher level + understanding, see the journal manual. In some cases there is outer JSON corresponding to a "Report" type. To understand that, go to the Hledger.Web.Handler.MiscR haddock and look at the source for the appropriate handler to see what it returns. Eg - for /accounttransactions it's getAccounttransactionsR, returning a "ac- - countTransactionsReport ...". Looking up the haddock for that we can - see that /accounttransactions returns an AccountTransactionsReport, + for /accounttransactions it's getAccounttransactionsR, returning a + "accountTransactionsReport ...". Looking up the haddock for that we + can see that /accounttransactions returns an AccountTransactionsReport, which consists of a report title and a list of AccountTransactionsRe- portItem (etc). @@ -485,8 +485,8 @@ JSON API "tstatus": "Unmarked" } - And here's how to test adding it with curl. This should add a new en- - try to your journal: + And here's how to test adding it with curl. This should add a new + entry to your journal: $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json @@ -500,9 +500,9 @@ ENVIRONMENT rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI - (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- - vironment.plist file containing + more thorough way that also affects applications started from the GUI + (say, an Emacs dock icon). Eg on MacOS Catalina I have a + ~/.MacOSX/environment.plist file containing { "LEDGER_FILE" : "~/finance/current.journal" @@ -511,13 +511,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-web can't read from stdin). @@ -531,7 +531,7 @@ BUGS REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -552,4 +552,4 @@ SEE ALSO -hledger-web-1.20.3 December 2020 HLEDGER-WEB(1) +hledger-web-1.20.4 December 2020 HLEDGER-WEB(1) |