The ControlRegistry structure

The ControlRegistry structure provides infrastructure for defining a hierarchical registry of controls.

Synopsis

signature CONTROL_REGISTRY
structure ControlRegistry : CONTROL_REGISTRY

Interface

type registry

type control_info = { envName : string option }

val new : {help : string} -> registry

val register : registry -> {
        ctl : string Controls.control,
        envName : string option
      } -> unit

val registerSet : registry -> {
        ctls : (string, 'a) ControlSet.control_set,
        mkEnvName : string -> string option
      } -> unit

val nest : registry -> {
        prefix : string option,
        pri : Controls.priority,
        obscurity : int,
        reg : registry
      } -> unit

val control : registry -> string list -> string Controls.control option

val init : registry -> unit

datatype registry_tree = RTree of {
    path : string list,
    help : string,
    ctls : { ctl : string Controls.control, info : control_info } list,
    subregs : registry_tree list
  }

val controls : (registry * int option) -> registry_tree

Description

type registry

the type of a control registry hierarchy.

type control_info = { envName : string option }

a record of information about a control. Currently, this record type only contains an optional environment-variable name for the control.

val new : {help : string} -> registry

new {help} creates a new registry, where the help string describes the registry.

val register : registry -> {ctl, envName} -> unit

register {ctl, envName} adds the control ctl to the registry reg. The optional string envName specifies the name of the environment variable that can be used to specify the value of the control.

val registerSet : registry -> {ctls, mkEnvName} -> unit

registerSet {ctls, mkEnvName} registers the controls in the control set ctls. The function mkEnvName is applied to the names of the controls to generate the optional environment-variable names.

val nest : registry -> {prefix, pri, obscurity, reg} -> unit

nest parent {prefix, pri, obscurity, reg} adds the registry reg as a child of the registry parent. The fields of the second argument have the following meaning:

prefix : string option

The prefix (or name) that qualifies the child registry (see the control function).

pri : Controls.priority

The registry’s priority; used when ordering the elements in a registry.

obscurity : int

The obscurity level of the registrion (higher means more obscure).

reg : registry

The child registry being added to parent.

val control : registry -> string list -> string Controls.control option

control reg path searches the registry for a control with the given path.

val init : registry -> unit

init reg uses the host process’s environment (as accessed by the OS.Process.getEnv function) to initialize those controls that have associated environment-variables.

datatype registry_tree = RTree of { …​ }

The registry_tree datatype provides a concrete representation of the registry hierarchy.

path : string list

is the full path to the node in the tree.

help : string

is the description of the node in the tree.

ctls : { ctl : string Controls.control, info : control_info } list

is a priority-ordered list of the controls at the node in the tree.

subregs : registry_tree list

is a priority-ordered list of the sub-registries at the node in the tree.

val controls : (registry * int option) -> registry_tree

controls (reg, optLevel) returns the registry_tree representation of the registry reg. If optLevel is SOME n, then sub-registries that have an obscurity level greater or equal to n are omitted from the result.

See Also

Controls, ControlSet, The Controls Library