From 54e1a8450e4acb64722e4aad794b1fc0a2185470 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 24 Jul 2022 07:20:01 +0100 Subject: [PATCH] doc: clean up errors README, now published as hledger.org/ERRORS.html --- hledger/test/errors/README.md | 91 ++++++++++++++++++++++------------- 1 file changed, 58 insertions(+), 33 deletions(-) diff --git a/hledger/test/errors/README.md b/hledger/test/errors/README.md index 04372f404..e88bd5217 100644 --- a/hledger/test/errors/README.md +++ b/hledger/test/errors/README.md @@ -1,26 +1,51 @@ -hledger error messages are currently quite varied in format. -Tools like flycheck-hledger parse them and need updating -whenever they change ([#1436][]). -Getting consistent high-quality errors and accurate flycheck region -highlighting, not to mention LSP support, for all of our journal -errors is a big project, but it's crowd-sourceable and every bit of -progress brings immediate practical benefits. +# ERRORS -Here are journals/scripts for reproducing hledger's journal error messages. -They are named similarly to [hledger check][]'s checks. -In the CLI, execute them to see the error messages. +
-In Emacs with [flycheck-hledger][], -customize flycheck-hledger-* to enable all appropriate checks, -and open the files to see how flycheck handles them. -Some files contain extra declarations to ease flycheck testing. + +
-[hledger check]: https://hledger.org/hledger.html#check -[flycheck-hledger]: https://github.com/DamienCassou/flycheck-hledger -[flycheck-hledger-10]: https://github.com/DamienCassou/flycheck-hledger/pull/10 -[#1436]: https://github.com/simonmichael/hledger/issues/1436 +hledger produces a variety of error messages in different situations. +They are intended first for humans and secondly for parsing by tools +like [flycheck-hledger][]. +Here we collect examples of these errors, which are listed below +for reference, and also tested as part of our test suite. +This document is the README in the [hledger/test/errors/][] directory, +and also published as Developer docs > [ERRORS][] on hledger.org. -## Goals +Each error has + +- a name (similar to [hledger check][] names when applicable) +- an executable script in this directory which reproduces the error (like `balanced.j`) +- which usually can also be used as a data file for manual testing (`hledger -f balanced.j check`) +- sometimes supplementary data files (like `csvdateparse.csv.rules`) +- an autogenerated shelltestrunner test (like `balanced.test`) + +To update this readme with the latest error messages, run `make readme`. +To regenerate the shelltestrunner tests, run `make tests`. +To test all of these error messages with hledger, run `make test`. +To test these errors with flycheck-hledger, +customize `flycheck-hledger-*` in Emacs to enable all appropriate checks, +then open the data files to see how flycheck handles them. +`C-c ! l` opens a pane for easy viewing. + + +[hledger/test/errors/]: https://github.com/simonmichael/hledger/tree/master/hledger/test/errors +[ERRORS]: https://hledger.org/ERRORS.html +[hledger check]: https://hledger.org/hledger.html#check +[flycheck-hledger-home]: https://github.com/DamienCassou/flycheck-hledger +[flycheck-hledger-10]: https://github.com/DamienCassou/flycheck-hledger/pull/10 +[flycheck-hledger]: https://hledger.org/editors.html#flycheck-hledger + + +## Error improvement + +Work is ongoing to make our error messages more consistent and more useful +([#1436](https://github.com/simonmichael/hledger/issues/1436), +[#1885](https://github.com/simonmichael/hledger/pull/1885), +[#1886](https://github.com/simonmichael/hledger/pull/1886)..). +This is a big project, and your help is welcome; every bit of progress +counts, and this is a fast way to help users. - [x] ~~phase 1: update flycheck to detect journal errors of current hledger release (and keep a branch updated to detect errors of latest hledger master)~~ - [x] ~~phase 2: survey/document current journal errors & status~~ @@ -37,18 +62,18 @@ Some files contain extra declarations to ease flycheck testing. - [x] ~~phase 13: decide/add error ids/explanations/web pages ? not needed~~ - [ ] phase 14: support Language Server Protocol & Visual Code -## Preferred error format +## Standard error format -Here is our current standard error message layout. -It is similar to the parse error messages we get from megaparsec. -(Easier to follow that than change it.): +Here is our current preferred layout for error messages. +It is similar to the parse error messages we get from megaparsec +(since it's easier to follow that than change it): ``` hledger: Error: FILE:LOCATION: EXCERPT EXPLANATION ``` -Notes (see also [#1436][]): +Notes: - line 1 includes "hledger" (dropping this would require some effort), the word "Error", and the error position - FILE is the file path @@ -64,7 +89,10 @@ Notes (see also [#1436][]): EXCERPT [DETAILS] ``` -- try https://github.com/mesabloo/diagnose / https://hackage.haskell.org/package/errata / https://hackage.haskell.org/package/chapelure later +- try + , + , + later ? ## Limitations @@ -78,19 +106,20 @@ Here are some current limitations of hledger's error messages: - For the same reason, the excerpts we show in error messages are not the original data. Instead we show a synthetic rendering that is similar enough to be explanatory. -## Current status + +## Error messages Here is the current status as of hledger (see version below) and flycheck-hledger g1310cb518. -Click error names to see an example. Key: +Click error names to see an example. The table headings mean: -- std format - the error message follows a standard format (location on first line, megaparsec-like excerpt, explanation) +- std format - the error message follows our standard error format - line - correct line numbers are reported - column - useful column numbers are reported - excerpt - a useful excerpt is shown, ideally with the error highlighted (✓✓) - flycheck - the current flycheck release (or a PR branch) recognises the error and highlights a useful region -| error/check name | std format | line | column | excerpt | flycheck | +| error name | std format | line | column | excerpt | flycheck | |-------------------------------------------------------|------------|------|--------|---------|----------| | [accounts](#accounts) | ✓ | ✓ | ✓ | ✓✓ | ✓ | | [assertions](#assertions) | ✓ | ✓ | ✓ | ✓✓ | ✓ | @@ -125,10 +154,6 @@ Click error names to see an example. Key: | [csvstdinrules](#csvstdinrules) | | | | | | -## Current error messages - -(To update: `make readme`) - hledger 1.26.99-ga7b920750-20220715 error messages: