expand on interpolated expressions

doc/manual/src/language/string-interpolation.md

@@ -1,19 +1,12 @@
 # String interpolation
 
-String interpolation is a language feature where a [string], [path], or [attribute name] can contain expressions enclosed in `${ }` (dollar-sign with curly brackets).
+String interpolation is a language feature where a [string], [path], or [attribute name][attribute set] can contain expressions enclosed in `${ }` (dollar-sign with curly brackets).
 
-Such a string is an *interpolated string*, and an expression inside is an *interpolated expression*.
+Such a construct is called *interpolated string*, and the expression inside is an [interpolated expression](#interpolated-expression).
-
-Interpolated expressions must evaluate to one of the following:
-
-- a [string]
-- a [path]
-- a [derivation]
 
 [string]: ./values.md#type-string
 [path]: ./values.md#type-path
-[attribute name]: ./values.md#attribute-set
+[attribute set]: ./values.md#attribute-set
-[derivation]: ../glossary.md#gloss-derivation
 
 ## Examples
 
@@ -80,3 +73,110 @@ let name = "foo"; in
 ```
 
     { foo = "bar"; }
+
+# Interpolated expression
+
+An interpolated expression must evaluate to one of the following:
+
+- a [string]
+- a [path]
+- an [attribute set] that has a `__toString` attribute or an `outPath` attribute
+
+  - `__toString` must be a function that takes the attribute set itself and returns a string
+  - `outPath` must be a string
+
+  This includes [derivations](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental).
+
+A string interpolates to itself.
+
+A path in an interpolated expression is first copied into the Nix store, and the resulting string is the [store path] of the newly created [store object](../glossary.md#gloss-store-object).
+
+[store path]: ../glossary.md#gloss-store-path
+
+> **Example**
+>
+> ```console
+> $ mkdir foo
+> ```
+>
+> Reference the empty directory in an interpolated expression:
+>
+> ```nix
+> "${./foo}"
+> ```
+>
+>     "/nix/store/2hhl2nz5v0khbn06ys82nrk99aa1xxdw-foo"
+
+A derivation interpolates to the [store path] of its first [output](./derivations.md#attr-outputs).
+
+> **Example**
+>
+> ```nix
+> let
+>   pkgs = import <nixpkgs> {};
+> in
+> "${pkgs.hello}"
+> ```
+>
+>     "/nix/store/4xpfqf29z4m8vbhrqcz064wfmb46w5r7-hello-2.12.1"
+
+An attribute set interpolates to the return value of the function in the `__toString` applied to the attribute set itself.
+
+> **Example**
+>
+> ```nix
+> let
+>   a = {
+>     value = 1;
+>     __toString = self: toString (self.value + 1);
+>   };
+> in
+> "${a}"
+> ```
+>
+>     "2"
+
+An attribute set also interpolates to the value of its `outPath` attribute.
+
+> **Example**
+>
+> ```nix
+> let
+>   a = { outPath = "foo"; };
+> in
+> "${a}"
+> ```
+>
+>     "foo"
+
+If both `__toString` and `outPath` are present in an attribute set, `__toString` takes precedence.
+
+> **Example**
+>
+> ```nix
+> let
+>   a = { __toString = _: "yes"; outPath = throw "no"; };
+> in
+> "${a}"
+> ```
+>
+>     "yes"
+
+If neither is present, an error is thrown.
+
+> **Example**
+>
+> ```nix
+> let
+>   a = {};
+> in
+> "${a}"
+> ```
+>
+>     error: cannot coerce a set to a string
+>
+>            at «string»:4:2:
+>
+>                 3| in
+>                 4| "${a}"
+>                  |  ^

doc/manual/src/language/values.md

@@ -112,18 +112,16 @@
   environment variable `NIX_PATH` will be searched for the given file
   or directory name.
 
-  When an [interpolated string][string interpolation] evaluates to a path, the path is first copied into the Nix store and the resulting string is the [store path] of the newly created [store object].
-
-  [store path]: ../glossary.md#gloss-store-path
-  [store object]: ../glossary.md#gloss-store-object
-
   For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
 
   Note that the Nix language assumes that all input files will remain _unchanged_ while  evaluating a Nix expression.
   For example, assume you used a file path in an interpolated string during a `nix repl` session.
-  Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new store path, since Nix might not re-read the file contents.
+  Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new [store path], since Nix might not re-read the file contents.
 
-  Paths themselves, except those in angle brackets (`< >`), support [string interpolation].
+  [store path]: ../glossary.md#gloss-store-path
+
+  Paths, except those in angle brackets (`< >`), support [string interpolation] and can be used in [interpolated expressions].
+  [interpolated expressions]: ./string-interpolation.md#interpolated-expressions
 
   At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.
 

src/libexpr/primops.cc

@@ -260,9 +260,7 @@ static RegisterPrimOp primop_import({
     .doc = R"(
       Load, parse and return the Nix expression in the file *path*.
 
-      The value *path* can be a path, a string, or an attribute set with an
+      The *path* argument must meet the same criteria as an [interpolated expression](@docroot@/language/string-interpolation.md#interpolated-expression).
-      `__toString` attribute or a `outPath` attribute (as derivations or flake
-      inputs typically have).
 
       If *path* is a directory, the file `default.nix` in that directory
       is loaded.