github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/events/onprompt.md (about) 1 # `onPrompt` 2 3 > Events triggered by changes in state of the interactive shell 4 5 ## Description 6 7 `onPrompt` events are triggered by changes in state of the interactive shell 8 (often referred to as _readline_). Those states are defined in the interrupts 9 section below. 10 11 ## Usage 12 13 ``` 14 event onPrompt name=(before|after|abort|eof) { code block } 15 16 !event onPrompt [before_|after_|abort_|eof_]name 17 ``` 18 19 ## Valid Interrupts 20 21 * `abort` 22 Triggered if `ctrl`+`c` pressed while in the interactive prompt 23 * `after` 24 Triggered after user has written a command into the interactive prompt and then hit `enter` 25 * `before` 26 Triggered before readline displays the interactive prompt 27 * `eof` 28 Triggered if `ctrl`+`d` pressed while in the interactive prompt 29 30 ## Payload 31 32 The following payload is passed to the function via STDIN: 33 34 ``` 35 { 36 "Name": "", 37 "Interrupt": { 38 "Name": "", 39 "Operation": "", 40 "CmdLine": "" 41 } 42 } 43 ``` 44 45 ### Name 46 47 This is the **namespaced** name -- ie the name and operation. 48 49 ### Interrupt/Name 50 51 This is the name you specified when defining the event. 52 53 ### Operation 54 55 This is the interrupt you specified when defining the event. 56 57 Valid interrupt operation values are specified below. 58 59 ### CmdLine 60 61 This is the commandline you typed in the prompt. 62 63 Please note this is only populated if the interrupt is **after**. 64 65 ## Examples 66 67 **Interrupt 'before':** 68 69 ``` 70 event onPrompt example=before { 71 out "This will appear before your command prompt" 72 } 73 ``` 74 75 **Interrupt 'after':** 76 77 ``` 78 event onPrompt example=after { 79 out "This will appear after you've hit [enter] on your command prompt" 80 out "...but before the command executes" 81 } 82 ``` 83 84 **Echo the command line:** 85 86 ``` 87 » event onPrompt echo=after { -> set event; out $event.Interrupt.CmdLine } 88 » echo hello world 89 echo hello world 90 hello world 91 ``` 92 93 ## Detail 94 95 ### Stdout 96 97 Stdout is written to the terminal. So this can be used to provide multiple 98 additional lines to the prompt since readline only supports one line for the 99 prompt itself and three extra lines for the hint text. 100 101 ### Order of execution 102 103 Interrupts are run in alphabetical order. So an event named "alfa" would run 104 before an event named "zulu". If you are writing multiple events and the order 105 of execution matters, then you can prefix the names with a number, eg `10_jump` 106 107 ### Namespacing 108 109 The `onPrompt` event differs a little from other events when it comes to the 110 namespacing of interrupts. Typically you cannot have multiple interrupts with 111 the same name for an event. However with `onPrompt` their names are further 112 namespaced by the interrupt name. In layman's terms this means `example=before` 113 wouldn't overwrite `example=after`. 114 115 The reason for this namespacing is because, unlike other events, you might 116 legitimately want the same name for different interrupts (eg a smart prompt 117 that has elements triggered from different interrupts). 118 119 ## See Also 120 121 * [Interactive Shell](../user-guide/interactive-shell.md): 122 What's different about Murex's interactive shell? 123 * [Terminal Hotkeys](../user-guide/terminal-keys.md): 124 A list of all the terminal hotkeys and their uses 125 * [`config`](../commands/config.md): 126 Query or define Murex runtime settings 127 * [`event`](../commands/event.md): 128 Event driven programming for shell scripts 129 * [`onCommandCompletion`](../events/oncommandcompletion.md): 130 Trigger an event upon a command's completion 131 * [onkeypress](../events/onkeypress.md): 132 133 134 <hr/> 135 136 This document was generated from [builtins/events/onPrompt/onprompt_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/events/onPrompt/onprompt_doc.yaml).