Module Line

module Line: sig .. end

Structured records for line-oriented data.

This module defines a Line.t type, useful to represent line-oriented data with structured content. A Line.t can be thought of as a (extensible) record. It has multiple fields storing the structured data, alongside the raw content of the line, from which they are extracted.

Additionally, a line must contain at least the following fields (see Mandatory fields for more details): raw, show, source, seq, after and before.

type label = ..

Extensible type for field labels.

Field identifiers, or labels, are constructors of the Line.label type, usually of arity zero. Several labels are predefined in this module, and more can be created by extending the Line.label variant type.

For example, one can define labels Foo and Bar using type label += Foo | Bar.

val add_label_string : label -> string -> unit

When defining a new label, it is expected that a conversion to string is registered for it. It will be used by printers, and can be queried using Line.string_of_label.

val string_of_label : label -> string

Query the string associated with a label. Raises Failure "string_of_label" if such string has not been registered.

module Fields: Hmap.S  with type 'a Key.info = label

A heterogeneous map, with keys indexed by Line.label.

exception Field_not_found of label

Exception returned by Fields.get if the queried key is not bound in the map.

type t = Fields.t

The type of a structured line.

A line is a heterogeneous map, with keys indexed by Line.label, which must contain the fields described in section Mandatory fields.

To create a custom line field foo, one must first define a new label (type label += Foo), then create a corresponding map key (let foo = Fields.Key.create Foo).

val line : ?after:string -> ?before:string -> string -> t

Construct a line from a string.

after is the trailing delimiter data associated with the line (default = "\n"); before is the leading delimiter data associated with the line (default = "").

val pp : Format.formatter -> t -> unit

Pretty-printer

Mandatory fields

In this section and the ones that follow, we define several line fields. We do not directly expose the Line.labels and Fields.Key.t created, but instead wrapper functions (accessors, updaters).

Fields being mandatory means that the accessors and updaters are guaranteed to never raise Line.Field_not_found.

val raw : t -> string

The raw string data from which a line was constructed.

This should typically not change after a line is created; to change the principal string value of a line, see Line.select and Line.show. (accessor, required)

val set_raw : string -> t -> t

Updater for Line.raw

val show : t -> string

The principal string representation of a line.

Unlike Line.raw above, the value of Line.show should reflect the data of concern in a line. Use Line.set_show or Line.select to change the value returned by Line.show. When a line is passed to an external process, Line.show is used to get a string to send.

val set_show : string -> t -> t

Choose the principal string value to be returned by Line.show.

val select : (t -> string) -> t -> t

Choose the principal string value, using a function. Line.select sel ln is equivalent to Line.set_show (sel ln) ln.

type source = [ `Command of string
       | `Directory of string
       | `File of string
       | `None
       | `Other of string
       | `Process of Proc.execspec ]

Type for the source of a line.

val source : t -> source

The source of a line. (accessor, nullable)

val set_source : source -> t -> t

Updater for Line.source

val seq : t -> int

The position of a line in its source. (accessor, nullable)

val set_seq : int -> t -> t

Updater for Line.seq

val after : t -> string

Trailing delimiter data associated with a line (accessor, required, default = "\n")

val set_after : string -> t -> t

Updater for Line.after

val before : t -> string

Leading delimiter data associated with a line (accessor, required, default = "")

val set_before : string -> t -> t

Updater for Line.before

Line structures

Several structures that may be read from a line. If the raw contents of a line matches a structure corresponding to module Foo, Foo.create will parse it and add the corresponding fields to the line.

For every module below, accessors and updaters raise exception Line.Field_not_found when the corresponding field is not present in a line.

module Key_value: sig .. end

Line structure to represent associations of keys with values.

module Delim: sig .. end

Line structure to represent records with delimited fields.

module Passwd: sig .. end

Line structure for /etc/passwd file records.

module Group: sig .. end

Line structure for /etc/group file records.

module Stat: sig .. end

Line structure for file status and mode information.

module Ps: sig .. end

Line structure for process status information.

module Fstab: sig .. end

Line structure for the file system table /etc/fstab records.

module Mailcap: sig .. end

Line structure for mailcap entries.