The ControlRegistry structure
Author: John Reppy
Keywords: Standard ML, SML, SML/NJ Library

The SML of NJ Library
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

SML/NJ Version 110.99 (December 24, 2020)
Last updated 2020-05-20 00:54:25 UTC