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  That is, 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    packageDefinitions = {
62      nixCats = { pkgs, ... }@misc: {
63        settings = settings.nixCats; 
64        categories = {
65          generalBuildInputs = true;
66          markdown = true;
67          general.vimPlugins = true;
68          general.gitPlugins = true;
69          custom = true;
70          neonixdev = true;
71          test = {
72            subtest1 = true;
73          };
74          debug = false;
75          # This does not have an associated category of plugins,
76          # but Lua can still check for it.
77          lspDebugMode = false;
78          # By default, we don't want lazy.nvim.
79          # We could omit this for the same effect.
80          lazy = false;
81          # You could also pass something else:
82          themer = true;
83          colorscheme = "onedark";
84          theBestCat = "says meow!!";
85          theWorstCat = {
86            thing'1 = [ "MEOW" "HISSS" ];
87            thing2 = [
88              {
89                thing3 = [ "give" "treat" ];
90              }
91              "I LOVE KEYBOARDS"
92            ];
93            thing4 = "couch is for scratching";
94          };
95          # see :help nixCats
96        };
97      };
98    };
99  
100 Using:
101 
102     :lua print(vim.inspect(require('nixCats').cats))
103     or
104     :lua print(vim.inspect(nixCats.cats))
105     or
106     :NixCats
107     or
108     :NixCats cats
109 
110 will return something like this:
111 
112   {
113     colorscheme = "onedark",
114     custom = true,
115     debug = false,
116     general = {
117       gitPlugins = true,
118       vimPlugins = true
119     },
120     generalBuildInputs = true,
121     lazy = false,
122     lspDebugMode = false,
123     markdown = true,
124     neonixdev = true,
125     nixCats_packageName = "nixCats",
126     nixCats_config_location = "/nix/store/fazkaci8bravyly4xahs0b69r1xxj4i3-nixCats-special-rtp-entry-LuaConfig",
127     nixCats_wrapRc = true,
128     test = {
129       subtest1 = true
130     },
131     theBestCat = "says meow!!",
132     theWorstCat = {
133       ["thing'1"] = { "MEOW", "HISSS" },
134       thing2 = { {
135           thing3 = { "give", "treat" }
136         }, "I LOVE KEYBOARDS" },
137       thing4 = "couch is for scratching"
138     },
139     themer = true
140   }
141 
142 Note: it also accepts other things.
143 lists will become arrays
144 sets will become tables
145 null will become nil
146 numbers will remain numbers
147 derivations will become store paths
148 
149 everything that isn't true, false, null,
150 a list, or a set becomes a Lua string.
151 it uses "[[${builtins.toString value}]]"
152 in order to achieve this.
153 It will throw an error if you pass an uncalled function.
154 
155 If theBestCat says meow, and you use this syntax,
156 
157     if nixCats('theBestCat') then
158       print("true")
159     end
160 
161 theBestCat will evaluate as true if 
162 it contains something that isnt false (or nil).
163 
164     if nixCats('theBestCat') == true then
165       print("true")
166     else
167       print("false")
168     end
169 
170 However, this one will print false.
171 
172 Regardless, dependencies included under vocal cats 
173 will not be included. So don't go changing all true 
174 values to "meow" it wont work. 
175 
176 Only categories with the boolean value true are included
177 from the flake.
178 
179 Use this fact as you wish.
180 You could use it to pass information like port numbers or paths
181 Or whatever else you want.
182 
183 In addition to nixCats.cats, nixCats also contains other info.
184 
185   ---@class nixCats.main
186   ---
187   ---See :h nixCats.flake.outputs.packageDefinitions
188   ---Function form will return vim.tbl_get for the attrpath
189   ---@field cats table|fun(attrpath: string|string[]): any
190   ---
191   ---See :h nixCats.flake.outputs.settings
192   ---Function form will return vim.tbl_get for the attrpath
193   ---@field settings table|fun(attrpath: string|string[]): any
194   ---
195   ---See :h nixCats.flake.outputs.packageDefinitions
196   ---Function form will return vim.tbl_get for the attrpath
197   ---@field extra table|fun(attrpath: string|string[]): any
198   ---
199   ---Contains the final set of plugins added for this package
200   ---Function form will return vim.tbl_get for the attrpath
201   ---@field pawsible table|fun(attrpath: string|string[]): any
202   ---
203   ---Contains all the defined categories that you COULD enable from nix
204   ---Function form will return vim.tbl_get for the attrpath
205   ---@field petShop table|fun(attrpath: string|string[]): any
206   ---
207   ---The path to your configuration for the package
208   ---@field configDir string
209   ---
210   ---Path to the nixCats wrapper script that launches nvim
211   ---@field packageBinPath string
212   ---
213   ---The path to the packpath directory with all your plugins from nix
214   ---Useful for things such as vim-startuptime which must reference the wrapper's actual path
215   ---@field vimPackDir string
216   ---
217   ---The path to the nixCats plugin
218   ---@field nixCatsPath string
219   ---
220   ---internal: this creates the nixCats global commands
221   ---@field addGlobals fun() 
222   ---
223   ---:h nixCats
224   ---This function will return the nearest parent category value, unless the nearest
225   ---parent is a table, in which case that means a different subcategory
226   ---was enabled but this one was not. In that case it returns nil.
227   ---@field get fun(category: string|string[]): any
228 
229   ---The main nixCats("cat.name") function
230   ---It is an alias for `nixCats.get("cat.name")`
231   ---@alias nixCats nixCats.main | fun(category: string|string[]): any
232 
233 All of the above may be accessed in lua via
234 nixCats.<item>, or require('nixCats').<item>, or :NixCats <item>,
235 and the :NixCats user command also
236 has the cat subcommand to preview the value from nixCats("catname")
237 You can view these for debugging purposes with :NixCats settings and
238 :NixCats pawsible user commands.
239 
240 Everything provided by the nixCats plugin can be printed
241 for debugging purposes via the :NixCats user command.
242 e.g. :NixCats cats shown above will print the nixCats.cats table.
243 
244 Using :NixCats cat path.to.value or :NixCats cat path to value
245 will print the value of nixCats('path.to.value')
246 
247 The debug command by default will create
248 a popup window to display the information.
249 
250 If you don't like that, or are using neovim embedded
251 in another application without buffer or window support,
252 (such as vscode), you may set
253 vim.g.nixcats_debug_ui = false
254 which will cause it to do a simple print(vim.inspect(value)) instead.
255 Or, you can simply print them yourself!
256 print(vim.inspect(nixCats.cats))
257 
258 In addition, you may also access these items directly within vimscript! 
259   v:lua.require('nixCats').cats
260 
261 There are some helper functions included in the plugin that call that for you,
262 but if you are going to use vimscript in neovim, knowing how to call lua is
263 important. So, I showed the general way first.
264 
265 GetNixCat(value) is equivalent to the nixCats(value) command in Lua.
266 GetNixSettings() is require('nixCats').settings
267 GetNixPawsible() is require('nixCats').pawsible
268 GetNixExtra() is require('nixCats').extra
269 GetNixCats() is require('nixCats').cats
270 
271 ----------------------------------------------------------------------------------------
272 vim:tw=78:ts=8:ft=help:norl: