apps/libtmux_erlang/src/tmux_error.erl

Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c

SHA-256: ccb10f5a434672a20068759ee1b54ba6c6c503f0f876247aad7125c6b4c5ad82

-module(tmux_error).
-moduledoc """
Explain library exceptions through Erlang's native error formatter.

The shell and `erl_error:format_exception/3` call `format_error/2` through
EEP-54 stack metadata. Explanations supplement the original exception reason;
tagged results from `tmux_filter:new/2` and `tmux_select:try_where/2` retain
their existing structured data. Formatting performs no tmux I/O.

Only library-raised errors carry this metadata. Application callback failures
retain their original class, reason and stack. Coverage errors describe missing
observations; formatting never loads those observations or retries an action.
Long detail values may be abbreviated in the explanation. The exception reason
retains the original error data. See [runtime diagnostics](diagnostics.md) for
the separate, bounded Logger report contract.
""".
-behaviour(erl_error).
-export([format_error/2]).

-doc """
Return supplemental native error text, or an empty map for an unknown reason.

This is the `c:erl_error:format_error/2` callback. It neither changes the
exception nor catches it on behalf of a caller.

```erlang
1> #{general := Text} = tmux_error:format_error({bad_query_limit, -1}, []), ok.
ok
2> unicode:characters_to_binary(Text).
<<"The query limit must be an integer from 0 through 65536.">>
```
""".
-spec format_error(term(), erlang:stacktrace()) -> #{general => unicode:chardata()}.
format_error({bad_filter, Detail}, _) -> detail("Invalid filter", Detail);
format_error({bad_selection, Detail}, _) -> detail("Invalid selection", Detail);
format_error({invalid_command, Detail}, _) -> detail("Invalid command value", Detail);
format_error({incomplete_snapshot, Detail}, _) ->
    detail("The captured data is incomplete for this read", Detail);
format_error({filter_evaluation_failed, Detail}, _) ->
    detail("Local filter evaluation failed", Detail);
format_error({prepared_context_mismatch, Detail}, _) ->
    detail("The row is outside the prepared filter's captured context", Detail);
format_error({bad_query_limit, _}, _) ->
    #{general => "The query limit must be an integer from 0 through 65536."};
format_error({unknown_field, Entity, Field}, _) ->
    #{general => ["Unknown ", print(Entity), " field ", print(Field),
        ". Use tmux_schema:fields/1 to inspect permitted fields."]};
format_error(no_match, _) -> #{general => "No row matched the selection."};
format_error({multiple_matches, _}, _) ->
    #{general => "More than one row matched; use tmux_select:first/1 to permit extra matches."};
format_error(invalid_matcher_result, _) ->
    #{general => "Matcher prepare/2 must return {ok, Fun} or {error, Detail}; Fun must be unary."};
format_error({scope_cleanup_failed, _}, _) ->
    #{general => "Resource cleanup failed; the error retains both primary and cleanup outcomes."};
format_error(_, _) -> #{}.

detail(Label, #{code := Code} = Detail) ->
    Path = case Detail of
        #{path := Value} -> [" at ", print(Value)];
        _ -> []
    end,
    Allowed = case Detail of
        #{allowed := Names} -> [" Allowed: ", print(Names), "."];
        _ -> []
    end,
    Required = case Detail of
        #{requirements := Missing} -> [" Missing observations: ", print(Missing), "."];
        _ -> []
    end,
    #{general => [Label, ": ", print(Code), Path, ".", Allowed, Required]};
detail(_, _) -> #{}.

print(Value) -> io_lib:format("~tP", [Value, 8], [{chars_limit, 240}]).