Library
Module
Module type
Parameter
Class
Class type
An input channel for reading (biological) records.
records
or with_file_records
.record_sequence
.fold_records
or with_file_fold_records
.iter_records
or with_file_iter_records
.For some more info, check out the usage examples.
Most functions in this module come in a few different flavors.
with_file_
prefix_exn
suffixOr_error.t
Functions that have the with_file_
prefix in their name take a filename string
rather than a t
. They are a convenient way to avoid wrapping your all your code in with_file
function calls.
Functions that the _exn
suffix in their name may raise exceptions, either from logic specific to this module, or from calls to other Core_kernel
functions.
Functions that return Or_error.t
catch all exceptions, even those not originating in the logic of this module. These functions shouldn't raise in practice. In other words, if you aren't using a function with _exn
in the name, and you get an exception, then you have found a bug.
Here is an example of the different "flavors" of fold_records
:
fold_records
: the normal t
accepting, Or_error.t
returning flavorfold_records_exn
: takes t
but may raise exceptions instead of returning Or_error.t
with_file_fold_records
: takes a file name (string
) rather than a t
, and returns Or_error.t
with_file_fold_records_exn
: takes a file name (string
) rather than a t
, and may raise exceptionsval stdin : t
create_exn file_name
opens an t
on the standard input channel.
val create_exn : Base.string -> t
create_exn file_name
opens an input channel on the file specified by file_name
.
val create : Base.string -> t Base.Or_error.t
create file_name
opens an input channel on the file specified by file_name
.
val close : t -> Base.unit Base.Or_error.t
close t
is like close_exnt t
except that it shouldn't raise.
val with_file_exn : Base.string -> f:(t -> 'a) -> 'a
with_file_exn file_name ~f
executes ~f
on the channel created from file_name
and closes it afterwards.
val with_file : Base.string -> f:(t -> 'a) -> 'a Base.Or_error.t
with_file file_name ~f
is like with_file_exn file_name ~f
except that it shouldn't raise.
val input_record_exn : t -> record Base.option
input_record_exn t
returns Some record
if there is a record
to return. If there are no more records, None
is returned. Exn
is raised on bad input.
val input_record : t -> record Base.option Base.Or_error.t
input_record t
is like input_record_exn t
except that it should not raise exceptions.
fold_records_exn t ~init ~f
reduces all records from a t
down to a single value of type 'a
.
val fold_records : t -> init:'a -> f:('a -> record -> 'a) -> 'a Base.Or_error.t
fold_records t ~init ~f
is like fold_records_exn t ~init ~f
except that it should not raise exceptions. Rather than deal with exceptions inside the reducing function, you must deal with them at the end when handling the return value.
Like fold_records_exn t ~init ~f
except that f
is provided the 0-based record index as its first argument. See fold_records_exn
.
val foldi_records :
t ->
init:'a ->
f:(Base.int -> 'a -> record -> 'a) ->
'a Base.Or_error.t
Like foldi_records_exn t ~init ~f
except that it shouldn't raise. See foldi_records_exn
.
val with_file_fold_records_exn :
Base.string ->
init:'a ->
f:('a -> record -> 'a) ->
'a
with_file_fold_records_exn file_name ~init ~f
is like fold_records_exn t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
val with_file_fold_records :
Base.string ->
init:'a ->
f:('a -> record -> 'a) ->
'a Base.Or_error.t
with_file_fold_records file_name ~init ~f
is like fold_records t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
val with_file_foldi_records_exn :
Base.string ->
init:'a ->
f:(Base.int -> 'a -> record -> 'a) ->
'a
with_file_foldi_records_exn file_name ~init ~f
is like foldi_records_exn t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
val with_file_foldi_records :
Base.string ->
init:'a ->
f:(Base.int -> 'a -> record -> 'a) ->
'a Base.Or_error.t
with_file_foldi_records file_name ~init ~f
is like fold'_records t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
The iter
functions are like the fold
functions except they do not take an init
value and the f
function returns unit
insead of some other value 'a
, and thus return unit
rather than a value 'a
.
They are mainly called for side effects.
iter_records_exn t ~f
calls f
on each record
in t
. As f
returns unit
this is generally used for side effects.
val iter_records : t -> f:(record -> Base.unit) -> Base.unit Base.Or_error.t
iter_records t ~f
is like iter_records_exn t ~f
except that it shouldn't raise.
iteri_records_exn t ~f
is like iteri_records_exn t ~f
except that f
is passed in the 0-indexed record index as its first argument.
iteri_records t ~f
is like iteri_records_exn t ~f
except that it shouldn't raise.
val with_file_iter_records_exn :
Base.string ->
f:(record -> Base.unit) ->
Base.unit
with_file_iter_records_exn file_name ~init ~f
is like iter_records_exn t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
val with_file_iter_records :
Base.string ->
f:(record -> Base.unit) ->
Base.unit Base.Or_error.t
with_file_iter_records file_name ~init ~f
is like iter_records t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
val with_file_iteri_records_exn :
Base.string ->
f:(Base.int -> record -> Base.unit) ->
Base.unit
with_file_iteri_records_exn file_name ~init ~f
is like iteri_records_exn t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
val with_file_iteri_records :
Base.string ->
f:(Base.int -> record -> Base.unit) ->
Base.unit Base.Or_error.t
with_file_iteri_records file_name ~init ~f
is like iteri_records t ~init ~f
except that it is passed a file name, and it manages t
automatically. See with_file
.
These functions return lists of records
s.
val records_exn : t -> record Base.List.t
val records : t -> record Base.List.t Base.Or_error.t
val with_file_records_exn : Base.string -> record Base.List.t
val with_file_records : Base.string -> record Base.List.t Base.Or_error.t
These are a bit different:
* There are no with_file
versions as you would have to do some fiddly things to keep the channel open, making them not so nice to use.
* Each record
that is yielded is wrapped in an Or_error.t
. This is different from the iter
, fold
, and other non _exn
functions in which case the entire result is wrapped in an Or_error.t
, letting you ignore errors in the passed in ~f
function and deal with failure once.
val record_sequence_exn : t -> record Base.Sequence.t
record_sequence_exn t
returns a Sequence.t
of record
. May raise exceptions.
val record_sequence : t -> record Base.Or_error.t Base.Sequence.t
record_sequence t
is like record_sequence_exn t
except that instead of raising exceptions, each item of the sequence is a record Or_error.t
rather than an "unwrapped" record
. This could make things annoying to deal with. If you don't want exceptions, you could instead wrap your entire sequence processing pipeline in a call to with_file
and handle the Or_error.t
in that way. See the pipelines usage examples for more info.