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

     1  - DocumentID: oncommandcompletion
     2    Title: >+
     3      `onCommandCompletion`
     4    CategoryID: events
     5    Summary: >-
     6      Trigger an event upon a command's completion
     7    Description: |-
     8      `onCommandCompletion` events are triggered after a command has finished
     9      executing in the interactive terminal.
    10      
    11      Background processes or commands ran from inside aliases, functions, nested
    12      blocks or from shell scripts cannot trigger this event. This is to protect
    13      against accidental race conditions, infinite loops and breaking expected
    14      behaviour / the portability of Murex scripts. On those processes directly ran
    15      from the prompt can trigger this event.
    16    Usage: |-
    17      ```
    18      event onCommandCompletion name=command { code block }
    19  
    20      !event onCommandCompletion name
    21      ```
    22      The following payload is passed to the function via STDIN:
    23  
    24      ```
    25      {
    26          "Name": "",
    27          "Interrupt": {
    28              "Command": "",
    29              "Parameters": [],
    30              "Stdout": "",
    31              "Stderr": "",
    32              "ExitNum": 0
    33          }
    34      }
    35      ```
    36    Payload: |-
    37      ### Name
    38  
    39      This is the name you specified when defining the event.
    40  
    41      ### Command
    42  
    43      Name of command executed prior to this event being triggered
    44  
    45      ### Operation
    46  
    47      The commandline parameters of the aforementioned command
    48  
    49      ### Stdout
    50  
    51      This is the name of the Murex named pipe which contains a copy of the STDOUT
    52      from the command which executed prior to this event.
    53  
    54      You can read this with `read-named-pipe`. eg
    55  
    56      ```
    57      » <stdin> -> set: event
    58      » read-named-pipe: $event.Interrupt.Stdout -> ...
    59      ```
    60  
    61      ### Stderr
    62  
    63      This is the name of the Murex named pipe which contains a copy of the STDERR
    64      from the command which executed prior to this event.
    65  
    66      You can read this with `read-named-pipe`. eg
    67  
    68      ```
    69      » <stdin> -> set: event
    70      » read-named-pipe: $event.Interrupt.Stderr -> ...
    71      ```
    72  
    73      ### ExitNum
    74  
    75      This is the exit number returned from the executed command.
    76    Flags:
    77      <command>: >-
    78        Name of command that triggers this event
    79    Examples: |-
    80      **Read STDERR:**
    81  
    82      In this example we check the output from `pacman`, which is ArchLinux's package
    83      management tool, to see if you have accidentally ran it as a non-root user. If
    84      the STDERR contains a message saying you are no root, then this event function
    85      will re-run `pacman` with `sudo`.
    86  
    87      ```
    88      event onCommandCompletion sudo-pacman=pacman {
    89          <stdin> -> set event
    90          read-named-pipe $event.Interrupt.Stderr \
    91          -> regexp 'm/error: you cannot perform this operation unless you are root/' \
    92          -> if {
    93                sudo pacman @event.Interrupt.Parameters
    94             }
    95      }
    96      ```
    97    Detail: |-
    98      ### Stdout
    99  
   100      Stdout is written to the terminal. So this can be used to provide multiple
   101      additional lines to the prompt since readline only supports one line for the
   102      prompt itself and three extra lines for the hint text.
   103    Synonyms:
   104    - oncommandcompletion
   105    - onCommandCompletion
   106    Related:
   107    - onprompt
   108    - event
   109    - config
   110    - read-named-pipe
   111    - alias
   112    - function
   113    - regexp
   114    - if
   115    - namedpipes
   116    - stdin