Merge remote-tracking branch 'origin/master' into multithreaded-eval

.clang-format

@@ -31,3 +31,4 @@ AlwaysBreakBeforeMultilineStrings: true
 IndentPPDirectives: AfterHash
 PPIndentWidth: 2
 BinPackArguments: false
+BreakBeforeTernaryOperators: true

doc/manual/redirects.js

@@ -344,6 +344,7 @@ const redirects = {
   },
   "language/syntax.html": {
     "scoping-rules": "scoping.html",
+    "string-literal": "string-literals.html",
   },
   "installation/installing-binary.html": {
     "linux": "uninstall.html#linux",

doc/manual/rl-next/ban-integer-overflow.md

@@ -0,0 +1,21 @@
+---
+synopsis: Define integer overflow in the Nix language as an error
+issues: [10968]
+prs: [11188]
+---
+
+Previously, integer overflow in the Nix language invoked C++ level signed overflow, which was undefined behaviour, but *usually* manifested as wrapping around on overflow.
+
+Since prior to the public release of Lix, Lix had C++ signed overflow defined to crash the process and nobody noticed this having accidentally removed overflow from the Nix language for three months until it was caught by fiddling around.
+Given the significant body of actual Nix code that has been evaluated by Lix in that time, it does not appear that nixpkgs or much of importance depends on integer overflow, so it appears safe to turn into an error.
+
+Some other overflows were fixed:
+- `builtins.fromJSON` of values greater than the maximum representable value in a signed 64-bit integer will generate an error.
+- `nixConfig` in flakes will no longer accept negative values for configuration options.
+
+Integer overflow now looks like the following:
+
+```
+$ nix eval --expr '9223372036854775807 + 1'
+error: integer overflow in adding 9223372036854775807 + 1
+```

doc/manual/src/SUMMARY.md.in

@@ -29,6 +29,7 @@
     - [String context](language/string-context.md)
   - [Syntax and semantics](language/syntax.md)
     - [Variables](language/variables.md)
+    - [String literals](language/string-literals.md)
     - [Identifiers](language/identifiers.md)
     - [Scoping rules](language/scope.md)
     - [String interpolation](language/string-interpolation.md)

doc/manual/src/language/identifiers.md

@@ -16,7 +16,7 @@ An *identifier* is an [ASCII](https://en.wikipedia.org/wiki/ASCII) character seq
 
 # Names
 
-A *name* can be written as an [identifier](#identifier) or a [string literal](./syntax.md#string-literal).
+A *name* can be written as an [identifier](#identifier) or a [string literal](./string-literals.md).
 
 > **Syntax**
 >

doc/manual/src/language/operators.md

@@ -67,8 +67,12 @@ After evaluating *attrset* and *attrpath*, the computational complexity is O(log
 
 ## Arithmetic
 
-Numbers are type-compatible:
-Pure integer operations will always return integers, whereas any operation involving at least one floating point number return a floating point number.
+Numbers will retain their type unless mixed with other numeric types:
+Pure integer operations will always return integers, whereas any operation involving at least one floating point number returns a floating point number.
+
+Evaluation of the following numeric operations throws an evaluation error:
+- Division by zero
+- Integer overflow, that is, any operation yielding a result outside of the representable range of [Nix language integers](./syntax.md#number-literal)
 
 See also [Comparison] and [Equality].
 

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

@@ -8,6 +8,10 @@ Such a construct is called *interpolated string*, and the expression inside is a
 [path]: ./types.md#type-path
 [attribute set]: ./types.md#attribute-set
 
+> **Syntax**
+>
+> *interpolation_element* → `${` *expression* `}`
+
 ## Examples
 
 ### String

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

@@ -0,0 +1,190 @@
+# String literals
+
+A *string literal* represents a [string](types.md#type-string) value.
+
+> **Syntax**
+>
+> *expression* → *string*
+>
+> *string* → `"` ( *string_char*\* [*interpolation_element*][string interpolation] )* *string_char*\* `"`
+>
+> *string* → `''` ( *indented_string_char*\* [*interpolation_element*][string interpolation] )* *indented_string_char*\* `''`
+>
+> *string* → *uri*
+>
+> *string_char* ~ `[^"$\\]|\$(?!\{)|\\.`
+>
+> *indented_string_char* ~ `[^$']|\$\$|\$(?!\{)|''[$']|''\\.|'(?!')`
+>
+> *uri* ~ `[A-Za-z][+\-.0-9A-Za-z]*:[!$%&'*+,\-./0-9:=?@A-Z_a-z~]+`
+
+Strings can be written in three ways.
+
+The most common way is to enclose the string between double quotes, e.g., `"foo bar"`.
+Strings can span multiple lines.
+The results of other expressions can be included into a string by enclosing them in `${ }`, a feature known as [string interpolation].
+
+[string interpolation]: ./string-interpolation.md
+
+The following must be escaped to represent them within a string, by prefixing with a backslash (`\`):
+
+- Double quote (`"`)
+
+> **Example**
+>
+> ```nix
+> "\""
+> ```
+>
+>     "\""
+
+- Backslash (`\`)
+
+> **Example**
+>
+> ```nix
+> "\\"
+> ```
+>
+>     "\\"
+
+- Dollar sign followed by an opening curly bracket (`${`) – "dollar-curly"
+
+> **Example**
+>
+> ```nix
+> "\${"
+> ```
+>
+>     "\${"
+
+The newline, carriage return, and tab characters can be written as `\n`, `\r` and `\t`, respectively.
+
+A "double-dollar-curly" (`$${`) can be written literally.
+
+> **Example**
+>
+> ```nix
+> "$${"
+> ```
+>
+>     "$\${"
+
+String values are output on the terminal with Nix-specific escaping.
+Strings written to files will contain the characters encoded by the escaping.
+
+The second way to write string literals is as an *indented string*, which is enclosed between pairs of *double single-quotes* (`''`), like so:
+
+```nix
+''
+This is the first line.
+This is the second line.
+  This is the third line.
+''
+```
+
+This kind of string literal intelligently strips indentation from
+the start of each line. To be precise, it strips from each line a
+number of spaces equal to the minimal indentation of the string as a
+whole (disregarding the indentation of empty lines). For instance,
+the first and second line are indented two spaces, while the third
+line is indented four spaces. Thus, two spaces are stripped from
+each line, so the resulting string is
+
+```nix
+"This is the first line.\nThis is the second line.\n  This is the third line.\n"
+```
+
+> **Note**
+>
+> Whitespace and newline following the opening `''` is ignored if there is no non-whitespace text on the initial line.
+
+> **Warning**
+>
+> Prefixed tab characters are not stripped.
+>
+> > **Example**
+> >
+> > The following indented string is prefixed with tabs:
+> >
+> > <pre><code class="nohighlight">''
+> > 	all:
+> > 		@echo hello
+> > ''
+> > </code></pre>
+> >
+> >     "\tall:\n\t\t@echo hello\n"
+
+Indented strings support [string interpolation].
+
+The following must be escaped to represent them in an indented string:
+
+- `$` is escaped by prefixing it with two single quotes (`''`)
+
+> **Example**
+>
+> ```nix
+> ''
+>   ''$
+> ''
+> ```
+>
+>     "$\n"
+
+- `''` is escaped by prefixing it with one single quote (`'`)
+
+> **Example**
+>
+> ```nix
+> ''
+>   '''
+> ''
+> ```
+>
+>     "''\n"
+
+These special characters are escaped as follows:
+- Linefeed (`\n`): `''\n`
+- Carriage return (`\r`): `''\r`
+- Tab (`\t`): `''\t`
+
+`''\` escapes any other character.
+
+A "double-dollar-curly" (`$${`) can be written literally.
+
+> **Example**
+>
+> ```nix
+> ''
+>   $${
+> ''
+> ```
+>
+>     "$\${\n"
+
+Indented strings are primarily useful in that they allow multi-line
+string literals to follow the indentation of the enclosing Nix
+expression, and that less escaping is typically necessary for
+strings representing languages such as shell scripts and
+configuration files because `''` is much less common than `"`.
+Example:
+
+```nix
+stdenv.mkDerivation {
+...
+postInstall =
+  ''
+    mkdir $out/bin $out/etc
+    cp foo $out/bin
+    echo "Hello World" > $out/etc/foo.conf
+    ${if enableBar then "cp bar $out/bin" else ""}
+  '';
+...
+}
+```
+
+Finally, as a convenience, *URIs* as defined in appendix B of
+[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
+is*, without quotes. For instance, the string
+`"http://example.org/foo.tar.bz2"` can also be written as
+`http://example.org/foo.tar.bz2`.