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