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

The SML of NJ Library
The `Controls` structure

The `Controls` structure defines the basic types and operations for the Controls Library.

## Synopsis

    signature CONTROLS
    structure Controls : CONTROLS

## Interface

    type priority = int list
    type 'a control

    type 'a value_cvt = {
        tyName : string,
        fromString : string -> 'a option,
        toString : 'a -> string
      }

    val control : {
            name : string,
            pri : priority,
            obscurity : int,
            help : string,
            ctl : 'a ref
          } -> 'a control

    val genControl : {
            name : string,
            pri : priority,
            obscurity : int,
            help : string,
            default : 'a
          } -> 'a control

    exception ValueSyntax of {tyName : string, ctlName : string, value : string}

    val stringControl : 'a value_cvt -> 'a control -> string control

    val name : 'a control -> string
    val get : 'a control -> 'a
    val set : 'a control * 'a -> unit
    val set' : 'a control * 'a -> unit -> unit
    val help : 'a control -> string
    val info : 'a control -> {priority : priority, obscurity : int, help : string}

    val mkOptionFlag : {
            ctl : bool control,
            short : string,
            long : string option
          } -> unit GetOpt.opt_descr

    val mkOptionReqArg : {
            ctl : string control,
            arg : string,
            short : string,
            long : string option
          } -> unit GetOpt.opt_descr

    val mkOption : {
            ctl : string control,
            arg : string,
            default : string,
            short : string,
            long : string option
          } -> unit GetOpt.opt_descr

    val save'restore : 'a control -> unit -> unit

    val compare : ('a control * 'a control) -> order

## Description

`type priority = int list`

  something

`type 'a control`

  something

`type 'a value_cvt = { …​ }`

  A value converter is used to convert between strings and another type. The fields have the following meaning:

  `tyName : string`

    The name of the type being converted,

  `fromString : string -> 'a option`

    The function for converting from strings to the type.

  `toString : 'a -> string'`

    The function for converting from the type to strings.

`val control : {name, pri, obscurity, help, ctl} -> 'a control`

  `control {name, pri, obscurity, help, ctl}` creates a new control, where the arguments are

  `name : string`

    the name of the control.

  `pri : priority`

    the control’s priority.

  `obscurity : int`

    the control’s obscurity level (higher means more obscure).

  `help : string`

    the control’s description.

  `ctl : 'a ref`

    the reference cell that holds the control’s state.

`val genControl : {name, pri, obscurity, help, ctl, default} -> 'a control`

  `genControl {name, pri, obscurity, help, default}` creates a new control, where the arguments are

  `name : string`

    the name of the control.

  `pri : priority`

    the control’s priority.

  `obscurity : int`

    the control’s obscurity level (higher means more obscure).

  `help : string`

    the control’s description.

  `default : 'a`

    the initial, or default, value of the control.

`exception ValueSyntax of {tyName : string, ctlName : string, value : string}`

  This exception is raised to communicate that there is a syntax error in a string representation of a control value.

`val stringControl : 'a value_cvt -> 'a control -> string control`

  `stringControl cvt ctl` creates a string-valued interface to the control `ctl` using the given value converter.

`val name : 'a control -> string`

  `name ctl` returns the name of the control `ctl`.

`val get : 'a control -> 'a`

  `get ctl` returns the value of the control `ctl`.

`val set : 'a control * 'a -> unit`

  `set (ctl, v)` sets the value of the control `ctl` to `v`.

`val set' : 'a control * 'a -> unit -> unit (* delayed; error checking in 1st stage *)`

  `set (ctl, v)` returns a `unit -> unit` function that will set the value of the control `ctl` to `v`. This staged evaluation is useful when the control does some error checking (i.e., because it is the result of `stringControl`) on the value `v`. In that case, the value is checked for syntactic correctness and converted when `set'` is applied.

`val help : 'a control -> string`

  `help ctl` returns the description of the control `ctl`.

`val info : 'a control -> {priority : priority, obscurity : int, help : string}`

  `info ctl` returns a record `{priority, obscurity, help}`, where the fields of the result are

  `priority : priority`

    the control’s priority.

  `obscurity : int`

    the control’s obscurity level (higher means more obscure).

  `help : string`

    the control’s description.

`val mkOptionFlag : {ctl, short, long} -> unit GetOpt.opt_descr`

  `mkOptionFlag {ctl, short, long}` returns a command-line-option `GetOpt.NoArg` descriptor for a boolean control. The arguments are

  `ctl : bool control`

    the control that will be set by the command-line option.

  `short : string`

    the short name for the command-line option; either zero or one chars.

  `long : string option`

    an optional long-name for the command-line option.

`val mkOptionReqArg : {ctl, arg, short, long} -> unit GetOpt.opt_descr`

  `mkOptionReqArg {ctl, arg, short, long}` returns a command-line-option `GetOpt.ReqArg` descriptor for a string control, where an argument for the command-line option is required. The arguments to the call are

  `ctl : string control`

    the control that will be set by the command-line option.

  `arg : string`

    the name for the argument, which is used in the usage message.

  `short : string`

    the short name for the option; either zero or one chars.

  `long : string option`

    an optional long-name for the option.

`val mkOption : {ctl, arg, default, short, long} -> unit GetOpt.opt_descr`

  `mkOptionReqArg {ctl, arg, short, long}` returns a command-line-option `GetOpt.OptArg` descriptor for a string control, where an argument for the command-line option is optional. The arguments to the call are

  `ctl : string control`

    the control that will be set by the command-line option.

  `arg : string`

    the name for the argument, which is used in the usage message.

  `default : string`

    the default value for when no argument is given.

  `short : string`

    the short name for the command-line option; either zero or one chars.

  `long : string option`

    an optional long-name for the command-line option.

`val save’restore : 'a control -> unit -> unit`

  `save’restore ctl` saves the current value of the control and returns a `unit -> unit` function that will restore the value.

`val compare : ('a control * 'a control) -> order`

  `compare (ctl1, ctl2)` returns the priority order of the two controls.

## See Also

`ControlUtil`, The Controls Library, `GetOpt`

SML/NJ Version 110.99.6.1 (October 25, 2024)
Last updated 2024-10-25 16:47:18 UTC