From 93c6476c1df96abef3fc3582fb23fae0776be085 Mon Sep 17 00:00:00 2001 From: kdav5758 Date: Thu, 1 Jul 2021 23:05:01 -0500 Subject: [PATCH] improvements --- README.md | 48 +++++++--- doc/autosave.txt | 230 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 265 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index d49b244..c52ef41 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,11 @@ * [Updating](#updating) * [Usage (commands)](#-usage-commands) * [Default](#default) + * [Extra](#extra) * [Configuration](#-configuration) * [General](#general) + * [Conditions](#conditions) + * [Hooks](#hooks) * [Contribute](#-contribute) * [Inspirations](#-inspirations) * [License](#-license) @@ -71,25 +74,22 @@ * [To-Do](#-to-do) # 🎁 Features -- Highlight visual selection in any given *pre-defined* color. -- Remove highlighting from lines in visual selection. -- Users can set up foreground and background of any color. -- Has a "smart" option to set foreground based on background. -- Users can add any amount of colors. -- Produce a *verbose* output for debugging (optional). ++ Automatically save current file(s). ++ Set conditions that files must meet to be saved (e.g. filetype, existence, ...). ++ Set events that will trigger the plugin. ++ Add custom hooks (e.g. print a message when the plugin is turned off). ++ Toggle the plugin on and off. # 📺 Notices Checkout the [CHANGELOG.md](https://github.com/Pocco81/AutoSave.nvim/blob/main/CHANGELOG.md) file for more information on the notices below: -- **26-05-21**: Fixed bug that prevented adding new colors and added option to remove all highlighting from the current buffer -- **25-05-21**: Just released! +- **01-07-21**: Just released! # 📦 Installation ## Prerequisites - [NeoVim nightly](https://github.com/neovim/neovim/releases/tag/nightly) (>=v0.5.0) -- A nice color scheme to complement your experience ;) ## Adding the plugin You can use your favorite plugin manager for this. Here are some examples with the most popular ones: @@ -204,8 +204,8 @@ All the commands follow the *camel casing* naming convention and have the `AS` p + `:ASToggle`: toggles AutoSave.nvim on and off. ## Extra -+ `:ASOn`: toggles AutoSave.nvim on. -+ `:ASOff`: toggles AutoSave.nvim off. ++ `:ASOn`: turns AutoSave.nvim on. ++ `:ASOff`: turns AutoSave.nvim off. # 🐬 Configuration Although settings already have self-explanatory names, here is where you can find info about each one of them and their classifications! @@ -225,6 +225,28 @@ These are the conditions that every file must meet so that it can be saved. If e + `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. +## Hooks +Use them to execute code at certain events [described by their names]. These are the ones available: + +| 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) | + +They can be used like so: + +```lua +local autosave = require("autosave") + +autosave.hook_after_off = function () + print("I was toggled off!") +end +``` + # 🙋 FAQ - Q: ***"How can I view the doc from NeoVim?"*** @@ -253,10 +275,10 @@ For more convoluted language, see the [LICENSE file](https://github.com/Pocco81/ # 📋 TO-DO **High Priority** -- Store and Restore highlights on a per-file basis ++ None **Low Priority** -- Add tab completion to get more than 10 numbers. ++ None

diff --git a/doc/autosave.txt b/doc/autosave.txt index e69de29..dec34ee 100644 --- a/doc/autosave.txt +++ b/doc/autosave.txt @@ -0,0 +1,230 @@ +*AutoSave.nvim* *AutoSave-help* A NeoVim plugin for highlighting visual selections like in a normal document editor! + +Author: Pocco81 +License: GPL-3.0 License + +CONTENTS *truezen-contents* + +TL;DR |autosave-tldr| +Installation |autosave-installation| + Prerequisites |autosave-prerequisites| + Adding the plugin |autosave-adding-the-plugin| + Setup Configuration |autosave-setup-configuration| + For init.lua |autosave-for-initlua| + For init.vim |autosave-for-initvim| + Updating |autosave-updating| +Features |autosave-features| +Usage (commands) |autosave-usage-commands| + Default |autosave-default| + Extra |autosave-extra| +Configuration |autosave-configuration| + General |autosave-general| + Conditions |autosave-conditions| + Hooks |autosave-hooks| + +============================================================================== + +# TL;DR *autosave-tldr* + + + + + + + + + + + + + + + + + + + +# 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: + +### Vim-plug + +```lua +Plug 'Pocco81/AutoSave.nvim' +``` +### Packer.nvim + +```lua +use "Pocco81/AutoSave.nvim" +``` + +### Vundle + +```lua +Plugin 'Pocco81/AutoSave.nvim' +``` + +### NeoBundle +```lua +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 +} +``` + +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") + +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 + } +}) +``` + +For init.vim *AutoSave-for-initvim* + +```lua +lua << EOF +local high_str = require("high-str") + + +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 + } +}) +EOF +``` +
+ + +For instructions on how to configure the plugin, check out the [configuration](#configuration) section. + +## 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: + +## Default *AutoSave-default* +- `:HSHighlight ` highlights current visual selection and receives an `` that indicates which colors to use from the `highlight_colors = {}` table; if none is given, AutoSave.nvim will pick `color_1`. +- `:HSRmHighlight ` 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. + +# 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. +- `verbosity`: (Integer) if greater that zero, enables verbose output (print what it does when you execute any of the two command). + +## 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_`. 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: + +``` +color_1 = {"#FFF9E3", "smart"} +``` + +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). + +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. + +# 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 `` to highlight stuff and `` to remove the highlighting: + +**For init.lua** +```lua +vim.api.nvim_set_keymap( + "v", + "", + ":HSHighlight 1", + { + noremap = true, + silent = true + } +) + +vim.api.nvim_set_keymap( + "v", + "", + ":HSRmHighlight", + { + noremap = true, + silent = true + } +) +``` + +**For init.vim** +```vimscript +vnoremap :HSHighlight 1 +vnoremap :HSRmHighlight + +``` + +# License *AutoSave-license* + +AutoSave.nvim is released under the GPL v3.0 license. It grants open-source permissions for users including: + +- The right to download and run the software freely +- The right to make changes to the software as desired +- The right to redistribute copies of the software +- The right to modify and distribute copies of new versions of the software + +For more convoluted language, see the [LICENSE file](https://github.com/Pocco81/AutoSave.nvim/blob/main/README.md). +