Add {In,Out}_channel to Stdlib (#10545)

Changes

@@ -41,6 +41,10 @@ Working version
    by the functions from module Marshal)
   (François Pottier, review by Gabriel Scherer and Kate Deplaix)
 
+- #10545: Add In_channel and Out_channel modules.
+  (Nicolás Ojeda Bär, review by Daniel Bünzli, Simon Cruanes, Gabriel Scherer,
+  Guillaume Munch-Maccagnoni, Alain Frisch and Xavier Leroy)
+
 ### Other libraries:
 
 - #10192: Add support for Unix domain sockets on Windows and use them

manual/src/library/stdlib-blurb.etex

@@ -77,6 +77,8 @@ integers
 \end{tabular}
 \subsubsection*{sss:stdlib-io}{input/output:}
 \begin{tabular}{lll}
+"In_channel" & p.~\stdpageref{In-underscorechannel} & input channels \\
+"Out_channel" & p.~\stdpageref{Out-underscorechannel} & output channels \\
 "Format" & p.~\stdpageref{Format} & pretty printing with automatic
 indentation and line breaking \\
 "Marshal" & p.~\stdpageref{Marshal} & marshaling of data structures \\
@@ -130,6 +132,7 @@ be called from C \\
 \stddocitem{Gc}{memory management control and statistics; finalized values}
 \stddocitem{Genlex}{a generic lexical analyzer}
 \stddocitem{Hashtbl}{hash tables and hash functions}
+\stddocitem{In_channel}{input channels}
 \stddocitem{Int}{integers}
 \stddocitem{Int32}{32-bit integers}
 \stddocitem{Int64}{64-bit integers}
@@ -143,6 +146,7 @@ be called from C \\
 \stddocitem{Nativeint}{processor-native integers}
 \stddocitem{Oo}{object-oriented extension}
 \stddocitem{Option}{option values}
+\stddocitem{Out_channel}{output channels}
 \stddocitem{Parsing}{the run-time library for parsers generated by \texttt{ocamlyacc}}
 \stddocitem{Printexc}{facilities for printing exceptions}
 \stddocitem{Printf}{formatting printing functions}

manual/tests/check-stdlib-modules

@@ -10,7 +10,7 @@ cut -c 2- $TMPDIR/stdlib-$$-files \
 exitcode=0
 for i in `cat $TMPDIR/stdlib-$$-modules`; do
   case $i in
-    Stdlib | Camlinternal* | *Labels | Obj | Pervasives) continue;;
+    Stdlib | Camlinternal* | *Labels | Obj | Pervasives | In_channel | Out_channel) continue;;
   esac
   grep -q -e '"'$i'" & p\.~\\stdpageref{'$i'} &' $1/manual/src/library/stdlib-blurb.etex || {
     echo "Module $i is missing from the module description in library/stdlib-blurb.etex." >&2

stdlib/.depend

@@ -359,6 +359,14 @@ stdlib__Hashtbl.cmx : hashtbl.ml \
     stdlib__Hashtbl.cmi
 stdlib__Hashtbl.cmi : hashtbl.mli \
     stdlib__Seq.cmi
+stdlib__In_channel.cmo : in_channel.ml \
+    stdlib.cmi \
+    stdlib__In_channel.cmi
+stdlib__In_channel.cmx : in_channel.ml \
+    stdlib.cmx \
+    stdlib__In_channel.cmi
+stdlib__In_channel.cmi : in_channel.mli \
+    stdlib.cmi
 stdlib__Int.cmo : int.ml \
     stdlib.cmi \
     stdlib__Int.cmi
@@ -496,6 +504,14 @@ stdlib__Option.cmx : option.ml \
     stdlib__Option.cmi
 stdlib__Option.cmi : option.mli \
     stdlib__Seq.cmi
+stdlib__Out_channel.cmo : out_channel.ml \
+    stdlib.cmi \
+    stdlib__Out_channel.cmi
+stdlib__Out_channel.cmx : out_channel.ml \
+    stdlib.cmx \
+    stdlib__Out_channel.cmi
+stdlib__Out_channel.cmi : out_channel.mli \
+    stdlib.cmi
 stdlib__Parsing.cmo : parsing.ml \
     stdlib__Obj.cmi \
     stdlib__Lexing.cmi \

stdlib/StdlibModules

@@ -42,7 +42,7 @@ STDLIB_MODULE_BASENAMES=\
   printexc fun gc digest random hashtbl weak \
   format scanf callback camlinternalOO oo camlinternalMod genlex ephemeron \
   filename complex arrayLabels listLabels bytesLabels stringLabels moreLabels \
-  stdLabels bigarray
+  stdLabels bigarray in_channel out_channel
 
 STDLIB_PREFIXED_MODULES=\
   $(filter-out stdlib camlinternal%, $(STDLIB_MODULE_BASENAMES))

stdlib/in_channel.ml

@@ -0,0 +1,66 @@
+(**************************************************************************)
+(*                                                                        *)
+(*                                 OCaml                                  *)
+(*                                                                        *)
+(*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           *)
+(*                                                                        *)
+(*   Copyright 2021 Institut National de Recherche en Informatique et     *)
+(*     en Automatique.                                                    *)
+(*                                                                        *)
+(*   All rights reserved.  This file is distributed under the terms of    *)
+(*   the GNU Lesser General Public License version 2.1, with the          *)
+(*   special exception on linking described in the file LICENSE.          *)
+(*                                                                        *)
+(**************************************************************************)
+
+type t = in_channel
+
+type open_flag = Stdlib.open_flag =
+  | Open_rdonly
+  | Open_wronly
+  | Open_append
+  | Open_creat
+  | Open_trunc
+  | Open_excl
+  | Open_binary
+  | Open_text
+  | Open_nonblock
+
+let stdin = Stdlib.stdin
+let open_bin = Stdlib.open_in_bin
+let open_text = Stdlib.open_in
+let open_gen = Stdlib.open_in_gen
+let seek = Stdlib.LargeFile.seek_in
+let pos = Stdlib.LargeFile.pos_in
+let length = Stdlib.LargeFile.in_channel_length
+let close = Stdlib.close_in
+let close_noerr = Stdlib.close_in_noerr
+
+let input_char ic =
+  match Stdlib.input_char ic with
+  | c -> Some c
+  | exception End_of_file -> None
+
+let input_byte ic =
+  match Stdlib.input_byte ic with
+  | n -> Some n
+  | exception End_of_file -> None
+
+let input_line ic =
+  match Stdlib.input_line ic with
+  | s -> Some s
+  | exception End_of_file -> None
+
+let input = Stdlib.input
+
+let really_input ic buf pos len =
+  match Stdlib.really_input ic buf pos len with
+  | () -> Some ()
+  | exception End_of_file -> None
+
+let really_input_string ic len =
+  match Stdlib.really_input_string ic len with
+  | s -> Some s
+  | exception End_of_file -> None
+
+let set_binary_mode = Stdlib.set_binary_mode_in

stdlib/in_channel.mli

@@ -0,0 +1,136 @@
+(**************************************************************************)
+(*                                                                        *)
+(*                                 OCaml                                  *)
+(*                                                                        *)
+(*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           *)
+(*                                                                        *)
+(*   Copyright 2021 Institut National de Recherche en Informatique et     *)
+(*     en Automatique.                                                    *)
+(*                                                                        *)
+(*   All rights reserved.  This file is distributed under the terms of    *)
+(*   the GNU Lesser General Public License version 2.1, with the          *)
+(*   special exception on linking described in the file LICENSE.          *)
+(*                                                                        *)
+(**************************************************************************)
+
+(** Input channels.
+
+    @since 4.14.0 *)
+
+type t = in_channel
+(** The type of input channel. *)
+
+type open_flag = Stdlib.open_flag =
+  | Open_rdonly      (** open for reading. *)
+  | Open_wronly      (** open for writing. *)
+  | Open_append      (** open for appending: always write at end of file. *)
+  | Open_creat       (** create the file if it does not exist. *)
+  | Open_trunc       (** empty the file if it already exists. *)
+  | Open_excl        (** fail if Open_creat and the file already exists. *)
+  | Open_binary      (** open in binary mode (no conversion). *)
+  | Open_text        (** open in text mode (may perform conversions). *)
+  | Open_nonblock    (** open in non-blocking mode. *)
+(** Opening modes for {!open_gen}. *)
+
+val stdin : t
+(** The standard input for the process. *)
+
+val open_bin : string -> t
+(** Open the named file for reading, and return a new input channel on that
+    file, positioned at the beginning of the file. *)
+
+val open_text : string -> t
+(** Same as {!open_bin}, but the file is opened in text mode, so that newline
+    translation takes place during reads. On operating systems that do not
+    distinguish between text mode and binary mode, this function behaves like
+    {!open_bin}. *)
+
+val open_gen : open_flag list -> int -> string -> t
+(** [open_gen mode perm filename] opens the named file for reading, as described
+    above. The extra arguments [mode] and [perm] specify the opening mode and
+    file permissions.  {!open_text} and {!open_bin} are special cases of this
+    function. *)
+
+val seek : t -> int64 -> unit
+(** [seek chan pos] sets the current reading position to [pos] for channel
+    [chan]. This works only for regular files. On files of other kinds, the
+    behavior is unspecified. *)
+
+val pos : t -> int64
+(** Return the current reading position for the given channel.  For files opened
+    in text mode under Windows, the returned position is approximate (owing to
+    end-of-line conversion); in particular, saving the current position with
+    {!pos}, then going back to this position using {!seek} will not work.  For
+    this programming idiom to work reliably and portably, the file must be
+    opened in binary mode. *)
+
+val length : t -> int64
+(** Return the size (number of characters) of the regular file on which the
+    given channel is opened.  If the channel is opened on a file that is not a
+    regular file, the result is meaningless.  The returned size does not take
+    into account the end-of-line translations that can be performed when reading
+    from a channel opened in text mode. *)
+
+val close : t -> unit
+(** Close the given channel.  Input functions raise a [Sys_error] exception when
+    they are applied to a closed input channel, except {!close}, which does
+    nothing when applied to an already closed channel. *)
+
+val close_noerr : t -> unit
+(** Same as {!close}, but ignore all errors. *)
+
+val input_char : t -> char option
+(** Read one character from the given input channel.  Returns [None] if there
+    are no more characters to read. *)
+
+val input_byte : t -> int option
+(** Same as {!input_char}, but return the 8-bit integer representing the
+    character. Returns [None] if the end of file was reached. *)
+
+val input_line : t -> string option
+(** [input_line ic] reads characters from [ic] until a newline or the end of
+    file is reached.  Returns the string of all characters read, without the
+    newline (if any).  Returns [None] if the end of the file has been reached.
+    In particular, this will be the case if the last line of input is empty.
+
+    A newline is the character [\n] unless the file is open in text mode and
+    {!Sys.win32} is [true] in which case it is the sequence of characters
+    [\r\n]. *)
+
+val input : t -> bytes -> int -> int -> int
+(** [input ic buf pos len] reads up to [len] characters from the given channel
+    [ic], storing them in byte sequence [buf], starting at character number
+    [pos]. It returns the actual number of characters read, between 0 and [len]
+    (inclusive). A return value of 0 means that the end of file was reached.
+
+    Use {!really_input} to read exactly [len] characters.
+
+    @raise Invalid_argument if [pos] and [len] do not designate a valid range of
+    [buf]. *)
+
+val really_input : t -> bytes -> int -> int -> unit option
+(** [really_input ic buf pos len] reads [len] characters from channel [ic],
+    storing them in byte sequence [buf], starting at character number [pos].
+
+    Returns [None] if the end of file is reached before [len] characters have
+    been read.
+
+    @raise Invalid_argument if [pos] and [len] do not designate a valid range of
+    [buf]. *)
+
+val really_input_string : t -> int -> string option
+(** [really_input_string ic len] reads [len] characters from channel [ic] and
+    returns them in a new string.  Returns [None] if the end of file is reached
+    before [len] characters have been read. *)
+
+val set_binary_mode : t -> bool -> unit
+(** [set_binary_mode ic true] sets the channel [ic] to binary mode: no
+    translations take place during input.
+
+    [set_binary_mode ic false] sets the channel [ic] to text mode: depending
+    on the operating system, some translations may take place during input.  For
+    instance, under Windows, end-of-lines will be translated from [\r\n] to
+    [\n].
+
+    This function has no effect under operating systems that do not distinguish
+    between text mode and binary mode. *)

stdlib/out_channel.ml

@@ -0,0 +1,47 @@
+(**************************************************************************)
+(*                                                                        *)
+(*                                 OCaml                                  *)
+(*                                                                        *)
+(*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           *)
+(*                                                                        *)
+(*   Copyright 2021 Institut National de Recherche en Informatique et     *)
+(*     en Automatique.                                                    *)
+(*                                                                        *)
+(*   All rights reserved.  This file is distributed under the terms of    *)
+(*   the GNU Lesser General Public License version 2.1, with the          *)
+(*   special exception on linking described in the file LICENSE.          *)
+(*                                                                        *)
+(**************************************************************************)
+
+type t = out_channel
+
+type open_flag = Stdlib.open_flag =
+  | Open_rdonly
+  | Open_wronly
+  | Open_append
+  | Open_creat
+  | Open_trunc
+  | Open_excl
+  | Open_binary
+  | Open_text
+  | Open_nonblock
+
+let stdout = Stdlib.stdout
+let stderr = Stdlib.stderr
+let open_bin = Stdlib.open_out_bin
+let open_text = Stdlib.open_out
+let open_gen = Stdlib.open_out_gen
+let seek = Stdlib.LargeFile.seek_out
+let pos = Stdlib.LargeFile.pos_out
+let length = Stdlib.LargeFile.out_channel_length
+let close = Stdlib.close_out
+let close_noerr = Stdlib.close_out_noerr
+let flush = Stdlib.flush
+let flush_all = Stdlib.flush_all
+let output_char = Stdlib.output_char
+let output_byte = Stdlib.output_byte
+let output_string = Stdlib.output_string
+let output_bytes = Stdlib.output_bytes
+let output = Stdlib.output
+let output_substring = Stdlib.output_substring
+let set_binary_mode = Stdlib.set_binary_mode_out