314 lines
11 KiB
XML
314 lines
11 KiB
XML
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
version="5.0"
|
|
xml:id='ssec-values'>
|
|
|
|
<title>Values</title>
|
|
|
|
|
|
<simplesect><title>Simple Values</title>
|
|
|
|
<para>Nix has the following basic data types:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para><emphasis>Strings</emphasis> can be written in three
|
|
ways.</para>
|
|
|
|
<para>The most common way is to enclose the string between double
|
|
quotes, e.g., <literal>"foo bar"</literal>. Strings can span
|
|
multiple lines. The special characters <literal>"</literal> and
|
|
<literal>\</literal> and the character sequence
|
|
<literal>${</literal> must be escaped by prefixing them with a
|
|
backslash (<literal>\</literal>). Newlines, carriage returns and
|
|
tabs can be written as <literal>\n</literal>,
|
|
<literal>\r</literal> and <literal>\t</literal>,
|
|
respectively.</para>
|
|
|
|
<para>You can include the result of an expression into a string by
|
|
enclosing it in
|
|
<literal>${<replaceable>...</replaceable>}</literal>, a feature
|
|
known as <emphasis>antiquotation</emphasis>. 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
|
|
|
|
<programlisting>
|
|
"--with-freetype2-library=" + freetype + "/lib"</programlisting>
|
|
|
|
(where <varname>freetype</varname> is a derivation), you can
|
|
instead write the more natural
|
|
|
|
<programlisting>
|
|
"--with-freetype2-library=${freetype}/lib"</programlisting>
|
|
|
|
The latter is automatically translated to the former. A more
|
|
complicated example (from the Nix expression for <link
|
|
xlink:href='http://www.trolltech.com/products/qt'>Qt</link>):
|
|
|
|
<programlisting>
|
|
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"}
|
|
";</programlisting>
|
|
|
|
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., <literal>"-thread"</literal>),
|
|
some of which in turn contain expressions (e.g.,
|
|
<literal>${mesa}</literal>).</para>
|
|
|
|
<para>The second way to write string literals is as an
|
|
<emphasis>indented string</emphasis>, which is enclosed between
|
|
pairs of <emphasis>double single-quotes</emphasis>, like so:
|
|
|
|
<programlisting>
|
|
''
|
|
This is the first line.
|
|
This is the second line.
|
|
This is the third line.
|
|
''</programlisting>
|
|
|
|
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
|
|
|
|
<programlisting>
|
|
"This is the first line.\nThis is the second line.\n This is the third line.\n"</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>Note that the whitespace and newline following the opening
|
|
<literal>''</literal> is ignored if there is no non-whitespace
|
|
text on the initial line.</para>
|
|
|
|
<para>Antiquotation
|
|
(<literal>${<replaceable>expr</replaceable>}</literal>) is
|
|
supported in indented strings.</para>
|
|
|
|
<para>Since <literal>${</literal> and <literal>''</literal> have
|
|
special meaning in indented strings, you need a way to quote them.
|
|
<literal>$</literal> can be escaped by prefixing it with
|
|
<literal>''</literal> (that is, two single quotes), i.e.,
|
|
<literal>''$</literal>. <literal>''</literal> can be escaped by
|
|
prefixing it with <literal>'</literal>, i.e.,
|
|
<literal>'''</literal>. <literal>$</literal> removes any special meaning
|
|
from the following <literal>$</literal>. Linefeed, carriage-return and tab
|
|
characters can be written as <literal>''\n</literal>,
|
|
<literal>''\r</literal>, <literal>''\t</literal>, and <literal>''\</literal>
|
|
escapes any other character.
|
|
|
|
</para>
|
|
|
|
<para>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 <literal>''</literal> is much less
|
|
common than <literal>"</literal>. Example:
|
|
|
|
<programlisting>
|
|
stdenv.mkDerivation {
|
|
<replaceable>...</replaceable>
|
|
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 ""}
|
|
'';
|
|
<replaceable>...</replaceable>
|
|
}
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>Finally, as a convenience, <emphasis>URIs</emphasis> as
|
|
defined in appendix B of <link
|
|
xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link>
|
|
can be written <emphasis>as is</emphasis>, without quotes. For
|
|
instance, the string
|
|
<literal>"http://example.org/foo.tar.bz2"</literal>
|
|
can also be written as
|
|
<literal>http://example.org/foo.tar.bz2</literal>.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem><para>Numbers, which can be <emphasis>integers</emphasis> (like
|
|
<literal>123</literal>) or <emphasis>floating point</emphasis> (like
|
|
<literal>123.43</literal> or <literal>.27e13</literal>).</para>
|
|
|
|
<para>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.</para></listitem>
|
|
|
|
<listitem><para><emphasis>Paths</emphasis>, e.g.,
|
|
<filename>/bin/sh</filename> or <filename>./builder.sh</filename>.
|
|
A path must contain at least one slash to be recognised as such; for
|
|
instance, <filename>builder.sh</filename> is not a
|
|
path<footnote><para>It's parsed as an expression that selects the
|
|
attribute <varname>sh</varname> from the variable
|
|
<varname>builder</varname>.</para></footnote>. 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
|
|
<filename>/foo/bar/bla.nix</filename> refers to
|
|
<filename>../xyzzy/fnord.nix</filename>, the absolute path is
|
|
<filename>/foo/xyzzy/fnord.nix</filename>.</para>
|
|
|
|
<para>If the first component of a path is a <literal>~</literal>,
|
|
it is interpreted as if the rest of the path were relative to the
|
|
user's home directory. e.g. <filename>~/foo</filename> would be
|
|
equivalent to <filename>/home/edolstra/foo</filename> for a user
|
|
whose home directory is <filename>/home/edolstra</filename>.
|
|
</para>
|
|
|
|
<para>Paths can also be specified between angle brackets, e.g.
|
|
<literal><nixpkgs></literal>. This means that the directories
|
|
listed in the environment variable
|
|
<envar linkend="env-NIX_PATH">NIX_PATH</envar> will be searched
|
|
for the given file or directory name.
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem><para><emphasis>Booleans</emphasis> with values
|
|
<literal>true</literal> and
|
|
<literal>false</literal>.</para></listitem>
|
|
|
|
<listitem><para>The null value, denoted as
|
|
<literal>null</literal>.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
|
<simplesect><title>Lists</title>
|
|
|
|
<para>Lists are formed by enclosing a whitespace-separated list of
|
|
values between square brackets. For example,
|
|
|
|
<programlisting>
|
|
[ 123 ./foo.nix "abc" (f { x = y; }) ]</programlisting>
|
|
|
|
defines a list of four elements, the last being the result of a call
|
|
to the function <varname>f</varname>. Note that function calls have
|
|
to be enclosed in parentheses. If they had been omitted, e.g.,
|
|
|
|
<programlisting>
|
|
[ 123 ./foo.nix "abc" f { x = y; } ]</programlisting>
|
|
|
|
the result would be a list of five elements, the fourth one being a
|
|
function and the fifth being a set.</para>
|
|
|
|
<para>Note that lists are only lazy in values, and they are strict in length.
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
|
<simplesect><title>Sets</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Sets are just a list of name/value pairs (called
|
|
<emphasis>attributes</emphasis>) enclosed in curly brackets, where
|
|
each value is an arbitrary expression terminated by a semicolon. For
|
|
example:
|
|
|
|
<programlisting>
|
|
{ x = 123;
|
|
text = "Hello";
|
|
y = f { bla = 456; };
|
|
}</programlisting>
|
|
|
|
This defines a set with attributes named <varname>x</varname>,
|
|
<varname>text</varname>, <varname>y</varname>. The order of the
|
|
attributes is irrelevant. An attribute name may only occur
|
|
once.</para>
|
|
|
|
<para>Attributes can be selected from a set using the
|
|
<literal>.</literal> operator. For instance,
|
|
|
|
<programlisting>
|
|
{ a = "Foo"; b = "Bar"; }.a</programlisting>
|
|
|
|
evaluates to <literal>"Foo"</literal>. It is possible to provide a
|
|
default value in an attribute selection using the
|
|
<literal>or</literal> keyword. For example,
|
|
|
|
<programlisting>
|
|
{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting>
|
|
|
|
will evaluate to <literal>"Xyzzy"</literal> because there is no
|
|
<varname>c</varname> attribute in the set.</para>
|
|
|
|
<para>You can use arbitrary double-quoted strings as attribute
|
|
names:
|
|
|
|
<programlisting>
|
|
{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
|
|
</programlisting>
|
|
|
|
This will evaluate to <literal>123</literal> (Assuming
|
|
<literal>bar</literal> is antiquotable). In the case where an
|
|
attribute name is just a single antiquotation, the quotes can be
|
|
dropped:
|
|
|
|
<programlisting>
|
|
{ foo = 123; }.${bar} or 456 </programlisting>
|
|
|
|
This will evaluate to <literal>123</literal> if
|
|
<literal>bar</literal> evaluates to <literal>"foo"</literal> when
|
|
coerced to a string and <literal>456</literal> otherwise (again
|
|
assuming <literal>bar</literal> is antiquotable).</para>
|
|
|
|
<para>In the special case where an attribute name inside of a set declaration
|
|
evaluates to <literal>null</literal> (which is normally an error, as
|
|
<literal>null</literal> is not antiquotable), that attribute is simply not
|
|
added to the set:
|
|
|
|
<programlisting>
|
|
{ ${if foo then "bar" else null} = true; }</programlisting>
|
|
|
|
This will evaluate to <literal>{}</literal> if <literal>foo</literal>
|
|
evaluates to <literal>false</literal>.</para>
|
|
|
|
<para>A set that has a <literal>__functor</literal> attribute whose value
|
|
is callable (i.e. is itself a function or a set with a
|
|
<literal>__functor</literal> attribute whose value is callable) can be
|
|
applied as if it were a function, with the set itself passed in first
|
|
, e.g.,
|
|
|
|
<programlisting>
|
|
let add = { __functor = self: x: x + self.x; };
|
|
inc = add // { x = 1; };
|
|
in inc 1
|
|
</programlisting>
|
|
|
|
evaluates to <literal>2</literal>. 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.
|
|
|
|
</para>
|
|
|
|
</simplesect>
|
|
|
|
|
|
</section>
|