HOME TOC REPO

1   =================================================================================
2                                                               nixCats.luaUtils
3   ---------------------------------------------------------------------------------
4                                                         nixCats.luaUtils.intro
5   nixCats has good integration with pckr and other similar neovim package
6   managers.
7   
8   Keep in mind they may not work so well on nixos,
9   so when you are on nixOS you should load neovim via nix
10  (not sure if that part needs stating)
11  
12  to get your lua utils run
13  
14    nix flake init -t github:BirdeeHub/nixCats-nvim#luaUtils
15  
16  ALSO keep in mind, if you are not using nix, you will have to download
17  all your non-plugin, non-lsp dependencies manually, and this may suck.
18  Therefore, all this stuff about package managers may be of limited utility.
19  
20  I have written some lua utilities to enable this.
21  There is a template for them, and you can use the flake init -t
22  variable to import the luaUtils template in the root directory of your config
23  to add it to your project in the correct place.
24  
25  -------------------------------------------------------------------------------
26                                                        nixCats.luaUtils.setup
27  They are located within the lua/nixCatsUtils directory of the
28  flake. The main init.lua in it contains a require("nixCatsUtils").setup
29  function, and a require("nixCatsUtils").isNixCats variable.
30  
31  The require("nixCatsUtils").isNixCats variable is true if
32  you installed neovim via nix, and otherwise it is false.
33  This is used to enable package managers only when not loaded via nix.
34  
35  You run the setup function in your init.lua file at the start, and tell it
36  what nixCats global command should default to if isNixCats is false.
37  The default is true.
38  
39  IF YOU DO NOT DO THIS SETUP CALL:
40  the result will be that, when you load this folder without using nix,
41  the global nixCats function which you use everywhere
42  to check for categories will throw an error.
43  This setup function will give it a default value.
44  Of course, if you only ever download nvim with nix, this isnt needed.
45  But it cant hurt to include anyway.
46  
47    vim.g.mapleader = ' '
48    vim.g.maplocalleader = ' '
49    -- it doesnt matter if its before or after leader key but
50    -- you want this first thing in your init.lua file
51    require('nixCatsUtils').setup {
52      non_nix_value = true,
53    }
54  
55    if require('nixCatsUtils').isNixCats then
56      print('using nixCats')
57    end
58  
59  it also has a few other things that may prove handy
60  
61    ---@overload fun(v: any): any|nil
62    ---@overload fun(v: any, o: any): any
63    require('nixCatsUtils').lazyAdd(v, o)
64    -- if not nix, return the first thing.
65    -- If it is nix, return the second, or nil if not provided.
66    -- used for disabling things like lazy build steps on nix when needed
67  
68    ---@overload fun(v: string|string[]): boolean
69    ---@overload fun(v: string|string[], default: boolean): boolean
70    require('nixCatsUtils').enableForCategory(v, default)
71  
72    -- v will be passed to nixCats function.
73    -- If the value fetched by nixCats is nil or false,
74    -- return false, otherwise return true
75    -- if not loaded by nix, return the default value,
76    -- or fall back on the nixCats default value provided by
77    -- the require("nixCatsUtils").setup function mentioned above
78  
79    ---@param v string|string[]
80    ---@param default any
81    ---@return any
82    require('nixCatsUtils').getCatOrDefault(v, default)
83    ---if nix, return value of nixCats(v) else return default
84    ---Exists to specify a different non_nix_value than the one in setup()
85  
86    ---@type string
87    require('nixCatsUtils').packageBinPath
88    ---Useful for things such as vim-startuptime which must reference the wrapper's actual path
89    ---If not using nix, this will simply return vim.v.progpath
90  
91  ---------------------------------------------------------------------------------
92                                                         nixCats.luaUtils.lazy
93  For instructions on using the lazy wrapper, check out this template example!
94  Disclaimer, it uses a new lazy option only
95  in pkgs.lazy-nvim from the unstable branch.
96  So if you are using nixpkgs stable for your neovim you will
97  need to download a newer version of lazy-nvim.
98  
99  Use the following command in a new directory and check it out!
100 
101   nix flake init -t github:BirdeeHub/nixCats-nvim#kickstart-nvim
102 
103 In that template, all notes about the lazy wrapper are in comments that begin
104 with the string: NOTE: nixCats: so to find all of the info, search for that.
105 
106 The 3 main utilities at require('nixCatsUtils.lazyCat')
107 
108   --the main wrapper
109   ---@param pluginTable table|string[]|nil
110   ---@param nixLazyPath string|nil
111   ---@param lazySpecs any
112   ---@param lazyCFG table
113   require('nixCatsUtils.lazyCat').setup(pluginTable, nixLazyPath, lazySpecs, lazyCFG)
114   -- pluginTable is a table of plugin names, either as a list or as the names
115   -- of a table of pluginName = "a string";
116 
117 
118 pluginTable should contain the plugin names, which lazy.nvim will match
119 against the repo names of the plugins.
120 You may get this by merging the tables of plugins provided by nix.
121 
122   local plugins = require('nixCats').pawsible.allPlugins
123   local pluginTable = require('nixCatsUtils.lazyCat')
124                       .mergePluginTables(plugins.start, plugins.opt)
125 
126 NOTE: Keep in mind you may need to add a few items for plugins with different
127 repo names from their nix plugin names. When you do this, you should also
128 set the name field in that plugin's spec to the nix-provided value.
129 
130   -- for example of when the the nix name is different:
131   -- this must match the repository name
132   pluginTable[ [[Comment.nvim]] ] = ""
133   pluginTable[ [[LuaSnip]] ] = ""
134   -- this also means that in their lazySpecs,
135   -- you must set the name field of comment.nvim and luasnip
136   -- to match their nix-provided values.
137   -- this will also ensure that it works regardless of if nix or lazy downloads it.
138 
139   -- usually, the names match and you do not need to do this.
140   -- you could also override the name of the plugin in nix instead!
141 
142 You may view the list of plugin names provided by nix to make
143 this easier via :NixCats pawsible
144 
145 If you do not have the correct name for the plugin in the pluginTable argument,
146 lazy.nvim will attempt to download the plugin normally. This will often work anyway.
147 
148 nixLazyPath is the path to lazy.nvim downloaded via nix. You may get it
149 via the same table you got the other plugin names from.
150 
151 lazy.nvim disables all normal plugin loading, so if you want to load a plugin
152 via nix, you must also fill out a spec for it.
153 
154 If you plan on loading a plugin via nix, and it has a build step,
155 you may conditionally disable it via nixCatsUtils.lazyAdd function,
156 thus ensuring it does not run if nix downloads it,
157 but still runs if you did not load your config via nix.
158 
159 The other 2 functions, which are useful for creating
160 the table of plugin names for the setup function above:
161 
162   -- to help you merge the start and opt lists in require('nixCats').included
163   require('nixCatsUtils.lazyCat').mergePluginTables(table1, table2)
164   -- its available if you want it, but it is used in the wrapper on pluginTable
165   require('nixCatsUtils.lazyCat').getTableNamesOrListValues(pluginTable)
166 
167 The tutorial:
168 
169     kickstart-nvim = {
170       path = ./kickstart-nvim;
171       description = ''
172         The entirety of kickstart.nvim implemented as a nixCats flake.
173         With additional nix lsps for editing the nix part.
174         This is to serve as the tutorial for using the nixCats lazy wrapper.
175       '';
176     };
177 
178 In that template, all notes about the lazy wrapper are in comments that begin
179 with the string: NOTE: nixCats: so to find all of the info, search for that.
180 
181 One other note.
182 
183 If you install your grammars via lazy.nvim rather than nix,
184 you will need to add a c compiler to your lspsAndRuntimeDeps section
185 in your categoryDefinitions
186 
187 If you install your grammars via nix rather than lazy.nvim,
188 the only methods supported via the lazy.nvim wrapper are the following.
189 
190   pkgs.vimPlugins.nvim-treesitter.withAllGrammars
191   # or
192   pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: with plugins; [
193     nix
194     lua
195     # etc...
196   ]);
197   # or
198   pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: pkgs.vimPlugins.nvim-treesitter.allGrammars)
199   # or
200   builtins.attrValues pkgs.vimPlugins.nvim-treesitter.grammarPlugins
201   # or
202   pkgs.neovimUtils.grammarToPlugin pkgs.tree-sitter-grammars.somegrammar
203 
204 Summary: as long as pkgs.neovimUtils.grammarToPlugin is called on it somehow, it will work.
205 
206 Any other ways will still work in nixCats, but not necessarily when using the lazy wrapper,
207 because the lazy wrapper has to add them back to the runtimepath.
208 
209 ---------------------------------------------------------------------------------
210                                                        nixCats.luaUtils.paq-nvim
211 load the plugins via paq-nvim when not on nix
212 YOU are in charge of putting the plugin
213 urls and build steps in there, which will only be used when not on nix,
214 and you should keep any setup functions
215 OUT of that file, as they are ONLY loaded when this
216 configuration is NOT loaded via nix.
217 
218 The way to think of this is, its very
219 similar to the main nix file for nixCats
220 
221 It can be used to download your plugins,
222 and it has an opt for optional plugins.
223 
224 we will do all our loading and configuring
225 elsewhere in our configuration, so that
226 we dont have to write it twice.
227 
228 All the rest of the setup will be done using the normal setup functions later,
229 thus working regardless of what method loads the plugins.
230 only stuff pertaining to downloading and building should be added to paq.
231 
232   require('nixCatsUtils.catPacker').setup({
233     { "BirdeeHub/lze", },
234     { "stevearc/oil.nvim", },
235     { 'joshdick/onedark.vim', },
236     { 'nvim-tree/nvim-web-devicons', },
237     { 'nvim-lua/plenary.nvim', },
238     { 'tpope/vim-repeat', },
239 
240     { 'nvim-treesitter/nvim-treesitter-textobjects', opt = true, },
241     { 'nvim-treesitter/nvim-treesitter', build = ':TSUpdate', opt = true, },
242 
243     { 'nvim-telescope/telescope-fzf-native.nvim', build = ':!which make && make', opt = true, },
244     { 'nvim-telescope/telescope-ui-select.nvim', opt = true, },
245     {'nvim-telescope/telescope.nvim', opt = true, },
246 
247     -- lsp
248     { 'williamboman/mason.nvim', opt = true, },
249     { 'williamboman/mason-lspconfig.nvim', opt = true, },
250     { 'j-hui/fidget.nvim', opt = true, },
251     { 'neovim/nvim-lspconfig', opt = true, },
252 
253     --  NOTE:  we take care of lazy loading elsewhere in an autocommand
254       -- so that we can use the same code on and off nix.
255       -- so here we just tell it not to auto load it
256     { 'folke/lazydev.nvim', opt = true, },
257 
258     -- completion
259     { 'onsails/lspkind.nvim', opt = true, },
260 
261     -- NOTE: when lazy loading, you might need to make the name
262     -- match the name from nix, so that you can call
263     -- packadd with the same name both on and off nix.
264     { 'L3MON4D3/LuaSnip', opt = true, as = "luasnip", },
265 
266     { 'saadparwaiz1/cmp_luasnip', opt = true, },
267     { 'hrsh7th/cmp-nvim-lsp', opt = true, },
268     { 'hrsh7th/cmp-nvim-lua', opt = true, },
269     { 'hrsh7th/cmp-nvim-lsp-signature-help', opt = true, },
270     { 'hrsh7th/cmp-path', opt = true, },
271     { 'rafamadriz/friendly-snippets', opt = true, },
272     { 'hrsh7th/cmp-buffer', opt = true, },
273     { 'hrsh7th/cmp-cmdline', opt = true, },
274     { 'dmitmel/cmp-cmdline-history', opt = true, },
275     { 'hrsh7th/nvim-cmp', opt = true, },
276 
277     -- lint and format
278     { 'mfussenegger/nvim-lint', opt = true, },
279     { 'stevearc/conform.nvim', opt = true, },
280 
281     -- dap
282     { 'nvim-neotest/nvim-nio', opt = true, },
283     { 'rcarriga/nvim-dap-ui', opt = true, },
284     { 'theHamsta/nvim-dap-virtual-text', opt = true, },
285     { 'jay-babu/mason-nvim-dap.nvim', opt = true, },
286     { 'mfussenegger/nvim-dap', opt = true, },
287 
288     -- { 'm-demare/hlargs.nvim', },
289     { 'mbbill/undotree', opt = true, },
290     { 'tpope/vim-fugitive', opt = true, },
291     { 'tpope/vim-rhubarb', opt = true, },
292     { 'tpope/vim-sleuth', opt = true, },
293     { 'folke/which-key.nvim', opt = true, },
294     { 'lewis6991/gitsigns.nvim', opt = true, },
295     { 'nvim-lualine/lualine.nvim', opt = true, },
296     { 'lukas-reineke/indent-blankline.nvim', opt = true, },
297     { 'numToStr/Comment.nvim', opt = true, as = "comment.nvim", },
298     { 'kylechui/nvim-surround', opt = true, },
299     {
300       "iamcco/markdown-preview.nvim",
301       build = ":call mkdp#util#install()",
302       opt = true,
303     },
304 
305 
306   })
307 
308   OK, again, none of the stuff in this file is needed
309   if you only load this setup via nix, but it is an option.
310 =================================================================================
311 vim:tw=78:ts=8:ft=help:norl: