Help Review the new "File Manipulation" tutorial on OCaml.org

Community
, ,
21

(The Unix shell has an exec command for doing precisely this.)

22

Hi.

I’m a newbie in Ocaml and the post was super easy to understand and very instructive.

Thank you.

2 Likes
23

I have a high-level question on the "file manipulation tutorial¨: are we sure that the stdlib is the right library for these kind of programs? I see that the new proposal intends to do things well, but it ends up with a mix of Sys, Filename and Unix modules that personally I find a bit hard to justify.

There are third-party libraries that try to provide a better experience for interaction with the filesystem, going in the direction of “scripting in OCaml”. One I am familiar with is Bos and in particular its Bos.OS module. But I am sure that there are other libraries that are dedicated to this topic (I’ve used ExtUnix in the past, but it is not designed for first-class Windows support) – and other library monoliths that may do a better job than the stdlib on this topic.

My intuition is that using a dedicated library from the start makes it easier to scale to a more complex real-world script.

I think that it would be interesting to give a go at rewriting the examples in the tutorial to use Bos.OS, and see if they look nicer.

Edit: to be clear, I think that showing {In,Out}_channel for file I/O is a fine choice. It is the “filesystem interaction” (everything that involves navigating it, creating files, etc.) aspect that I find less convincing. The stdlib supports what the compiler needs, but not much else, and not in a consistent way (using Unix directly offers more consistency, but there probably are higher-level APIs for end-users).

5 Likes
24

It’s a very unusual state of affairs. New users would have no idea that this is true unless the docs make it clear, with at least a warning about this at the top of the Stdlib docs.

I’ve been relying on OCamlVerse, which doesn’t list Bos but does list Fpath.

1 Like
25

The problem with moving away from the Stdlib is that newcomers must now have an opam installation, and can’t just do the tutorial through a toplevel or a basic installation (cf. my own university, where opam isn’t available by default in our environment, but OCaml is).

There are a number of third-party libraries available, all with their own focal points and support cone. Bos has a big interface warning (although it has been really stable in practise), there’s Extunix, Lwt, the files and modules chapter in RWO for Async. I’d prefer that we stick to the core distribution for the tutorials on the OCaml website, and then link prominently as “followup reading material” for the third-party libraries to their own tutorials and manuals.

4 Likes
26

Sorry for arriving so late in the discussion. What I miss from this tutorial is a mention of the new better interfaces we have. At the end we could say that a lot of the boilerplate that was written above is no longer necessary, for example since OCaml 4.14.0 we can do the same with

let file = "example.dat"
let message = "Hello!"

let () =
  (* Write message to file *)
  Out_channel.with_open_text file (fun oc -> Printf.fprintf oc "%s\n" message);
  (* This creates or truncates the file and then calls the function in parentheses
     with the channel it just created, ensuring that the channel is closed also in case
     of errors and eventual exceptions are propagated. You can also use
     [Out_channel.output_string message] to write to the channel, but this does
     not add extra newlines. *)

  (* To read the file, the story is similar *)
  let content = In_channel.with_open_text file In_channel.input_all in
  print_endline (string_of_bool (content = "Hello!\n"))
3 Likes
27

Don’t underestimate the value of learning how not to do things. That’s how we learn, really. What’s important is a clear explanation of what went wrong.

2 Likes
28

What’s important is a clear explanation of what went wrong.

Yeah agreed, there’s something here we can rearrange and reuse to show intentionally how not to do things.

1 Like
29

since OCaml 4.14.0 we can do the same with

We should just update the code examples to be for 4.14.1 and above at this point, I think, since that’s the current LTS version.

1 Like
30

Hi @arbipher,

Not sure it still makes sense to answer. Basically, just file a PR with your proposal.

We have a style guide:

Here are a few examples of such PRs: