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

     1  # `onCommandCompletion`
     2  
     3  > Trigger an event upon a command's completion
     4  
     5  ## Description
     6  
     7  `onCommandCompletion` events are triggered after a command has finished
     8  executing in the interactive terminal.
     9  
    10  Background processes or commands ran from inside aliases, functions, nested
    11  blocks or from shell scripts cannot trigger this event. This is to protect
    12  against accidental race conditions, infinite loops and breaking expected
    13  behaviour / the portability of Murex scripts. On those processes directly ran
    14  from the prompt can trigger this event.
    15  
    16  ## Usage
    17  
    18  ```
    19  event onCommandCompletion name=command { code block }
    20  
    21  !event onCommandCompletion name
    22  ```
    23  The following payload is passed to the function via STDIN:
    24  
    25  ```
    26  {
    27      "Name": "",
    28      "Interrupt": {
    29          "Command": "",
    30          "Parameters": [],
    31          "Stdout": "",
    32          "Stderr": "",
    33          "ExitNum": 0
    34      }
    35  }
    36  ```
    37  
    38  ## Valid Interrupts
    39  
    40  * `<command>`
    41      Name of command that triggers this event
    42  
    43  ## Payload
    44  
    45  ### Name
    46  
    47  This is the name you specified when defining the event.
    48  
    49  ### Command
    50  
    51  Name of command executed prior to this event being triggered
    52  
    53  ### Operation
    54  
    55  The commandline parameters of the aforementioned command
    56  
    57  ### Stdout
    58  
    59  This is the name of the Murex named pipe which contains a copy of the STDOUT
    60  from the command which executed prior to this event.
    61  
    62  You can read this with `read-named-pipe`. eg
    63  
    64  ```
    65  » <stdin> -> set: event
    66  » read-named-pipe: $event.Interrupt.Stdout -> ...
    67  ```
    68  
    69  ### Stderr
    70  
    71  This is the name of the Murex named pipe which contains a copy of the STDERR
    72  from the command which executed prior to this event.
    73  
    74  You can read this with `read-named-pipe`. eg
    75  
    76  ```
    77  » <stdin> -> set: event
    78  » read-named-pipe: $event.Interrupt.Stderr -> ...
    79  ```
    80  
    81  ### ExitNum
    82  
    83  This is the exit number returned from the executed command.
    84  
    85  ## Examples
    86  
    87  **Read STDERR:**
    88  
    89  In this example we check the output from `pacman`, which is ArchLinux's package
    90  management tool, to see if you have accidentally ran it as a non-root user. If
    91  the STDERR contains a message saying you are no root, then this event function
    92  will re-run `pacman` with `sudo`.
    93  
    94  ```
    95  event onCommandCompletion sudo-pacman=pacman {
    96      <stdin> -> set event
    97      read-named-pipe $event.Interrupt.Stderr \
    98      -> regexp 'm/error: you cannot perform this operation unless you are root/' \
    99      -> if {
   100            sudo pacman @event.Interrupt.Parameters
   101         }
   102  }
   103  ```
   104  
   105  ## Detail
   106  
   107  ### Stdout
   108  
   109  Stdout is written to the terminal. So this can be used to provide multiple
   110  additional lines to the prompt since readline only supports one line for the
   111  prompt itself and three extra lines for the hint text.
   112  
   113  ## See Also
   114  
   115  * [Named Pipes](../user-guide/namedpipes.md):
   116    A detailed breakdown of named pipes in Murex
   117  * [`<stdin>`](../commands/stdin.md):
   118    Read the STDIN belonging to the parent code block
   119  * [`alias`](../commands/alias.md):
   120    Create an alias for a command
   121  * [`config`](../commands/config.md):
   122    Query or define Murex runtime settings
   123  * [`event`](../commands/event.md):
   124    Event driven programming for shell scripts
   125  * [`function`](../commands/function.md):
   126    Define a function block
   127  * [`if`](../commands/if.md):
   128    Conditional statement to execute different blocks of code depending on the result of the condition
   129  * [`onPrompt`](../events/onprompt.md):
   130    Events triggered by changes in state of the interactive shell
   131  * [`regexp`](../commands/regexp.md):
   132    Regexp tools for arrays / lists of strings
   133  * [read-named-pipe](../parser/namedpipe.md):
   134    Reads from a Murex named pipe
   135  
   136  <hr/>
   137  
   138  This document was generated from [builtins/events/onCommandCompletion/oncommandcompletion_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/events/onCommandCompletion/oncommandcompletion_doc.yaml).