From 95ea6335476b70b0012ab4afcaf0a7df44458f95 Mon Sep 17 00:00:00 2001 From: Jade Lovelace Date: Sun, 6 Jul 2025 15:55:42 -0700 Subject: [PATCH] docs: properly explain conversions in nix eval --json/--raw options. jade: I rewrote this PR to be consistent between nix-instantiate and nix eval. It turns out that nix eval *doesn't* copy to store with `--json`, whereas nix-instantiate does. Wat. Closes: https://github.com/lix-project/lix/pull/17 Co-authored-by: tyberiusprime Change-Id: Id22deec1cee0fed3bd5689567869b70bab26bae5 --- doc/manual/src/command-ref/nix-instantiate.md | 21 ++++++++++++------- lix/nix/eval.md | 18 +++++++++++----- 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index c0c025205..e94fd9975 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -107,20 +107,27 @@ See that section for complete details (`nix-build --help`), but in summary, a pa > This option can cause non-termination, because lazy data > structures can be infinitely large. - - `--raw` + - `--raw`\ When used with `--eval`, the result must be coercible to a string, i.e., - something that can be converted using `${...}`. The output is - printed exactly as-is, with no quotes, escaping, or trailing newline. + something that can be converted using `${...}`. + + Integers will always generate an error when output via `--raw`, regardless of + [`coerce-integers`](../contributing/experimental-features.md#xp-feature-coerce-integers) being enabled, to avoid ambiguity. + + The output is printed exactly as-is, with no quotes, escaping, or trailing + newline. - `--json`\ When used with `--eval`, print the resulting value as an JSON - representation of the abstract syntax tree rather than as a Nix expression. + representation of the resulting value rather than as a Nix expression. + + The conversion behaviour, if `--strict` is passed, is the same as + [`builtins.toJSON`](../language/builtins.md#builtins-toJSON). - `--xml`\ When used with `--eval`, print the resulting value as an XML - representation of the abstract syntax tree rather than as a Nix expression. - The schema is the same as that used by the [`toXML` - built-in](../language/builtins.md). + representation of the resulting value rather than as a Nix expression. + The schema is the same as that used by [`builtins.toXML`](../language/builtins.md#builtins-toXML). - `--read-write-mode`\ When used with `--eval`, perform evaluation in read/write mode so diff --git a/lix/nix/eval.md b/lix/nix/eval.md index eb9f753c5..0e2b70b94 100644 --- a/lix/nix/eval.md +++ b/lix/nix/eval.md @@ -61,12 +61,20 @@ result on standard output. * By default, the evaluation result is printed as a Nix expression. -* With `--json`, the evaluation result is printed in JSON format. Note - that this fails if the result contains values that are not - representable as JSON, such as functions. +* With `--json`, the evaluation result is printed in JSON format. -* With `--raw`, the evaluation result must be a string, which is - printed verbatim, without any quoting. + The conversion behaviour is the same as + [`builtins.toJSON`](../../language/builtins.md#builtins-toJSON) except that + paths are printed as-is without being copied to the Nix store. + +* With `--raw`, the result must be coercible to a string, i.e., + something that can be converted using `${...}`. + + Integers will always generate an error when output via `--raw`, regardless of + [`coerce-integers`](../../contributing/experimental-features.md#xp-feature-coerce-integers) being enabled, to avoid ambiguity. + + The output is printed exactly as-is, with no quotes, escaping, or trailing + newline. * With `--write-to` *path*, the evaluation result must be a string or a nested attribute set whose leaf values are strings. These strings