github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/core/config/config_doc.yaml (about)

     1  - DocumentID: config
     2    Title: >+
     3      `config`
     4    CategoryID: commands
     5    Summary: >-
     6      Query or define Murex runtime settings
     7    Description: |-
     8      Rather than Murex runtime settings being definable via obscure environmental
     9      variables, Murex instead supports a registry of config defined via the
    10      `config` command. This means any preferences and/or runtime config becomes
    11      centralised and discoverable.
    12  
    13    Usage: |-
    14      List all settings:
    15      
    16      ```
    17      config -> <stdout>
    18      ```
    19  
    20      Get a setting:
    21  
    22      ```
    23      config get app key -> <stdout>
    24      ```
    25  
    26      Set a setting:
    27  
    28      ```
    29      config set app key value
    30  
    31      <stdin> -> config set app key
    32  
    33      config eval app key { -> code-block }
    34      ```
    35  
    36      Define a new config setting:
    37  
    38      ```
    39      config define app key { json }
    40      ```
    41  
    42      Reset a setting to it's default value:
    43  
    44      ```
    45      !config app key
    46  
    47      config default app key
    48      ```
    49    Examples: |-
    50      Using `eval` to append to an array (in this instance, adding a function
    51      name to the list of "safe" commands)
    52      
    53      ```
    54      » function foobar { -> match foobar }
    55      » config eval shell safe-commands { -> append foobar }
    56      ```
    57    Flags:
    58    Detail: |-
    59      With regards to `config`, the following terms are applied:
    60  
    61      ### app
    62  
    63      This refers to a grouped category of settings. For example the name of a built
    64      in.
    65          
    66      Other app names include
    67  
    68      * `shell`: for "global" (system wide) Murex settings
    69      * `proc`: for scoped Murex settings
    70      * `http`: for settings that are applied to any processes which use the builtin
    71          HTTP user agent (eg `open`, `get`, `getfile`, `post`)
    72      * `test`: settings for Murex's test frameworks
    73      * `index`: settings for `[` (index)
    74  
    75      ### key
    76  
    77      This refers to the config setting itself. For example the "app" might be `http`
    78      but the "key" might be `timeout` - where the "key", in this instance, holds the
    79      value for how long any HTTP user agents might wait before timing out.
    80  
    81      ### value
    82  
    83      Value is the actual value of a setting. So the value for "app": `http`, "key":
    84      `timeout` might be `10`. eg
    85  
    86      ```
    87      » config get http timeout
    88      10
    89      ```
    90  
    91      ### scope
    92  
    93      Settings in `config`, by default, are scoped per function and module. Any
    94      functions called will inherit the settings of it's caller parent. However any
    95      child functions that then change the settings will only change settings for it's
    96      own function and not the parent caller.
    97  
    98      Please note that `config` settings are scoped differently to local variables.
    99  
   100      ### global
   101  
   102      Global settings defined inside a function will affect settings queried inside
   103      another executing function (same concept as global variables).
   104  
   105      ## Directives
   106  
   107      {{ include "builtins/core/config/config_doc.inc.md" }}
   108    Synonyms:
   109    - config
   110    - "!config"
   111    Related:
   112    - runtime
   113    - open
   114    - event
   115    - append
   116    - function
   117    - match
   118    - get
   119    - post
   120    - getfile
   121    - item-index
   122    - element
   123    - create-object
   124