[Caml-list] Preferred use of Invalid_argument and Failure
Michaël Le Barbier
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
_______________________________________________
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
Alain Frisch
> 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
Xavier Leroy
>
> 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
Yaron Minsky
>
>
> 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
Joel Reymont
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?
Yaron Minsky
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
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
Jon Harrop
> 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
Jon Harrop
> 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
_______________________________________________
Richard Jones
>
> 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
Michaël Le Barbier
> 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