From ef606760abd87c98371fbc08c1f25ad897823a2a Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 22 Jul 2020 23:17:48 +0200 Subject: Pandoc conversion --- doc/manual/src/expressions/language-values.md | 209 ++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 doc/manual/src/expressions/language-values.md (limited to 'doc/manual/src/expressions/language-values.md') diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md new file mode 100644 index 000000000..98ad97c97 --- /dev/null +++ b/doc/manual/src/expressions/language-values.md @@ -0,0 +1,209 @@ +# Values + +Nix has the following basic data types: + + - *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 special + characters `"` and `\` and the character sequence `${` must be + escaped by prefixing them with a backslash (`\`). Newlines, carriage + returns and tabs can be written as `\n`, `\r` and `\t`, + respectively. + + You can include the result of an expression into a string by + enclosing it in `${...}`, a feature known as *antiquotation*. The + enclosed expression must evaluate to something that can be coerced + into a string (meaning that it must be a string, a path, or a + derivation). For instance, rather than writing + + "--with-freetype2-library=" + freetype + "/lib" + + (where `freetype` is a derivation), you can instead write the more + natural + + "--with-freetype2-library=${freetype}/lib" + + The latter is automatically translated to the former. A more + complicated example (from the Nix expression for + [Qt](http://www.trolltech.com/products/qt)): + + configureFlags = " + -system-zlib -system-libpng -system-libjpeg + ${if openglSupport then "-dlopen-opengl + -L${mesa}/lib -I${mesa}/include + -L${libXmu}/lib -I${libXmu}/include" else ""} + ${if threadSupport then "-thread" else "-no-thread"} + "; + + Note that Nix expressions and strings can be arbitrarily nested; in + this case the outer string contains various antiquotations that + themselves contain strings (e.g., `"-thread"`), some of which in + turn contain expressions (e.g., `${mesa}`). + + The second way to write string literals is as an *indented string*, + which is enclosed between pairs of *double single-quotes*, like so: + + '' + 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 space, while the third + line is indented four spaces. Thus, two spaces are stripped from + each line, so the resulting string is + + "This is the first line.\nThis is the second line.\n This is the third line.\n" + + Note that the whitespace and newline following the opening `''` is + ignored if there is no non-whitespace text on the initial line. + + Antiquotation (`${expr}`) is supported in indented strings. + + Since `${` and `''` have special meaning in indented strings, you + need a way to quote them. `$` can be escaped by prefixing it with + `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped + by prefixing it with `'`, i.e., `'''`. `$` removes any special + meaning from the following `$`. Linefeed, carriage-return and tab + characters can be written as `''\n`, `''\r`, `''\t`, and `''\` + escapes any other character. + + 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: + + 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`. + + - Numbers, which can be *integers* (like `123`) or *floating point* + (like `123.43` or `.27e13`). + + Numbers are type-compatible: pure integer operations will always + return integers, whereas any operation involving at least one + floating point number will have a floating point number as a result. + + - *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at + least one slash to be recognised as such; for instance, `builder.sh` + is not a path\[1\]. If the file name is relative, i.e., if it does + not begin with a slash, it is made absolute at parse time relative + to the directory of the Nix expression that contained it. For + instance, if a Nix expression in `/foo/bar/bla.nix` refers to + `../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`. + + If the first component of a path is a `~`, it is interpreted as if + the rest of the path were relative to the user's home directory. + e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user + whose home directory is `/home/edolstra`. + + Paths can also be specified between angle brackets, e.g. + ``. This means that the directories listed in the + environment variable NIX\_PATH will be searched for the given file + or directory name. + + - *Booleans* with values `true` and `false`. + + - The null value, denoted as `null`. + +Lists are formed by enclosing a whitespace-separated list of values +between square brackets. For example, + + [ 123 ./foo.nix "abc" (f { x = y; }) ] + +defines a list of four elements, the last being the result of a call to +the function `f`. Note that function calls have to be enclosed in +parentheses. If they had been omitted, e.g., + + [ 123 ./foo.nix "abc" f { x = y; } ] + +the result would be a list of five elements, the fourth one being a +function and the fifth being a set. + +Note that lists are only lazy in values, and they are strict in length. + +Sets are really the core of the language, since ultimately the Nix +language is all about creating derivations, which are really just sets +of attributes to be passed to build scripts. + +Sets are just a list of name/value pairs (called *attributes*) enclosed +in curly brackets, where each value is an arbitrary expression +terminated by a semicolon. For example: + + { x = 123; + text = "Hello"; + y = f { bla = 456; }; + } + +This defines a set with attributes named `x`, `text`, `y`. The order of +the attributes is irrelevant. An attribute name may only occur once. + +Attributes can be selected from a set using the `.` operator. For +instance, + + { a = "Foo"; b = "Bar"; }.a + +evaluates to `"Foo"`. It is possible to provide a default value in an +attribute selection using the `or` keyword. For example, + + { a = "Foo"; b = "Bar"; }.c or "Xyzzy" + +will evaluate to `"Xyzzy"` because there is no `c` attribute in the set. + +You can use arbitrary double-quoted strings as attribute names: + + { "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" + +This will evaluate to `123` (Assuming `bar` is antiquotable). In the +case where an attribute name is just a single antiquotation, the quotes +can be dropped: + + { foo = 123; }.${bar} or 456 + +This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced +to a string and `456` otherwise (again assuming `bar` is antiquotable). + +In the special case where an attribute name inside of a set declaration +evaluates to `null` (which is normally an error, as `null` is not +antiquotable), that attribute is simply not added to the set: + + { ${if foo then "bar" else null} = true; } + +This will evaluate to `{}` if `foo` evaluates to `false`. + +A set that has a `__functor` attribute whose value is callable (i.e. is +itself a function or a set with a `__functor` attribute whose value is +callable) can be applied as if it were a function, with the set itself +passed in first , e.g., + + let add = { __functor = self: x: x + self.x; }; + inc = add // { x = 1; }; + in inc 1 + +evaluates to `2`. This can be used to attach metadata to a function +without the caller needing to treat it specially, or to implement a form +of object-oriented programming, for example. + +1. It's parsed as an expression that selects the attribute `sh` from + the variable `builder`. -- cgit v1.2.3 From f3903035667e158112dfd414091d8d50ef90c5f4 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 23 Jul 2020 10:44:54 +0200 Subject: Reconvert --- doc/manual/src/expressions/language-values.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/expressions/language-values.md') diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index 98ad97c97..fac0be47e 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -120,8 +120,8 @@ Nix has the following basic data types: Paths can also be specified between angle brackets, e.g. ``. This means that the directories listed in the - environment variable NIX\_PATH will be searched for the given file - or directory name. + environment variable NIX\_PATH\ will be searched for the + given file or directory name. - *Booleans* with values `true` and `false`. -- cgit v1.2.3 From ee051084723333fc5889c604c829669800e8b43c Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 23 Jul 2020 14:20:54 +0200 Subject: ->
Pandoc silently ignores ... --- doc/manual/src/expressions/language-values.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc/manual/src/expressions/language-values.md') diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index fac0be47e..8ffe2f0f9 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -1,5 +1,7 @@ # Values +## Simple Values + Nix has the following basic data types: - *Strings* can be written in three ways. @@ -127,6 +129,8 @@ Nix has the following basic data types: - The null value, denoted as `null`. +## Lists + Lists are formed by enclosing a whitespace-separated list of values between square brackets. For example, @@ -143,6 +147,8 @@ function and the fifth being a set. Note that lists are only lazy in values, and they are strict in length. +## Sets + Sets are really the core of the language, since ultimately the Nix language is all about creating derivations, which are really just sets of attributes to be passed to build scripts. -- cgit v1.2.3 From 8d0b311a1ccd0aef49c6f272aad4ecb5105b285a Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 24 Jul 2020 11:43:44 +0200 Subject: Get rid of footnotes Markdown doesn't support them. --- doc/manual/src/expressions/language-values.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) (limited to 'doc/manual/src/expressions/language-values.md') diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index 8ffe2f0f9..eca2cab51 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -108,12 +108,14 @@ Nix has the following basic data types: floating point number will have a floating point number as a result. - *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at - least one slash to be recognised as such; for instance, `builder.sh` - is not a path\[1\]. If the file name is relative, i.e., if it does - not begin with a slash, it is made absolute at parse time relative - to the directory of the Nix expression that contained it. For - instance, if a Nix expression in `/foo/bar/bla.nix` refers to - `../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`. + least one slash to be recognised as such. For instance, `builder.sh` + is not a path: it's parsed as an expression that selects the + attribute `sh` from the variable `builder`. If the file name is + relative, i.e., if it does not begin with a slash, it is made + absolute at parse time relative to the directory of the Nix + expression that contained it. For instance, if a Nix expression in + `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path + is `/foo/xyzzy/fnord.nix`. If the first component of a path is a `~`, it is interpreted as if the rest of the path were relative to the user's home directory. @@ -122,8 +124,8 @@ Nix has the following basic data types: Paths can also be specified between angle brackets, e.g. ``. This means that the directories listed in the - environment variable NIX\_PATH\ will be searched for the - given file or directory name. + environment variable `NIX_PATH` will be searched for the given file + or directory name. - *Booleans* with values `true` and `false`. @@ -210,6 +212,3 @@ passed in first , e.g., evaluates to `2`. This can be used to attach metadata to a function without the caller needing to treat it specially, or to implement a form of object-oriented programming, for example. - -1. It's parsed as an expression that selects the attribute `sh` from - the variable `builder`. -- cgit v1.2.3 From 1d0a7b54fa330b041a720932ee4e05dcad1d2d5c Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 31 Jul 2020 15:43:25 +0200 Subject: Enable syntax highlighting --- doc/manual/src/expressions/language-values.md | 110 ++++++++++++++++---------- 1 file changed, 70 insertions(+), 40 deletions(-) (limited to 'doc/manual/src/expressions/language-values.md') diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index eca2cab51..ce31029cc 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -19,24 +19,30 @@ Nix has the following basic data types: into a string (meaning that it must be a string, a path, or a derivation). For instance, rather than writing - "--with-freetype2-library=" + freetype + "/lib" + ```nix + "--with-freetype2-library=" + freetype + "/lib" + ``` (where `freetype` is a derivation), you can instead write the more natural - "--with-freetype2-library=${freetype}/lib" + ```nix + "--with-freetype2-library=${freetype}/lib" + ``` The latter is automatically translated to the former. A more complicated example (from the Nix expression for [Qt](http://www.trolltech.com/products/qt)): - configureFlags = " - -system-zlib -system-libpng -system-libjpeg - ${if openglSupport then "-dlopen-opengl - -L${mesa}/lib -I${mesa}/include - -L${libXmu}/lib -I${libXmu}/include" else ""} - ${if threadSupport then "-thread" else "-no-thread"} - "; + ```nix + configureFlags = " + -system-zlib -system-libpng -system-libjpeg + ${if openglSupport then "-dlopen-opengl + -L${mesa}/lib -I${mesa}/include + -L${libXmu}/lib -I${libXmu}/include" else ""} + ${if threadSupport then "-thread" else "-no-thread"} + "; + ``` Note that Nix expressions and strings can be arbitrarily nested; in this case the outer string contains various antiquotations that @@ -46,11 +52,13 @@ Nix has the following basic data types: The second way to write string literals is as an *indented string*, which is enclosed between pairs of *double single-quotes*, like so: - '' - This is the first line. - This is the second line. - This is the third line. - '' + ```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 @@ -60,7 +68,9 @@ Nix has the following basic data types: line is indented four spaces. Thus, two spaces are stripped from each line, so the resulting string is - "This is the first line.\nThis is the second line.\n This is the third line.\n" + ```nix + "This is the first line.\nThis is the second line.\n This is the third line.\n" + ``` Note that the whitespace and newline following the opening `''` is ignored if there is no non-whitespace text on the initial line. @@ -82,17 +92,19 @@ Nix has the following basic data types: configuration files because `''` is much less common than `"`. Example: - 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 ""} - ''; - ... - } + ```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 @@ -136,13 +148,17 @@ Nix has the following basic data types: Lists are formed by enclosing a whitespace-separated list of values between square brackets. For example, - [ 123 ./foo.nix "abc" (f { x = y; }) ] +```nix +[ 123 ./foo.nix "abc" (f { x = y; }) ] +``` defines a list of four elements, the last being the result of a call to the function `f`. Note that function calls have to be enclosed in parentheses. If they had been omitted, e.g., - [ 123 ./foo.nix "abc" f { x = y; } ] +```nix +[ 123 ./foo.nix "abc" f { x = y; } ] +``` the result would be a list of five elements, the fourth one being a function and the fifth being a set. @@ -159,10 +175,12 @@ Sets are just a list of name/value pairs (called *attributes*) enclosed in curly brackets, where each value is an arbitrary expression terminated by a semicolon. For example: - { x = 123; - text = "Hello"; - y = f { bla = 456; }; - } +```nix +{ x = 123; + text = "Hello"; + y = f { bla = 456; }; +} +``` This defines a set with attributes named `x`, `text`, `y`. The order of the attributes is irrelevant. An attribute name may only occur once. @@ -170,24 +188,32 @@ the attributes is irrelevant. An attribute name may only occur once. Attributes can be selected from a set using the `.` operator. For instance, - { a = "Foo"; b = "Bar"; }.a +```nix +{ a = "Foo"; b = "Bar"; }.a +``` evaluates to `"Foo"`. It is possible to provide a default value in an attribute selection using the `or` keyword. For example, - { a = "Foo"; b = "Bar"; }.c or "Xyzzy" +```nix +{ a = "Foo"; b = "Bar"; }.c or "Xyzzy" +``` will evaluate to `"Xyzzy"` because there is no `c` attribute in the set. You can use arbitrary double-quoted strings as attribute names: - { "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" +```nix +{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" +``` This will evaluate to `123` (Assuming `bar` is antiquotable). In the case where an attribute name is just a single antiquotation, the quotes can be dropped: - { foo = 123; }.${bar} or 456 +```nix +{ foo = 123; }.${bar} or 456 +``` This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced to a string and `456` otherwise (again assuming `bar` is antiquotable). @@ -196,7 +222,9 @@ In the special case where an attribute name inside of a set declaration evaluates to `null` (which is normally an error, as `null` is not antiquotable), that attribute is simply not added to the set: - { ${if foo then "bar" else null} = true; } +```nix +{ ${if foo then "bar" else null} = true; } +``` This will evaluate to `{}` if `foo` evaluates to `false`. @@ -205,9 +233,11 @@ itself a function or a set with a `__functor` attribute whose value is callable) can be applied as if it were a function, with the set itself passed in first , e.g., - let add = { __functor = self: x: x + self.x; }; - inc = add // { x = 1; }; - in inc 1 +```nix +let add = { __functor = self: x: x + self.x; }; + inc = add // { x = 1; }; +in inc 1 +``` evaluates to `2`. This can be used to attach metadata to a function without the caller needing to treat it specially, or to implement a form -- cgit v1.2.3