Pack Ann: pack_errors 2.0

[nicos.ang...@gmail.com]

This version is a radical, options-based, rewrite of this stoics.infrastructure pack

with emphasis on intuition and ease of use. The pack,

  1. implements a mid layer for uniform handling of Prolog errors
  2. provides a couple of simple ways for displaying originating pack/module and predicate
  3. includes useful pre-canned errors
  4. incorporates error related predicates
  5. decouples the type of printing from the execution behaviour and controls both aspects
     through simple options, allowing cascading of decision on these to higher level predicates

The pack manages mid-level error handling in a uniform way, so other packs can use message writing SWI's infrastructure
in a simple way. The user only needs to define the print messages (if the pre-canned ones are not suitable)
and then throw the appropriate terms during execution.

Two simple ways to identifying originating caller are provided by allowing options in either
the message, or via using an new version of throw, throw/2.

In addition the library includes a number or pre-canned messages and
has evolved to provide some error related predicates.

Install:
   ?- pack_install(pack_errors).
   ?- use_module(library(pack_errors)).

Throwing pack errors
---

Any term recognised as the first argument of the defined pack_errors:message/3 can be made to spit
a token identifying the originating pack/module and predicate. The main intuition is that this is the
predicate responsible for the error. You can do this by either wrapping the message or by using
pack_error's own version of throw, throw/2. For instance:

?- throw( lengths_mismatch(a,b,1,2), foo:bar/1 ).
ERROR: foo:bar/1: Lists for a and b have mismatching lengths: 1 and 2 respectively

Some good examples of usage can be found in pack(os_lib) (version >= 1.3).

eg.


?- throw(cast(abc('file.csv'),atom), os:os_exists/2), writeln(later).
ERROR: os:os_exists/2: Cannot cast: abc(file.csv), to type: atom

?- throw(cast(abc('file.csv'),atom), err(test)), writeln(later).
false.

- cd( pack('os_lib/examples/testo') ).
?- os_exists(file1).
true.

?- os_exists( file2 ).
false.

?- os_exists( file2, err(error) ).
ERROR: os:os_exists/2: OS entity: file2, does not exist

?- os_exists( file2, err(exists) ).
Warning: os:os_exists/2: OS entity: file2, does not exist
false.

?- os_exists( file2, [on_exit(fail),message(warning)] ).
Warning: os:os_exists/2: OS entity: file2, does not exist
false.

?- os_exists( file2, [on_exit(true),message(warning)] ).
Warning: os:os_exists/2: OS entity: file2, does not exist
true

?- os_exists( file1, [type(dir),err(error)] ).
ERROR: os:os_exists/2: OS entity: file1, not of requested type: dir, but has type: file


links:
   pack.page: http://stoics.org.uk/~nicos/sware/pack_errors/
   github:  https://github.com/nicos-angelopoulos/stoics.infra


Nicos Angelopoulos
---
http://stoics.org.uk/~nicos/