# vis-pin-files

A [vis-plugin](https://github.com/martanne/vis/wiki/Plugins/) to pin a file to a number
 with a key (default: `␣p1` ... `␣p9`). The number may be later used to bring back the file with another key (default: `␣1` ... `␣9`).

Keys are configurable. The pins does not persist after editor restart (but both keys and files table are available in module namespace for customization).

The plugin is basic implementation of the idea of [neovim](https://neovim.io/) plugin [harpoon](https://github.com/ThePrimeagen/harpoon/tree/harpoon2)
(there are also many other similar neovim plugins, such as [arrow](https://github.com/otavioschwanck/arrow.nvim)).

The package could be used with its default settings by cloning the project directory
into the `plugins` subdirectory in the directory of your `visrc.lua` file and importing it
with

```lua
require('plugins/vis-pin-files')
```

See the *Default keys and configuration* section for default key bindings and possible customization.

## Commands

The plugin adds single command `:pin-files [command] [num]`

Where `[command]` is either:

-  `pin`, then the current file is pinned to the given number `[num]` (i.e., its path, if any, is stored for later use), or
- any other command (such as `e`, `o`, `split`, `vsplit`), in this case the command is called with the filename
  pinned to the given `[num]` (or message is displayed that the pin is empty).

Actually `[num]` is converted to a number if possible, otherwise it is used as a string.

The `[num]` is optional, if not given the number should be given as the count argument of the command, if both are missing, only the info message is displayed
and nothing happens.

## Default keys and configuration

The default set of keys consists of two groups:
- `␣p1` ... `␣p9` -- pin current file to given number,
- `␣1` ... `␣9` -- switch to given file with `e` command,

The default keys defined in the plugin are equivallent to the following
settings in your `visrc.lua`:
```lua
local pin = require('plugins/vis-pin-files')

pin.keys = {
	[' p%d'] = '<vis-prompt-show>pin-files pin %d<Enter>',
	[' %d'] = '<vis-prompt-show>pin-files e %d<Enter>',
}
```

where keys with `%d` in them are filled with numbers from 1 to 9 in the key and in the command.
If `%d` is not found in the key then the single key (without number interpolation) is bind
to the given command.

To remove the given key just set it to `nil`, for example:
```lua
pin.keys[' p%d'] = nil
```
to remove all default keys (so you can set them yourself):
```lua
pin.keys = nil
```