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 
104   --the main wrapper
105   ---@overload fun(nixLazyPath: string|nil, lazySpec: any, opts: table)
106   ---@overload fun(nixLazyPath: string|nil, opts: table)
107   require('nixCatsUtils.lazyCat').setup(nixCats.pawsible({"allPlugins", "start", "lazy.nvim" }), lazySpec, opts)
108   -- as long as you call the require('nixCatsUtils').setup function first,
109   -- nixCats.pawsible will not throw an error even
110   -- if no nix was used to load your config
111   -- this is covered in the mentioned template
112 
113 The tutorial:
114 
115     kickstart-nvim = {
116       path = ./kickstart-nvim;
117       description = ''
118         The entirety of kickstart.nvim implemented as a nixCats flake.
119         With additional nix lsps for editing the nix part.
120         This is to serve as the tutorial for using the nixCats lazy wrapper.
121       '';
122     };
123 
124 In that template, all notes about the lazy wrapper are in comments that begin
125 with the string: NOTE: nixCats: so to find all of the info, search for that.
126 
127 One other note.
128 
129 If you install your grammars via lazy.nvim rather than nix,
130 you will need to add a c compiler to your lspsAndRuntimeDeps section
131 in your categoryDefinitions
132 
133 If you install your grammars via nix rather than lazy.nvim,
134 the only methods supported via the lazy.nvim wrapper are the following.
135 
136   pkgs.vimPlugins.nvim-treesitter.withAllGrammars
137   # or
138   pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: with plugins; [
139     nix
140     lua
141     # etc...
142   ]);
143   # or
144   pkgs.vimPlugins.nvim-treesitter.withPlugins (plugins: pkgs.vimPlugins.nvim-treesitter.allGrammars)
145   # or
146   builtins.attrValues pkgs.vimPlugins.nvim-treesitter.grammarPlugins
147   # or
148   pkgs.neovimUtils.grammarToPlugin pkgs.tree-sitter-grammars.somegrammar
149 
150 Summary: as long as pkgs.neovimUtils.grammarToPlugin is called on it somehow, it will work.
151 
152 Any other ways will still work in nixCats if they would work in other schemes,
153 but not necessarily when using the lazy wrapper,
154 because the lazy wrapper has to be given their paths from nix,
155 and thus need to be sorted from other plugins somehow.
156 
157 ---------------------------------------------------------------------------------
158                                                        nixCats.luaUtils.paq-nvim
159 load the plugins via paq-nvim when not on nix
160 YOU are in charge of putting the plugin
161 urls and build steps in there, which will only be used when not on nix,
162 and you should keep any setup functions
163 OUT of that file, as they are ONLY loaded when this
164 configuration is NOT loaded via nix.
165 
166 The way to think of this is, its very
167 similar to the main nix file for nixCats
168 
169 It can be used to download your plugins,
170 and it has an opt for optional plugins.
171 
172 we will do all our loading and configuring
173 elsewhere in our configuration, so that
174 we dont have to write it twice.
175 
176 All the rest of the setup will be done using the normal setup functions later,
177 thus working regardless of what method loads the plugins.
178 only stuff pertaining to downloading and building should be added to paq.
179 
180   require('nixCatsUtils.catPacker').setup({
181     { "BirdeeHub/lze", },
182     { "stevearc/oil.nvim", },
183     { 'joshdick/onedark.vim', },
184     { 'nvim-tree/nvim-web-devicons', },
185     { 'nvim-lua/plenary.nvim', },
186     { 'tpope/vim-repeat', },
187 
188     { 'nvim-treesitter/nvim-treesitter-textobjects', opt = true, },
189     { 'nvim-treesitter/nvim-treesitter', build = ':TSUpdate', opt = true, },
190 
191     { 'nvim-telescope/telescope-fzf-native.nvim', build = ':!which make && make', opt = true, },
192     { 'nvim-telescope/telescope-ui-select.nvim', opt = true, },
193     {'nvim-telescope/telescope.nvim', opt = true, },
194 
195     -- lsp
196     { 'williamboman/mason.nvim', opt = true, },
197     { 'williamboman/mason-lspconfig.nvim', opt = true, },
198     { 'j-hui/fidget.nvim', opt = true, },
199     { 'neovim/nvim-lspconfig', opt = true, },
200 
201     --  NOTE:  we take care of lazy loading elsewhere in an autocommand
202       -- so that we can use the same code on and off nix.
203       -- so here we just tell it not to auto load it
204     { 'folke/lazydev.nvim', opt = true, },
205 
206     -- completion
207     { 'onsails/lspkind.nvim', opt = true, },
208 
209     -- NOTE: when lazy loading, you might need to make the name
210     -- match the name from nix, so that you can call
211     -- packadd with the same name both on and off nix.
212     { 'L3MON4D3/LuaSnip', opt = true, as = "luasnip", },
213 
214     { 'saadparwaiz1/cmp_luasnip', opt = true, },
215     { 'hrsh7th/cmp-nvim-lsp', opt = true, },
216     { 'hrsh7th/cmp-nvim-lua', opt = true, },
217     { 'hrsh7th/cmp-nvim-lsp-signature-help', opt = true, },
218     { 'hrsh7th/cmp-path', opt = true, },
219     { 'rafamadriz/friendly-snippets', opt = true, },
220     { 'hrsh7th/cmp-buffer', opt = true, },
221     { 'hrsh7th/cmp-cmdline', opt = true, },
222     { 'dmitmel/cmp-cmdline-history', opt = true, },
223     { 'hrsh7th/nvim-cmp', opt = true, },
224 
225     -- lint and format
226     { 'mfussenegger/nvim-lint', opt = true, },
227     { 'stevearc/conform.nvim', opt = true, },
228 
229     -- dap
230     { 'nvim-neotest/nvim-nio', opt = true, },
231     { 'rcarriga/nvim-dap-ui', opt = true, },
232     { 'theHamsta/nvim-dap-virtual-text', opt = true, },
233     { 'jay-babu/mason-nvim-dap.nvim', opt = true, },
234     { 'mfussenegger/nvim-dap', opt = true, },
235 
236     -- { 'm-demare/hlargs.nvim', },
237     { 'mbbill/undotree', opt = true, },
238     { 'tpope/vim-fugitive', opt = true, },
239     { 'tpope/vim-rhubarb', opt = true, },
240     { 'tpope/vim-sleuth', opt = true, },
241     { 'folke/which-key.nvim', opt = true, },
242     { 'lewis6991/gitsigns.nvim', opt = true, },
243     { 'nvim-lualine/lualine.nvim', opt = true, },
244     { 'lukas-reineke/indent-blankline.nvim', opt = true, },
245     { 'numToStr/Comment.nvim', opt = true, as = "comment.nvim", },
246     { 'kylechui/nvim-surround', opt = true, },
247     {
248       "iamcco/markdown-preview.nvim",
249       build = ":call mkdp#util#install()",
250       opt = true,
251     },
252 
253 
254   })
255 
256   OK, again, none of the stuff in this file is needed
257   if you only load this setup via nix, but it is an option.
258 =================================================================================
259 vim:tw=78:ts=8:ft=help:norl: