Package: litrepl
LitREPLLitREPLis a command-line tool and a Vim plugin forliterate
programmingin Python,
aimed at providing user-friendly code editing and execution workflows.Consider a Markdown document:``` python
print("Hello, World!")```With LitREPL users get :LEval command executing the code above. The executiontakes place in a persistent background Python interpreter session.``` resultHello, World!```FeaturesSupported document formats: Markdown[Example], Latex[Example][Example (PDF)].Supported Python interpreters: Python, IPythonSupported modes: Vim, Command-lineRequirementsPOSIX-compatible OS, typically a Linux. The plugin relies on POSIX pipes and
depends on certain shell commands.More or less recentVimPython3 with the following libraries:lark-parser(Required).Command line tools:GNU socat(Optional),ipython(Optional).ContentsInstallationUsageMarkdownLaTeXReferenceCommandsVariables and argumentsHintsVim, adding keybindingsVim, inserting new sectionsVim, executing first section after restartVim, running shell commandsCommand line, basic usageDevelopmentDevelopment shellsCommon workflowsOther Nix targetsGalleryTechnical detailsLimitationsRelated projectsThird-party issuesInstallationThe repository includes a Python tool and an interface Vim plugin. The Python
part should be installed withpip installas usual. The Vim part requires
plugin manager likePlugor hand-copying files to a .vim config folder.The generic installation procedure:Pip-install and Vim-PlugInstructions for the Python Pip andVim Plug:Install thelitreplPython package with pip:$pipinstall--usergit+https://github.com/grwlf/litrepl.vim
$litrepl--versionInstall the Vim plugin by adding the following line between theplug#beginandplug#endlines of your.vimrcfile:Plug'https://github.com/grwlf/litrepl.vim',{'rtp':'vim'}Note:rtpsets the custom vim-plugin source directory of the plugin.Alternatively, Nix/NixOS users can follow the formalized path:Nix and vim_configurableNix supportsconfigurable Vim expressions.
To enable the Litrepl plugin, just add thevim-litrepl.vim-litrepl-releaseto the
list of Vim packages.letvim-litrepl=import<path/to/litrepl.vim>{};invim_configurable.customize{name="vim";vimrcConfig.packages.myVimPackage=withpkgs.vimPlugins;{start=[...vim-litrepl.vim-litrepl-release...];};}Note:vim-demoexpression from thedefault.nixprovides
an example Vim configuration. Usenix build '.#vim-demo'to build it and then./result/bin/vim-demoto run the editor.See theDevelopmentsection for more details.UsageMarkdownCreate code and result sections. Put some Python code into the code section.
Leave the result section emtpy.``` python
print('Code here!')`````` result```Place the cursor on any of the secions and run the:LEvalcommand. Litrepl
will run the Python interpreter, evaluate the code and paste the output into
the result section.Re-evaluate sections as needed. The interpreter will preserve its internal
state between runs.See also:Formatting Markdown documentsLaTeXDefinelcodeandlresultLaTeX environments according to the style of your
document. The minimal working example might look like this:\newenvironment{lcode}{\verbatim}{\endverbatim}\newenvironment{lresult}{\verbatim}{\endverbatim}Create code and result sections in the body of your document. Put some Python
code into the code section.  Leave the result section emtpy.\begin{lcode}print('Code here!')\end{lcode}\begin{lresult}\end{lresult}Place the cursor on any of the secions and run the:LEvalcommand.Re-evaluate sections as needed. The interpreter will preserve its internal
state between runs.See also:Formatting LaTeX documentsReferenceCommandsVimCommand lineDescription:LStartlitepl startStart the interpreter:LStoplitepl stopStop the interpreter:LStatuslitepl status <FPrint the daemon status:LRestartlitrepl restartRestart the interpreter:LEval Nlirtepl eval-sections (N|L:C) <FRun or update section under the cursor and wait until the completion:LEvalAbove Nlirtepl eval-sections '0..(N|L:C)' <FRun sections above and under the cursor and wait until the completion:LEvalBelow Nlirtepl eval-sections '(N|L:C)..$' <FRun sections below and under the cursor and wait until the completion:LEvalAsync Nlirtepl --timeout-initial=0.5 --timeout-continue=0 eval-sections (N|L:C) <FRun section under the cursor and wait a bit before going asynchronous. Also, update the output from the already running section.:LInterruptlirtepl interrupt (N|L:C) <FSend Ctrl+C signal to the interpreter and get a feedback:LEvalAlllirtepl eval-sections '0..$' <FEvaluate all code sectionslirtepl eval-code <PEvaluate the given Python code:LTermlirtepl replOpen the terminal to the interpreter:LOpenErrN/AOpen the stderr window:LVersionlitrepl --versionShow versionWhereFdenotes the documentPdenotes the Python codeNdenotes the number of code section starting from 0.L:Cdenotes line:column of the cursor.Variables and argumentsVim settingCLI argumentDescriptionset filetype--filetype=TInput file type:latex|markdownN/A--interpreter=IThe interpreter to use:python|ipython|auto(the default)let g:litrepl_debug=0/1--debug=1Print debug messages to the stderrlet g:litrepl_errfile="/tmp/litrepl.vim"N/AIntermediary file for debug and error messageslet g:litrepl_always_show_stderr=0/1N/ASet to auto-open stderr window after each executionlet g:litrepl_timeout=FLOAT--timeout-initial=FLOATTimeout to wait for the new executions, in seconds, defaults to infN/A--timeout-continue=FLOATTimeout to wait for executions which are already running, in seconds, defaults to infIis taken into account by thestartcommand or by the first call toeval-sections.HintsVim, adding keybindingsThe 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 sectionsLets define a handful command:C<CR>for inserting new sections.command!-buffer-nargs=0C normal0i``` python<CR>```<CR><CR>``` result<CR>```<Esc>4kVim, executing first section after restartWe define the:LRcommand running first section after the restart.command!-nargs=0LR LRestart|LEval0Vim, running shell commandsThanks to IPython features, we can use exclamation to run shell commands
directly from Python code sections.``` python
!cowsay "Hi Litrepl"
```

``` result
 ____________ 
< Hi Litrepl >
 ------------ 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
```Command line, basic usageTo evaluate code section in a document:$catdoc/example.md|litrepl--filetype=markdown--interpreter=ipython\eval-sections0..$>output.mdTo evaluate a Python script:$catscript.py|litrepl--interpreter=ipythoneval-codeDevelopmentThis project usesNixas a primary development
framework.flake.nixhandles the source-level Nix dependencies
while thedefault.nixdefines the common build targets
including Pypi and Vim packages, demo Vim configurations, development shells,
etc.Development shellsThe default development shell is defined in the./default.nixas a Nix
expression namedshell. Nix makes sure that all the dependencies are available
inside. To enter this shell, run:$nixdevelopAnother shell which might be useful isshell-screencast. To run it, specify
the full Nix-flake path as follows:$nixdevelop'.#shell-screencast'Common workflowsThe top-levelMakefileencodes typical workflows to be executed
from within the development shell:[LitREPL-develop]$makehelpLitREPLisamacroprocessingPythonlibraryforLitrateprogrammingandcodeexecution
Buildtargets:
help:Printhelptest:Runthetestscript(./sh/test.sh)wheel:BuildPythonwheel(theDEFAULTtarget)version:Printtheversion
upload:UploadwheeltoPypi.org(./_token.pypiisrequired)Other Nix targetsTo build individual Nix expressions, run thenix build '.#NAME'passing the
name of the expression to build. If succeeded, Nix publishes the last build
results under the./resultsymlink.$nixbuild'.#vim-demo'$./result/bin/vim-demo# Run the pre-configured demo instance of VimThe list of Nix build targets includes:litrepl-release- Litrepl script and Python liblitrepl-release-pypi- Litrepl script and Python libvim-litrepl-release- Vim with locally built litrepl pluginvim-litrepl-release-pypi- Vim with litrepl plugin built from PYPIvim-test- A minimalistic Vim with a single litrepl pluginvim-demo- Vim configured to use litrepl suitable for recording screencastsvim-plug- Vim configured to use litrepl via the Plug managershell-dev- The development shellshell-screencast- The shell for recording demonstrations, includesvim-demo.GalleryBasic usageUsing LitREPL in combination with theVimtexplugin to edit Latex documents on the fly.Asynchronous code executionTechnical detailsThe following events should normally happen after users type the:LitEval1command:On the first run, LitREPL starts the Python interpreter in the background.
Its standard input and output are redirected into UNIX pipes in the current
directory.LitREPL runs the whole document through the express Markdown/Latex parser
determining the start/stop positions of code and result sections. The cursor
position is also available and the code from the right code section can
reach the interpreter.The process which reads the interpreter's response is forked out of the main
LitREPL process. The output goes to the temporary file.If the interpreter reports the completion quickly, the output is pasted to
the resulting document immediately. Otherwise, the temporary results are
pasted.Re-evaluating sections with temporary results causes LitREPL to update
these results.LimitationsFormatting: Nested code sections are not supported.Formatting: Special symbols in the Python output could invalidate the
document.Interpreter: Extra newline is required after Python function definitions.Interpreter: Stdout and stderr are joined together.Interpreter: Evaluation of a code section locks the editor.Interpreter: Tweakingos.ps1/os.ps2prompts of the Python interpreter
could break the session.Interpreter: No asynchronous code execution.Interpreter: Background Python interpreter couldn't be interruptedRelated projectsEdititng:https://github.com/lervag/vimtex(LaTeX editing, LaTeX preview)https://github.com/shime/vim-livedown(Markdown preview)https://github.com/preservim/vim-markdown(Markdown editing)Code execution:Vim-medievalhttps://github.com/gpanders/vim-medievalEvaluates Markdown code sectionsPyluatexhttps://www.ctan.org/pkg/pyluatexMagma-nvimhttps://github.com/dccsillag/magma-nvimCodihttps://github.com/metakirby5/codi.vimPythontexhttps://github.com/gpoore/pythontexEvaluates Latex code sectionsCodebraidhttps://github.com/gpoore/codebraidVim-ipython-cellhttps://github.com/hanschen/vim-ipython-cellVim-ipythonhttps://github.com/ivanov/vim-ipythonJupytexthttps://github.com/goerz/jupytext.vimAlternative?https://github.com/mwouts/jupytextIpython-vimceptionhttps://github.com/ivanov/ipython-vimceptionUseful Vim plugins:https://github.com/sergei-grechanik/vim-terminal-images(Graphics in vim terminals)Useful tools:https://pandoc.org/Third-party issuesVim-plughttps://github.com/junegunn/vim-plug/issues/1010#issuecomment-1221614232Pandochttps://github.com/jgm/pandoc/issues/8598Jupytexthttps://github.com/mwouts/jupytext/issues/220#issuecomment-1418209581Vim-LSChttps://github.com/natebosch/vim-lsc/issues/469