github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/events/events_doc.yaml (about)

     1  - DocumentID: event
     2    Title: >+
     3      `event`
     4    CategoryID: commands
     5    Summary: >-
     6      Event driven programming for shell scripts
     7    Description: |-
     8      Create or destroy an event interrupt,
     9  
    10      Each event will have subtilty different behaviour depending on the event itself
    11      due to the differing roles of each event system. Therefore it is recommended
    12      that you read the docs on each event to understand its behaviour.
    13  
    14      However while they might differ, the `event` API does try to retain a level of
    15      external consistency. For example each event in defined via `name=interrupt`
    16      where **name** is a user defined handle (like a variable or function would have
    17      a name) and **interrupt** is a system state you wish the event to be fired on.
    18  
    19      Each event function will have a payload sent via STDIN which would look a
    20      little like the following:
    21  
    22      ```
    23      {
    24          "Name": "",
    25          "Interrupt": {}
    26      }
    27      ```
    28  
    29      **Name** will always refer to the name you passed when defining the event. And
    30      **Interrupt** will carry any event specific metadata that might be useful to
    31      the event function. Thus the value of **Interrupt** will vary from one event to
    32      another.
    33    Usage: |-
    34      ```
    35      event event-type name=interrupt { code block }
    36  
    37      !event event-type name
    38      ```
    39    Examples: |-
    40      Create an event:
    41  
    42      ```
    43      event onSecondsElapsed autoquit=60 {
    44          out "You're 60 second timeout has elapsed. Quitting murex"
    45          exit 1
    46      }
    47      ```
    48  
    49      Destroy an event:
    50  
    51      ```
    52      !event onSecondsElapsed autoquit
    53      ```
    54    Flags:
    55    Detail: |-
    56      ### Supported events
    57  
    58      {{ include "gen/includes/autogenerated.events.inc.md" }}
    59  
    60      ### ANSI constants
    61  
    62      The `interrupt` field in the CLI supports ANSI constants. eg
    63  
    64      ```
    65      event onKeyPress f1={F1-VT100} {
    66          tout qs HintText="Key F1 Pressed"
    67      }
    68      ```
    69  
    70      ### Compiled events
    71  
    72      To list compiled event types:
    73  
    74      ```
    75      ยป runtime --events -> formap event ! { out $event }
    76      onCommandCompletion
    77      onFileSystemChange
    78      onKeyPress
    79      onPrompt
    80      onSecondsElapsed
    81      ```
    82    Synonyms:
    83      - event
    84      - "!event"
    85    Related:
    86      - runtime
    87      - private
    88      - function
    89      - open
    90      - formap