_________       ______       ______       ______
   |  _____  \     /  __  \     |  __  \     |  __  \
   | |     | |    /  /  \  \    | |  \  \    | |  \  \
   | |_____| |   |  |    |  |   | |__/  /    | |__/  /
   |  __  __/    |  |____|  |   |  __  /     |  __  /
   | |  \ \      |   ____   |   | |  \ \     | |  \ \
   | |   \ \     |  |    |  |   | |   \ \    | |   \ \
   |_|    \_\    |__|    |__|   |_|    \_\   |_|    \_\ 


                _
              (`  ).                   _
             (     ).              .:(`  )`.
)           _(       '`.          :(   .    )
        .=(`(      .   )     .--  `.  (    ) )
       ((    (..__.:'-'   .+(   )   ` _`  ) )
`.     `(       ) )       (   .  )     (   )  ._
  )      ` __.:'   )     (   (   ))     `-'.-(`  )
)  )  ( )       --'       `- __.'         :(      ))
.-'  (_.'          .')                    `(    )  ))    ___
                  (_  )                     ` __.:'  .')   _|.-.___\__
                                                    (_  ) -|  _      _`-.
                                                           '-(_)----(_)--` 
--..,___.--,--'`,---..-.--+--.,,-,,..._.--..-._..._.--..-._.,,-,,-,--'`,---..

rarr

rarr: racing along with R is a cross-platform Rust console for embedded R. It keeps the normal R prompt model, but adds a modern terminal editor, persistent history, completion, script execution, and a Debug Adapter Protocol (DAP) server for editor debugging.

The project is Neovim-first. It is designed to be used with rarr.nvim, R.nvim, and debugger clients such as nvim-dap-r. Rarr is still work in progress, so treat the command-line and debugger interfaces as active development surfaces.

Feature Summary

• Embedded R REPL with multiline input, startup profile handling, and terminal width synchronization.
• Vi or Emacs editing through reedline, with smart bracket and quote matching, R-aware history hints, and configurable prompt/status styling.
• R completion backed by the embedded runtime, fuzzy path completion inside strings, and completion for rarr meta commands.
• Separate R and shell histories, an interactive history browser, :system, persistent :shell mode, :setwd, :restart, and :info.
• Script mode via -e, positional files, -f/--file, and stdin with -.
• Built-in DAP server for live R sessions: breakpoints, stepping, stack frames, scopes, locals, variable expansion, frame-local evaluation, logpoints, and error or warning breakpoints.

Script Execution

Use -e for a single expression, pass a script path positionally, or use -f/--file for R-compatible script invocation:

rarr -e '1 + 1'
rarr path/to/script.R
rarr -f path/to/script.R

Pass - as the script path to read R code from stdin:

printf '1 + 1\n' | rarr -f -
printf '1 + 1\n' | rarr -

Debug Adapter Protocol

Rarr can start a Debug Adapter Protocol server inside the live embedded R process:

rarr --dap --dap-host 127.0.0.1 --dap-port 0

Use --dap-port 0 to let the OS choose a free port. Rarr writes session metadata so Neovim plugins can discover the active server:

rarr --dap --dap-metadata /tmp/rarr-dap-session.json

When --dap-metadata is not provided, rarr uses:

• $RNVIM_TMPDIR/rarr-dap-session.json when RNVIM_TMPDIR is set
• $XDG_RUNTIME_DIR/rarr/dap-session.json when XDG_RUNTIME_DIR is set
• the system temp directory otherwise

The DAP server owns R runtime state: browser prompts, stepping, breakpoints, stack frames, scopes, variables, and frame-local evaluation. Neovim plugins should connect to it through DAP instead of sending debugger text directly to the terminal.

R promises are shown conservatively. A function argument that has not been inspected by the debugger is reported as a promise placeholder, because forcing promises can change program behavior. Expand the promise row in the DAP variables UI to explicitly evaluate it and inspect list fields.

Neovim Workflow

The intended editor split is:

• rarr runs the R console and DAP server
• rarr.nvim starts the console and exposes DAP session metadata
• nvim-dap-r registers the R adapter and default configurations
• generic nvim-dap UI plugins show scopes, stack frames, watches, and virtual text

This keeps the console integration separate from debugger UI state while still debugging the same live R session.