github.com/NeowayLabs/nash@v0.2.2-0.20200127205349-a227041ffd50/docs/interactive.md (about)

     1  <!-- mdtocstart -->
     2  
     3  # Table of Contents
     4  
     5  - [Line mode](#line-mode)
     6  - [Autocomplete](#autocomplete)
     7  - [Hooks](#hooks)
     8  - [bindfn](#bindfn)
     9  
    10  <!-- mdtocend -->
    11  
    12  When used as an interactive shell, nash supports a few features to
    13  enhance user experience.
    14  
    15  # Line mode
    16  
    17  Nash supports line editing with `emacs` and `vim` modes. The default
    18  mode is `emacs` but it can be changed by the command `set mode vim`,
    19  or setting the environment variable `LINEMODE` with desired value.
    20  
    21  When in emacs mode, the following shortcuts can be used:
    22  
    23  | Shortcut           | Comment                           |
    24  | ------------------ | --------------------------------- |
    25  | `Ctrl`+`A`         | Beginning of line                 |
    26  | `Ctrl`+`B` / `←`   | Backward one character            |
    27  | `Meta`+`B`         | Backward one word                 |
    28  | `Ctrl`+`C`         | Send io.EOF                       |
    29  | `Ctrl`+`D`         | Delete one character/Close nash   |
    30  | `Meta`+`D`         | Delete one word                   |
    31  | `Ctrl`+`E`         | End of line                       |
    32  | `Ctrl`+`F` / `→`   | Forward one character             |
    33  | `Meta`+`F`         | Forward one word                  |
    34  | `Ctrl`+`H`         | Delete previous character         |
    35  | `Ctrl`+`I` / `Tab` | Command line completion           |
    36  | `Ctrl`+`J`         | Line feed                         |
    37  | `Ctrl`+`K`         | Cut text to the end of line       |
    38  | `Ctrl`+`L`         | Clear screen                      |
    39  | `Ctrl`+`M`         | Same as Enter key                 |
    40  | `Ctrl`+`T`         | Transpose characters              |
    41  | `Ctrl`+`U`         | Cut text to the beginning of line |
    42  | `Ctrl`+`W`         | Cut previous word                 |
    43  | `Backspace`        | Delete previous character         |
    44  | `Meta`+`Backspace` | Cut previous word                 |
    45  | `Enter`            | Line feed                         |
    46  
    47  # Autocomplete
    48  
    49  Nash doesn't have autocomplete built in, but it do has triggers to you
    50  implement it yourself.
    51  
    52  Every time the `TAB` or `CTRL-I (in emacs mode)` is pressed, nash
    53  looks for a function called `nash_complete` declared in the
    54  environment and calls it passing the line buffer and cursor position.
    55  
    56  The function must make the autocomplete using some external software
    57  (like [fzf fuzzy finder](https://github.com/junegunn/fzf)) and then
    58  return the characters to be completed. Below is a simple example to
    59  autocomplete system binaries using `fzf`:
    60  
    61  ```sh
    62  fn diffword(complete, line) {
    63      diff <= echo -n $complete | sed "s#^"+$line+"##g" | tr -d "\n"
    64  
    65      return $diff
    66  }
    67  
    68  fn nash_complete(line, pos) {
    69      ret = ()
    70      parts <= split($line, "\n")
    71  
    72      choice <= (
    73  		find /bin /usr/bin -maxdepth 1 -type f |
    74  		sed "s#/.*/##g" |
    75  		sort -u |
    76  		-fzf -q "^"+$line
    77  				-1
    78  				-0
    79  				--header "Looking for system-wide binaries"
    80  				--prompt "(λ programs)>"
    81  				--reverse
    82  
    83  	)
    84  
    85      if $status != "0" {
    86          return $ret
    87      }
    88  
    89      choice <= diffword($choice, $line)
    90  
    91  	ret = ($choice+" " "0")
    92  
    93  	return $ret
    94  }
    95  ```
    96  
    97  # Hooks
    98  
    99  There are two functions that can be used to update the environment
   100  while typing commands. The function `nash_repl_before` is called every
   101  time in the cli main loop *before* the printing of the `PROMPT`
   102  variable (and before user can type any command). And the function
   103  called `nash_repl_after` is called every time in the cli main loop
   104  too, but *after* the command was interpreted and executed.
   105  
   106  See the examples below:
   107  
   108  ```sh
   109  DEFPROMPT = "λ> "
   110  fn nash_repl_before() {
   111      # do something before prompt is ready
   112      datetime <= date "+%d/%m/%y %H:%M:%S"
   113      PROMPT = "("+$datetime+")"+$DEFPROMPT
   114      setenv PROMPT
   115  }
   116  
   117  fn nash_repl_after(line, status) {
   118      # do something after command was executed
   119      # line and status are the command issued and their
   120      # exit status (if applicable)
   121  }
   122  ```
   123  
   124  # bindfn
   125  
   126  Functions are commonly used for nash libraries,
   127  but when needed it can be bind'ed to some command name,
   128  so it can be used as a command from your shell prompt.
   129  
   130  For example, lets implement a **cd** using a function and bindfn.
   131  First define the function:
   132  
   133  ```nash
   134  fn cd(path) {
   135      fullpath <= realpath $path | xargs echo -n
   136      chdir($path)
   137      PROMPT="[" + $fullpath + "]> "
   138      setenv PROMPT
   139  }
   140  ```
   141  
   142  Using the **cd** function above, we can override the built-in
   143  **cd** with that function with the **bindfn** statement.
   144  
   145  ```nash
   146  λ> bindfn cd cd
   147  λ> cd /var/log
   148  [/var/log]>
   149  ```
   150  
   151  The bindfn syntax is:
   152  
   153  ```nash
   154  bindfn <function-name> <cmd-name>
   155  ```