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

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