1 =======================================================================================
2 Flake Help nixCats.flake
3
4 A Lua-natic's Neovim flake, with extra cats! nixCats!
5
6 This is the documentation for the flake itself.
7 This flake uses Nix for importing plugins, LSPs, dependencies, and more,
8 in place of usual nvim package managers such as packer, lazy or Mason.
9
10 Everything else is done in a regular Lua config style.
11 Download in flake.nix and then, simply pretend the root of the flake
12 is the root of your Lua config.
13
14 *******************************************************
15 AN IMPORTANT NOTE:
16
17 <1> When editing the files within the flake directory,
18 Nix will not package a new file if it isn't staged in git.
19 run git add before rebuilding it whenever adding a new file.
20 Using wrapRc = true would mean this also applies to Lua files.
21 Only tracked files will recieve their updates when
22 rebuilt without git add being ran first. New files need to be added.
23 *******************************************************
24
25 Related:
26 For detecting what was included by
27 the flake in your Lua, see:
28 :help nixCats
29
30 stdpath('config') will still point to ~/.config/<configDirName>.
31 But your Lua config will be in the store.
32 This is okay, because most of the reason for a plugin to use
33 it would be to write to it, and we cant write to store paths anyway.
34 You could use require('nixCats').configDir,
35 or nixCats('nixCats_config_location')
36 to get current config directory for your uses, if ever necessary.
37 It will be present and correct regardless of settings.
38
39 However if you did not use Nix at all and did not run the setup
40 function, of course the nixCats plugin wont be there to ask.
41
42 The setup function from require('nixCatsUtils').setup
43 will provide a mock nixCats plugin with SOME values
44 and empty tables to prevent accidental indexing errors.
45 You could instead do require('nixCatsUtils').isNixCats to default to
46 vim.fn.stdpath('config') if all you wanted was this path though.
47
48 Keep in mind they will be read-only if in the store!
49
50 =======================================================================================
51 Flake Inputs: nixCats.flake.inputs
52
53 If a plugin does not have an extra build step, and are not on nixpkgs,
54 you may use this format to import them, replacing the fields marked with <>
55
56 "plugins-<pluginName>" = {
57 url = "github:<userName>/<repositoryName>";
58 flake = false;
59 };
60
61 More info on flake url syntax at:
62 https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#examples
63 You may also use this syntax to pin the version of a plugin regardless of whether
64 you ran nix flake update or not.
65 You may choose the directory, branch, commit, tag, or even directory
66 imported.
67
68 All inputs named in the plugins-<pluginName> format will be added to pkgs
69 at pkgs.neovimPlugins.<pluginName> for you to add to your configuration.
70
71 If the plugin has a dot . character in it's name, you should name it something else
72 because . is not a valid character in an identifier in Nix.
73
74 The name here only affects the filename of the overall plugin, and should
75 only affect things like vim.cmd("packadd <filename>") that refer to
76 the actual filename of the plugin. Usually I would replace it with -
77 You will then add it to categoryDefinitions later with the NEW name.
78
79 If you use this method to import a plugin, and really dont
80 want to change the filename of the plugin when they have a
81 dot in their name, you may
82 swap the call to (utils.standardPluginOverlay inputs)
83 with (utils.sanitizedPluginOverlay inputs)
84 and then plugins-plugin.name would become pkgs.neovimPlugins.plugin-name
85 but Neovim would see it as vim.cmd("packadd plugin.name") still
86
87 If they have a build step or are not a plugin,
88 i.e. an LSP, or if they are a plugin from a flake,
89 dont name them in that format.
90 If they are a plugin from a flake, they can be added directly,
91 or they may be added as an overlay if offered.
92 If they are anything else they arent a plugin at all and obviously
93 should not be added as a plugin via plugins-<pluginName>
94
95 If they are on nixpkgs, you dont need to put them in inputs,
96 because you will be able to access them through pkgs.vimPlugins variable.
97 Most plugins will not require you to use the inputs section due to being on nixpkgs.
98 But you may still use it to pin the plugin to a specific version.
99
100 If you decided not to use utils.sanitizedPluginOverlay
101 and wanted to do it with utils.standardPluginOverlay:
102 If in your inputs you had:
103
104 "plugins-<plugin-name>" = {
105 url = "github:<userName>/<repository.name>";
106 flake = false;
107 };
108
109 Where you put plugins in your categoryDefinitions, instead of:
110
111 pkgs.neovimPlugins.<plugin-name>
112
113 You could put this:
114
115 { name = "<plugin.name>"; plugin = pkgs.neovimPlugins.<plugin-name>; }
116
117 You can also override them instead of (or before/during) the above:
118
119 (pkgs.neovimPlugins.<plugin-name>.overrideAttrs { pname = "<plugin.name>"; })
120
121 overrideAttrs can be used for a lot more than just fixing the name of the
122 imported plugin. See:
123 https://ryantm.github.io/nixpkgs/using/overrides/
124
125 If they have a build step and are not on nixpkgs,
126 you will deal with them in overlays/customBuildsOverlay.nix
127 then import them into a category of the builder.
128 Alternatively you may use overrideAttrs as mentioned above instead of an
129 overlay for these sorts of packages, but this would possibly get messy if the
130 build step were complex.
131
132 =======================================================================================
133 Flake Outputs Introduction nixCats.flake.outputs
134
135 With our inputs to our flake taken care of:
136 First, we take care of importing our utils set from nixCats.
137 The reason we are doing this now, is so that it can be defined outside of
138 the utils.eachSystem function, and thus we can export it
139 without having to include a system variable when we import it somewhere else.
140
141 We also define our luaPath, which is the path to be loaded into the store as
142 your new Neovim config directory. (see :help 'rtp' for the directories
143 available for you to use!)
144
145 We also define our extra_pkg_config, which is used when initializing the
146 nixpkgs instance that will build your Neovim! It's the same one from
147
148 pkgs = import nixpkgs { inherit system; overlays = []; config = {}; }
149
150 That is,
151
152 outputs = { self, nixpkgs, ... }@inputs: let
153
154 inherit (inputs.nixCats) utils;
155
156 luaPath = "${./.}";
157
158 extra_pkg_config = {
159
160 };
161
162 nixCats.flake.outputs.getOverlays
163
164 Managing the system variable in combination with overlays
165 can be one of the hardest parts of flake usage.
166 This flake resolves our pkgs instance for Neovim itself to help with this,
167 and takes care of passing the correct pkgs instance
168 to the relevant locations later for use in defining your dependencies.
169
170
171 dependencyOverlays = (import ./overlays inputs) ++ [
172 (utils.standardPluginOverlay inputs)
173 inputs.neorg-overlay.overlays.default
174 inputs.lz-n.overlays.default
175
176
177
178
179
180
181
182
183
184
185 (utils.fixSystemizedOverlay inputs.codeium.overlays
186 (system: inputs.codeium.overlays.${system}.default)
187 )
188 ];
189
190
191 nixCats.flake.outputs.overlays
192 utils.standardPluginOverlay
193 Usage of this function to create an overlay is described in:
194 :h nixCats.flake.inputs
195 along with its friend, utils.sanitizedPluginOverlay
196
197 It takes all the inputs named in the format
198 plugins-somepluginname and makes them into plugins.
199 Access them to add them to a category of the builder function
200 with pkgs.neovimPlugins.somepluginname
201
202 If the plugin doesn't have a build step,
203 and it wasnt on nixpkgs, then use this method.
204
205 If the plugin does have a build step and isn't on nixpkgs,
206 then you can either make your own overlay from scratch,
207 or you can call overrideAttrs on the generated plugin
208 to add the required items to it.
209 more info at :h nixCats.flake.inputs
210
211 If you decide you wish to split your customBuildsOverlay up,
212 see :help nixCats.flake.nixperts.overlays
213 or look at the overlays/default.nix file for advice on how to do that.
214
215 ---------------------------------------------------------------------------------------
216 nixCats.flake.outputs.categories
217 Then we define what is in our categories!
218 This section is a function that takes the package definition for this
219 particular package as an argument.
220 The builder will call it with that argument, you may use it.
221 This allows categoryDefinitions to access their packages categories and settings,
222 which allows categoryDefinitions to be much more dynamic.
223
224 It also gets mkNvimPlugin = src: name: as an argument. mkNvimPlugin takes a src, either flake input
225 or fetched drv, and then a name, and it returns a nvim plugin that can be further
226 overriden via overrideAttrs if desired.
227 There is an overlay to do this automatically from flake inputs, mentioned
228 above. But sometimes it can be advantageous to do one of them individually.
229
230 These are the things you can return:
231
232 categoryDefinitions = { pkgs, settings, categories, extra, name, mkNvimPlugin, ... }@packageDef: {
233
234 <lspsAndRuntimeDeps>
235 a flexible set of categories, each containing LSPs or
236 other internal runtime dependencies such as ctags or debuggers
237 these are available to the PATH while within the Neovim program.
238 this includes the Neovim terminal.
239
240 <startupPlugins>
241 a flexible set of categories, each containing startup plugins.
242 Startup plugins are loaded and can be required.
243
244 <optionalPlugins>
245 a flexible set of categories, each containing optional plugins.
246 Optional plugins need to be added with packadd before being required.
247 Use :NixCats pawsible to see the names to use for packadd
248
249 <sharedLibraries>
250 a flexible set of categories, each containing a derivation for
251 a runtime shared library. Will be prepended to the LD_LIBRARY_PATH variable.
252
253 <environmentVariables>
254 a flexible set of categories, each containing an ATTRIBUTE SET of
255 EnvironmentVariableName = "EnvironmentVariableValue";
256
257 <extraWrapperArgs>
258 a flexible set of categories, each containing extra wrapper arguments.
259 If you don't know what that is, see here:
260 github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/setup-hooks/make-wrapper.sh
261
262 <extraLuaPackages>
263 a flexible set of categories, each containing FUNCTIONS
264 that return lists of extra Lua packages.
265 These functions are the same thing that you would pass to lua.withPackages.
266 Is used to populate $LUA_PATH and $LUA_CPATH
267
268 <extraPython3Packages>
269 a flexible set of categories, each containing FUNCTIONS
270 that return lists of Python packages.
271 These functions are the same thing that you would pass to python.withPackages.
272 You may get the path to this Python environment in your Lua config via
273 vim.g.python3_host_prog
274 or run from nvim terminal via :!<packagename>-python3
275
276 <extraPython3wrapperArgs>
277 the same as extraWrapperArgs but for bundled python3 executable
278
279 <propagatedBuildInputs>
280 a flexible set of categories, each containing internal BUILD dependencies.
281 Will not be available to the PATH unless in a devShell.
282 USING THIS OPTION WILL CAUSE NVIM TO BUILD FROM SOURCE.
283
284 <optionalLuaPreInit>
285 a flexible set of categories, each containing a Lua string
286 that will be ran before sourcing your init.lua
287 Yes it can access nixCats.
288 It is not the recommended way to create Lua for this flake,
289 but it may be useful in editing flake imports
290 of other already configured setups following the nixCats format.
291 <optionalLuaAdditions>
292 a flexible set of categories, each containing a Lua string
293 that will be ran after sourcing your init.lua
294 Yes it can access nixCats.
295 It is not the recommended way to create Lua for this flake,
296 but it may be useful in editing flake imports
297 of other already configured setups following the nixCats format.
298 <bashBeforeWrapper>
299 a flexible set of categories, each containing arbitrary Bash code
300 to run before the wrapper starts within the wrapper's Bash environment.
301 CAUTION: only use this if you know what you are doing and why you need
302 to do it. Whenever possible, use extraWrapperArgs instead.
303 <extraCats>
304 a flexible set of categories, each containing a list of attribute paths,
305 specified as lists of strings. Thus each category would contain a list of
306 lists of strings.
307 Allows inclusion of extra categories contingent on each lists inclusion in the package,
308 and is useful for creating default values for subcategories.
309 For more info, see below at
310 :h nixCats.flake.outputs.categoryDefinitions.default_values
311 # WARNING: use of categories argument in this set will cause infinite recursion
312 # The categories argument of this function is the FINAL value.
313 # You may use it in any of the other sets.
314 }
315
316 In essence, the contents of each set listed here are filtered
317 based on the packageDefinitions set you provide,
318 whereby including categoryname = true; you enable that category.
319 :help nixCats.flake.outputs.packageDefinitions
320
321 It will remove duplicate items, so feel free to include the same thing in
322 multiple categories if it suits your purposes.
323
324 It does this recursively. (explained below)
325
326 If, inside one of these main sets, you had another set,
327 it would consider that a subcategory, and you could enable it
328 just like you do with a normal category, by setting a value with the
329 corresponding attribute path to true in the category
330 set of nixCats.flake.outputs.packageDefinitions.
331 You can nest them as much as you like, or just have a category that is a
332 single derivation.
333
334 nixCats.flake.outputs.categoryDefinitions.schemas
335
336 You may also use the variables passed to your categoryDefinitions function
337 to get access to the set of categories and settings that are being
338 used to define the current package being built!
339
340 themer = with pkgs.vimPlugins;
341 (builtins.getAttr packageDef.categories.colorscheme {
342
343 "onedark" = onedark-vim;
344 "catppuccin" = catppuccin-nvim;
345 }
346 );
347
348 In addition to all this, if a plugin is defined within a list, it may
349 instead be defined within an attribute set that also contains config
350 to be ran after sourcing init.lua and optionalLuaAdditions
351 to do this, you may use the following syntax in opt or start sections:
352 [
353
354 { plugin = derivation; config.lua = ""; config.vim = "";}
355 { plugin = derivation; config = ""; type = "<viml or lua>"; }
356 { plugin = derivation; config = ""; }
357 { plugin = derivation; }
358
359
360
361
362
363
364
365
366
367
368
369
370 derivation
371
372
373
374 ]
375
376 nixCats.flake.outputs.categoryDefinitions.default_values
377
378 There are 2 ways of creating default values in nixCats.
379
380 #1 Implicit: when value is in another section of categoryDefinitions
381
382 If in your categoryDefinitions you had the following:
383
384 environmentVariables = {
385 test = {
386 subtest1 = {
387 CATTESTVAR = "It worked!";
388 };
389 subtest2 = {
390 CATTESTVAR3 = "It didn't work!";
391 };
392 };
393 };
394 extraWrapperArgs = {
395 test = [
396 '' --set CATTESTVAR2 "It worked again!"''
397 ];
398 };
399
400 And in your packageDefinitions set, under categories, you had the following:
401
402 test = {
403 subtest1 = true;
404 };
405
406 you could echo $CATTESTVAR and $CATTESTVAR2 in your terminal to see them.
407 However you could not echo $CATTESTVAR3.
408
409 All items that are not attributes of the parent set will be included
410 when you enable a subcategory. This includes lists, strings, functions, etc...
411
412 However, attributes will not and you must explicitly enable all attributes of
413 a subcategory if you set even 1 explicitly.
414
415 Thus to include CATTESTVAR3, you would have to enable it like so:
416 test = {
417 subtest1 = true;
418 subtest2 = true;
419 };
420 However, those are all the items in the test category.
421 So instead we can do this to enable all the subcategories in test.
422 test = true;
423
424 This applies in many situations. Take this one for example.
425
426 lspsAndRuntimeDeps = {
427 neonixdev = {
428 inherit (pkgs)
429 nix-doc nil lua-language-server nixd;
430 };
431 };
432 startupPlugins = {
433 neonixdev = with pkgs.vimPlugins; [
434 neodev-nvim
435 neoconf-nvim
436 ];
437 };
438
439 If you were to put the following in your packageDefinitions:
440 neonixdev.nix-doc = true;
441
442 neodev-nvim and neoconf-nvim would still be included.
443 However, nil, lua-language-server, and nixd would not be!
444 You would need to pick which of those you wanted separately.
445 Sometimes this is the desired behavior.
446 Sometimes it is not and a list of packages would be better suited.
447
448 This leads us to our second way to make a default value:
449
450 #2 Explicit: using extraCats section of categoryDefinitions.
451
452 The extraCats section of categoryDefinitions contains categories of attribute
453 paths. If that category is defined, the categories specified by the attribute
454 paths will also be enabled. This means you could make it so that if you
455 included the go category, it could then enable debug.go and lsp.go for you.
456 But in addition to that, it can be combined with the implicit form of creating
457 default values above in an interesting way.
458
459 categoryDefinitions = { pkgs, settings, categories, extra, name, ... }@packageDef: {
460 lspsAndRuntimeDeps = {
461 debug = with pkgs; {
462 go = [ delve ];
463 };
464 go = with pkgs; [
465 gopls
466 gotools
467 go-tools
468 gccgo
469 ];
470 };
471 startupPlugins = {
472 debug = with pkgs.vimPlugins; {
473 default = [
474 nvim-dap
475 nvim-dap-ui
476 nvim-dap-virtual-text
477 ];
478 go = [ nvim-dap-go ];
479 };
480 };
481
482
483
484 extraCats = {
485
486
487
488
489 debug = [
490 [ "debug" "default" ]
491 ];
492
493
494 go = [
495 [ "debug" "go" ]
496 ];
497 };
498 };
499
500 If you wish to only enable a value via extraCats if multiple other categories
501 are enabled, the categories in extraCats also accept a set form!
502
503 extraCats = {
504
505 target.cat = [
506
507 [ "to" "enable" ]
508
509 {
510 cat = [ "other" "toenable" ];
511
512
513
514 when = [
515 [ "another" "cat" ]
516 ];
517
518 cond = [
519 [ "other" "category" ]
520 ];
521 }
522 ];
523 };
524
525 ---------------------------------------------------------------------------------------
526 Package Generation: nixCats.flake.outputs.packageDefinitions
527
528 generate packages by calling that builder function we just created.
529 Place them in the packageDefinitions set.
530
531 First, pick the set of settings you wish to include.
532
533 Then, pass it a set of named boolean values like this:
534 { categoryname1 = true; categoryname2 = false; etc... }
535 False may be omitted. True may not.
536 Only true matters for what plugins will be added.
537
538 These categories are defined in the Builder function above
539 by placing named lists of plugins in the flexible sets provided.
540 The category names are the names of those lists.
541 Add a new list, then enable the category here.
542
543 If you have categories with the same name in
544 multiple different sets outlined above in the builder,
545 all plugins in those categories will be
546 included when you set "thatname = true;" here.
547 hence, general = true; will include the general lspsAndDeps category,
548 as well as the general startupPlugins category.
549
550 an example package definition:
551
552 packageDefinitions = {
553 nixCats = { pkgs, ... }: {
554 setting = {
555 wrapRc = true;
556
557 aliases = [ "viCat" ];
558 };
559 categories = {
560 custom = true;
561 gitPlugins = true;
562 general = true;
563 neonixdev = true;
564
565
566
567 lspDebugMode = false;
568
569
570
571 theBestCat = "says meow!!!";
572
573
574
575
576 };
577 extra = {
578 there_is = "also";
579 an_extra = "table";
580 for = ''if you dont want the main subcategory get function
581 to apply to something, or think it all being in categories is too
582 messy
583 '';
584 you_can = ''nixCats.extra("path.to.val")'';
585 for_safer = ''table access via vim.tbl_get'';
586 };
587 };
588 };
589
590 You can use the nixCats plugin for the set you define here in your Lua
591 It returns a Lua table of the same format.
592
593 see :help nixCats
594
595 For more nuances on enabling categories and subcategories, see above at
596 :help nixCats.flake.outputs.categoryDefinitions.default_values
597 and
598 :help nixCats.flake.outputs.categoryDefinitions.schemas
599
600 ----------------------------------------------------------------------------------------
601 Settings nixCats.flake.outputs.settings
602
603 These are the defaults:
604
605 default_settings = {
606
607
608
609 aliases = null;
610 viAlias = false;
611 vimAlias = false;
612
613
614 extraName = "";
615
616 withRuby = true;
617 withPython3 = true;
618 withNodeJs = false;
619 withPerl = false;
620
621
622
623
624
625
626
627 wrapRc = true;
628
629
630
631
632
633
634
635 configDirName = "nvim";
636
637
638
639
640
641
642 unwrappedCfgPath = null;
643
644
645
646
647
648 neovim-unwrapped = null;
649
650
651
652 nvimSRC = null;
653
654
655
656
657 suffix-path = false;
658
659
660 suffix-LD = false;
661
662
663
664
665
666
667
668
669 autowrapRuntimeDeps = "suffix";
670
671
672
673
674
675
676
677 autoconfigure = "prefix";
678
679
680
681
682
683
684
685
686 collate_grammars = true;
687
688
689
690
691 disablePythonSafePath = false;
692
693
694
695
696
697
698
699 gem_path = null;
700
701
702
703
704
705
706
707
708
709
710
711 moduleNamespace = [ <packagename> ];
712 };
713
714
715 QUICK TIP: wrapRc
716
717 The wrapRc option is very useful for testing Lua changes.
718 It removes the need to stage and rebuild to see your Lua changes reflected.
719 You will still need to rebuild when making changes to Nix regardless of the
720 value of wrapRc.
721
722 However it also means that the Lua isn't going run if it isn't in the right
723 folder, i.e. when installed and run from GitHub with nix run.
724
725 If the Lua is not in vim.fn.stdpath('config'), wrapRc = false will not work.
726 By default this is ~/.config/nvim on Linux systems, although we can
727 change nvim to whatever we wish via the configDirName setting.
728
729 Alternatively, you can set the unwrappedCfgPath option to allow the
730 configuration to be set to an absolute path. You still may want to set
731 the configDirName option anyway to change the data directories,
732 or explicitly keep it the same on both so that they share stuff like auths.
733
734 The most convenient way to use this is the following:
735 Make a second identical packageDefinition, but with wrapRc disabled.
736 Then install both the wrapped one and unwrapped one with different aliases.
737 When you want to hack in Lua, use unwrapped! When you're done, just rebuild
738 and go back to the wrapped one.
739
740 The templates/example/flake.nix file from the example config template
741 has an example of this with nixCats and regularCats.
742
743 Then, when testing Lua changes, you run the other package and have a vanilla
744 Neovim experience, only rebuilding when you install new packages.
745
746 When you are satisfied, simply rebuild and go back to using the main package,
747 as it was the same except for the single option!
748
749 --------------------------------------------------------------------------------------
750 Neovim Builder Creation: nixCats.flake.outputs.builder
751
752 Now we define our builder function.
753 We inherit utils.baseBuilder which is
754 a function that takes five arguments. It is defined in ./builder.
755 Right now we are going to call it with just the first four arguments. This will
756 leave us with a function that takes 1 argument.
757 That argument is the name of the Neovim package to be packaged.
758
759 1. The path to the Lua to include (in the flake, we use the self variable to get
760 this path and wrap the Lua when wrapRc = true)
761
762 2. A set containing parameters for the pkgs to be used:
763 It takes 2 forms. You can either pass it a nixpkgs and a system and it
764 will resolve the pkgs for you and pass it to your categoryDefinitions and
765 packageDefinitions,
766 or you can pass it a pkgs instead to inherit the values and do the same.
767
768 You may also provide a dependencyOverlays list to add overlays for nvim only,
769 extra_pkg_config (maps to the config argument to import nixpkgs { ... }),
770 nixCats_passthru (extra items to put into passthru in the final drv),
771 and extra_pkg_params (contains any fields in import nixpkgs { ... } not mentioned).
772
773 3. our function that takes an individual package definition
774 and returns a set of categoryDefinitions.
775
776 4. our set of packageDefinitions see: nixCats.flake.outputs.packageDefinitions
777
778 It is now a function that takes a name, and returns your chosen Neovim package.
779
780 packages = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all (system: let
781
782 nixCatsBuilder = utils.baseBuilder luaPath {
783 inherit nixpkgs system dependencyOverlays extra_pkg_config;
784 } categoryDefinitions packageDefinitions;
785 in {
786
787
788 default = nixCatsBuilder defaultPackageName;
789 });
790
791
792 packages = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all (system: let
793
794 pkgs = import nixpkgs {
795 inherit system;
796 overlays = dependencyOverlays;
797 config = extra_pkg_config;
798 };
799
800 nixCatsBuilder = utils.baseBuilder luaPath {
801
802 inherit pkgs;
803 } categoryDefinitions packageDefinitions;
804 in {
805
806
807 default = nixCatsBuilder defaultPackageName;
808 });
809
810 ---------------------------------------------------------------------------------------
811 Flake Exports and Export options nixCats.flake.outputs.exports
812
813 They look something like this:
814
815
816
817 utils.eachSystem nixpkgs.lib.platforms.all (system: let
818
819 nixCatsBuilder = utils.baseBuilder luaPath {
820 inherit nixpkgs system dependencyOverlays extra_pkg_config;
821 } categoryDefinitions packageDefinitions;
822
823
824
825 defaultPackage = nixCatsBuilder defaultPackageName;
826
827
828
829
830 pkgs = import nixpkgs { inherit system; };
831
832
833
834
835
836 in
837 {
838
839
840
841
842 packages = utils.mkAllWithDefault defaultPackage;
843
844
845
846 devShells = {
847 default = pkgs.mkShell {
848 name = defaultPackageName;
849 packages = [ defaultPackage ];
850 inputsFrom = [ ];
851 shellHook = ''
852 '';
853 };
854 };
855
856 }) // {
857
858
859
860
861
862
863
864
865
866
867 overlays = utils.makeOverlays luaPath {
868
869 inherit nixpkgs dependencyOverlays extra_pkg_config;
870
871 } categoryDefinitions packageDefinitions defaultPackageName;
872
873
874
875
876 nixosModules.default = utils.mkNixosModules {
877 inherit dependencyOverlays luaPath defaultPackageName
878 categoryDefinitions packageDefinitions nixpkgs;
879 };
880
881 homeModule = utils.mkHomeModules {
882 inherit dependencyOverlays luaPath defaultPackageName
883 categoryDefinitions packageDefinitions nixpkgs;
884 };
885
886 inherit utils;
887 inherit (utils) templates;
888 };
889
890 nixCats.flake.outputs.utils
891
892 The <utils> set exports all the functions used in creating the format in the
893 templates, including the main builder!
894 (see :h nixCats.flake.outputs.builder for builder explanation)
895
896 In the interests of not repeating ourselves,
897 a list of most functions exported in the <utils> set
898 can be found here:
899 https://nixcats.org/nixCats_utils.html
900
901 Missing from that list however,
902 is an explanation of the internal <n2l> library
903 nixCats uses to create the nixCats Lua plugin!
904
905 The library fully escapes all items passed to it,
906 so usually you can't execute lua code in them.
907 But you may still explicitly pass it lua code to execute at runtime
908 by declaring them as inline lua types!
909
910 An intricate explanation of the full set
911 of features the <n2l> library contains are below.
912
913 All other functions made available by
914 the <utils> set are explained in the documentation
915 at https://nixcats.org/nixCats_utils.html
916
917 nixCats.flake.outputs.utils.n2l
918 <n2l> This is the Nix to Lua library nixCats
919 uses to create the nixCats Lua plugin
920 You may wish to use some functions from it.
921
922 The library is exported from the <utils> set as utils.n2l
923
924 It contains <toLua> and <prettyLua> and <uglyLua> which convert Nix to Lua.
925
926 it contains a <member> function to determine if a value is a special "inline lua" type
927 it contains a <typeof> function to determine which special "inline lua" type it is
928 it contains a <resolve> function which knows how to resolve the types to a string of code
929 it contains the <default_subtype> name as well.
930
931 But of much more interest to you is the types you may declare.
932
933 Everything being passed through settings, categories, and extra in packageDefinitions
934 will be properly escaped. But this also means that
935 you cannot write any Lua code there.
936
937 Luckily, we have some types we can declare that will allow you to do this.
938
939 To declare that an item is a Lua value rather than a hard coded one,
940 you may choose one of these types. To do this, call its constructor!
941
942 for example, types.inline-unsafe has 1 field, body.
943
944 To declare one in our settings, categories, and extra sets, it would look
945 something like this:
946
947 categories = {
948 somecat = utils.n2l.types.inline-unsafe.mk {body = "vim.fn.stdpath('data')"; }`
949 }
950
951 inline-safe is the default type, and it gets to define a shorthand form.
952
953 categories = {
954 somecat = utils.n2l.types.inline-safe.mk "vim.fn.stdpath('data')";`
955 }
956
957 These are all the types, each one has an associated mk
958 function to create a value of that type,
959 which accepts the fields listed here, defined with default values.
960
961
962 inline-safe = {
963 default = (v: if v ? body then v else { body = v; });
964 fields = { body = "nil"; };
965 format = LI: "assert(loadstring(${luaEnclose "return ${LI.expr.body or LI.expr or "nil"}"}))()";
966 };
967
968 inline-unsafe = {
969 fields = { body = "nil"; };
970 format = LI: "${LI.expr.body or "nil"}";
971 };
972
973
974 function-safe = {
975 fields = { body = "return nil"; args = []; };
976 format = LI:
977 ''assert(loadstring(${luaEnclose ''return (function(${fixargs (LI.expr.args or [])}) ${LI.expr.body or "return nil"} end)''}))()'';
978 };
979
980
981 function-unsafe = {
982 fields = { body = "return nil"; args = []; };
983 format = LI: ''(function(${fixargs (LI.expr.args or [])}) ${LI.expr.body or "return nil"} end)'';
984 };
985 with-meta = {
986 fields = {
987 table = {};
988 meta = {};
989 newtable = null;
990 tablevar = "tbl_in";
991 };
992 format = LI: opts: let
993 metaarg1 = if LI.expr.newtable or null == null then LI.expr.tablevar or "{}" else toLuaFull opts LI.expr.newtable;
994 result = inline.types.function-unsafe.mk {
995 args = [ (LI.expr.tablevar or "tbl_in") ];
996 body = ''return setmetatable(${metaarg1}, ${toLuaFull opts LI.expr.meta})'';
997 };
998 in "${toLuaFull opts result}(${toLuaFull opts LI.expr.table})";
999 };
1000
1001
1002 Some more useage examples:
1003
1004 exampleSafeFunc = utils.n2l.types.function-safe.mk {
1005 args = [ "hello" ];
1006 body = ''
1007 print(hello)
1008 return hi
1009 '';
1010 };
1011 exampleUnsafeFunc = utils.n2l.types.function-unsafe.mk {
1012 args = [ "hi" "hello" ];
1013 body = ''
1014 print(hi)
1015 print(hello)
1016 return hi .. hello
1017 '';
1018 };
1019 };
1020 funcResults = {
1021 test1 = utils.n2l.types.inline-safe.mk ''${utils.n2l.resolve exampleSafeFunc}("Hello World!")'';
1022 };
1023 lua_table_with_meta = utils.n2l.types.with-meta.mk (let
1024 tablevar = "tbl_in";
1025 in {
1026 table = {
1027 this = "is a test table";
1028 inatesttable = "that will be translated to a Lua table with a metatable";
1029 };
1030
1031
1032 inherit tablevar;
1033 meta = {
1034
1035 __call = utils.n2l.types.function-unsafe.mk {
1036 args = [ "self" "..." ];
1037 body = ''
1038 print("This table is named ${tablevar}")
1039 return ${tablevar}.this
1040 '';
1041 };
1042 };
1043
1044
1045
1046 newtable = null;
1047 });
1048
1049 ---------------------------------------------------------------------------------------
1050 vim:tw=78:ts=8:ft=help:norl: