doc: clean up errors README, now published as hledger.org/ERRORS.html
This commit is contained in:
Simon Michael
parent
ed72763987
commit
54e1a8450e
@ -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.
|
||||
<div class=pagetoc>
|
||||
|
||||
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.
|
||||
<!-- toc -->
|
||||
</div>
|
||||
|
||||
[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.
|
||||
|
||||
<!-- Use absolute urls as this page can be viewed on github or hledger.org. -->
|
||||
[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
|
||||
<https://github.com/mesabloo/diagnose>,
|
||||
<https://hackage.haskell.org/package/errata>,
|
||||
<https://hackage.haskell.org/package/chapelure> 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`)
|
||||
|
||||
<!-- GENERATED: -->
|
||||
hledger 1.26.99-ga7b920750-20220715 error messages:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user