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

     1  The directives for `config define` are listed below.
     2  
     3  {{ if env "DOCGEN_TARGET=" }}<div id="toc">
     4  
     5  - [DataType](#datatype)
     6  - [Description"](#description)
     7  - [Global](#global)
     8  - [Default](#default)
     9  - [Options](#options)
    10  - [Dynamic](#dynamic)
    11    - [Dynamic Read](#dynamic-read)
    12    - [Dynamic Write](#dynamic-write)
    13  
    14  </div>
    15  {{ end }}
    16  
    17  ```
    18  "DirectiveName": json data-type (default value)
    19  ```
    20  
    21  Where "default value" is what will be auto-populated if you don't include that
    22  directive (or "required" if the directive must be included).
    23  
    24  ### DataType
    25  
    26  > Value: `str` (required)
    27  
    28  This is the Murex data-type for the value.
    29  
    30  ### Description"
    31  
    32  > Value: `str` (required)
    33  
    34  Description is a required field to force developers into writing meaning hints
    35  enabling the discoverability of settings within Murex.
    36  
    37  ### Global
    38  
    39  > Value: `bool` (default: `false`)
    40  
    41  This defines whether this setting is global or scoped.
    42  
    43  All **Dynamic** settings _must_ also be **Global**. This is because **Dynamic**
    44  settings rely on a state that likely isn't scoped (eg the contents of a config
    45  file).
    46  
    47  ### Default
    48  
    49  > Value: any (required)
    50  
    51  This is the initialized and default value.
    52  
    53  ### Options
    54  
    55  > Value: array (default: `null`)
    56  
    57  Some suggested options (if known) to provide as autocompletion suggestions in
    58  the interactive command line.
    59  
    60  ### Dynamic
    61  
    62  > Value: map of strings (default: `null`)
    63  
    64  Only use this if config options need to be more than just static values stored
    65  inside Murex's runtime. Using **Dynamic** means `autocomplete get app key`
    66  and `autocomplete set app key value` will spawn off a subshell running a code
    67  block defined from the `Read` and `Write` mapped values. eg
    68  
    69  ```
    70  # Create the example config file
    71  out "this is the default value" |> example.conf
    72  
    73  config define example test5 %{
    74      Description: This is only an example
    75      DataType: str
    76      Global: true
    77      Dynamic: {
    78          Read: '{
    79              open example.conf
    80          }'
    81          Write: '{
    82              |> example.conf
    83          }'
    84      },
    85      
    86      # read the config file to get the default value
    87      Default: ${open example.conf}
    88  }
    89  ```
    90  
    91  It's also worth noting the different syntax between **Read** and **Default**.
    92  The **Read** code block is being executed when the **Read** directive is being
    93  requested, whereas the **Default** code block is being executed when the JSON
    94  is being read.
    95  
    96  In technical terms, the **Default** code block is being executed by Murex 
    97  when `config define` is getting executed where as the **Read** and **Write**
    98  code blocks are getting stored as a JSON string and then executed only when
    99  those hooks are getting triggered.
   100  
   101  #### Dynamic Read
   102  
   103  > Value: `str` (default: empty)
   104  
   105  This is executed when `autocomplete get app key` is ran. The STDOUT of the code
   106  block is the setting's value.
   107  
   108  #### Dynamic Write
   109  
   110  > Value: `str` (default: empty)
   111  
   112  This is executed when `autocomplete` is setting a value (eg `set`, `default`,
   113  `eval`). is ran. The STDIN of the code block is the new value.