Merge branch 'feature/dynamic-background' into master

README.md

@@ -69,3 +69,22 @@ This template's _design_ focuses on:
 This repository in itself is an example of how to use `nvim-highlite`. Aside from this, the following colorschemes are built using `nvim-highlite`:
 
 * (if you use this, open an issue and I'll add it here!)
+
+```lua
+--[[Keep in mind, the following example is meant to be used within the context of the `colors/highlite.vim` file.]]
+-- First, define some colors
+local red = {'#FF0000', 1, 'red'}
+local black = {'#000000', 0, 'black'}
+local white = {'#FFFFFF', 255, 'white'}
+
+-- Next define some highlight groups.
+local highlight_groups = {
+	-- Any field which can be set to "NONE" doesn't need to be set, it will be automatically assumed to be "NONE".
+	Identifier = {bg=red, fg=black, style='bold'},
+	-- If you want to have a colorscheme which is responsive to multiple background settings, you can do that too:
+	Function = {dark={bg=black}, light={bg=white}, fg=red}
+	--[[ Note that light/dark differentiation is completely optional. ]]
+}
+
+-- The rest is mostly handled by the template.
+```

colors/highlite.vim

@@ -59,8 +59,6 @@ lua << EOF
 
 -- This is the name of your colorscheme which will be used as per |g:colors_name|.
 vim.g.colors_name = 'highlite'
--- This is the kind of colorscheme you are creating. Either 'light' or 'dark'
-vim.o.background = 'dark'
 
 --[[ Step 3: Colors
 	Next you will define all of the colors that you will use for the color scheme.
@@ -124,10 +122,11 @@ local purple_light = {'#af60af', 63,  'magenta'}
 
 ```lua
 	<highlight group name> = {
-		bg=<color>, -- The color used for background color, or use `NONE`, `FG` or `BG`
+		bg=<color>, -- The color for the background, `NONE`, `FG` or `BG`
-		fg=<color>, -- The color used for foreground color, or use `NONE`, `FG` or `BG`
+		fg=<color>, -- The color for the foreground, `NONE`, `FG` or `BG`
 		blend=<integer> -- The |highlight-blend| value, if one is desired.
-		-- Style can be 'bold', 'italic', and more. See |attr-list| for more information. It can also have a color, and/or multiple <cterm>s.
+		-- Style can be 'bold', 'italic', and more. See |attr-list| for more information.
+		-- It can also have a color, and/or multiple <cterm>s.
 		style=<cterm>|{<cterm> [, <cterm>] [color=<color>]})
 	}
 ```
@@ -137,8 +136,10 @@ local purple_light = {'#af60af', 63,  'magenta'}
 ```lua
 	<highlight group name> = '<highlight group name>'
 ```
+	____________________________________________________________________________
 
-	Here is an example to define `SpellBad` and then link some new group `SpellWorse` to it:
+	Here is an example to define `SpellBad` and then link some new group
+	`SpellWorse` to it:
 
 ```lua
 	SpellBad = { -- ← name of the highlight group
@@ -157,7 +158,7 @@ local purple_light = {'#af60af', 63,  'magenta'}
 
 ```lua
 	SpellBad = { -- ← name of the highlight group
-		bg='NONE', -- background color
+		bg=NONE, -- background color
 		fg=red, -- foureground color
 		style={ -- the style
 			'undercurl', -- undercurl (squiggly line)
@@ -166,20 +167,39 @@ local purple_light = {'#af60af', 63,  'magenta'}
 		}
 	}
 ```
+	____________________________________________________________________________
 
-	You can add any custom highlight group to the standard list below but you shouldn't
+	If you want to create a colorscheme that is responsive to the user's
-	remove any if you want a working colorscheme. Most of them are described under
+	'background' setting, you can specify special `light` and `dark` keys to
-	|highlight-default|, some from |group-name|, and others from common syntax groups.
+	define how each group should be highlighted in each case.
-	Both help sections are good reads.
+
+```lua
+	SpellBad = {
+		bg=NONE,
+		dark={fg=white},
+		light={fg=black},
+		style={'undercurl', color=red}
+	}
+```
+
+	Whenever the user changes their 'background' setting, the settings inside of
+	whichever key is relevant will be loaded.
+	____________________________________________________________________________
+
+	You can add any custom highlight group to the standard list below but you
+	shouldn't remove any if you want a working colorscheme. Most of them are
+	described under |highlight-default|, some from |group-name|, and others from
+	common syntax groups.  Both help sections are good reads.
 
 	NOTE: |Replace-mode| will probably be useful here.
 
-	NOTE: /As long as you do not remove any highlight groups or colors/, you can safely
+	NOTE: /As long as you do not remove any highlight groups or colors/, you can
-	      ignore any highlight groups that are `link`ed to others.
+	      safely ignore any highlight groups that are `link`ed to others.
+
 	      For example, programming languages almost exclusively link to the 1st
-	      and 2nd sections, so as long as you define everything there you will automatically
+	      and 2nd sections, so as long as you define everything there you will
-	      be defining the rest of the highlights, which is one of the benefits of using
+	      automatically be defining the rest of the highlights, which is one of
-	      this template.
+	      the benefits of using this template.
 ]]
 
 --[[ DO NOT EDIT `BG`, `FG`, or `NONE`.

lua/highlite.lua

@@ -26,7 +26,7 @@ local PALETTE_HEX  = 1
 local NONE = "NONE"
 
 -- Get the color value of a color variable, or "NONE" as a default.
-local function get(color, index)
+local function get(color, index) -- {{{ †
 	if type(color) == 'table' and color[index] then
 		return color[index]
 	elseif type(color) == 'string' then
@@ -34,30 +34,54 @@ local function get(color, index)
 	else
 		return NONE
 	end
+end --}}} ‡
+
+-- Add the 'blend' parameter to some highlight command, if there is one.
+local function blend(command, attributes) -- {{{ †
+	if attributes.blend then -- There is a value for the `highlight-blend` field.
+		command[#command + 1] = ' blend='..attributes.blend
 	end
+end --}}} ‡
 
 --[[ If using hex and 256-bit colors, then populate the gui* and cterm* args.
 	If using 16-bit colors, just populate the cterm* args. ]]
-local colorize = using_hex_or_256 and function(command, attributes) command[#command + 1] =
+local colorize = using_hex_or_256 and function(command, attributes) -- {{{ †
+	command[#command + 1] =
 		' ctermbg='..get(attributes.bg, PALETTE_256)
 		..' ctermfg='..get(attributes.fg, PALETTE_256)
 		..' guibg='..get(attributes.bg, PALETTE_HEX)
 		..' guifg='..get(attributes.fg, PALETTE_HEX)
-end or function(command, attributes) command[#command + 1] =
+	blend(command, attributes)
+end or function(command, attributes)
+	command[#command + 1] =
 		' ctermbg='..get(attributes.bg, PALETTE_ANSI)
 		..' ctermfg='..get(attributes.fg, PALETTE_ANSI)
-end
+	blend(command, attributes)
+end --}}} ‡
 
 -- This function appends `selected_attributes` to the end of `highlight_cmd`.
-local stylize = using_hex_or_256 and function(command, attributes)
+local stylize = using_hex_or_256 and function(command, style, color) -- {{{ †
-	command[#command + 1] = ' cterm='..attributes..' gui='..attributes
+	command[#command + 1] = ' cterm='..style..' gui='..style
-end or function(command, attributes)
+
-	command[#command + 1] = ' cterm='..attributes
+	if color then -- There is an undercurl color.
+		command[#command + 1] = ' guisp='..get(color, PALETTE_HEX)
 	end
+end or function(command, style)
+	command[#command + 1] = ' cterm='..style
+end --}}} ‡
 
 -- Generate a `:highlight` command from a group and some attributes.
 local function highlight(highlight_group, attributes) -- {{{ †
+	-- The base highlight command
 	local highlight_cmd = {'hi! ', highlight_group}
+
+	-- Take care of special instructions for certain background colors.
+	if attributes[vim.o.background] then
+		attributes.__index = attributes
+		attributes = setmetatable(attributes[vim.o.background], attributes)
+	end
+
+	-- Determine if there is a highlight link, and if so, assign it.
 	local link = (type(attributes) == 'string' and attributes)
 		or attributes.link
 
@@ -68,19 +92,11 @@ local function highlight(highlight_group, attributes) -- {{{ †
 	else -- The `highlight_group` is uniquely defined.
 		colorize(highlight_cmd, attributes)
 
-		if attributes.blend then -- There is a value for the `highlight-blend` field.
-			highlight_cmd[#highlight_cmd + 1] = ' blend='..attributes.blend
-		end
-
 		local style = attributes.style or NONE
 		if type(style) == 'table' then
 			-- Concat all of the entries together with a comma between before styling.
-			stylize(highlight_cmd, table.concat(style, ','))
+			stylize(highlight_cmd, table.concat(style, ','), style.color)
-
+		else -- The style is just a single entry.
-			if style.color then -- there won't is a color for undercurl.
-				highlight_cmd[#highlight_cmd + 1] = ' guisp='..get(style.color, PALETTE_HEX)
-			end
-		else -- just style the single entry.
 			stylize(highlight_cmd, style)
 		end
 	end