hledger-web 1.23 → 1.24
raw patch · 5 files changed
+196/−184 lines, 5 filesdep ~hledgerdep ~hledger-libPVP ok
version bump matches the API change (PVP)
Dependency ranges changed: hledger, hledger-lib
API changes (from Hackage documentation)
Files
- CHANGES.md +7/−0
- hledger-web.1 +2/−2
- hledger-web.cabal +7/−7
- hledger-web.info +178/−173
- hledger-web.txt +2/−2
CHANGES.md view
@@ -9,6 +9,13 @@ User-visible changes in hledger-web. See also the hledger changelog. +# 1.24 2021-12-01++Improvements++- Allow megaparsec 9.2++ # 1.23 2021-09-21 Improvements
hledger-web.1 view
@@ -1,12 +1,12 @@ -.TH "HLEDGER-WEB" "1" "September 2021" "hledger-web-1.23 " "hledger User Manuals"+.TH "HLEDGER-WEB" "1" "December 2021" "hledger-web-1.24 " "hledger User Manuals" .SH NAME .PP hledger-web is a web interface (WUI) for the hledger accounting tool.-This manual is for hledger-web 1.23.+This manual is for hledger-web 1.24. .SH SYNOPSIS .PP \f[C]hledger-web [OPTIONS]\f[R]
hledger-web.cabal view
@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack name: hledger-web-version: 1.23+version: 1.24 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.@@ -151,7 +151,7 @@ hs-source-dirs: ./ ghc-options: -Wall -fwarn-tabs -Wcompat -Wincomplete-uni-patterns -Wincomplete-record-updates -Wredundant-constraints- cpp-options: -DVERSION="1.23"+ cpp-options: -DVERSION="1.24" build-depends: Decimal >=0.5.1 , aeson >=1@@ -171,13 +171,13 @@ , extra >=1.6.3 , filepath , hjsmin- , hledger ==1.23.*- , hledger-lib ==1.23.*+ , hledger ==1.24.*+ , hledger-lib ==1.24.* , hspec , http-client , http-conduit , http-types- , megaparsec >=7.0.0 && <9.2+ , megaparsec >=7.0.0 && <9.3 , mtl >=2.2.1 , network , shakespeare >=2.0.2.2@@ -212,7 +212,7 @@ hs-source-dirs: app ghc-options: -Wall -fwarn-tabs -Wcompat -Wincomplete-uni-patterns -Wincomplete-record-updates -Wredundant-constraints- cpp-options: -DVERSION="1.23"+ cpp-options: -DVERSION="1.24" build-depends: base , hledger-web@@ -232,7 +232,7 @@ hs-source-dirs: test ghc-options: -Wall -fwarn-tabs -Wcompat -Wincomplete-uni-patterns -Wincomplete-record-updates -Wredundant-constraints- cpp-options: -DVERSION="1.23"+ cpp-options: -DVERSION="1.24" build-depends: base , hledger
hledger-web.info view
@@ -1,4 +1,5 @@-This is hledger-web.info, produced by makeinfo version 6.8 from stdin.+This is hledger-web/hledger-web.info, produced by makeinfo version 4.8+from stdin. INFO-DIR-SECTION User Applications START-INFO-DIR-ENTRY@@ -6,40 +7,39 @@ END-INFO-DIR-ENTRY -File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)+File: hledger-web.info, Node: Top, Up: (dir) hledger-web(1) ************** hledger-web is a web interface (WUI) for the hledger accounting tool.-This manual is for hledger-web 1.23.+This manual is for hledger-web 1.24. - '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). * Menu: @@ -59,180 +59,177 @@ ********* 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 (will be adjusted to preceding subperiod start when using a report interval)-'-e --end=DATE' +`-e --end=DATE' include postings/txns before this date (will be adjusted to following subperiod end when using a report interval)-'-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)-'--today=DATE' +`--today=DATE' override today's date (affects relative smart dates, for tests/examples)-'-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-market-prices' +`--infer-market-prices' use transaction prices (recorded with @ or @@) as additional market prices, as if they were P directives-'--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.-'--commodity-style' +`--commodity-style' Override the commodity style in the output for the specified commodity. For example 'EUR1.000,00'.-'--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.-'--pretty[=WHEN]' - Show prettier output, e.g. using unicode box-drawing characters.+`--pretty[=WHEN]'+ Show prettier output, e.g. using unicode box-drawing characters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never' also work). If you provide an argument you must use '=', e.g. '-pretty=yes'.@@ -244,62 +241,62 @@ hledger help options: -'-h --help'-+`-h --help' show general or COMMAND help-'--man' +`--man' show general or COMMAND user manual with man-'--info' +`--info' show general or COMMAND user manual with info-'--version' +`--version' show general or ADDONCMD 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. @@ -314,28 +311,32 @@ 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@@ -343,8 +344,8 @@ 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. @@ -353,13 +354,13 @@ 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@@ -369,7 +370,7 @@ 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. @@ -383,14 +384,16 @@ ********** 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@@ -403,6 +406,7 @@ 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",@@ -422,6 +426,7 @@ Or all transactions: + $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool [ {@@ -443,25 +448,26 @@ 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) >>> :q@@ -469,6 +475,7 @@ Here's how it looks as of hledger-1.17 (remember, this JSON corresponds to hledger's Transaction and related data types): + { "tcomment": "", "tpostings": [@@ -555,9 +562,10 @@ "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 @@ -566,25 +574,26 @@ 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@@ -593,9 +602,9 @@ ******* 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@@ -603,10 +612,10 @@ 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. @@ -614,29 +623,25 @@ Does not work well on small screens. + Tag Table:-Node: Top223-Node: OPTIONS1886-Ref: #options1991-Node: PERMISSIONS9902-Ref: #permissions10041-Node: EDITING UPLOADING DOWNLOADING11253-Ref: #editing-uploading-downloading11434-Node: RELOADING12268-Ref: #reloading12402-Node: JSON API12835-Ref: #json-api12949-Node: ENVIRONMENT18439-Ref: #environment18555-Node: FILES19288-Ref: #files19388-Node: BUGS19601-Ref: #bugs19679+Node: Top235+Node: OPTIONS1875+Ref: #options1980+Node: PERMISSIONS9870+Ref: #permissions10009+Node: EDITING UPLOADING DOWNLOADING11221+Ref: #editing-uploading-downloading11402+Node: RELOADING12233+Ref: #reloading12367+Node: JSON API12799+Ref: #json-api12913+Node: ENVIRONMENT18402+Ref: #environment18518+Node: FILES19250+Ref: #files19350+Node: BUGS19563+Ref: #bugs19641 End Tag Table---Local Variables:-coding: utf-8-End:
hledger-web.txt view
@@ -5,7 +5,7 @@ NAME hledger-web is a web interface (WUI) for the hledger accounting tool.- This manual is for hledger-web 1.23.+ This manual is for hledger-web 1.24. SYNOPSIS hledger-web [OPTIONS]@@ -570,4 +570,4 @@ -hledger-web-1.23 September 2021 HLEDGER-WEB(1)+hledger-web-1.24 December 2021 HLEDGER-WEB(1)