[request] Lua configuration API

[bennypowers]

Thank you for publishing this helpful package 🙇

Please consider adding a lua configuration API for neovim users. A straw example of what I mean:

local hexokinase = require'vim-hexokinase'
hexokinase.setup {
  palettes = { vim.fn.expand('~/Developer/design-tokens/build/editor/hexokinase.json') },
  opt_in_patterns = { 'full_hex', 'triple_hex', 'colour_names' },
  ft_opt_out_patterns = {
    json = { 'colour_names' },
    yaml = { 'colour_names' },
  },
}

I've configured hexokinase to eat my project's design tokens.

Code to generate hexokinase colour_table

const isColorAlias = token => token.original?.value?.startsWith?.('{color.');

const pairAliasWithValue = token => {
  if (typeof token.value === 'string') {
    return [ [ token.original.value.replace(/\._}$/, '}'), token.value ] ];
  } else if (token.value) {
    return Object.fromEntries(Object.entries(token.value).map(pairAliasWithValue))
  } else {
    return []
  }
}

/**
 * Exports [vim-hexokinase](https://github.com/RRethy/vim-hexokinase) custom patterns
 */
StyleDictionary.registerFormat({
  name: 'editor/hexokinase',
  formatter: ({ dictionary }) =>
    JSON.stringify({
      regex_pattern: '\\{color\\.(\\w+)\.(\\d{1,3})\\}',
      colour_table: Object.fromEntries(
      dictionary.allTokens.filter(isColorAlias).flatMap(pairAliasWithValue))
    }, null, 2),
});

Once built, I can load up the patterns via the vimscript global configuration keys:

vim.g.Hexokinase_optInPatterns = { 'full_hex', 'triple_hex', 'colour_names' }

vim.g.Hexokinase_ftOptOutPatterns = {
  json = { 'colour_names' },
  yaml = { 'colour_names' },
}

vim.g.Hexokinase_palettes = {
  -- replace with relevant path on your drive
  vim.fn.expand('~/Developer/design-tokens/build/editor/hexokinase.json')
}

This is fine, but as a user I'll need to make sure to set these prior to loading hexokinase. When using packer.nvim plugin manager, it's typical practice to configure plugins with a setup function after loading. I can work around this by using packer's setup key, so nothing is blocked, but a lua API would be a drop more ergonomic for neovim users.

Thanks for considering this request and thanks again for this nice package.

[maxmahlke]

To extend on @bennypowers nice explanation, here is an explicit example of installing and configuring vim-hexokinase using the packer startup function:

use({
    "RRethy/vim-hexokinase",
    run = "make hexokinase",
    setup = function()
        vim.g.Hexokinase_highlighters = { "foregroundfull" }
    end,
})

Note that you have to run :PackerSync after changing the setup function in order for changes in the configuration to be applied.