zoriya/auto-save.nvim
1
0
Fork 0
mirror of https://github.com/zoriya/auto-save.nvim.git synced 2025-12-06 06:36:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

finished doc

Browse Source
This commit is contained in:
kdav5758
2021-07-02 00:02:27 -05:00
parent 89f29f9774
commit 5b0d132727
1 changed files with 81 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
doc/autosave.txt
View File

@@ -25,32 +25,13 @@ Configuration |autosave-configuration|
==============================================================================
# TL;DR *autosave-tldr*
AutoSave.nvim is a NeoVim plugin written in Lua that aims to provide the simple functionality of automatically saving your work whenever you make changes to it. You can filter under which conditions which files are saved and when the auto-save functionality should triggered (events). To get started simply install the plugin with your favorite plugin manager!
# Installation *autosave-installation*
## Prerequisites *autosave-prerequisites*
- [NeoVim nightly](https://github.com/neovim/neovim/releases/tag/nightly) (>=v0.5.0)
- [Lua ver. >= 5.3](https://www.lua.org/manual/5.3/readme.html#changes)
- A nice color scheme to complement your experience ;)
## Adding the plugin *AutoSave-adding-the-plugin*
You can use your favorite plugin manager for this. Here are some examples with the most popular ones:
@@ -80,70 +61,64 @@ NeoBundleFetch 'Pocco81/AutoSave.nvim'
## Setup (configuration) *AutoSave-setup-configuration*
As it's stated in the TL;DR, there are already some sane defaults that you may like, however you can change them to match your taste. These are the defaults:
```lua
verbosity = 0,
highlight_colors = {
color_0 = {"#0c0d0e", "smart"}, -- Cosmic charcoal
color_1 = {"#e5c07b", "smart"}, -- Pastel yellow
color_2 = {"#7FFFD4", "smart"}, -- Aqua menthe
color_3 = {"#8A2BE2", "smart"}, -- Proton purple
color_4 = {"#FF4500", "smart"}, -- Orange red
color_5 = {"#008000", "smart"}, -- Office green
color_6 = {"#0000FF", "smart"}, -- Just blue
color_7 = {"#FFC0CB", "smart"}, -- Blush pink
color_8 = {"#FFF9E3", "smart"}, -- Cosmic latte
color_9 = {"#7d5c34", "smart"}, -- Fallow brown
}
enabled = true,
execution_message = "AutoSave: saved at " .. vim.fn.strftime("%H:%M:%S"),
events = {"InsertLeave", "TextChanged"},
conditions = {
exists = true,
filetype_is_not = {},
modifiable = true,
},
write_all_buffers = false,
on_off_commands = false,
clean_command_line_interval = 0
```
The way you setup the settings on your config varies on whether you are using vimL for this or Lua.
For init.lua *AutoSave-for-initlua*
```lua
local high_str = require("high-str")
local autosave = require("autosave")
high_str.setup({
verbosity = 0,
highlight_colors = {
-- color_id = {"bg_hex_code",<"fg_hex_code"/"smart">}
color_0 = {"#0c0d0e", "smart"}, -- Cosmic charcoal
color_1 = {"#e5c07b", "smart"}, -- Pastel yellow
color_2 = {"#7FFFD4", "smart"}, -- Aqua menthe
color_3 = {"#8A2BE2", "smart"}, -- Proton purple
color_4 = {"#FF4500", "smart"}, -- Orange red
color_5 = {"#008000", "smart"}, -- Office green
color_6 = {"#0000FF", "smart"}, -- Just blue
color_7 = {"#FFC0CB", "smart"}, -- Blush pink
color_8 = {"#FFF9E3", "smart"}, -- Cosmic latte
color_9 = {"#7d5c34", "smart"}, -- Fallow brown
}
})
autosave.setup(
{
enabled = true,
execution_message = "AutoSave: saved at " .. vim.fn.strftime("%H:%M:%S"),
events = {"InsertLeave", "TextChanged"},
conditions = {
exists = true,
filetype_is_not = {},
modifiable = true
},
write_all_buffers = true,
on_off_commands = true,
clean_command_line_interval = 2500
}
)
```
For init.vim *AutoSave-for-initvim*
```lua
lua << EOF
local high_str = require("high-str")
local autosave = require("autosave")
high_str.setup({
verbosity = 0,
highlight_colors = {
-- color_id = {"bg_hex_code",<"fg_hex_code"/"smart">}
color_0 = {"#0c0d0e", "smart"}, -- Cosmic charcoal
color_1 = {"#e5c07b", "smart"}, -- Pastel yellow
color_2 = {"#7FFFD4", "smart"}, -- Aqua menthe
color_3 = {"#8A2BE2", "smart"}, -- Proton purple
color_4 = {"#FF4500", "smart"}, -- Orange red
color_5 = {"#008000", "smart"}, -- Office green
color_6 = {"#0000FF", "smart"}, -- Just blue
color_7 = {"#FFC0CB", "smart"}, -- Blush pink
color_8 = {"#FFF9E3", "smart"}, -- Cosmic latte
color_9 = {"#7d5c34", "smart"}, -- Fallow brown
}
})
autosave.setup(
{
enabled = true,
execution_message = "AutoSave: saved at " .. vim.fn.strftime("%H:%M:%S"),
events = {"InsertLeave", "TextChanged"},
conditions = {
exists = true,
filetype_is_not = {},
modifiable = true
},
write_all_buffers = true,
on_off_commands = true,
clean_command_line_interval = 2500
}
)
EOF
```
<br />
@@ -151,70 +126,60 @@ EOF
For instructions on how to configure the plugin, check out the [configuration](#configuration) section.
## Updating *AutoSave-updating*
## Updating *autosave-updating*
This depends on your plugin manager. If, for example, you are using Packer.nvim, you can update it with this command:
```lua
:PackerUpdate
```
# Usage (commands) *AutoSave-usage-commands*
All the commands follow the *camel casing* naming convention and have the `HS` prefix so that it's easy to remember that they are part of the AutoSave.nvim plugin. These are all of them:
# Usage (commands) *autosave-usage-commands*
All the commands follow the *camel casing* naming convention and have the `AS` prefix so that it's easy to remember that they are part of this plugin. These are all of them:
## Default *AutoSave-default*
- `:HSHighlight <integer>` highlights current visual selection and receives an `<integer>` that indicates which colors to use from the `highlight_colors = {}` table; if none is given, AutoSave.nvim will pick `color_1`.
- `:HSRmHighlight <rm_all>` If the `rm_all` argument is given, removes all the highlighting in the current buffer. If not, does the same but for every line in visual selection.
## Default
+ `:ASToggle`: toggles AutoSave.nvim on and off.
# Configuration *AutoSave-configuration*
## Extra
+ `:ASOn`: turns AutoSave.nvim on.
+ `:ASOff`: turns AutoSave.nvim off.
# Configuration *autosave-configuration*
Although settings already have self-explanatory names, here is where you can find info about each one of them and their classifications!
## General *AutoSave-general*
This settings are unrelated to any group and are independent.
## General
- `verbosity`: (Integer) if greater that zero, enables verbose output (print what it does when you execute any of the two command).
+ `enabled:`: (Boolean) if true, enables AutoSave.nvim at startup (Note: this is not for loading the plugin it self but rather the "auto-save" functionality. This is like running `:ASOn`).
+ `execution_message`: (String) message to be displayed when saving [a] file[s].
+ `events`: (Table): events that will trigger the plugin.
+ `write_all_buffers`: (Boolean) if true, writes to all modifiable buffers that meet the `conditions`.
+ `on_off_commands`: (Boolean) if true, enables extra commands for toggling the plugin on and off (`:ASOn` and `:ASOff`).
+ `clean_command_line_interval` (Integer) if greater than 0, cleans the command line after *x* amount of milliseconds after printing the `execution_message`.
## Highlight Colors *AutoSave-highlight-colors*
The table `highlight_colors = {}` contains all of the colors AutoSave.nvim will use when you highlight something. The convention is simple: `color_<a_number>`. Each color is a table in which the first element represents the background of the color (the highlight it self), and the second one represents the foreground (the color of the text that's being highlighted). The second parameter may also be the word "smart", to change the color of the foreground based on the background in order to get a better contrast (e.g. if background is white, set foreground to black). Here is an example:
## Conditions
These are the conditions that every file must meet so that it can be saved. If every file to be auto-saved doesn't meet all of the conditions it won't be saved.
+ `exists`: (Boolean) if true, enables this condition. If the file doesn't exist it won't save it (e.g. if you `nvim stuff.txt` and don't save the file then this condition won't be met)
+ `modifiable`: (Boolean) if true, enables this condition. If the file isn't modifiable, then this condition isn't met.
+ `filetype_is_not`: (Table, Strings) if there is one or more filetypes (should be strings) in the table, it enables this condition. Use this to exclude filetypes that you don't want to automatically save.
```
color_1 = {"#FFF9E3", "smart"}
```
## Hooks
Use them to execute code at certain events [described by their names]. These are the ones available:
Here we are setting a cool color called Cosmic Latte (looks like white), that we are assigning to `color_1` and we are giving its parameters to a table: the first one is the highlight itself ("#FFF9E3") and in the second one ("smart") we are telling it to set a foreground that will make contrast with the background (black in this case).
| Function | Description |
|----------------------|--------------------------------------------------------------------|
| hook_before_on() | Before toggling the plugin on |
| hook_after_on() | After toggling the plugin on |
| hook_before_off() | Before toggling the plugin off |
| hook_after_off() | After toggling the plugin off |
| hook_before_saving() | Before its even checked if the current file(s) meet the conditions |
| hook_after_saving | After saving the file(s) |
Conditions:
- The numbers that are assigned to the colors (e.g. `color_2`) should not be repeated, because it's what you'll use to "call" that highlight color.
- The color it self (argument one in a color's table) should be in its hex value.
They can be used like so:
# Key-bindings *AutoSave-keybindings*
There are no default key-bindings. However, you can set them on your own as you'd normally do! Here is an example mapping `<F3>` to highlight stuff and `<F4>` to remove the highlighting:
**For init.lua**
```lua
vim.api.nvim_set_keymap(
"v",
"<F3>",
":<c-u>HSHighlight 1<CR>",
{
noremap = true,
silent = true
}
)
vim.api.nvim_set_keymap(
"v",
"<F4>",
":<c-u>HSRmHighlight<CR>",
{
noremap = true,
silent = true
}
)
```
**For init.vim**
```vimscript
vnoremap <silent> <f3> :<c-u>HSHighlight 1<CR>
vnoremap <silent> <f4> :<c-u>HSRmHighlight<CR>
local autosave = require("autosave")
autosave.hook_after_off = function ()
print("I was toggled off!")
end
```
# License *AutoSave-license*