Preferred use of Invalid_argument and Failure

Preferred use of Invalid_argument and Failure

[Michaël Le Barbier]

Hi,

I am working on a library, I want the interfaces to look like standard
library modules interfaces. From the standard library modules, it is
usually possible to tell if fonction should be called `of'_string,
`from'_string, etc. Considering exceptions, the situation is not so
clear to me, and I would be glad to get a piece of advice or your
feelings to help me towards a consistant use of these two exceptions.


Small discussion:

Let's quote the manual (release 3.09):

  exception Invalid_argument of string

    Exception raised by library functions to signal that the given
    arguments do not make sense.

  exception Failure of string

    Exception raised by library functions to signal that they are
    undefined on the given arguments.


It seems to me that Invalid_argument is a sort of specialisation of
Failure. A general rule that emerges from standard library modules is
that:
  * when a function can tell a priori it's undefined on its arguments
    (exemple: String.blit) it should raise Invalid_argument;
  * when a function must try to compute an answer before it turns out
    there is no answer, it raises Failure (let's say you try to solve
    a singular system).
However this general rule is not strictly followed by standard library
modules. Again, I would be glad to get advices of discipline in using
theses two exceptions. What works for you?
-- 
Cheers,
Michaël

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Alain Frisch]

Michaël Le Barbier wrote:
> I am working on a library, I want the interfaces to look like standard
> library modules interfaces.
...
> Again, I would be glad to get advices of discipline in using
> theses two exceptions. What works for you?

My advice would be not to use these two exceptions and to define custom 
exceptions in your library. You'll be able to pattern match on them 
more easily and to store extra relevant information. Of course, this 
breaks your design constraint of looking like the standard library.

-- Alain

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Xavier Leroy]

> Let's quote the manual (release 3.09):
>
>   exception Invalid_argument of string
>
>     Exception raised by library functions to signal that the given
>     arguments do not make sense.
>
>   exception Failure of string
>
>     Exception raised by library functions to signal that they are
>     undefined on the given arguments.
>
>
> It seems to me that Invalid_argument is a sort of specialisation of
> Failure.

The convention that the standard library tries to follow is this.

Invalid_argument is very much like a failed assertion: it indicates
that something is wrong in the program itself, i.e. negative character
positions in string functions.  Most programs will not catch
Invalid_argument, treating as a fatal error.  Others will catch it,
but only to enter a piece of generic "recover from unexpected error"
code.

Failure, on the other hand, signals errors that can happen in normal
runs of the code.  For instance, you're converting a user-provided
string to a number, and the string does not represent a number.  It is
expected that the client code catches Failure and recovers gracefully,
e.g. by asking for the number again, or producing a precise "syntax
error" message.

I recommend the use of Invalid_argument to report "should never
happen" conditions at the boundary between library functions and user
code.  On the other hand, the "Failure" exception is a bit of a legacy
from earlier designs (Caml Light and even the original LeLisp-based
Caml), and often is not the best way to report "normal error"
conditions: instead, you could consider defining your own exceptions
as Alain suggested, or even have your functions return "option" types
instead of raising exceptions.

Hope this helps,

- Xavier Leroy

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Yaron Minsky]

[-- Attachment #1: Type: text/plain, Size: 867 bytes --]

On 10/24/07, Xavier Leroy <Xavier.Leroy@inria.fr> wrote:
>
>
> I recommend the use of Invalid_argument to report "should never
> happen" conditions at the boundary between library functions and user
> code.  On the other hand, the "Failure" exception is a bit of a legacy
> from earlier designs (Caml Light and even the original LeLisp-based
> Caml), and often is not the best way to report "normal error"
> conditions: instead, you could consider defining your own exceptions
> as Alain suggested, or even have your functions return "option" types
> instead of raising exceptions.


Where I work, we have come to dearly love the practice of returning
polymorphic variants with explicit  variants for various "normal" error
cases.  This is pretty lightweight, and is also very clear and explicit,
both when looking at the function signature and at the call point.

y

[-- Attachment #2: Type: text/html, Size: 1242 bytes --]

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Joel Reymont]

Yaron,

On Oct 24, 2007, at 12:05 PM, Yaron Minsky wrote:

> Where I work, we have come to dearly love the practice of returning  
> polymorphic variants with explicit  variants for various "normal"  
> error cases.

Can you elaborate? Are your explicit variants still polymorphic?

--
http://wagerlabs.com

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Yaron Minsky]

[-- Attachment #1: Type: text/plain, Size: 853 bytes --]

As in:

  map_of_alist : ('a * 'b) list -> [ `Repeated_key of 'a | `Succ of ('a,'b)
Map.t ]

The return value is both explicit and a polymorphic variant.

y

On 10/24/07, Joel Reymont <joelr1@gmail.com> wrote:
>
> Yaron,
>
> On Oct 24, 2007, at 12:05 PM, Yaron Minsky wrote:
>
> > Where I work, we have come to dearly love the practice of returning
> > polymorphic variants with explicit  variants for various "normal"
> > error cases.
>
> Can you elaborate? Are your explicit variants still polymorphic?
>
> --
> http://wagerlabs.com
>
>
>
>
> _______________________________________________
> Caml-list mailing list. Subscription management:
> http://yquem.inria.fr/cgi-bin/mailman/listinfo/caml-list
> Archives: http://caml.inria.fr
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 1486 bytes --]

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Daniel Bünzli]

Le 24 oct. 07 à 15:15, Yaron Minsky a écrit :

> As in:
>
>   map_of_alist : ('a * 'b) list -> [ `Repeated_key of 'a | `Succ of  
> ('a,'b) Map.t ]
>
> The return value is both explicit and a polymorphic variant.

Interesting solution. I would however suggest `Value instead of `Succ 
(ess ?). I was confused thinking about  `Succ(essor) because of  
Pervasives.succ.

Best,

Daniel

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Jon Harrop]

On Wednesday 24 October 2007 14:15:36 Yaron Minsky wrote:
> As in:
>
>   map_of_alist : ('a * 'b) list -> [ `Repeated_key of 'a | `Succ of ('a,'b)
> Map.t ]
>
> The return value is both explicit and a polymorphic variant.

We also use that pattern. I'll document it somewhere...

-- 
Dr Jon D Harrop, Flying Frog Consultancy Ltd.
http://www.ffconsultancy.com/products/?e

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Jon Harrop]

On Wednesday 24 October 2007 14:22:39 Daniel Bünzli wrote:
> Interesting solution. I would however suggest `Value instead of `Succ
> (ess ?). I was confused thinking about  `Succ(essor) because of
> Pervasives.succ.

Why do people use Pervasives.succ? I never understood that... :-)

-- 
Dr Jon D Harrop, Flying Frog Consultancy Ltd.
http://www.ffconsultancy.com/products/?e

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Richard Jones]

On Wed, Oct 24, 2007 at 03:22:39PM +0200, Daniel Bünzli wrote:
> 
> Le 24 oct. 07 à 15:15, Yaron Minsky a écrit :
> 
> >As in:
> >
> >  map_of_alist : ('a * 'b) list -> [ `Repeated_key of 'a | `Succ of  
> >('a,'b) Map.t ]
> >
> >The return value is both explicit and a polymorphic variant.
> 
> Interesting solution. I would however suggest `Value instead of `Succ 
> (ess ?). I was confused thinking about  `Succ(essor) because of  
> Pervasives.succ.

Same confusion here (Succ notation for natural numbers).

Rich.

-- 
Richard Jones
Red Hat

Re: [Caml-list] Preferred use of Invalid_argument and Failure

[Michaël Le Barbier]

Xavier Leroy <Xavier.Leroy@inria.fr> writes:

> The convention that the standard library tries to follow is this.
>
> Invalid_argument is very much like a failed assertion: it indicates
> that something is wrong in the program itself, i.e. negative character
> positions in string functions.  Most programs will not catch
> Invalid_argument, treating as a fatal error.  Others will catch it,
> but only to enter a piece of generic "recover from unexpected error"
> code.
>
> Failure, on the other hand, signals errors that can happen in normal
> runs of the code.  For instance, you're converting a user-provided
> string to a number, and the string does not represent a number.  It is
> expected that the client code catches Failure and recovers gracefully,
> e.g. by asking for the number again, or producing a precise "syntax
> error" message.
>
> I recommend the use of Invalid_argument to report "should never
> happen" conditions at the boundary between library functions and user
> code.  On the other hand, the "Failure" exception is a bit of a legacy
> from earlier designs (Caml Light and even the original LeLisp-based
> Caml), and often is not the best way to report "normal error"
> conditions: instead, you could consider defining your own exceptions
> as Alain suggested, or even have your functions return "option" types
> instead of raising exceptions.

Thank you very much for your description of the error reporting scheme
used in the standard library, you made the things very clear.

Following your joined advices with Alain Frisch, I will rethink error
reporting scheme in that library to provide more accurate error
diagnostics. Accurate errors are clearly more useful than vague ones.

I suppose the ``right thing to do'' depends greatly of the application
type. Specifically, I am working on a program that do scientific
computations, and I am very interesting in getting a precise
description of parameters that crashed my program: throwing exception
seems a convenient way to provide this feedback.

Thanks again to all contributors for their valuable advices.
-- 
Cheers,
Michaël