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

     1  - DocumentID: onsignalreceived
     2    Title: >+
     3      `onSignalReceived`
     4    CategoryID: events
     5    Summary: >-
     6      Trap OS signals
     7    Description: |-
     8      `onSignalReceived` events are triggered by OS signals.
     9  
    10      {{ include "builtins/events/onSignalReceived/signals.inc.md" }}
    11  
    12      This event is designed to be used in shell scripts. While this event can be
    13      used with the shell in interactive mode (ie from the REPL prompt), this might
    14      result in unexpected behaviour. Thus it is only recommended to use
    15      `onSignalReceived` for shell scripts.
    16    Usage: |-
    17      ```
    18      event onSignalReceived name=SIGNAL { code block }
    19  
    20      !event onSignalReceived [SIGNAL]name
    21      ```
    22    Payload: |-
    23      The following payload is passed to the function via STDIN:
    24  
    25      ```
    26      {
    27          "Name": "",
    28          "Interrupt": {
    29              "Name": "",
    30              "Signal": ""
    31          }
    32      }
    33      ```
    34  
    35      ### Name
    36  
    37      This is the **namespaced** name -- ie the name and operation.
    38  
    39      ### Interrupt/Name
    40  
    41      This is the name you specified when defining the event.
    42  
    43      ### Signal
    44  
    45      This is the signal you specified when defining the event.
    46  
    47      Valid interrupt operation values are specified below. All interrupts / signals
    48      are UPPERCASE strings.
    49  
    50    Examples: |-
    51      **Interrupt 'SIGINT':**
    52  
    53      ```
    54      event onSignalReceived example=SIGINT {
    55          out "SIGINT received, not quitting"
    56      }
    57      ```
    58  
    59    Flags:
    60      SIGHUP: >-
    61        **"Signal hangup"** -- triggered when a controlling terminal is closed (eg the terminal emulator closed)
    62      SIGINT: >-
    63        **"Signal interrupt"** -- triggered when a user interrupts a process, typically via `ctrl`+`c`
    64      SIGQUIT: >-
    65        **"Signal quit"** -- when the user requests that the process quits and performs a core dump
    66      SIGTERM: >-
    67        **"Signal terminate"** -- triggered by a request for a processes termination. Similar to `SIGINT`
    68      SIGWINCH: >-
    69        **"Signal window change"** -- triggered when the TTY (eg terminal emulator) is resized
    70      SIGUSR1: >-
    71        **"Signal user 1"** -- user defined
    72      SIGUSR2: >-
    73        **"Signal user 2"** -- user defined
    74  
    75    Detail: |-
    76      {{ include "builtins/events/onSignalReceived/signal_detail.inc.md" }}
    77  
    78      ### Stdout
    79  
    80      Stdout is written to the terminal. So this can be used to provide multiple
    81      additional lines to the prompt since readline only supports one line for the
    82      prompt itself and three extra lines for the hint text.
    83    
    84      ### Order of execution
    85  
    86      Interrupts are run in alphabetical order. So an event named "alfa" would run
    87      before an event named "zulu". If you are writing multiple events and the order
    88      of execution matters, then you can prefix the names with a number, eg `10_jump`
    89  
    90      ### Namespacing
    91  
    92      The `onSignalReceived` event differs a little from other events when it comes
    93      to the namespacing of interrupts. Typically you cannot have multiple interrupts
    94      with the same name for an event. However with `onPrompt` their names are
    95      further namespaced by the interrupt name. In layman's terms this means
    96      `example=SIGINT` wouldn't overwrite `example=SIGQUIT`.
    97      
    98      The reason for this namespacing is because, unlike other events, you might
    99      legitimately want the same name for different interrupts.
   100    Synonyms:
   101    - onsignalreceived
   102    - onSignalReceived
   103    Related:
   104    - onprompt
   105    - oncommandcompletion
   106    - terminal-keys
   107    - interactive-shell
   108    - event
   109    - signal