github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/commands/runtime.md (about)

     1  # `runtime`
     2  
     3  > Returns runtime information on the internal state of Murex
     4  
     5  ## Description
     6  
     7  `runtime` is a tool for querying the internal state of Murex. It's output
     8  will be JSON dumps.
     9  
    10  ## Usage
    11  
    12  ```
    13  runtime flags -> <stdout>
    14  ```
    15  
    16  `builtins` is an alias for `runtime --builtins`:
    17  
    18  ```
    19  builtins -> <stdout>
    20  ```
    21  
    22  ## Examples
    23  
    24  List all the builtin data-types that support WriteArray()
    25  
    26  ```
    27  » runtime --writearray
    28  [
    29      "*",
    30      "commonlog",
    31      "csexp",
    32      "hcl",
    33      "json",
    34      "jsonl",
    35      "qs",
    36      "sexp",
    37      "str",
    38      "toml",
    39      "yaml"
    40  ]
    41  ```
    42  
    43  List all the functions
    44  
    45  ```
    46  » runtime --functions -> [ agent aliases ]
    47  [
    48      {
    49          "Block": "\n    # Launch ssh-agent\n    ssh-agent -\u003e head -n2 -\u003e [ :0 ] -\u003e prefix \"export \" -\u003e source\n    ssh-add: @{g \u003c!null\u003e ~/.ssh/*.key} @{g \u003c!null\u003e ~/.ssh/*.pem}\n",
    50          "FileRef": {
    51              "Column": 1,
    52              "Line": 149,
    53              "Source": {
    54                  "DateTime": "2019-07-07T14:06:11.05581+01:00",
    55                  "Filename": "/home/lau/.murex_profile",
    56                  "Module": "profile/.murex_profile"
    57              }
    58          },
    59          "Summary": "Launch ssh-agent"
    60      },
    61      {
    62          "Block": "\n\t# Output the aliases in human readable format\n\truntime --aliases -\u003e formap name alias {\n        $name -\u003e sprintf \"%10s =\u003e ${esccli @alias}\\n\"\n\t} -\u003e cast str\n",
    63          "FileRef": {
    64              "Column": 1,
    65              "Line": 6,
    66              "Source": {
    67                  "DateTime": "2019-07-07T14:06:10.886706796+01:00",
    68                  "Filename": "(builtin)",
    69                  "Module": "source/builtin"
    70              }
    71          },
    72          "Summary": "Output the aliases in human readable format"
    73      }
    74  ]
    75  ```
    76  
    77  To get a list of every flag supported by `runtime`
    78  
    79  ```
    80  » runtime --help
    81  [
    82      "--aliases",
    83      "--config",
    84      "--debug",
    85      "--events",
    86      "--fids",
    87      "--flags",
    88      "--functions",
    89      "--help",
    90      "--indexes",
    91      "--marshallers",
    92      "--memstats",
    93      "--modules",
    94      "--named-pipes",
    95      "--open-agents",
    96      "--pipes",
    97      "--privates",
    98      "--readarray",
    99      "--readmap",
   100      "--sources",
   101      "--test-results",
   102      "--tests",
   103      "--unmarshallers",
   104      "--variables",
   105      "--writearray"
   106  ]
   107  ```
   108  
   109  Please also note that you can supply more than one flag. However when you
   110  do use multiple flags the top level of the JSON output will be a map of the
   111  flag names. eg
   112  
   113  ```
   114  » runtime --pipes --tests
   115  {
   116      "pipes": [
   117          "file",
   118          "std",
   119          "tcp-dial",
   120          "tcp-listen",
   121          "udp-dial",
   122          "udp-listen"
   123      ],
   124      "tests": {
   125          "state": {},
   126          "test": []
   127      }
   128  }
   129  
   130  » runtime --pipes
   131  [
   132      "file",
   133      "std",
   134      "tcp-dial",
   135      "tcp-listen",
   136      "udp-dial",
   137      "udp-listen"
   138  ]
   139  
   140  » runtime --tests
   141  {
   142      "state": {},
   143      "test": []
   144  }
   145  ```
   146  
   147  ## Flags
   148  
   149  * `--aliases`
   150      Lists all aliases
   151  * `--autocomplete`
   152      Lists all `autocomplete` schemas - both user defined and automatically generated one
   153  * `--builtins`
   154      Lists all builtin commands, compiled into Murex
   155  * `--config`
   156      Lists all properties available to `config`
   157  * `--debug`
   158      Outputs the state of debug and inspect mode
   159  * `--events`
   160      Lists all builtin event types and any defined events
   161  * `--exports`
   162      Outputs environmental variables. For Murex variables (`global` and `set`/`let`) use `--variables`
   163  * `--fids`
   164      Lists all running processes / functions
   165  * `--functions`
   166      Lists all Murex global functions
   167  * `--globals`
   168      Lists all global variables
   169  * `--help`
   170      Outputs a list of `runtimes`'s flags
   171  * `--indexes`
   172      Lists all builtin data-types which are supported by index (`[`)
   173  * `--marshallers`
   174      Lists all builtin data-types with marshallers (eg required for `format`)
   175  * `--memstats`
   176      Outputs the running state of Go's runtime
   177  * `--methods`
   178      Lists all commands with a defined STDOUT and STDIN data type. This is used to generate smarter autocompletion suggestions with `->`
   179  * `--modules`
   180      Lists all installed modules
   181  * `--named-pipes`
   182      Lists all named pipes defined
   183  * `--not-indexes`
   184      Lists all builtin data-types which are supported by index (`![`)
   185  * `--open-agents`
   186      Lists all registered `open` handlers 
   187  * `--pipes`
   188      Lists builtin pipes compiled into Murex. These can be then be defined as named-pipes
   189  * `--privates`
   190      Lists all Murex private functions
   191  * `--readarray`
   192      Lists all builtin data-types which support ReadArray()
   193  * `--readarraywithtype`
   194      Lists all builtin data-types which support ReadArrayWithType()
   195  * `--readmap`
   196      Lists all builtin data-types which support ReadMap()
   197  * `--sources`
   198      Lists all loaded murex sources
   199  * `--summaries`
   200      Outputs all the override summaries 
   201  * `--test-results`
   202      A dump of any unreported test results
   203  * `--tests`
   204      Lists defined tests
   205  * `--unmarshallers`
   206      Lists all builtin data-types with unmarshallers (eg required for `format`)
   207  * `--variables`
   208      Lists all local Murex variables which doesn't include environmental nor global variables
   209  * `--writearray`
   210      Lists all builtin data-types which support WriteArray()
   211  
   212  ## Detail
   213  
   214  ### Usage in scripts
   215  
   216  `runtime` should not be used in scripts because the output of `runtime` may
   217  be subject to change as and when the internal mechanics of Murex change.
   218  The purpose behind `runtime` is not to provide an API but rather to provide
   219  a verbose "dump" of the internal running state of Murex.
   220  
   221  If you require a stable API to script against then please use the respective
   222  command line tool. For example `fid-list` instead of `runtime --fids`. Some
   223  tools will provide a human readable output when STDOUT is a TTY but output
   224  a script parsable version when STDOUT is not a terminal.
   225  
   226  ```
   227  » fid-list
   228      FID   Parent    Scope  State         Run Mode  BG   Out Pipe    Err Pipe    Command     Parameters
   229        0        0        0  Executing     Shell     no                           -murex
   230   265499        0        0  Executing     Normal    no   out         err         fid-list
   231  
   232  » fid-list -> pretty
   233  [
   234      {
   235          "FID": 0,
   236          "Parent": 0,
   237          "Scope": 0,
   238          "State": "Executing",
   239          "Run Mode": "Shell",
   240          "BG": false,
   241          "Out Pipe": "",
   242          "Err Pipe": "",
   243          "Command": "-murex",
   244          "Parameters": ""
   245      },
   246      {
   247          "FID": 265540,
   248          "Parent": 0,
   249          "Scope": 0,
   250          "State": "Executing",
   251          "Run Mode": "Normal",
   252          "BG": false,
   253          "Out Pipe": "out",
   254          "Err Pipe": "err",
   255          "Command": "fid-list",
   256          "Parameters": ""
   257      },
   258      {
   259          "FID": 265541,
   260          "Parent": 0,
   261          "Scope": 0,
   262          "State": "Executing",
   263          "Run Mode": "Normal",
   264          "BG": false,
   265          "Out Pipe": "out",
   266          "Err Pipe": "err",
   267          "Command": "pretty",
   268          "Parameters": ""
   269      }
   270  ]
   271  ```
   272  
   273  ### File reference
   274  
   275  Some of the JSON dumps produced from `runtime` will include a map called
   276  `FileRef`. This is a trace of the source file that defined it. It is used
   277  by Murex to help provide meaningful errors (eg with line and character
   278  positions) however it is also useful for manually debugging user-defined
   279  properties such as which module or script defined an `autocomplete` schema.
   280  
   281  ### Debug mode
   282  
   283  When `debug` is enabled garbage collection is disabled for variables and
   284  FIDs. This means the output of `runtime --variables` and `runtime --fids`
   285  will contain more than just the currently defined variables and running
   286  functions.
   287  
   288  ## Synonyms
   289  
   290  * `runtime`
   291  * `builtins`
   292  
   293  
   294  ## See Also
   295  
   296  * [`[ Index ]`](../parser/item-index.md):
   297    Outputs an element from an array, map or table
   298  * [`autocomplete`](../commands/autocomplete.md):
   299    Set definitions for tab-completion in the command line
   300  * [`config`](../commands/config.md):
   301    Query or define Murex runtime settings
   302  * [`debug`](../commands/debug.md):
   303    Debugging information
   304  * [`event`](../commands/event.md):
   305    Event driven programming for shell scripts
   306  * [`export`](../commands/export.md):
   307    Define an environmental variable and set it's value
   308  * [`fid-list`](../commands/fid-list.md):
   309    Lists all running functions within the current Murex session
   310  * [`foreach`](../commands/foreach.md):
   311    Iterate through an array
   312  * [`formap`](../commands/formap.md):
   313    Iterate through a map or other collection of data
   314  * [`format`](../commands/format.md):
   315    Reformat one data-type into another data-type
   316  * [`function`](../commands/function.md):
   317    Define a function block
   318  * [`global`](../commands/global.md):
   319    Define a global variable and set it's value
   320  * [`let`](../commands/let.md):
   321    Evaluate a mathematical function and assign to variable (deprecated)
   322  * [`method`](../commands/method.md):
   323    Define a methods supported data-types
   324  * [`open`](../commands/open.md):
   325    Open a file with a preferred handler
   326  * [`openagent`](../commands/openagent.md):
   327    Creates a handler function for `open`
   328  * [`pipe`](../commands/pipe.md):
   329    Manage Murex named pipes
   330  * [`pretty`](../commands/pretty.md):
   331    Prettifies JSON to make it human readable
   332  * [`private`](../commands/private.md):
   333    Define a private function block
   334  * [`set`](../commands/set.md):
   335    Define a local variable and set it's value
   336  * [`source`](../commands/source.md):
   337    Import Murex code from another file of code block
   338  * [`test`](../commands/test.md):
   339    Murex's test framework - define tests, run tests and debug shell scripts
   340  
   341  <hr/>
   342  
   343  This document was generated from [builtins/core/runtime/runtime_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/runtime/runtime_doc.yaml).