Missing exceptions warnings in Str documentation

Ecosystem
1

I couldn’t find documentation for the following behaviour in https://caml.inria.fr/pub/docs/manual-ocaml/libref/Str.html:

utop # Str.string_before "test" (-1);;
Exception: Invalid_argument "String.sub / Bytes.sub".

Anyone able to patch that?

PS: Posted this on the caml-list but still hasn’t appeared there yet.

2

If you read the doc string it’s not surprising. n must be a position in the string, see definitions here.

3

You are right. But I was searching the docs for “raise” to find where my exception was coming from. It is the nature of exceptions to get buried if not handled with early. Seems Str lets through the exceptions but doesn’t document that. Even if I suspected this was happening, it would be hard to know which exceptions to catch without looking at the source code.

I can make a patch if I can submit here.

4

You are not supposed to catch Invalid_argument, that exception means that there is a programming error with your code (except in bool_of_string :–). Modify your code so that the exception doesn’t get raised.

5

But how do I know it’s an Invalid_argument? That’s the point… I either have to wait for my app to crash with that or have some serendipitous intuition and dig into the source code… :roll_eyes:

I brought it to the attention of the community; it may bite others too and would save time by adding a line in the docs. I can do it if the patch will be accepted by email or here.

1 Like
6

The Str library is more missing a warning to use other regexp library than anything else.

2 Likes
7

I’d say that it is still surprising. Potentially raised exceptions are often documented for the stdlib. That call to Str.string_before could return an empty string, raise a custom exception - there’s no way to know from the documentation.

While I agree with @octachron that the real solution is to warn loudly in the Str documentation that users should pick a different library, it’s also unreasonable to blame users for wanting more clarity about exceptions raised by libraries shipped with the compiler.

3 Likes
8

@anon72795300 Why don’t you submit a pull request to improve the documentation? That’s always the easiest way to get it to happen.

9

https://discuss.ocaml.org/t/publishing-without-github/3232/8:

10

I will not try to persuade you to do otherwise. But I will note that your ability to get things done will be dramatically limited by your choice.

1 Like
11

Our internet in 2020 :laughing:

I trust that you mean well and I invite you to look at this from another perspective; where the choice of the core team has limited the interoperability with the rest of community. Open source but not open network.

I can submit a patch or a pull request from here, but that’s apparently not smooth enough for Github. It’s no big deal, I’ll work on other projects till this becomes possible again.

12

From: otherlibs/str/str.ml

(** String utilities *)

let string_before s n = String.sub s 0 n

let string_after s n = String.sub s n (String.length s - n)

let first_chars s n = String.sub s 0 n

let last_chars s n = String.sub s (String.length s - n) n

These are just utilities functions for the Str module, just a String.sub not even regexp functions, so these should probably not be exported into the interface .mli file. Or if we want to export it for use by users these functions should probably be into the String module.

1 Like