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

     1  # `event`
     2  
     3  > Event driven programming for shell scripts
     4  
     5  ## Description
     6  
     7  Create or destroy an event interrupt,
     8  
     9  Each event will have subtilty different behaviour depending on the event itself
    10  due to the differing roles of each event system. Therefore it is recommended
    11  that you read the docs on each event to understand its behaviour.
    12  
    13  However while they might differ, the `event` API does try to retain a level of
    14  external consistency. For example each event in defined via `name=interrupt`
    15  where **name** is a user defined handle (like a variable or function would have
    16  a name) and **interrupt** is a system state you wish the event to be fired on.
    17  
    18  Each event function will have a payload sent via STDIN which would look a
    19  little like the following:
    20  
    21  ```
    22  {
    23      "Name": "",
    24      "Interrupt": {}
    25  }
    26  ```
    27  
    28  **Name** will always refer to the name you passed when defining the event. And
    29  **Interrupt** will carry any event specific metadata that might be useful to
    30  the event function. Thus the value of **Interrupt** will vary from one event to
    31  another.
    32  
    33  ## Usage
    34  
    35  ```
    36  event event-type name=interrupt { code block }
    37  
    38  !event event-type name
    39  ```
    40  
    41  ## Examples
    42  
    43  Create an event:
    44  
    45  ```
    46  event onSecondsElapsed autoquit=60 {
    47      out "You're 60 second timeout has elapsed. Quitting murex"
    48      exit 1
    49  }
    50  ```
    51  
    52  Destroy an event:
    53  
    54  ```
    55  !event onSecondsElapsed autoquit
    56  ```
    57  
    58  ## Detail
    59  
    60  ### Supported events
    61  
    62  * [`onCommandCompletion`](../events/oncommandcompletion.md):
    63    Trigger an event upon a command's completion
    64  * [`onFileSystemChange`](../events/onfilesystemchange.md):
    65    Add a filesystem watch
    66  * [`onPrompt`](../events/onprompt.md):
    67    Events triggered by changes in state of the interactive shell
    68  * [`onSecondsElapsed`](../events/onsecondselapsed.md):
    69    Events triggered by time intervals
    70  * [`onSignalReceived`](../events/onsignalreceived.md):
    71    Trap OS signals
    72  
    73  ### ANSI constants
    74  
    75  The `interrupt` field in the CLI supports ANSI constants. eg
    76  
    77  ```
    78  event onKeyPress f1={F1-VT100} {
    79      tout qs HintText="Key F1 Pressed"
    80  }
    81  ```
    82  
    83  ### Compiled events
    84  
    85  To list compiled event types:
    86  
    87  ```
    88  ยป runtime --events -> formap event ! { out $event }
    89  onCommandCompletion
    90  onFileSystemChange
    91  onKeyPress
    92  onPrompt
    93  onSecondsElapsed
    94  ```
    95  
    96  ## Synonyms
    97  
    98  * `event`
    99  * `!event`
   100  
   101  
   102  ## See Also
   103  
   104  * [`formap`](../commands/formap.md):
   105    Iterate through a map or other collection of data
   106  * [`function`](../commands/function.md):
   107    Define a function block
   108  * [`open`](../commands/open.md):
   109    Open a file with a preferred handler
   110  * [`private`](../commands/private.md):
   111    Define a private function block
   112  * [`runtime`](../commands/runtime.md):
   113    Returns runtime information on the internal state of Murex
   114  
   115  <hr/>
   116  
   117  This document was generated from [builtins/events/events_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/events/events_doc.yaml).