- DocumentID: read
  Title: >+
    `read`
  CategoryID: commands
  Summary: >-
    `read` a line of input from the user and store as a variable
  Description: |-
    A readline function to allow a line of data inputed from the terminal.
  Usage: |-
    Classic usage:

    ```
    read: "prompt" var_name

    <stdin> -> read: var_name
    ```

    Script usage:

    ```
    read: [ --prompt "prompt"         ]
          [ --variable var_name       ]
          [ --default "default value" ]
          [ --datatype data-type      ]
          [ --autocomplete { json }   ]
          [ --mask character          ]
    ```
  Examples: |-
    **Classic usage:**

    ```
    read: "What is your name? " name
    out: "Hello $name"

    out: What is your name? -> read: name
    out: "Hello $name"
    ```

    **Script usage:**

    ```
    read: --prompt "Are you sure? [Y/n]" \
          --variable yn \
          --default Y
    ```

    **Secrets:**

    ```
    read: --prompt "Password: " --variable pw --mask *
    ```
  Detail: |-
    ### Classic Usage

    If `read` is called as a method then the prompt string is taken from STDIN.
    Otherwise the prompt string will be the first parameter. However if no prompt
    string is given then `read` will not write a prompt.

    The last parameter will be the variable name to store the string read by `read`.
    This variable cannot be prefixed by dollar, `$`, otherwise the shell will write
    the output of that variable as the last parameter rather than the name of the
    variable.

    The data type the `read` line will be stored as is `str` (string). If you
    require this to be different then please use `tread` (typed read) or call `read`
    with the `--datatype` flag as per the **script usage**.
  Flags:
    --prompt: User notification to display
    --variable: "Variable name to store the read data (default: read)"
    --datatype: "Murex data-type for the read data (default: str)"
    --default: If a zero length string is returned but neither `ctrl`+`c` nor `ctrl`+`d`
               were pressed, then the default value defined here will be returned
    --autocomplete: "Autocompletion suggestions. Can be either a JSON array or a JSON object"
    --mask: "Optional password mask, for reading secrets"
  Synonyms:
  Related:
  - tout
  - err
  - brace-quote
  - cast
  - greater-than
  - greater-than-greater-than
  - out
  - tread



- DocumentID: tread
  Title: >+
    `tread`
  CategoryID: commands
  Summary: >-
    `read` a line of input from the user and store as a user defined *typed* variable (deprecated)
  Description: |-
    A readline function to allow a line of data inputted from the terminal and then
    store that as a typed variable.

    **This builtin is now deprecated. Please use `read --datatype ...` instead**
  Usage: |-
    ```
    tread: data-type "prompt" var_name

    <stdin> -> tread: data-type var_name
    ```
  Examples: |-
    ```
    tread: qs "Please paste a URL: " url
    out: "The query string values included were:"
    $url -> format json

    out: Please paste a URL: -> tread: qs url
    out: "The query string values included were:"
    $url -> format json
    ```
  Detail: |-
    If `tread` is called as a method then the prompt string is taken from STDIN.
    Otherwise the prompt string will be the first parameter. However if no prompt
    string is given then `tread` will not write a prompt.

    The last parameter will be the variable name to store the string read by `tread`.
    This variable cannot be prefixed by dollar, `$`, otherwise the shell will write
    the output of that variable as the last parameter rather than the name of the
    variable.
  Synonyms:
  Related:
  - tout
  - err
  - brace-quote
  - cast
  - pretty
  - format
  - out
  - read