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  
35  nixCats command will return the nearest parent category value, unless the nearest
36  parent is a table, in which case that means a different subcategory
37  was enabled but this one was not.
38  In that case it will try to find the next value, fail, and return nil.
39  If the item you are checking is a table,
40  if nixCats('the.table') then print("true") end
41  will print true, and nixCats('the.table') will return the table.
42  
43  The nixCats global function is an alias for require('nixCats').get()
44  
45  The nixCats "plugin" is just some tables and a get function.
46  It is generated by the flake, and the table is
47  the same one you provided to choose what
48  categories are included in each package in the flake.nix file.
49  
50  However it also adds a few values for convenience.
51    nixCats_packageName
52    nixCats_config_location
53    nixCats_wrapRc
54  
55  Because it adds these to nixCats, do not use them as
56  a category name in your package definition (example package definition below).
57  They will be replaced.
58  
59  If in your flake, your package definition looked like this:
60    see :help nixCats.flake.outputs.packageDefinitions
61  
62  
63    packageDefinitions = {
64      nixCats = { pkgs, ... }@misc: {
65        settings = settings.nixCats; 
66        categories = {
67          generalBuildInputs = true;
68          markdown = true;
69          general.vimPlugins = true;
70          general.gitPlugins = true;
71          custom = true;
72          neonixdev = true;
73          test = {
74            subtest1 = true;
75          };
76          debug = false;
77          # this does not have an associated category of plugins, 
78          # but lua can still check for it
79          lspDebugMode = false;
80          # by default, we dont want lazy.nvim
81          # we could omit this for the same effect
82          lazy = false;
83          # you could also pass something else:
84          themer = true;
85          colorscheme = "onedark";
86          theBestCat = "says meow!!";
87          theWorstCat = {
88            thing'1 = [ "MEOW" "HISSS" ];
89            thing2 = [
90              {
91                thing3 = [ "give" "treat" ];
92              }
93              "I LOVE KEYBOARDS"
94            ];
95            thing4 = "couch is for scratching";
96          };
97          # see :help nixCats
98        };
99      };
100   };
101 
102 
103 Using:
104 
105     :lua print(vim.inspect(require('nixCats').cats))
106     or
107     :NixCats
108     or
109     :NixCats cats
110 
111 will return something like this:
112 
113   {
114     colorscheme = "onedark",
115     custom = true,
116     debug = false,
117     general = {
118       gitPlugins = true,
119       vimPlugins = true
120     },
121     generalBuildInputs = true,
122     lazy = false,
123     lspDebugMode = false,
124     markdown = true,
125     neonixdev = true,
126     nixCats_packageName = "nixCats",
127     nixCats_config_location = "/nix/store/fazkaci8bravyly4xahs0b69r1xxj4i3-nixCats-special-rtp-entry-LuaConfig",
128     nixCats_wrapRc = true,
129     test = {
130       subtest1 = true
131     },
132     theBestCat = "says meow!!",
133     theWorstCat = {
134       ["thing'1"] = { "MEOW", "HISSS" },
135       thing2 = { {
136           thing3 = { "give", "treat" }
137         }, "I LOVE KEYBOARDS" },
138       thing4 = "couch is for scratching"
139     },
140     themer = true
141   }
142 
143 Note: it also accepts other things.
144 lists will become arrays
145 sets will become tables
146 null will become nil
147 derivations will become store paths
148 
149 everything that isnt 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 require('nixCats').cats, nixCats also contains other info.
184 
185 
186   require('nixCats').pawsible
187     -- contains a final list of all the plugins included
188     -- in the package and their paths, and the path to treesitter parsers.
189     -- does not include lsps and runtime dependencies,
190     -- you can retrieve their paths with vim.fn.exepath if needed.
191 
192   require('nixCats').settings
193     -- contains the settings set for the package
194 
195 
196 you can view these for debugging purposes with :NixCats settings and
197 :NixCats pawsible user commands.
198 
199 You may also use the following to debug. Using
200 :NixCats cat path.to.value or :NixCats cat path to value
201 will print the value of nixCats('path.to.value') for debugging purposes.
202 
203 In addition to the user commands, you may access these items directly within
204 vimscript!
205 
206 GetNixCat(value) is equivalent to the nixCats(value) command in
207 lua.
208 
209 GetNixSettings() is require('nixCats').settings
210 
211 GetNixPawsible() is require('nixCats').pawsible
212 
213 GetAllNixCats() is require('nixCats').cats
214 
215 ----------------------------------------------------------------------------------------
216 vim:tw=78:ts=8:ft=help:norl: