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).