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   nixCats.pawsible
186     -- contains a final set of all the plugins included
187     -- in the package and their paths, and the path to treesitter parsers.
188     -- does not include LSPs and runtime dependencies,
189     -- you can retrieve their paths with vim.fn.exepath if needed.
190 
191   nixCats.settings
192     -- contains the settings set for the package
193 
194 You can view these for debugging purposes with :NixCats settings and
195 :NixCats pawsible user commands.
196 
197 You may also use the following to debug. Using
198 :NixCats cat path.to.value or :NixCats cat path to value
199 will print the value of nixCats('path.to.value') for debugging purposes.
200 
201 In addition to the user commands, you may access these items directly within
202 vimscript!
203 
204 GetNixCat(value) is equivalent to the nixCats(value) command in Lua.
205 
206 GetNixSettings() is require('nixCats').settings
207 
208 GetNixPawsible() is require('nixCats').pawsible
209 
210 GetAllNixCats() is require('nixCats').cats
211 
212 All of the following may be accessed by require('nixCats').<item>,
213 or :NixCats <item>, except the :NixCats user command also
214 has the cat subcommand to preview the value from nixCats("catname"),
215 
216   ---@class nixCats.main
217   ---See :h nixCats.flake.outputs.packageDefinitions
218   ---Function form will return vim.tbl_get for the attrpath
219   ---@field cats table|fun(attrpath: string|string[]): any
220   ---See :h nixCats.flake.outputs.settings
221   ---Function form will return vim.tbl_get for the attrpath
222   ---@field settings table|fun(attrpath: string|string[]): any
223   ---See :h nixCats.flake.outputs.packageDefinitions
224   ---Function form will return vim.tbl_get for the attrpath
225   ---@field extra table|fun(attrpath: string|string[]): any
226   ---Contains the final set of plugins added for this package
227   ---Function form will return vim.tbl_get for the attrpath
228   ---@field pawsible table|fun(attrpath: string|string[]): any
229   ---Contains all the defined categories that you COULD enable from nix
230   ---Function form will return vim.tbl_get for the attrpath
231   ---@field petShop table|fun(attrpath: string|string[]): any
232   ---@field nixCatsPath string
233   ---@field vimPackDir string
234   ---@field configDir string
235   ---@field packageBinPath string
236   ---internal: this creates the nixCats global commands
237   ---@field addGlobals fun() 
238   ---:h nixCats
239   ---This function will return the nearest parent category value, unless the nearest
240   ---parent is a table, in which case that means a different subcategory
241   ---was enabled but this one was not. In that case it returns nil.
242   ---@field get fun(category: string|string[]): any
243 
244   ---:h nixCats
245   ---This function will return the nearest parent category value, unless the nearest
246   ---parent is a table, in which case that means a different subcategory
247   ---was enabled but this one was not. In that case it returns nil.
248   ---@alias nixCats nixCats.main | fun(category: string|string[]): any
249 
250 ----------------------------------------------------------------------------------------
251 vim:tw=78:ts=8:ft=help:norl: