lib.lazyFunction: init

[roberth]

Description of changes

Adds a function that makes attrset-matching functions lazy using reflection.
This is similar to what the module system does for module arguments, but not powerful enough to abstract that.

This isn't used in nixpkgs yet, but may be used in #193336; however, I'd like for this to be reviewed separately.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• 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/)
• 22.11 Release Notes (or backporting 22.05 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
  • (Release notes changes) Ran nixos/doc/manual/md-to-db.sh to update generated release notes
• Fits CONTRIBUTING.md.

cc @infinisil

[infinisil]

Suggested change

	Make a function lazy in its arguments.
	Make a function lazy in its argument.

I don't like how this detail matters, but it does because there's only one actual argument here, the destructuring only makes it seem like multiple arguments. And lazy in arguments could be interpreted as making the attribute values lazy instead of strict (but that part is always lazy)

[infinisil]

Suggested change

	can return a the (partially evaluated) function body (`{ r = ...; }`).
	can return a the (partially evaluated) function body (`{ r = ...; }`).
	`lazyFunction` can change such a function to not evaluate the attribute
	names of the argument before the body is returned.

[roberth]

I've rewritten a lot to make better use of the example instead.

[infinisil]

It using reflection (which is not really a known term) is an implementation detail, can be omitted. And the note about it only working with set patterns should be moved down.

Suggested change

	`lazyFunction` uses reflection on the passed in function and it only works
	for functions defined with a "set pattern".

[roberth]

I think it's relevant because using reflection breaks the function abstraction, which is a big deal.
I've removed it for now, because I agree describing the consequences is more important.

[infinisil]

Suggested change

	It makes a function like `{ a, b }: { r = foo a b; }` behave like
	`args: { r = foo args.a args.b; }`.
	In other words, it makes a function like `{ a, b }: { r = foo a b; }` behave like
	`args: { r = foo args.a args.b; }` instead.

[roberth]

I've changed this to show the "generated wrapper" instead. I think that helps more with understanding.

[infinisil]

Suggested change

	It is not compatible with ellipsis patterns, `{ ... }:`, because only the
	explicitly declared parameters are passed through. For example, the
	following will not work: `lazyFunction(args@{ a, ... }: args.b)`;
	even if the caller provides `b`.
	It also removes the checks against unexpected arguments.
	This function has some limitations:
	- It doesn't work for functions that don't do attribute destructuring like `arg: { r = foo arg.a arg.b; }` (`a`/`b` wouldn't be accessible)
	- It doesn't work for functions with ellipses (`...`) like `arg@{ a, ... }: { r = foo a arg.b; }` (`b` wouldn't be accessible)
	- It removes checks against unexpected arguments, so `lazyFunction ({ a }: a) { a = "a"; b = "b"; }` doesn't give an error.

[infinisil]

I'm just calling it attribute destructuring here instead of "set pattern", because nobody calls it that

[infinisil]

Somewhat jokingly I wrote #194992, which could check for some of these limitations in the code itself

[roberth]

An author of the Nix manual uses this term.

[infinisil]

We could try to prevent some misuse by throwing an error when functionArgs f is {}, but that might not be worthwhile.

[roberth]

That could be a problem if someone uses lazyFunction to construct another function where constant functions are a valid argument.

[roberth]

Super bad example, but better than no example?

let
  testCase.foo = { a }: a * 2 == a + a;
  testCase.bar = { }: true;
in mapAttrs (k: lazyFunction) testCase