initial commit

README.md

@@ -0,0 +1,64 @@
+# 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
+```