Application Scenarios

Command Line, Foreground Evaluation

When performing batch processing of documents, it might be necessary to initiate a new interpreter session solely for the evaluation's duration rather than re-using the currently running session. The --foreground option can be used to activate this mode.

$ cat document.md.in | litrepl --foreground eval-sections > document.md

Command Line, Detecting Python Exceptions

Another frequently requested feature is the ability to report unhandled exceptions. Litrepl can be configured to return a non-zero exit code in such scenarios.

$ cat document.md
``` python
raise Exception("D'oh!")
```
$ cat document.md | litrepl --foreground --exception-exit=200 eval-sections
$ echo $?
200

In this example, the --foreground option instructs Litrepl to start a new interpreter session, stopping it upon completion. The --exception-exit=200 option specifies the exit code to be returned in the event of unhandled exceptions.

Command Line, Running Remote Interpreters Over SSH

Litrepl supports running interpreters over SSH on a remote machine. In order to do so, one needs to create a shell script establishing the communication and name it in a recognizable way.

For example, consider the case where we edit a local document but all sections that we want to execute should be run on a remote machine named testbed.

We prepare an executable script named ipython-testbed.sh and put it into a directory listed in the PATH environment variable. The contents of the script is the following:

#!/bin/sh
exec ssh testbed -p 22 -- bash --login -c ipython "$@"

Now, we can process our document as usual, but add ipython-testbed.sh as a new IPython interpreter:

# Executes code sections on a remote machine.
cat README.md | litrepl --python-interpreter=ipython-testbed.sh

Note that the string ipython must appear in the interpreter name, to let Litrepl exercise IPyhton-specific communication settings.

GNU Make, Evaluating Code Sections in Project Documentation

A typical Makefile recipe for updating documentation is structured as follows:

SRC = $(shell find -name '*\.py')

.stamp_readme: $(SRC) Makefile
    cp README.md _README.md.in
    cat _README.md.in | \
        litrepl --foreground --exception-exit=100 \
                --python-interpreter=ipython \
                --sh-interpreter=- \
        eval-sections >README.md
    touch $@

.PHONY: readme
readme: .stamp_readme

Here, $(SRC) is expected to include the filenames of dependencies. With this recipe, we can run make readme to evaluate the python sections. By passing - wealso tell Litrepl to ignore shell sections.

Vim, Setting Up Keybindings

The litrepl.vim plugin does not define any keybindings, but users could do it by themselves, for example:

nnoremap <F5> :LEval<CR>
nnoremap <F6> :LEvalAsync<CR>

Vim, Inserting New Sections

The litrepl.vim plugin doesn't include tools for creating section formatting, however they can be added easily if required. Below, we demonstrate how to define the :C command inserting new python sections.

command! -buffer -nargs=0 C normal 0i``` python<CR>```<CR><CR>``` result<CR>```<Esc>4k

Vim, Running the Initial Section After Interpreter Restart

Below we demonstrate how to define the :LR command for running first section after the restart.

command! -nargs=0 LR LRestart | LEval 0

Vim, Evaluating Selected Text

Litrepl vim plugin defines LitReplEvalSelection function which runs the selection as a virtual code section. The section type is passed as the function argument. For example, calling LitReplEvalSelection('ai') will execute the selection as if it is an ai code section. The execution result is pasted right after the selection as a plain text. LitReplEvalSelection('python') would pipe the selection through the current Python interpreter.

To use the feature, define a suitable key binding (Ctrl+K in this example),

vnoremap <C-k> :call LitReplEvalSelection('ai')<CR>

Now write a question to the AI in any document, select it and hit Ctrl+K.

Hi model. What is the capital of New Zealand?

Upon the keypress, Litrepl pipes the selection through the AI interpreter - the aicli at the time of this writing - and paste the response right after the last line of the original selection.

Hi model. What is the capital of New Zealand?
The capital of New Zealand is Wellington.

Internally, the plugin just uses eval-code Litrepl command.

Vim, Calling for AI on a visual selection

Note: litrepl_extras.vim has been reworked since 3.14.0.

Note: this is not stable and a subject to change.

The repository includes litrepl_extras.vim, which defines a generic interface for external text‑rewriting tools. While it can work with a variety of backends, it is primarily designed to integrate smoothly with Aicli sessions powered by Litrepl.

The litrepl_extras.vim defines the following Vim commands:

  • :LPush[!] <script> <prompt> Calls the litrepl-<script> executable and echoes its output.
  • :LPipe[!] <script> <prompt> pipes the selection through the litrepl-<script> executable (if there is a selection) or inserts the executable's output at the cursor position.
  • :LPipeFile[!] <script> <prompt> pipes the current file through the litrepl-<script> executable (if there is a selection) or inserts the executable's output at the cursor position.

All the above commands get translated into a command line matching the following convension (subject to change):

usage: litrepl-<script> [-h] [-P PROMPT_LIST] [-s SELECTION_PASTE]
                        [-S SELECTION_RAW] [-f OUTPUT_FORMAT] [-w TEXTWIDTH]
                        [-v] [--location NAME LOC]
                        [--location-raw NAME LOC] [--command COMMAND]
                        ...

positional arguments:
  files

options:
  -h, --help            show this help message and exit
  -P PROMPT_LIST, --prompt PROMPT_LIST
  -s SELECTION_PASTE, --selection-paste SELECTION_PASTE
  -S SELECTION_RAW, --selection-raw SELECTION_RAW
  -f OUTPUT_FORMAT, --output-format OUTPUT_FORMAT
  -w TEXTWIDTH, --textwidth TEXTWIDTH
  -v, -d, --debug, --verbose
  --dry-run
  --location NAME LOC
  --location-raw NAME LOC
  --command COMMAND

The command is currently set to the fixed eval-code string literal.

The bang versions of the Vim commands cause -S (disable escaping commands within the selection) to be used instead of -s (escape the selection). For Aicli this means that the /commands would be executed rather than passed to an LLM model.

Users are free to write their own scripts. The completion will try to match the litrepl-* pattern to a unique match. For example, below is the example of the litrepl-grammar.sh script, which asks AI to correct the grammar of the selected text:

#!/bin/sh

exec litrepl-aicli.py -P "Please correct English grammar within the 'selection'. Keep the choice of words, minimize the changes you make." "$@"