about summary refs log tree commit diff
path: root/doc/manual/expressions/language-values.xml
blob: bb2090c881fd10d9f8fb64bbacc13e2b1526c8a0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
<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>&lt;nixpkgs&gt;</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>