lush.txt

*lush* color scheme creation tool with real time feedback

          ,gggg,
         d8" "8I                         ,dPYb,
         88  ,dP                         IP'`Yb
      8888888P"                          I8  8I
         88                              I8  8'
         88        gg      gg    ,g,     I8 dPgg,
    ,aa,_88        I8      8I   ,8'8,    I8dP" "8I
   dP" "88P        I8,    ,8I  ,8'  Yb   I8P    I8
   Yb,_,d88b,,_   ,d8b,  ,d8b,,8'_   8) ,d8     I8,
    "Y8P"  "Y888888P'"Y88P"`Y8P' "YY8P8P88P     `Y8

Lush is a color scheme creation aid, written in Lua, for Neovim.

Lush lets you define your scheme as a mini-dsl, provides HSL colour
manipulation aids, and gives you real time feedback of your changes.

Lush colorschemes can be exported easily exported for distribution
without Lush, in both lua and vimscript formats, or they can also be
imported into other Lua systems to access color data.

================================================================================
CONTENTS                                                              *lush-toc*

Lush Tutorials                                                  |lush-tutorials|
HSL & HSLuv Colors                         |lush-hsl-colors| |lush-hsluv-colors|
  Define a Color                                             |lush-define-color|
  Color Operations                                       |lush-color-operations|
  rotate, ro                                                 |lush-color-rotate|
  saturate, desaturate, sa, de     |lush-color-saturate| |lush-color-desaturate|
  lighten, darken, li, da               |lush-color-lighten| |lush-color-darken|
  mix                                                           |lush-color-mix|
  readable                                                 |lush-color-readable|
  abs_*                                         |lush-color-absolute-operations|
  hue, saturation, lightness, .h, .s, .l                     |lush-color-direct|
  .hex, tostring                                    |lush-color-string-coercion|
  .rgb                                                          |lush-color-rgb|
  Example                                                   |lush-color-example|
Lush Spec                                                            |lush-spec|
  Sample lush-spec                                            |lush-spec-sample|
  Lush-Spec Spec                                                |lush-spec-spec|
    Direct Definition                              |lush-spec-direct-definition|
    Linked Group                                        |lush-spec-linked-group|
    Inherited Group                                  |lush-spec-inherited-group|
Extending lush-specs                                      |lush-extending-specs|
  extends({parsed_lush_spec, ...}).with(spec)                |lush-extends-with|
  merge({parsed_lush_spec, ...})                                    |lush-merge|
Lush.Ify                                                               |lushify|
Converting an Existing Theme to Lush      |lush-converting-existing-colorscheme|
Exporting from Lush                                                |lush-export|
Manual Toolchain                                         |lush-manual-toolchain|
Pitfalls, Beartraps, Dragons                                     |lush-pitfalls|
Bugs or Limitations                                                  |lush-bugs|

--------------------------------------------------------------------------------
Lush Tutorials                                                  *lush-tutorials*

An interactive tutorial is provided via the :LushRunTutorial command.

--------------------------------------------------------------------------------
HSL & HSLuv Colors                          *lush-hsl-colors* *lush-hsluv-colors*

Lush supports two color spaces:

  - HSL which is defined by hue, saturation and lightness components and
  - HSLuv, which functionally similar to HSL but maps better to
    human perception.

That is to say, increasing a hsluv colors lightness by 10% may be more likely
to give you a color you would _perceive_ as "10% lighter" rather than what hsl
would give you, a color which is mathematically "10% lighter".

For more information on HSLuv see: https://www.hsluv.org/

Both colorspaces can be accessed from the `lush` module and may be used
interchangeably.

For the rest of this document the term hsl can be taken to mean hsl or hsluv.
>
  hsl = lush.hsl
  hsluv = lush.hsluv
  hsl(100, 50, 50)
  hsluv(100, 50, 50)
<

Define a color                                               *lush-define-color*

You can create HSL(UV) colors by providing hue, saturation and lightness values,
or providing a hexadecimal string.
>
  color = hsl(0, 100, 50) -- equivilent to rgb(255,0,0) elsewhere
  hex_color = hsl("#FF0000") -- hex_color == color
<

Color Operations                                         *lush-color-operations*

All color operation functions are pure, they alway return new colors objects
and leaving the originals unmodified.
>
  c1 = hsl(0, 100, 50)
  c2 = c1.rotate(10) -- c2 != c1
<

Functions can be chained.
>
  c.rotate(10).saturate(20).lighten(5)
<

rotate, ro                                                   *lush-color-rotate*

Rotate values are wrap around 0-360 degrees, `ro` is shorthand for `rotate`.
>
  color.rotate(n)
  color.rotate(-n)
  color.ro(n)
  color.ro(-n)
<

saturate, desaturate, sa, de       *lush-color-saturate* *lush-color-desaturate*

Saturation operations are clamped between 0-100. Operations are relative,
they increase/decrease a percentage, not by adding a flat value
(see |lush-color-absolute-operations|).

`sa` is shorthand for `saturate`.
`de` is shorthand for `desaturate`.
>
  color.saturate(n)
  color.desaturate(n)
  color.sa(n)
  color.de(n)
<

lighten, darken, li, da                 *lush-color-lighten* *lush-color-darken*

Lightness operations are clamped between 0-100. Operations are relative,
they increase/decrease a percentage, not by adding a flat value
(see |lush-color-absolute-operations|).

`li` is shorthand for `lighten`.
`da` is shorthand for `darken`.
>
  color.lighten(n)
  color.darken(n)
  color.li(n)
  color.da(n)
<

mix                                                             *lush-color-mix*

Mix one colour into another. Accepts a target color and strength, where the
target is a hsl, hsluv type and strength is between 0-100.

A strength of 0 effectively returns the original color, while 100 will return
the target color.
>
  color.mix(target, 50)
  color.mix(target, 0) == color
  color.mix(target, 100) == target
<

readable                                                   *lush-color-readable*

Given a color, return either white or black, which ever provides the better
contrast. Most useful when setting a foreground color.
>
  color.readable()
<

abs_*                                           *lush-color-absolute-operations*

Saturation and Lightness operatins work relative to the current values. This is
generally preferred when making those kind of adjustments, but all functions,
including shorthands, have absolute counterparts, prefixed by `abs_` which will
add or subtract an absolute value.

Rotate does not have an `abs_` prefixed function, it always operates absolutely.
>
  color = hsl(0, 50, 50)
  color.saturate(10) -- saturates the color by 10%
  color.abs_saturate(10) -- adds 10 to 50
<

hue, saturation, lightness, .h, .s, .l                       *lush-color-direct*

You may also directly set a HSL value via:
>
  hue(n)
  saturation(n)
  lightness(n)
<

And access members with,
>
  color.h -- hue
  color.s -- saturation
  color.l -- lightness
<

.hex, tostring                                      *lush-color-string-coercion*

HSL colors can be coerced into a hex string, either by concatenation
with another string, passing to a function which will invoke tostring()
or accessing the `.hex` accessor.

.rgb()                                                          *lush-color-rgb*

HSL colors can be converted to RGB values, this should only be done
outside of a Lush spec, when you are intending to extract the red, green
and blue values for use elsewhere.

Example                                                     *lush-color-example*
>
  local hsl = require('lush').hsl                 -- include the module
  local red = hsl(0, 100, 50)                     -- define a color
  local light_red = red.lighten(20)               -- modify
  local orange = red.hue(20)                      -- set
  local sum_hues = red.h + light_red.h + orange.h -- access
  local chained_compliment = red.ro(180)          -- chain via aliases
                                .da(30)
                                .sa(10)
  print(red)                                      -- as string "#FF0000"
<

--------------------------------------------------------------------------------
Lush Spec                                                            *lush-spec*

You define your color scheme by writing a lush-spec, which can leverage the
HSL module (or any other lua module) and be exported to other parts of Neovim.
Lush will expose your lush-spec as a Lua module.

The basic definition of a lush-spec is, a Lua table which defines your
highlight groups, by name, and their associated color and decoration details.

The advantage of using Lush and a lush-spec is that you're able to define
groups from previous groups, and make modifications on those groups to easily
define relational colours between groups.

Sample Lush-Spec                                              *lush-spec-sample*

Here's a very simple lush-spec:
>
  -- cool_name/lua/lush_theme/cool_name.lua
  -- require lush
  local lush = require('lush')
  -- lush(), when given a spec, will parse it and return a table
  -- containing your color information.
  -- We should return it for use in other files.
  return lush(function()
    return {
      -- Define what vims Normal highlight group should look like
      Normal { bg = lush.hsl(208, 90, 30), fg = lush.hsl(208, 80, 80) },
      -- And make whitespace slightly darker than normal.
      -- Note you must define Normal before you try to use it.
      Whitespace { fg = Normal.fg.darken(40) },
      -- And make comments look the same, but with italic text
      Comment { Whitespace, gui="italic" },
      -- and clear all highlighting for CursorLine
      CursorLine { },
    }
  end)
<

And the corresponding colorscheme loading file for nvim:
>
  " cool_name/colors/cool_name.vim
  " yes, unfortunately you still have to write some Vim Script
  set background=dark
  let g:colors_name="cool_name"
  " you could detect background == dark || light here and require
  " different files
  lua require('lush')(require('lush_theme.cool_name'))
<

--------------------------------------------------------------------------------
Lush-Spec Spec                                                  *lush-spec-spec*

Lush supports the following group definitions:

Direct Definition                                  *lush-spec-direct-definition*

Used to define a stand alone highlight group.

Syntax:
>
  GroupName { fg = value, bg = value, gui = value, sp = value, blend = value }
<

Supports the following keys:

  fg:    sets the `fg` property of a highlight group.
         value must be a string, or respond to tostring().

  bg:    sets the `bg` property of a highlight group.
         value must be a string, or respond to tostring().

  sp:    sets the `sp` property of a highlight group.
         value must be a string, or respond to tostring().

  blend: sets the `blend` property of a highlight group.
         value must be an integer between 0 and 100.

         note: you must have enabled blending in neovim via
               `pumblend` or `winblend`!

  gui:   a string containing any of the following format modifier
         values, separated by space or comma.

  bold:          boolean, enables or disables bold.
  italic:        boolean, enables or disables italics.
  underline:     boolean, enables or disables underline.
  underlineline: boolean, enables or disables double underline.
  underdouble:   boolean, underlineline in nvim 0.8
  undercurl:     boolean, enables or disables undercurl.
  underdot:      boolean, enables or disables underdot.
  underdotted:   boolean, underdot in nvim 0.8
  underdash:     boolean, enables or disables underdash.
  underdashed:   boolean, underdash in nvim 0.8
  strikethrough: boolean, enables or disables strikethrough.
  reverse:       boolean, enables or disables flipping fg and bg values.
  standout:      boolean, enables or disables standout.
  nocombine:     boolean, enables or disables nocombine.

  lush:  a namespace to save arbitrary data to a group. Is not
         exported to the final highlight but may be accessed in
         the lush-spec or the parsed-lush-spec.

Constraints:

  `value` may be any Lua type which will concatenate with a string.

  `value` may be derived from previously defined group properties.

  All unsupported keys are dropped.

  Group name is CamelCase by convention, but may be any string beginning with
  alpha characters.

  Group names may not be `ALL`, `NONE`, `ALLBUT`, `contained` or `contains`,
  this is a vim constraint.


Linked Group                                            *lush-spec-linked-group*

Used to define a highlight link.

Syntax:
>
  LinkedGroup { GroupName },
<

Supported keys:

  N/A.

Constraints:

  Linked group must be defined before the link definition.


Inherited Group                                      *lush-spec-inherited-group*

Used to define a new highlight group, with properties inherited from another
group.

This is logically similar to a Linked Group, except you wish to define new
keys, or redefine old keys.

Syntax:
>
  InheritedGroup { Parent, gui = "bold" },
<

Supported keys:

  See Direct Definition.

Constraints:

  Only one parent group may be specified and it must be the first value in the
  group definition.

  Inherits constraints of Direct Definition

--------------------------------------------------------------------------------
Extending lush-specs                                      *lush-extending-specs*

Lush provides two ways to combine multiple lush specs into one: `extends` and
`merge`.

If you want to combine a list of one or more parsed lush specs, and apply any
tweaks, you should use `extends({parsed_spec, ...}).with(spec)`.

If you want to combine a list of one or more parsed lush specs, but don't need
to adjust them, you can use `merge({parsed_spec, ...}).

In both cases, groups later in the list will overwrite any groups before them.

Given:
>
  group_1 = {
    A { fg = "1_a_fg" },
    B { fg = "1_b_fg" }
  }

  group_2 = {
    B { fg = "2_b_fg" }
  }
<

Extend/merging the groups in order would result in:
>
  {group_1, group_2} = {
    A { fg = "1_a_fg" },
    B { fg = "2_b_fg" }
  }
<

extends({parsed_lush_spec, ...}).with(spec)                  *lush-extends-with*

`extends({parsed_lush_spec, ...})` *must* be proceeded by `with(spec)`, which
returns a parsed_lush_spec.

If you have an existing spec that you wish to modify, you may want to use
`extends.with`.

Potential use cases:

  - You like a lush colorscheme you got online, but want to change a few
    specific parts of it, such as the comment style, or the background color.

  - You want to add a plugin to an colorscheme by using it's existing groups.

  - You are writing your own colorscheme and want to make a small tweaks to
    create a variant, for example a high-contrast or colorblind safe mode.

Example - adding plugin support:
>
  local lush = require('lush')
  local hsl = lush.hsl

  -- some colorscheme from the internet
  local harbour = require('lush_theme.harbour')

  local spec = lush.extends({harbour}).with(function()
    return {
      -- make Sneak look like Search
      Sneak { harbour.Search },
      -- you can now use Sneak just like any other group (ref, inherit, etc)
      SneakScope { bg = Sneak.bg.li(10) },
      SneakLabel { Sneak, gui = "italic" },
      -- you can use bits from anywhere
      MixAndMatch { bg = harbour.Normal.fg, fg = SneakLabel.fg, gui = "underline" },
    }
  end)

  return spec
<

Example - complex combination:
>
  -- You may have installed this colorscheme via your package manager or similar
  -- (good lush colorschemes should be portable), or you might be writing a variant
  -- for your main colorscheme.
  local some_colorscheme = require('lush_theme.some_colorscheme')

  -- Maybe you also want to include a community extension that patches
  -- some missing styles in the original colorscheme.
  local some_colorscheme_lsp = require('lush_theme.some_colorscheme_lsp')

  local spec = lush.extends({some_colorscheme, some_colorscheme_lsp}).with(function()
    -- It is also valid to return an empty spec. This is functionally
    -- equivalent to calling merge({some_colorscheme}).
    -- return { }

    return {
      -- You can use the same group tools as normal: linking and group
      -- inheritance, but you must access the groups through their imported
      -- variables.

      -- Inherit fg and gui settings, but adjust bg
      Normal { some_colorscheme.Normal, bg = some_colorscheme.Normal.bg.li(10).sa(20) },

      -- Overwrite comment group completely
      Comment { fg = some_colorscheme.Normal.fg.da(10) },

      -- link cursorline to normal
      CursorLine { some_colorscheme.Normal }
    }
  end)

  return spec
<

merge({parsed_lush_spec, ...})                                      *lush-merge*

`merge({parsed_lush_spec, ...})` returns a parsed_lush_spec.

If you have an group of parsed lush specs that you do not want to tweak, you
can simply merge them.

Potential use cases:

  - You have a collection of plugin highlight groups want to let users
    configure which highlight groups are enabled.

  - You want to apply a patch/extension to a colorscheme that isn't provided by
    the main colorscheme repo.

  - You simply want to define your colorscheme in parts for maintenance
    reasons.

Example:
>
  -- See also extends.with, most concepts are applicable.

  local some_colorscheme = require('lush_theme.some_colorscheme')

  -- Maybe LSP highlights are complex and you define them in a different file
  local some_colorscheme_lsp = require('lush_theme.some_colorscheme_lsp')

  local specs = {
    some_colorscheme,
    some_colorscheme_lsp
  }

  -- Only include xyz groups if the user wants them
  if user_config.enable_xyz then
    table.insert(specs, require('lush_theme.some_colorscheme.xyz')
  end

  -- You might also include variants this way
  it user_config.italic_comments then
    -- You can also do this inline, or by using extends.with
    table.insert(specs, lush(function()
      return {
        Comment { some_colorscheme.Comment, gui = "italic" }
      }
    end)

  -- Combine into one
  local spec = lush.merge(specs)

  return spec
<

--------------------------------------------------------------------------------
Lush.ify                                                               *lushify*

Lush.ify will provide automatic, real-time highlighting of any `hsl(...)` calls,
as well as highlighting any groups in your lush-spec with their appropriate
colors and decorations.

To use lush.ify, open your colorscheme Lua file and run the vim command,
>
  :Lushify
<
or run it directly via Lua,
>
  :lua require('lush').ify()
<
Now changes you make to a colorscheme are reflected in real time. See the two
starter files for more information and a demonstration.

Performance of lush.ify is somewhat dependent on your hardware and probably
more specifically, your terminal. Some re-render faster than others.

Lush.ify will perform some minor event debouncing, with an increased window on
multiple parser failures. The defaults should allow for a smooth experience,
but if you desire to change them, you can pass options to lush.ify like so
(times are in ms),
>
  :lua require('lush').ify({natural_timeout = 25, error_timeout = 300})
<
If you feel performance is poor, please try disabling any linter/lsp/etc first.

--------------------------------------------------------------------------------
Converting an Existing Theme to Lush      *lush-converting-existing-colorscheme*

Lush provides a `:LushImport` command that creates a draft lush spec from the
currently loaded colorscheme. It places this in the `z` register, so you can
paste it into a new file by typing `"zp`.

--------------------------------------------------------------------------------
Exporting From Lush                                                *lush-export*

Lush has a comprehensive build system, see BUILD.md until vimdocs are written
for this system (sorry).

--------------------------------------------------------------------------------
Manual Toolchain                                         *lush-manual-toolchain*

If desired, you can manually parse -> compile -> apply your lush-spec.
Most usecases are probably better served by the build system, see
BUILD.md.
>
  local lush = require('lush')
  local parsed = lush.parse(function() return { ... } end)
  local compiled = lush.compile(parsed)
  lush.apply(compiled)
<

Parse                                              *lush-manual-toolchain-parse*

Accepts a lush spec and returns a parsed lush spec.

Accepts no options.
>
  local parsed = lush.parse(function() return { ... } end)
<

Compile                                          *lush-manual-toolchain-compile*

Accepts a parsed lush spec and returns a table of group-attribute pairs
which can be passed to `nvim_set_hl`.

>
  local compiled = lush.compile(parsed)
<

Apply                                              *lush-manual-toolchain-apply*

Accepts a table of group-attribute pairs and passes them to nvim_set_hl.

Accepts an optional options table:

- force_clean: boolean, clear existing highlight before applying given
               highlights.

>
  lush.apply(compiled, options)
<

--------------------------------------------------------------------------------
Pitfalls, Beartraps, Dragons                                     *lush-pitfalls*

Linters:

  You will likely get warnings from linters while writing a lush-spec,
  specifically around "undefined globals". Most of these warnings can be safely
  ignored, you may wish to disable LSP/Linters temporarily when working on a
  colorscheme.

Dependency Injection:

  Lush-specs are executed a bare environment, so they don't have access to Lua
  globals or other modules. However, they are also written as closures, so they
  do have access to any local level variables in the colorscheme file.

  This means if you want to access a global module, you simply have to bind it
  to a local scope variable.

>
  -- all these local variables can be accessed in the spec closure
  local weather = require('local_weather')
  local harbour = require('lush_theme.harbour')
  local math = math
  lush(function()
    return {
      -- set fg color depending on rain or snow
      Normal  { fg = hsl(weather.hex_color_for_current_weather) },
      -- set comment color from normal fg, but set to a random
      -- analogous-ish color
      Comment { fg = Normal.fg.ro(math.random(-60, 60)) },
      -- we can even access other colorscheme data
      -- automatic colorscheme inheritance and extension is WIP
      CursorLine { fg =  harbour.CursorLine.fg, bg = harbour.CursorLine.bg },
    }
  end)
<

Easy Motion:

  Activating the easy motion plugin in a lush.ify'd buffer will cause a lot of
  syntax errors. This is because easy-motion directly modifies the buffer to
  display its "jump keys", which we try to parse.

  It is not recommended you activate easy motion in a lush.ify'd buffer.

Live Search-Replace:

  If you use Neovim's live-updating search-and-replace feature (),
  you may see Neovim errors being reported. In my experience these can be safely
  ignored and you may continue as normal.

Lightline

  While Lightline can be styled through Lush, real-time updating has some
  caveats and performance may be less than optimal due to Vim Script performance.

  See `examples/lightline-one-file` and `examples/lightline-two-files` for
  guidance. Generally, if real time performance with Lightline is problematic,
  I would recommend developing your colorscheme first, then disabling lush.ify
  with `:e!` in the buffer and applying your changes via .

  The two examples go into some more detail regarding this method.

--------------------------------------------------------------------------------
Bugs or Limitations                                                  *lush-bugs*

Sometimes line group and HSL highlighting may appear out of sync if you've
applied undo/redo chains to a lush.ify'd file. Generally typing more into
the buffer will fix these issues as the highlighter re-syncs with the buffer
state.

You may find some elements don't update in real time (LSP sign column for
example). This is a side effect of how colours are applied to those elements,
they are only as they are created (afaik). The group name in your lush-spec
should update to let you see how it will look when your colorscheme is loaded.

Lush.ify'd `hsl()` and group name highlight may sometimes be obscured by
CursorLine highlighting. If this is a problem, you can set CursorLine to an
empty definition or disable the cursor line with .