Combining | Merging | Extending themes

[lxsymington]

First off thanks for a great plugin! It's made configuring a personal colour scheme a pleasure.
I should probably mention that I have minimal knowledge of lua (something I plan to change - but haven't yet). I have also put this under Q&A as I'm less than sure that this functionality isn't either already implemented or trivial to implement.

From my limited understanding, it doesn't look as if there is a way to extend a theme? For example I would like to have variants of my colour scheme (namely light and dark, but doesn't need to be) but there are quite a lot of highlight groups that are the same between them, ideally one could extend a shared base with the different groups. e.g.

Base highlight groups

{
    ErrorMsg {bg = lightWhite, fg = red, gui = "nocombine"},
    WarningMsg { bg = yellow, fg = black.darken(40), gui = "nocombine,bold,italic" },
    Ignore {},
    Error {bg = red, fg = lightWhite, gui = "nocombine,bold,italic"},
    Todo {bg = blue, fg = lightWhite, gui = "nocombine,bold,italic"},
    -- ... More common highlight groups
}

Variant highlight groups (dark)

{
    Normal {bg = black, fg = white, gui = "nocombine"},
    NormalFloat {bg = grey, gui = "nocombine"},
    NormalNC {bg = lightBlack, fg = white, gui = "nocombine"},
    ColorColumn {bg = black.darken(20), gui = "nocombine"},
    Comment {fg = black.lighten(15), gui = "nocombine,italic"},
    CursorLine {bg = black.darken(20), gui = "nocombine"},
    CursorLineNr {bg = black, fg = yellow, gui = "nocombine,bold"},
    -- ... More variant highlight groups
}

similarly for light highlights.

Being able to then combine these to produce a full theme would make maintenance and consistency easier.

Something like:

lush.merge(base, if background == 'dark' then dark else light end)

If this is already trivial, please forgive my lack of understanding and it would be greatly appreciated if you could point me in the right direction!

[rktjmp]

TLDR: you can't do it in one step right now but I can plan to (try to) make it work.

This has been something on my mind from the start https://github.com/rktjmp/lush.nvim/blob/main/TODO.md#theme-inheritance

It was some time ago, pretty sure I wrote a demo implementation for that but it was on a different OS install so I think the local branch got nuked. I wasn't sure anyone would even use Lush at the time so I didn't pursue it much further.

I actually think the main roadblock was how the API should look, rather than any technical limitation.

You would have to import the spec (base) in the child (dark), then pass the child into lush(), but basically I thought it felt awkward to do that at the end of the spec.

-- options at end
local base = require('lush_theme.burrito_base')

local spec = lush(function()
  return {
    Normal {...}
  }
end, {inherit: base}) -- awkward when the spec is longer

I think I toyed with optionally accepting options as the first argument, but I think I didn't like the complexity it added to maintaining the lush() function, which was feeling pretty overloaded.

-- optional options at start
local base = require('lush_theme.burrito_base')

rush({parent: base}, function() -- sometimes options, sometimes not
  return {
    Normal {...}
  }
end)

Thinking about it now I would like something like,

-- functionally spec'd
local base = require('lush_theme.burrito_base')

local spec = lush(base).extend(function()
  return {
    Normal {...}
  }
end)

You can sneak by, maybe you already know, by requiring your base spec then just accessing it in your second spec, which sort of lessens the burden (not really).

local base = require('lush_theme.burrito_base')

local spec = lush(function()
  return {
    Normal { fg = base.Normal.fg }
  }
end)

Ideally you could just pass the group in via the group inheritance stuff,see doc and demo but you have discovered a bug #9

You mentioning merge does make me wonder though...

If you, thinking out loud,

• write a base spec
• require that spec in dark as a lua module (i.e. a lua table)
• write dark
• use whatever lua's merge table function is (might need external deep merge code, not sure) to merge dark onto base.
• return the merged table to be compiled and applied.

That might work for free, no guarantee though.

local base = require('lush_theme.burrito_base')

local spec = lush(function()
  return {
    Normal {...}
  }
end)

return deep_merge_a_onto_b(base, spec)

[rktjmp]

You may also find this https://github.com/alaric/nortia.nvim interesting as an exercise in lush (ab)use, though he's doing more than just light/dark.

[lxsymington]

Wow! Thanks for such a thorough reply! That's really interesting I'll give your last suggestion a go and see where I get.

Nortia does look really interesting, made me think of the live contrast value (next to the Δ) on the colour picker from https://github.com/lifepillar/vim-colortemplate (it's nice to know that the colour combination works for more than just oneself in the current lighting)

Nortia's temporal shifting is a really nice touch too.

[lxsymington]

Just wanted to say, I finally got around to giving your last suggestion a go and it worked a treat, so thanks!

[rktjmp]

Great. I definitely want to make it easier, just a matter of finding time to write it. At least there is a kind of viable work around now.

[ellisonleao]

This would be a nice feature for my current plugin. I am now using vim.tbl_extend to create the whole theme group, by checking for some plugin existence and then extend the base theme table. Not sure if its the right approach, but having this type of feature would definitely make the code a little bit better

[kunzaatko]

I unfortunately filed an issue about this before reading through the whole discussion, but this is exactly what I was suggesting. I have some files that define colour groups for different laguages (and even different plugins if you would like)

[rktjmp]

@ellisonleao I see you had then removed the HL group checks

ellisonleao/gruvbox.nvim@b938b6d

What was the reasoning for this? Lush or Vim?

I did wonder if you might hit load order issues with that, if the plugin is hot loaded on a file load you might never get to define the highlight group.

[ellisonleao]

hey @rktjmp i've removed it for now until i get all the colors correct in first place, i am still working towards getting them done, the i will get back to the conditional group adding part.

[rktjmp]

I have pushed a WIP branch that I would appreciate some feedback on. Does it let you do what you want? I think it probably solves the original post here, as well as #10 and #13.

https://github.com/rktjmp/lush.nvim/compare/main..extend-spec

The functionality should not change (I believe it covers all it needs to) but the external API (extends, with) might change. (The {extends: {...}} is unlikely to change.

Later parents take precedence.

base = lush(function
  return {
    Normal { ... },
    Function { ... },
    Search { ... }
  })
extras = lush(function
  return {
    Normal { ... },
    Comment { ... },
    Function { ... },
    CursorColumn { Normal },
  })
dark = lush.extends(base, extras).with{function
  return {
    Match { Function },
    CursorLine { CursorColumn },
  })

Roughly results in:

  Match link extras.Function
  CursorLine link Normal
  Function is extras.Function
  Comment is extras.Comment
  Normal is extras.Normal
  Search is base.Search

You can see the basics of how to use it in the test file.
https://github.com/rktjmp/lush.nvim/blob/extend-spec/spec/lush_extends_spec.moon

lush(function
  return {
    B { A }
  }, {extends: {parent})

or

lush.extends(parent).with(function 
  return {
    B { A }
  })

or

lush.extends(parent).extends(parent2).with(function 
  return {
    B { A }
  })

-- i.e:

x = lush.extends(parent)
x = x.extends(parent2)
return x.with(function 
  return {
    B { A }
  })

or

lush.extends(parent, parent2).with(function 
  return {
    B { A }
  })

or

parents = {p1, p2}
-- unpack list
lush.extends(unpack(parents)).with(function 
  return {
    B { A }
  })

The extends chaining isn't hygenic, mostly because lua isn't, so it might change, though I think returning the extends table from files may be useful. Not 100% decided yet, maybe the usage would be basically the same if you just returned specs like normal. Also there is probably too many ways to use it which just makes the API wider to learn.

[kunzaatko]

It is entirely necessary to have extends because without it, with has no function. They're part of the same API. eyes eyes

OK, I think I see it now. I did not understand the API correctly.

[ellisonleao]

You can pass any group of a required spec into your new groups. So if you just want to have a group inherit from another spec's group without totally extending the other spec you can.

That's kinda what i've been wanting. I am thinking about having multiple lua groups files for each language/plugin, then will combine then in the main one using the inheritance support. That gruvbox example is definitely something i would use when its available

[rktjmp]

Something like this?

-- undo_tree.lua
local base = require 'lush_theme.gruv_base' 

return lush(function()
  return {
   UndoTreeHeading { fg = base.Normal.fg, bg = base.Normal.bg },
   -- note: it *should* be ok to write links here, but whether they work is 
   --       dependent on you actually including the base group in the
   --       final spec, else it ends up linking to nothing.
   UndoTreeTime { base.Comment }
  }
end)

-- gruvbox.lua
local base = require 'lush_theme.gruv_base'

specs = {base}
for _, plugin in ipairs(config.plugins) do
  -- where plugins is something like {"undo_tree", "elixir", "fzf"}
  table.insert(specs, require('lush_theme.plugins.'..plugin))
end

return lush.extends(specs).with((function() return {} end)

[kunzaatko]

The template files are now ready and I think that they adhere to this API (that is not yet in mainline). I added you both (@rktjmp , @ellisonleao ) to the private repo, with the templates.

[ellisonleao]

thanks @kunzaatko i will be live streaming on wednesday and i hope to make those changes over there (twitch.tv/npxbr btw)

[rktjmp]

extends.with and merge now in mainline cc5ba40. https://github.com/rktjmp/lush.nvim#advanced-usage.