config_doc.yaml

- DocumentID: config
  Title: >+
    Shell Configuration And Settings (`config`)
  CategoryID: commands
  SubCategoryIDs: [ commands.shell ]
  Summary: >-
    Query or define Murex runtime settings
  Description: |-
    Rather than Murex runtime settings being definable via obscure environmental
    variables, Murex instead supports a registry of config defined via the
    `config` command. This means any preferences and/or runtime config becomes
    centralised and discoverable.

    ## Terminology
    
    The following terms have special means with regards to `config`:

    ### app

    _app_ refers to a grouped category of settings. For example the name of an
    integration or builtin.
        
    Other _app_ names include

    * `shell`: for "global" (system wide) Murex settings
    * `proc`: for scoped Murex settings
    * `http`: for settings that are applied to any processes which use the builtin
        HTTP user agent (eg `open`, `get`, `getfile`, `post`)
    * `test`: settings for Murex's test frameworks
    * `index`: settings for `[` (index)

    ### key

    _key_ refers to the config setting itself. For example the _app_ might be `http`
    but the _key_ might be `timeout` - where the _key_, in this instance, holds the
    value for how long any HTTP user agents might wait before timing out.

    ### value

    _value_ is the actual value of a setting. So the value for _app_: `http`, _key_:
    `timeout` might be `10`. eg

    ```
    » config get http timeout
    10
    ```
  Usage: |-
    ### Get value

    ```
    config get app key -> <stdout>
    ```

    ### Set value

    ```
               config set  app key value
    <stdin> -> config set  app key
               config eval app key { code-block }
    ```

    ### Reset to default

    ```
    !config app key
    config default app key
    ```

    ### Define custom configs

    ```
    config define app key { json }
    ```
  Examples: |-
    ### eval

    Using `eval` to append to an array (in this instance, adding a function
    name to the list of "safe" commands):
    
    ```
    » config eval shell safe-commands { -> append function-name }
    ```

    You could also use the `~>` operator too:

    ```
    » config eval shell safe-commands { ~> %[function-name] }
    ```
  Flags:
    get: >-
      Output the currently held config _value_ without changing it
    set: >-
      Change the _value_ of an _app_'s _key_. `set` does not print any output
    default: >-
      Reset a the value of _app_'s _key_ to its default _value_
      (the default _value_ is defined by the same process that defines the config field)
    define: >-
      Allows you to create custom config options.
      See {{bookmark "Custom Config Directives" "config" "custom-config-directives"}} to learn how to use `define`
  Detail: |-
    ### scope

    Settings in `config`, by default, are scoped per function and module. Any
    functions called will inherit the settings of it's caller parent. However any
    child functions that then change the settings will only change settings for it's
    own function and not the parent caller.

    ### global

    Global settings defined inside a function will affect settings queried inside
    another executing function (same concept as global variables).

    ## Custom Config Directives

    {{ include "builtins/core/config/config_doc.inc.md" }}
  Synonyms:
  - config
  - "!config"
  Related:
  - runtime
  - open
  - event
  - append
  - function
  - match
  - get
  - post
  - getfile
  - item-index
  - element
  - create-object
  - alter