From d7efd7639420f4c840cbfdfcbbb3c45292f3ac54 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Mon, 16 Oct 2006 15:55:34 +0000
Subject: * Big cleanup of the semantics of paths, strings, contexts, string  
 concatenation and string coercion.  This was a big mess (see   e.g. NIX-67). 
 Contexts are now folded into strings, so that they   don't cause evaluation
 errors when they're not expected.  The   semantics of paths has been
 clarified (see nixexpr-ast.def).   toString() and coerceToString() have been
 merged.

  Semantic change: paths are now copied to the store when they're in a
  concatenation (and in most other situations - that's the
  formalisation of the meaning of a path).  So

    "foo " + ./bla

  evaluates to "foo /nix/store/hash...-bla", not "foo
  /path/to/current-dir/bla".  This prevents accidental impurities, and
  is more consistent with the treatment of derivation outputs, e.g.,
  `"foo " + bla' where `bla' is a derivation.  (Here `bla' would be
  replaced by the output path of `bla'.)
---
 src/libexpr/nixexpr-ast.def | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

(limited to 'src/libexpr/nixexpr-ast.def')

diff --git a/src/libexpr/nixexpr-ast.def b/src/libexpr/nixexpr-ast.def
index b797fcfc440e..fe5fe71b0a05 100644
--- a/src/libexpr/nixexpr-ast.def
+++ b/src/libexpr/nixexpr-ast.def
@@ -24,8 +24,37 @@ Call | Expr Expr | Expr |
 Select | Expr string | Expr |
 Var | string | Expr |
 Int | int | Expr |
-Str | string | Expr |
+
+# Strings in the evaluator carry a so-called `context' (the ATermList)
+# which is a list of strings representing store paths.  This is to
+# allow users to write things like
+#
+#   "--with-freetype2-library=" + freetype + "/lib"
+#
+# where `freetype' is a derivation (or a source to be copied to the
+# store).  If we just concatenated the strings without keeping track
+# of the referenced store paths, then if the string is used as a
+# derivation attribute, the derivation will not have the correct
+# dependencies in its inputDrvs and inputSrcs.
+#
+# The semantics of the context is as follows: when a string with
+# context C is used as a derivation attribute, then the derivations in
+# C will be added to the inputDrvs of the derivation, and the other
+# store paths in C will be added to the inputSrcs of the derivations.
+#
+# For canonicity, the store paths should be in sorted order.
+Str | string ATermList | Expr |
+
+# A path is a reference to a file system object that is to be copied
+# to the Nix store when used as a derivation attribute.  When it is
+# concatenated to a string (i.e., `str + path'), it is also copied and
+# the resulting store path is concatenated to the string (with the
+# store path in the context).  If a string or path is concatenated to
+# a path (i.e., `path + str' or `path + path'), the result is a new
+# path (if the right-hand side is a string, the context must be
+# empty).
 Path | string | Expr |
+
 List | ATermList | Expr |
 BlackHole | | Expr |
 Undefined | | Expr |
@@ -36,7 +65,6 @@ Closed | Expr | Expr |
 Rec | ATermList ATermList | Expr |
 Bool | ATerm | Expr |
 Null | | Expr |
-Context | ATermList Expr | Expr |
 
 Bind | string Expr Pos | ATerm |
 Bind | string Expr | ATerm | Bind2
-- 
cgit 1.4.1

