Module Ligand

module Ligand: sig  end

Definitions for the ligand objects, the string-analogues living within the Incubator layer of the design stack. The functionality essentially mirrors that of associative extents. Assocext.

type t

The type of ligands, which are essentially basestrings with a binding state, with zero, one or more processing unit ligand binding domain.

This data structure is not thread safe.

exception Illegal_character

Exception raised by create below.

val create : string -> t

Ligand constructor. Will raise exception Illegal_character if a character appears in the string which can not be part of a ligand. For instance, ^ and $ can not appear in ligands. FIXME: For now, anyway.

val get_string : t -> string

Extract the string from a ligand.

type interval

Pretty much the same as associative extent intervals. We keep the type opaque because ligand intervals may over time become a little bit more complex. Assocext.interval.

val get_interval_length : interval -> int

Return the length of the interval. The terminals are excluded from the length accounting.

exception Overlapping_intervals

This exception is raised by compare_intervals when the intervals provided overlap.

val compare_intervals : interval -> interval -> int

compare i1 i2 returns -1 if i1 precedes i2 on the ligand, 1 if i1 follows i2 and 0 if they're equal. FIXME: Do error checking too, as in if they overlap but are not equal?

type frag

A bound chunk of a ligand. It has an associated sub-basestring and a range. A frag always remembers which ligand it is a part of. The head and the tail of a ligand are distinct sub-entities of a ligand, and can be bound to frags. A frag can have length zero.

val get_interval : frag -> interval

Get the interval of an opaque frag type.

val contains_end : interval -> bool

val contains_begin : interval -> bool

exception Stale_frag

A frag can get stale as the ligand that it belongs to changes. For instance, its binding state can change. When this happens, certain routines below will raise Stale_frag.

val get_whole : frag -> t

Returns the ligand which contains the specified frag. If the frag is not a valid part of any ligand anymore, exception Stale_frag will be raised.

val get_frag_list : t -> frag list

Return the list of bound frags.

val get_active_interval_list : t -> interval list

Return the list of maximal non-bound intervals.

exception Out_of_bounds

exception Empty

val first : t -> frag

val last : t -> frag

val next_frag : frag -> frag

val prev_frag : frag -> frag

val iter : (frag -> unit) -> t -> unit

module Matcher: sig  end

Contains the definitions for the objects which are used to find binding regions on ligands.

exception Unable_to_bind

exception Illegal_interval

val bind : t -> interval -> frag

bind l i attempts to bind the ligand l from i.start to i.start + i.len - 1. The result is the newly bound frag. If the interval is already bound (fully or partially), exception Unable_to_bind will be raised. If the range is illegal, Illegal_interval will be raised.

val check : t -> interval -> bool

Performs the same checks that bind above would perform, but does not bind anything. Returns true if binding would be successful, or false otherwise. If the interval is illegal, raise Illegal_interval.

exception Invalid_frag

val release : frag -> unit

Will raise Invalid_frag if the frag is stale or otherwise not registered.

val replace : frag -> string -> unit

Replace, in place, the bound frag with the new basestring. If the frag is not bound, raise Invalid_frag. The extremities are unaffected by a replacement.

type whichside =

`\|`	`LeftSplit`
`\|`	`RightSplit`	`(*`	`Returned by split and join.`	`*)`

type apportf = frag -> whichside * frag

Returned by split.

val split : frag ->
       int -> (t * frag) * (t * frag) * apportf

split f pos splits a ligand into two parts. Precisely, the ligand is split at position pos of frag f (note that we can only split a bound ligand). The result is a structure of the form

(l1,
f1), (l2, f2), apportf

, where l1 and l2 are the new ligands, left and right of the split respectively, f1 and f2 are the frags which correspond to the original split frag, which are such that f1 is bound to the end of the ligand l1 and f2 is bound to the beginning of the ligand l2, and apportf is a function which maps any bound frag on the original ligand to a frag on either of the resulting split frags.

type joinf = whichside * frag -> frag

Returned by join.

val join : frag -> frag -> (t * frag) * joinf

join f1 f2 joins two ligands into one. More precisely, f1 must be a tail frag on a ligand l1 and f2 a start frag on a ligand l2. The result (l, f), joinf of join is a single ligand, with a new frag f which corresponds to the join of f1 and f2. The returned function joinf is used to map each original bound frag to a frag on the resulting joined ligand.

val collapse_interval : interval -> int * int

collapse_interval i returns (start, length), where the start and length parameters correspond to the accounting introduced by the original string from which the ligand was created. This is a lossy operation, as, for instance, the ligand terminals are simply forgotten.

val basic_interval : t -> int -> int -> interval

basic_interval start length creates an interval based on the original string.

val get_interval_string : t -> interval -> string

get_interval_string l i returns the base string associated to the interval i in the ligand l. It is equal to the empty string if the length of the interval is zero.

val get_frag_string : frag -> string

FIXME: ...