HOME TOC REPO

1   =======================================================================================
2   NIX CATEGORIES                                                       nixCats
3   
4   For help with the nix flake files, see :help nixCats.flake
5   
6   *******************************************************
7   AN IMPORTANT NOTE:
8   
9   <1> When editing the files within the flake directory,
10  nix will not package a new file if it isn't staged in git.
11  run git add before rebuilding it whenever adding a new file.
12  Using wrapRc = true would mean this also applies to lua files.
13  In fact, when wrapRc = true, even changes within a lua file
14  will not be reflected unless you run git add.
15  *******************************************************
16  
17  nixCats: returns category names included by nix for this package 
18  
19  Use a dot-separated string to check if this neovim was packaged with 
20  a particular category included:
21  
22      if nixCats('lua.someSubcategory') then
23          -- some stuff here
24      end
25  
26  Checking a category that is not present rather than false,
27  will still return false from this if statement because nil in lua is "falsey"
28  I.e. if nix was not a category you included a value true or false for,
29  it would evaluate as if it was false.
30  if your category has an illegal lua name you may instead use this syntax
31  
32      nixCats { 'attr-set', "path", "to", [[valu.e'!#$@]] }
33  
34  nixCats command will return the nearest parent category value, unless the nearest
35  parent is a table, in which case that means a different subcategory
36  was enabled but this one was not.
37  In that case it will try to find the next value, fail, and return nil.
38  If the item you are checking is a table,
39  if nixCats('the.table') then print("true") end
40  will print true, and nixCats('the.table') will return the table.
41  
42  The nixCats global function is an alias for require('nixCats').get()
43  
44  The nixCats "plugin" is just some tables and a get function.
45  It is generated by the flake, and the table is
46  the same one you provided to choose what
47  categories are included in each package in the flake.nix file.
48  
49  However it also adds a few values for convenience.
50    nixCats_packageName
51    nixCats_config_location
52    nixCats_wrapRc
53  
54  Because it adds these to nixCats, do not use them as
55  a category name in your package definition (example package definition below).
56  They will be replaced.
57  
58  If in your flake, your package definition looked like this:
59    see :help nixCats.flake.outputs.packageDefinitions
60  
61  
62    packageDefinitions = {
63      nixCats = { pkgs, ... }@misc: {
64        settings = settings.nixCats; 
65        categories = {
66          generalBuildInputs = true;
67          markdown = true;
68          general.vimPlugins = true;
69          general.gitPlugins = true;
70          custom = true;
71          neonixdev = true;
72          test = {
73            subtest1 = true;
74          };
75          debug = false;
76          # this does not have an associated category of plugins, 
77          # but lua can still check for it
78          lspDebugMode = false;
79          # by default, we dont want lazy.nvim
80          # we could omit this for the same effect
81          lazy = false;
82          # you could also pass something else:
83          themer = true;
84          colorscheme = "onedark";
85          theBestCat = "says meow!!";
86          theWorstCat = {
87            thing'1 = [ "MEOW" "HISSS" ];
88            thing2 = [
89              {
90                thing3 = [ "give" "treat" ];
91              }
92              "I LOVE KEYBOARDS"
93            ];
94            thing4 = "couch is for scratching";
95          };
96          # see :help nixCats
97        };
98      };
99    };
100 
101 
102 Using:
103 
104     :lua print(vim.inspect(require('nixCats').cats))
105     or
106     :lua print(vim.inspect(nixCats.cats))
107     or
108     :NixCats
109     or
110     :NixCats cats
111 
112 will return something like this:
113 
114   {
115     colorscheme = "onedark",
116     custom = true,
117     debug = false,
118     general = {
119       gitPlugins = true,
120       vimPlugins = true
121     },
122     generalBuildInputs = true,
123     lazy = false,
124     lspDebugMode = false,
125     markdown = true,
126     neonixdev = true,
127     nixCats_packageName = "nixCats",
128     nixCats_config_location = "/nix/store/fazkaci8bravyly4xahs0b69r1xxj4i3-nixCats-special-rtp-entry-LuaConfig",
129     nixCats_wrapRc = true,
130     test = {
131       subtest1 = true
132     },
133     theBestCat = "says meow!!",
134     theWorstCat = {
135       ["thing'1"] = { "MEOW", "HISSS" },
136       thing2 = { {
137           thing3 = { "give", "treat" }
138         }, "I LOVE KEYBOARDS" },
139       thing4 = "couch is for scratching"
140     },
141     themer = true
142   }
143 
144 Note: it also accepts other things.
145 lists will become arrays
146 sets will become tables
147 null will become nil
148 numbers will remain numbers
149 derivations will become store paths
150 
151 everything that isnt true, false, null, 
152 a list, or a set becomes a lua string.
153 it uses "[[${builtins.toString value}]]"
154 in order to achieve this.
155 It will throw an error if you pass an uncalled function.
156 
157 If theBestCat says meow, and you use this syntax,
158 
159     if nixCats('theBestCat') then
160       print("true")
161     end
162 
163 theBestCat will evaluate as true if 
164 it contains something that isnt false (or nil).
165 
166     if nixCats('theBestCat') == true then
167       print("true")
168     else
169       print("false")
170     end
171 
172 However, this one will print false.
173 
174 Regardless, dependencies included under vocal cats 
175 will not be included. So don't go changing all true 
176 values to "meow" it wont work. 
177 
178 Only categories with the boolean value true are included
179 from the flake.
180 
181 Use this fact as you wish.
182 You could use it to pass information like port numbers or paths
183 Or whatever else you want.
184 
185 In addition to nixCats.cats, nixCats also contains other info.
186 
187 
188   nixCats.pawsible
189     -- contains a final set of all the plugins included
190     -- in the package and their paths, and the path to treesitter parsers.
191     -- does not include lsps and runtime dependencies,
192     -- you can retrieve their paths with vim.fn.exepath if needed.
193 
194   nixCats.settings
195     -- contains the settings set for the package
196 
197 
198 you can view these for debugging purposes with :NixCats settings and
199 :NixCats pawsible user commands.
200 
201 You may also use the following to debug. Using
202 :NixCats cat path.to.value or :NixCats cat path to value
203 will print the value of nixCats('path.to.value') for debugging purposes.
204 
205 In addition to the user commands, you may access these items directly within
206 vimscript!
207 
208 GetNixCat(value) is equivalent to the nixCats(value) command in
209 lua.
210 
211 GetNixSettings() is require('nixCats').settings
212 
213 GetNixPawsible() is require('nixCats').pawsible
214 
215 GetAllNixCats() is require('nixCats').cats
216 
217 All of the following may be accessed by require('nixCats').<item>,
218 or :NixCats <item>, except the :NixCats user command also
219 has the cat subcommand to preview the value from nixCats("catname"),
220 
221   ---@class nixCats.main
222   ---See :h nixCats.flake.outputs.packageDefinitions
223   ---Function form will return vim.tbl_get for the attrpath
224   ---@field cats table|fun(attrpath: string|string[]): any
225   ---See :h nixCats.flake.outputs.settings
226   ---Function form will return vim.tbl_get for the attrpath
227   ---@field settings table|fun(attrpath: string|string[]): any
228   ---See :h nixCats.flake.outputs.packageDefinitions
229   ---Function form will return vim.tbl_get for the attrpath
230   ---@field extra table|fun(attrpath: string|string[]): any
231   ---Contains the final set of plugins added for this package
232   ---Function form will return vim.tbl_get for the attrpath
233   ---@field pawsible table|fun(attrpath: string|string[]): any
234   ---Contains all the defined categories that you COULD enable from nix
235   ---Function form will return vim.tbl_get for the attrpath
236   ---@field petShop table|fun(attrpath: string|string[]): any
237   ---@field nixCatsPath string
238   ---@field vimPackDir string
239   ---@field configDir string
240   ---@field packageBinPath string
241   ---internal: this creates the nixCats global commands
242   ---@field addGlobals fun() 
243   ---:h nixCats
244   ---This function will return the nearest parent category value, unless the nearest
245   ---parent is a table, in which case that means a different subcategory
246   ---was enabled but this one was not. In that case it returns nil.
247   ---@field get fun(category: string|string[]): any
248 
249   ---:h nixCats
250   ---This function will return the nearest parent category value, unless the nearest
251   ---parent is a table, in which case that means a different subcategory
252   ---was enabled but this one was not. In that case it returns nil.
253   ---@alias nixCats nixCats.main | fun(category: string|string[]): any
254 
255 ----------------------------------------------------------------------------------------
256 vim:tw=78:ts=8:ft=help:norl: