about summary refs log tree commit diff
path: root/third_party/nix/doc/manual/expressions/language-values.xml
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/nix/doc/manual/expressions/language-values.xml')
-rw-r--r--third_party/nix/doc/manual/expressions/language-values.xml313
1 files changed, 0 insertions, 313 deletions
diff --git a/third_party/nix/doc/manual/expressions/language-values.xml b/third_party/nix/doc/manual/expressions/language-values.xml
deleted file mode 100644
index bb2090c881fd..000000000000
--- a/third_party/nix/doc/manual/expressions/language-values.xml
+++ /dev/null
@@ -1,313 +0,0 @@
-<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>