Frame it!

A simple Vim/Neovim plugin to highlight comments by "framing" them with different styles.

NOTE: The Vim version is lagging a little bit behind!

I use it mainly to separate logic sections in a single file of code and for headings.

ToC

• Installation
• Basic usage
• Examples
• API

Installation

Using Lazy

Example in .config/nvim/lua/plugins/frameit.lua

return {
	-- ╭────────────────────────────╮
	-- │ This is how you use it! 💖 │
	-- ╰────────────────────────────╯
	"mec-nyan/frame-it",
}

Using Vim/Neovim native packages

Neovim

git clone https://github.com/mec-nyan/frame-it.git .config/nvim/pack/frameit/start/frameit

Vim

git clone https://github.com/mec-nyan/frame-it.git .vim/pack/frameit/start/frameit

That way you can keep it updated!

Or if you want, you can just put it in .vim/plugin/frame-it.vim or even just source the file.

Both

Open the corresponding file (the Lua version won't work with Vim) and just:

:source %

Basic usage:

This plugin doesn't provide any keymaps, so it won't interfere with yours.

It's recommended that you provide your key bindings in your configuration. The examples below show how to simply call these functions.

Write a comment:

// Something important begins here.

With the cursor on that line, call one of the framing functions.

:FrameMeRounded<CR>

Result:

// ╭──────────────────────────────────╮
// │ Something important begins here. │
// ╰──────────────────────────────────╯

Examples

TODO:

Replace these examples with images, since the font in Github are not the best.

Before:

-- This function does something.
function do_something()
    ...
end

After:

-- ╭───────────────────────────────╮
-- │ This function does something. │
-- ╰───────────────────────────────╯
function do_something()
    ...
end

It works in visual mode too!

Before:

-- do_something is a function
-- that does something.
-- that's it!
function do_something()
    ...
end

Select the lines you want to "frame"

After:

-- ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-- ┃ do_something is a function ┃
-- ┃ that does something.       ┃
-- ┃ that's it!                 ┃
-- ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
function do_something()
    ...
end

Before:

// The following stuff is related.

// FrameIt does a thing...
func (f *Frame) FrameIt() string {
    // ...
}

After:

// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
// ┃ The following stuff is related. ┃
// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

// FrameIt does a thing...
func (f *Frame) FrameIt() string {
    // ...
}

Before:

# Warning! There will be dragons 🐉!

def some_func(n: int) -> bool:
    '''some_func takes an int and returns a bool (duh!)'''

    pass

After:

# ╔════════════════════════════════════╗
# ║ Warning! There will be dragons 🐉! ║
# ╚════════════════════════════════════╝

def some_func(n: int) -> bool:
    '''some_func takes an int and returns a bool (duh!)'''

    pass

API

The following commands are provided. They work in both NORMAL and VISUAL modes.

Draw a frame with:

• FrameMeSharp (sharp corners)
• FrameMeRounded (rounded corners)
• FrameMeDotted (dotted outline)
• FrameMeDottedRounded (dotted outline and rounded corners)
• FrameMeDottedFat (dotted, thick outline)
• FrameMeFat (thick outline)
• FrameMeDouble (double outline)

Lua API

You can access the lua functions directly if you want (i.e. to create a custom command or mapping).

local frame_it = require "frame-it"

frame_it.__FrameMe("fat", "cpp")

The module exports the following functions:

• FrameMeSharp (sharp corners)
• FrameMeRounded (rounded corners)
• FrameMeDotted (dotted outline)
• FrameMeDottedRounded (dotted outline and rounded corners)
• FrameMeDottedFat (dotted, thick outline)
• FrameMeFat (thick outline)
• FrameMeDouble (double outline)
• __FrameMe (generic)
• __FrameMeVisual (generic)

They all accept an optional argument: "opts: (table)". Thay way we can call them in both NORMAL and VISUAL modes.

The functions that start with "__" are mainly provided for testing purposes (hence their name).

The function FrameMe(style: string, lang: string[, opts: table]) is the base of the others and serves also for testing.

Its first argument is a (constant) string that selects the style:

• sharp
• rounded
• dotted
• dotted_rounded
• dotted_fat
• fat
• double

The second argument (also a string) is the file type:

• c, c++, go, rust
• lua
• python, bash, sh
• etc

The third argument is an optional table. Neovim will fill this parameter when invoking the function via command.

TODO / Fixes

• [Fixed] In visual mode, support for wide chars is broken (because of string.format(...))
• Keep the Vim version updated.
• [Fixed] Range error in visual mode.
• [Fixed] Use the same names/commands in normal and visual modes.