diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -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 diff --git a/hledger-web.1 b/hledger-web.1 --- a/hledger-web.1 +++ b/hledger-web.1 @@ -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] diff --git a/hledger-web.cabal b/hledger-web.cabal --- a/hledger-web.cabal +++ b/hledger-web.cabal @@ -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 diff --git a/hledger-web.info b/hledger-web.info --- a/hledger-web.info +++ b/hledger-web.info @@ -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: diff --git a/hledger-web.txt b/hledger-web.txt --- a/hledger-web.txt +++ b/hledger-web.txt @@ -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)