nixCats.txt

=======================================================================================
NIX CATEGORIES                                                       *nixCats*

For help with the nix flake files, see :help `nixCats.flake`

*******************************************************
TWO IMPORTANT NOTES:

<1> YOU CANNOT LAUNCH THIS VIA nvim COMMAND
      IT HAS THE NAME OF THE PACKAGE YOU SET,
      AND WHATEVER ALIASES YOU GAVE IT.
      This is due to the ability to install multiple nvims via home manager
      or per single user on nixos.

<2> When editing the files within the flake directory,
nix will not package a new file if it isn't staged in git.
run git add before rebuilding it whenever adding a new file.
Using wrapRc = true would mean this also applies to lua files.
In fact, when wrapRc = true, even changes within a lua file
will not be reflected unless you run git add.
*******************************************************

nixCats: returns category names included by nix for this package 

Use a dot-separated string to check if this neovim was packaged with 
a particular category included:
>lua
    if nixCats('lua.someSubcategory') then
        -- some stuff here
    end
<
Checking a category that is not present rather than false,
will still return false from this if statement because nil in lua is "falsey"
I.e. if nix was not a category you included a value true or false for,
it would evaluate as if it was false.
if your category has an illegal lua name you may instead use this syntax
>lua
    nixCats({'attr-set', "path", "to", [[valu.e'!#$@]]})
<

nixCats command will return the nearest parent category value, unless the nearest
parent is a table, in which case that means a different subcategory
was enabled but this one was not.
In that case it will try to find the next value, fail, and return nil.
If the item you are checking is a table,
if nixCats('the.table') then print("true") end
will print true, and nixCats('the.table') will return the table.

The nixCats command is an alias for require('nixCats').get()

The nixCats "plugin" is just a table and a get function.
It is generated by the flake, and the table is
the same one you provided to choose what
categories are included in each package in the flake.nix file.
However it also adds a few values for convenience.
  nixCats_packageName
  nixCats_store_config_location
  nixCats_wrapRc
Because it adds these to nixCats, do not use them as
a category name in your package definition (example package definition below).
They will be replaced.

If in your flake, your package definition looked like this:
  see :help `nixCats.flake.outputs.packaging`
>nix

  packageDefinitions = {
    nixCats = {
      settings = settings.nixCats; 
      categories = {
        generalBuildInputs = true;
        markdown = true;
        general.vimPlugins = true;
        general.gitPlugins = true;
        custom = true;
        neonixdev = true;
        test = {
          subtest1 = true;
        };
        debug = false;
        # this does not have an associated category of plugins, 
        # but lua can still check for it
        lspDebugMode = false;
        # by default, we dont want lazy.nvim
        # we could omit this for the same effect
        lazy = false;
        # you could also pass something else:
        themer = true;
        colorscheme = "onedark";
        theBestCat = "says meow!!";
        theWorstCat = {
          thing'1 = [ "MEOW" "HISSS" ];
          thing2 = [
            {
              thing3 = [ "give" "treat" ];
            }
            "I LOVE KEYBOARDS"
          ];
          thing4 = "couch is for scratching";
        };
        # see :help nixCats
      };
    };
  };

<
Using:
>vim
    :lua print(vim.inspect(require('nixCats').cats))
    or
    :NixCats
<
will return something like this:
>lua
  {
    colorscheme = "onedark",
    custom = true,
    debug = false,
    general = {
      gitPlugins = true,
      vimPlugins = true
    },
    generalBuildInputs = true,
    lazy = false,
    lspDebugMode = false,
    markdown = true,
    neonixdev = true,
    nixCats_packageName = "nixCats",
    nixCats_store_config_location = "/nix/store/fazkaci8bravyly4xahs0b69r1xxj4i3-nixCats-special-rtp-entry-LuaConfig",
    nixCats_wrapRc = true,
    test = {
      subtest1 = true
    },
    theBestCat = "says meow!!",
    theWorstCat = {
      ["thing'1"] = { "MEOW", "HISSS" },
      thing2 = { {
          thing3 = { "give", "treat" }
        }, "I LOVE KEYBOARDS" },
      thing4 = "couch is for scratching"
    },
    themer = true
  }
<
Note: it also accepts other things.
lists will become arrays
sets will become tables
null will become nil
derivations will become store paths

everything that isnt true, false, null, 
a list, or a set becomes a lua string.
it uses "[[${builtins.toString value}]]"
in order to achieve this.
It will throw an error if you pass an uncalled function.

If theBestCat says meow, and you use this syntax,
>lua
    if nixCats('theBestCat') then
      print("true")
    end
<
theBestCat will evaluate as true if 
it contains something that isnt false (or nil).
>lua
    if nixCats('theBestCat' == true) then
      print("true")
    else
      print("false")
    end
<
However, this one will print false.

Regardless, dependencies included under vocal cats 
will not be included. So don't go changing all true 
values to "meow" it wont work. 

Only categories with the boolean value true are included
from the flake.

Use this fact as you wish.
You could use it to pass information like port numbers or paths
Or whatever else you want.

nixCats also contains other info.

>lua
  require('nixCats').included
    -- contains a final list of all the plugins included
    -- in the package and their paths, and the path to treesitter parsers.

  require('nixCats').settings
    -- contains the settings set for the package
<

----------------------------------------------------------------------------------------
vim:tw=78:ts=8:ft=help:norl: