Re: zsh_error_db --- hash-based database of error messages

["Daniel Shahaf" <d.s@xxxxxxxxxxxxxxxxxx>]

Peter Stephenson wrote on Fri, 16 Dec 2022 18:05 +00:00:
> On Fri, 2022-12-16 at 17:46 +0000, Daniel Shahaf wrote:
>> Peter Stephenson wrote on Fri, Dec 16, 2022 at 16:42:53 +0000:
>> > Following on from the retread of the discussion on error messages,
>> > here's a very simply proof of concept for a hash-based database of
>> > error messages.  Even if it's adopted I don't intend the C code
>> > to get much larger as the point is to allow it to be able to do
>> > everything in shell code.
>> > 
>> 
>> So, tl;dr:
>> 
>> - Every error message would get an E42 identifier in the source string.
>> 
>> - The "E42" will be looked up as a string key in a well-known assoc,
>>   where the value will be a more elaborate error message.
>> 
>> - The more elaborate message, if there is one, will be used instead of
>>   the default message.
>

FWIW, I'm not sure whether I would prefer for the elaborate message to
be shown /instead of/ the default message or /in addition/ to it.

> Yes, that's it in a nutshell; any further complexity would ideally
> be in shell code.

How some other projects do this:

- Apache httpd: a APLOGNO(00042) macro in the C sources expands to
  "AH00042: ".  See
  https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/log-message-tags/README
  for details, including why they use a macro (their reasoning seems to
  apply to our case too).  They have a script for use before commit that
  assigns new error message numbers to newly-added APLOGNO() calls.

- Vim: E<number>.  I don't know what they do when they add new errors,
  but every E42 code has an entry in the manual's tags file (≈ an index
  entry), so something like `< runtime/doc/tags grep -E '^E[0-9]' |
  sort -n | tail -n1` would programmatically determine the highest
  unused E-number.

- Subversion: E<number> where the number is taken from a particular .h
  file in the project's sources.  The numbers are assigned non-consecutively
  and grouped by module (e.g., all CLI parse error codes are numerically
  next to each other).

> I think at least we need something better than E <num> to try to avoid
> duplicates, for example E <file-code> <num>.  It's easy to search
> the file for a duplicate, a bit more of a pain to search the entire
> codebase.  Maybe a two letter code, so we can have ZW for zle_word.c?

I don't think grepping all of Src/ is that much of a problem.  I do that
regularly.  It's also what httpd's aforementioned script does, since httpd
doesn't have a single file registry of all error numbers it has assigned.

So, perhaps E<num> would suffice for us, too.  Where it might fall short
is with third-party modules.  Therefore, I guess should invent some
scheme for third-party modules to use, say, «X-<identifier>:E<num>»
where <identifier> matches /[A-Za-z_][A-Za-z0- 9_]+/.

Conversely, if we want per-file error numbers:

- "A single .c source file" seems like the wrong level of abstraction to
  expose in a user-facing error message.

- Two-letter codes would effect a risk of collisions between different
  files.  I suppose we could use ${__file__#**/Src/} instead of the
  acronym of __file__'s basename, but see the previous bullet.  Or we
  could have a single file registry of assigned two-letter codes, but then
  why don't we amend that and have a single file registry of assigned
  global numeric codes?

- How'd we implement a script that automatically determines the highest
  error number already in use in a particular file?  (If we adopt the APLOGNO()
  idea this will be easy, but I'm not assuming either way.)

Cheers,

Daniel