lib.options.filterOptions

[mightyiam]

Co-authored-by: Samyak S Sarnayak samyak201@gmail.com

Description of changes

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 24.05 Release Notes (or backporting 23.05 and 23.11 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[roberth]

What's the use case?

I feel like generally there should be a better solution than doing postprocessing on options.

[roberth]

Suggested change

	filterOptions :: ([n] -> o -> bool) -> opts -> opts
	filterOptions :: (List String -> Option -> Bool) -> Options -> Options

[mightyiam]

Applied.

[roberth]

This is very minimal. It's good to have "tree", but what does it do? How is the callback used?

Something like:

Filters an option tree, such that the returned tree only contains the options for which the callback returns true.

Arguments passed to the callback are:

• The option path, as a list of strings representing the attribute names.
• The option declaration at that path.

It is not possible to prune entire branches of the option tree in one go, as the callback is only invoked for each option (leaf).

---

Question: doesn't this leave empty branches behind?

[mightyiam]

Applied.

[mightyiam]

There's a test for leaving no empty branches now.

[roberth]

This can not be the result. Please test it.

[mightyiam]

Amended.

[mightyiam]

The use case is filtering options prior to generating documentation for them.
The actual usage is here. Docs here.

Without that filtering, documentation for all of Nixpkgs' NixOS options would be generated.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/prs-ready-for-review/3032/3683

[infinisil]

Here's a potentially cleaner alternative: If you create a submodule of all the options that you want to generate documentation for, you can use options.my.submodule.type.getSubOptions [ "my" "submodule" ], e.g. for services.maubot.settings:

pkgs.nixosOptionsDoc {
  options = options.services.maubot.settings.type.getSubOptions [ ];
  # ...;
}

You can change the [ ] to [ "my" "submodule" ] to generate the prefixed options instead if desired.

[infinisil]

Relevant discussion on Matrix: https://matrix.to/#/!wfudwzqQUiJYJnqfSY:nixos.org/$RPpTLbRWDFqr763W3_GpXVigwWAwlJnJg_qJjA1EORs?via=nixos.org&via=matrix.org&via=nixos.dev