👀 Slime-peek

A Neovim plugin that adds several convenience functions for data exploration, allowing you to peek at your Python, R and Julia objects together with vim-slime.

slime-peek-demo.mp4

✨ Features

• Peek at the head / tail of the word under the cursor
• Peek at the column names of the word under the cursor
• Peek at the dimensions of the word under the cursor
• Peek at the data types / classes of the columns of the word under the cursor
• Operator/motion-based variants of the above that work on arbitrary expressions (e.g. df$col, slices, etc.)
• Automatic language and file type detection for Python, R and Julia across scripts, R Markdown, and Quarto

📚 Requirements

• Neovim >= 0.11.0
• The vim-slime Vim plugin

📦 Installation

You can install the plugin with your preferred package manager:

-- vim.pack
vim.pack.add({
    "https://github.com/jpalardy/vim-slime",
    "https://github.com/fasterius/slime-peek.nvim",
})

-- lazy.nvim
{
    "fasterius/slime-peek.nvim",
    dependencies = "jpalardy/vim-slime",
}

🚀 Usage

The slime-peek plugin supplies several operations, each with two variants: one that uses the word under the cursor, and one that uses Vim's operator-pending mode (a motion or text object) to select the text. Each word-based operation is named e.g. peek_head, while its motion equivalent is named peek_head_motion. The motion variants will enter operator-pending mode and wait for the user to supply a motion or a text object before sending the final text to the REPL.

For Python, operations like peek_head translate to attribute or method accesses such as <text>.head(). The equivalent is head(<text>) for R and first(<text>, 5) for Julia; see the documentation for details. The plugin detects Python, R and Julia scripts as well as R Markdown and Quarto documents, then sends the appropriate code using vim-slime.

slime-peek does not set any key mappings by default, but instead provides several Lua functions and user-commands that you can set key binds for:

• peek_head[_motion]: Print the head of some text.
• peek_tail[_motion]: Print the tail of some text.
• peek_names[_motion]: Print the column names of some text.
• peek_dims[_motion]: Print the dimensions of some text.
• peek_types[_motion]: Print the data types of the columns of some text.
• peek_help[_motion]: Print the help pages of some text.

If you want to create a key map for the commands, you can do something like this:

vim.keymap.set('n', '<localleader>h', require("slime_peek").peek_head)
vim.keymap.set('n', '<localleader>mh', require("slime_peek").peek_head_motion)

Or the equivalent using the user-commands:

vim.keymap.set('n', '<localleader>h', '<CMD>PeekHead<CR>')
vim.keymap.set('n', '<localleader>mh', '<CMD>PeekHeadMotion<CR>')

Note

Please note that slime-peek doesn't actually have any knowledge regarding the objects that are sent to your REPL, so if you try to get e.g. the dimensions of a dimensionless object you'll receive an error.

The plugin will automatically detect which of the supported languages are currently in use in your document, whether that be Python, R or Julia scripts, R Markdown or Quarto documents. For scripts and R Markdown documents, the language is inferred by the file type, as those documents are only used with their respective programming language. For Quarto documents, slime-peek will check the current code chunk's language by default, with an option to instead use the language specified in the YAML header of the document (using either the shorter jupyter: <kernel>, a fully nested jupyter: plus kernelspec:, knitr: or engine:).

⚙️ Configuration

slime-peek comes with the following options and their respective defaults:

{
    -- Uses the Quarto YAML header for language detection instead of using the
    -- current code chunk's language. This is useful if you want to specify
    -- Quarto languages in a document-wide manner, rather than per code chunk.
    use_yaml_language = false
}

A complete installation and configuration might look something like this:

-- vim.pack
vim.pack.add({
    "https://github.com/jpalardy/vim-slime",
    "https://github.com/fasterius/slime-peek.nvim",
})
-- Configuration
vim.g.slime_peek = {
    use_yaml_language = false,
}
-- Word under cursor mappings
vim.keymap.set("n", "<localleader>h", require("slime_peek").peek_head)
vim.keymap.set("n", "<localleader>T", require("slime_peek").peek_tail)
vim.keymap.set("n", "<localleader>n", require("slime_peek").peek_names)
vim.keymap.set("n", "<localleader>d", require("slime_peek").peek_dims)
vim.keymap.set("n", "<localleader>t", require("slime_peek").peek_types)
vim.keymap.set("n", "<localleader>H", require("slime_peek").peek_help)
-- Motion mappings
vim.keymap.set("n", "<localleader>mh", require("slime_peek").peek_head_motion)
vim.keymap.set("n", "<localleader>mT", require("slime_peek").peek_tail_motion)
vim.keymap.set("n", "<localleader>mn", require("slime_peek").peek_names_motion)
vim.keymap.set("n", "<localleader>md", require("slime_peek").peek_dims_motion)
vim.keymap.set("n", "<localleader>mt", require("slime_peek").peek_types_motion)
vim.keymap.set("n", "<localleader>mH", require("slime_peek").peek_help_motion)

-- lazy.nvim
{
    "fasterius/slime-peek.nvim",
    dependencies = "jpalardy/vim-slime",
    config = function()
        local peek = require("slime_peek")
        peek.setup({
            use_yaml_language = false,
        })
        -- Word under cursor mappings
        vim.keymap.set("n", "<localleader>h", peek.peek_head)
        vim.keymap.set("n", "<localleader>T", peek.peek_tail)
        vim.keymap.set("n", "<localleader>n", peek.peek_names)
        vim.keymap.set("n", "<localleader>d", peek.peek_dims)
        vim.keymap.set("n", "<localleader>t", peek.peek_types)
        vim.keymap.set("n", "<localleader>H", peek.peek_help)
        -- Motion mappings
        vim.keymap.set("n", "<localleader>mh", peek.peek_head_motion)
        vim.keymap.set("n", "<localleader>mT", peek.peek_tail_motion)
        vim.keymap.set("n", "<localleader>mn", peek.peek_names_motion)
        vim.keymap.set("n", "<localleader>md", peek.peek_dims_motion)
        vim.keymap.set("n", "<localleader>mt", peek.peek_types_motion)
        vim.keymap.set("n", "<localleader>mH", peek.peek_help_motion)
    end,
}

Note

Please note that slime-peek assumes that vim-slime has been correctly installed and configured.

📕 About

This plugin was originally just a few functions living in my Neovim config, but I decided to formalise them into a plugin and share it with others. I hope you find it useful!