package core_extended

  1. Overview
  2. Docs
package core_extended
Legend:
Library
Module
Module type
Parameter
Class
Class type

Line-by-line reading of a file. A line buffer allows one to read one line of a file at a time, blocking until a line is available. Line buffers are distinct from Pervasives.read_line in that they "notice" new data arriving in the file more quickly.

type t

The type of a line buffer.

type error_type =
  1. | Null_retry
  2. | Too_many_nulls
  3. | Exception of string * exn
type lnum =
  1. | Known of int
  2. | Unknown
type result =
  1. | Success of lnum * string
  2. | Nothing_available
  3. | Error of error_type
  4. | Fatal_error of string * exn
exception File_truncated_or_deleted
val create : ?pos:Stdlib.Int64.t -> ?close_on_eof:bool -> ?null_hack:[ `Off | `Retry_then_fail | `Retry ] -> ?eprint_nulls:bool -> ?follow_deletes:bool -> ?signal_on_truncate_or_delete:bool -> string -> t

Open a line buffer from the passed filename. If close_on_eof is set, when eof is read, the file will be closed and reopened if necessary. if follow_deletes is set, then when eof is read linebuf will stat the file, and if it has been deleted and recreated it will open the new file. If eprint_nulls is set, then when nulls are found, a warning message will be printed to stderr. null_hack specifies the behaviour of the linebuf upon reception of null characters in the file (as seen when tailing files over CIFS). Null hack options: `Off: don't check for nulls, just keep going. `Retry: close and reopen file when nulls are read from the file. If max_null_retries is reached, then pass the line with nulls. `Retry_then_fail: the same as retry, except that an exception is raised once max_null_retries is reached.

val close : t -> unit

Closes the line buffer (and the underlying file).

val is_closed : t -> bool

Returns whether or not the line buffer is closed

val try_read : t -> string option

Tries to read a line from the file. If no more lines are available, returns None.

val try_read_lnum : t -> (lnum * string) option

try_read_lnum is like try_read except also provides the line number of the read line.

val try_read_lnum_verbose : t -> result

Like try_read, except that it returns more verbose errors

val read : t -> string

Calls try_read every 0.01 seconds and returns when a line is available.

val tail : t -> unit

Seeks to the end of the file and blocks until another line is available -- this new line is not returned. Successive return values of try_read_lnum and try_read_lnum will return Unknown as the current line number until reset is called

val unsafe_tail : t -> unit

Same as tail except it may return before a new line is available on the file i.e. it (usually) doesn't block. Note that this does interact with files in a fairly naive way, so there's no guarantee that it absolutely doesn't block.

Note that when this functions is called, the next line that's read may be a partial line. After that first line, only full lines will be read.

val name : t -> string
val reset : t -> unit

reopens the file and seeks to the beginning. Also recovers the ability to get line numbers if tail has been called

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct