mirror of
https://github.com/NixOS/nix
synced 2025-07-06 21:41:48 +02:00
Rename "attribute sets" to "sets"
We don't have any other kind of sets so calling them attribute sets is unnecessarily verbose.
This commit is contained in:
Eelco Dolstra
parent
9e4bb20455
commit
5bc41d78ff
13 changed files with 152 additions and 160 deletions
|
|
@ -12,9 +12,9 @@ such as <function>derivation</function>, are always in scope of every
|
|||
Nix expression; you can just access them right away. But to prevent
|
||||
polluting the namespace too much, most built-ins are not in scope.
|
||||
Instead, you can access them through the <varname>builtins</varname>
|
||||
built-in value, which is an attribute set that contains all built-in
|
||||
functions and values. For instance, <function>derivation</function>
|
||||
is also available as <function>builtins.derivation</function>.</para>
|
||||
built-in value, which is a set that contains all built-in functions
|
||||
and values. For instance, <function>derivation</function> is also
|
||||
available as <function>builtins.derivation</function>.</para>
|
||||
|
||||
|
||||
<variablelist>
|
||||
|
|
@ -39,14 +39,14 @@ is also available as <function>builtins.derivation</function>.</para>
|
|||
|
||||
|
||||
<varlistentry><term><function>builtins.attrNames</function>
|
||||
<replaceable>attrs</replaceable></term>
|
||||
<replaceable>set</replaceable></term>
|
||||
|
||||
<listitem><para>Return the names of the attributes in the
|
||||
attribute set <replaceable>attrs</replaceable> in a sorted list.
|
||||
For instance, <literal>builtins.attrNames { y = 1; x = "foo";
|
||||
}</literal> evaluates to <literal>[ "x" "y" ]</literal>. There is
|
||||
no built-in function <function>attrValues</function>, but you can
|
||||
easily define it yourself:
|
||||
<listitem><para>Return the names of the attributes in the set
|
||||
<replaceable>set</replaceable> in a sorted list. For instance,
|
||||
<literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
|
||||
evaluates to <literal>[ "x" "y" ]</literal>. There is no built-in
|
||||
function <function>attrValues</function>, but you can easily
|
||||
define it yourself:
|
||||
|
||||
<programlisting>
|
||||
attrValues = attrs: map (name: builtins.getAttr name attrs) (builtins.attrNames attrs);</programlisting>
|
||||
|
|
@ -68,8 +68,8 @@ attrValues = attrs: map (name: builtins.getAttr name attrs) (builtins.attrNames
|
|||
|
||||
<varlistentry><term><varname>builtins</varname></term>
|
||||
|
||||
<listitem><para>The attribute set <varname>builtins</varname>
|
||||
contains all the built-in functions and values. You can use
|
||||
<listitem><para>The set <varname>builtins</varname> contains all
|
||||
the built-in functions and values. You can use
|
||||
<varname>builtins</varname> to test for the availability of
|
||||
features in the Nix installation, e.g.,
|
||||
|
||||
|
|
@ -258,11 +258,11 @@ stdenv.mkDerivation {
|
|||
|
||||
|
||||
<varlistentry><term><function>builtins.getAttr</function>
|
||||
<replaceable>s</replaceable> <replaceable>attrs</replaceable></term>
|
||||
<replaceable>s</replaceable> <replaceable>set</replaceable></term>
|
||||
|
||||
<listitem><para><function>getAttr</function> returns the attribute
|
||||
named <replaceable>s</replaceable> from the attribute set
|
||||
<replaceable>attrs</replaceable>. Evaluation aborts if the
|
||||
named <replaceable>s</replaceable> from
|
||||
<replaceable>set</replaceable>. Evaluation aborts if the
|
||||
attribute doesn’t exist. This is a dynamic version of the
|
||||
<literal>.</literal> operator, since <replaceable>s</replaceable>
|
||||
is an expression rather than an identifier.</para></listitem>
|
||||
|
|
@ -289,15 +289,15 @@ stdenv.mkDerivation {
|
|||
|
||||
|
||||
<varlistentry><term><function>builtins.hasAttr</function>
|
||||
<replaceable>s</replaceable> <replaceable>attrs</replaceable></term>
|
||||
<replaceable>s</replaceable> <replaceable>set</replaceable></term>
|
||||
|
||||
<listitem><para><function>hasAttr</function> returns
|
||||
<literal>true</literal> if the attribute set
|
||||
<replaceable>attrs</replaceable> has an attribute named
|
||||
<replaceable>s</replaceable>, and <literal>false</literal>
|
||||
otherwise. This is a dynamic version of the <literal>?</literal>
|
||||
operator, since <replaceable>s</replaceable> is an expression
|
||||
rather than an identifier.</para></listitem>
|
||||
<literal>true</literal> if <replaceable>set</replaceable> has an
|
||||
attribute named <replaceable>s</replaceable>, and
|
||||
<literal>false</literal> otherwise. This is a dynamic version of
|
||||
the <literal>?</literal> operator, since
|
||||
<replaceable>s</replaceable> is an expression rather than an
|
||||
identifier.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -331,12 +331,12 @@ stdenv.mkDerivation {
|
|||
<listitem><para>Load, parse and return the Nix expression in the
|
||||
file <replaceable>path</replaceable>. If <replaceable>path
|
||||
</replaceable> is a directory, the file <filename>default.nix
|
||||
</filename> in that directory is loaded. Evaluation aborts if
|
||||
the file doesn’t exist or contains an incorrect Nix
|
||||
expression. <function>import</function> implements Nix’s module
|
||||
system: you can put any Nix expression (such as an attribute set
|
||||
or a function) in a separate file, and use it from Nix expressions
|
||||
in other files.</para>
|
||||
</filename> in that directory is loaded. Evaluation aborts if the
|
||||
file doesn’t exist or contains an incorrect Nix expression.
|
||||
<function>import</function> implements Nix’s module system: you
|
||||
can put any Nix expression (such as a set or a function) in a
|
||||
separate file, and use it from Nix expressions in other
|
||||
files.</para>
|
||||
|
||||
<para>A Nix expression loaded by <function>import</function> must
|
||||
not contain any <emphasis>free variables</emphasis> (identifiers
|
||||
|
|
@ -383,9 +383,9 @@ x: x + 456</programlisting>
|
|||
<varlistentry><term><function>builtins.intersectAttrs</function>
|
||||
<replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
|
||||
|
||||
<listitem><para>Return an attribute set consisting of the
|
||||
attributes in the set <replaceable>e2</replaceable> that also
|
||||
exist in the set <replaceable>e1</replaceable>.</para></listitem>
|
||||
<listitem><para>Return a set consisting of the attributes in the
|
||||
set <replaceable>e2</replaceable> that also exist in the set
|
||||
<replaceable>e1</replaceable>.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
|
@ -394,7 +394,7 @@ x: x + 456</programlisting>
|
|||
<replaceable>e</replaceable></term>
|
||||
|
||||
<listitem><para>Return <literal>true</literal> if
|
||||
<replaceable>e</replaceable> evaluates to an attribute set, and
|
||||
<replaceable>e</replaceable> evaluates to a set, and
|
||||
<literal>false</literal> otherwise.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
|
@ -490,9 +490,9 @@ x: x + 456</programlisting>
|
|||
<varlistentry><term><function>builtins.listToAttrs</function>
|
||||
<replaceable>e</replaceable></term>
|
||||
|
||||
<listitem><para>Construct an attribute set from a list specifying
|
||||
the names and values of each attribute. Each element of the list
|
||||
should be an attribute set consisting of a string-valued attribute
|
||||
<listitem><para>Construct a set from a list specifying the names
|
||||
and values of each attribute. Each element of the list should be
|
||||
a set consisting of a string-valued attribute
|
||||
<varname>name</varname> specifying the name of the attribute, and
|
||||
an attribute <varname>value</varname> specifying its value.
|
||||
Example:
|
||||
|
|
@ -547,7 +547,7 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
|
|||
a package name and version. The package name is everything up to
|
||||
but not including the first dash followed by a digit, and the
|
||||
version is everything following that dash. The result is returned
|
||||
in an attribute set <literal>{ name, version }</literal>. Thus,
|
||||
in a set <literal>{ name, version }</literal>. Thus,
|
||||
<literal>builtins.parseDrvName "nix-0.12pre12876"</literal>
|
||||
returns <literal>{ name = "nix"; version = "0.12pre12876";
|
||||
}</literal>.</para></listitem>
|
||||
|
|
@ -598,12 +598,12 @@ in config.someSetting</programlisting>
|
|||
|
||||
|
||||
<varlistentry><term><function>removeAttrs</function>
|
||||
<replaceable>attrs</replaceable> <replaceable>list</replaceable></term>
|
||||
<replaceable>set</replaceable> <replaceable>list</replaceable></term>
|
||||
|
||||
<listitem><para>Remove the attributes listed in
|
||||
<replaceable>list</replaceable> from the attribute set
|
||||
<replaceable>attrs</replaceable>. The attributes don’t have to
|
||||
exist in <replaceable>attrs</replaceable>. For instance,
|
||||
<replaceable>list</replaceable> from
|
||||
<replaceable>set</replaceable>. The attributes don’t have to
|
||||
exist in <replaceable>set</replaceable>. For instance,
|
||||
|
||||
<screen>
|
||||
removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</screen>
|
||||
|
|
@ -792,7 +792,7 @@ in foo</programlisting>
|
|||
servlet container</link>. A servlet container contains a number
|
||||
of servlets (<filename>*.war</filename> files) each exported under
|
||||
a specific URI prefix. So the servlet configuration is a list of
|
||||
attribute sets containing the <varname>path</varname> and
|
||||
sets containing the <varname>path</varname> and
|
||||
<varname>war</varname> of the servlet (<xref
|
||||
linkend='ex-toxml-co-servlets' />). This kind of information is
|
||||
difficult to communicate with the normal method of passing
|
||||
|
|
|
|||
|
|
@ -153,11 +153,10 @@ also <xref linkend="sec-common-options" />.</phrase></para>
|
|||
default.</para>
|
||||
|
||||
<para>The Nix expressions in this directory are combined into a
|
||||
single attribute set, with each file as an attribute that has the
|
||||
name of the file. Thus, if <filename>~/.nix-defexpr</filename>
|
||||
contains two files, <filename>foo</filename> and
|
||||
<filename>bar</filename>, then the default Nix expression will
|
||||
essentially be
|
||||
single set, with each file as an attribute that has the name of
|
||||
the file. Thus, if <filename>~/.nix-defexpr</filename> contains
|
||||
two files, <filename>foo</filename> and <filename>bar</filename>,
|
||||
then the default Nix expression will essentially be
|
||||
|
||||
<programlisting>
|
||||
{
|
||||
|
|
@ -405,7 +404,7 @@ $ nix-env -f ./foo.nix -i -E \
|
|||
I.e., this evaluates to <literal>(f: (f {system =
|
||||
"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus
|
||||
selecting the <literal>subversionWithJava</literal> attribute from the
|
||||
attribute set returned by calling the function defined in
|
||||
set returned by calling the function defined in
|
||||
<filename>./foo.nix</filename>.</para>
|
||||
|
||||
<para>A dry-run tells you which paths will be downloaded or built from
|
||||
|
|
|
|||
|
|
@ -118,10 +118,10 @@ the single Nix expression in that directory
|
|||
<varname>stdenv.mkDerivation</varname>.
|
||||
<varname>mkDerivation</varname> is a function provided by
|
||||
<varname>stdenv</varname> that builds a package from a set of
|
||||
<emphasis>attributes</emphasis>. An attribute set is just a list
|
||||
of key/value pairs where each value is an arbitrary Nix
|
||||
expression. They take the general form
|
||||
<literal>{ <replaceable>name1</replaceable> =
|
||||
<emphasis>attributes</emphasis>. A set is just a list of
|
||||
key/value pairs where each key is a string and each value is an
|
||||
arbitrary Nix expression. They take the general form <literal>{
|
||||
<replaceable>name1</replaceable> =
|
||||
<replaceable>expr1</replaceable>; <replaceable>...</replaceable>
|
||||
<replaceable>nameN</replaceable> =
|
||||
<replaceable>exprN</replaceable>; }</literal>.</para>
|
||||
|
|
@ -384,9 +384,9 @@ some fragments of
|
|||
|
||||
<para>This is where the actual composition takes place. Here we
|
||||
<emphasis>call</emphasis> the function imported from
|
||||
<filename>../applications/misc/hello/ex-1</filename> with an
|
||||
attribute set containing the things that the function expects,
|
||||
namely <varname>fetchurl</varname>, <varname>stdenv</varname>, and
|
||||
<filename>../applications/misc/hello/ex-1</filename> with a set
|
||||
containing the things that the function expects, namely
|
||||
<varname>fetchurl</varname>, <varname>stdenv</varname>, and
|
||||
<varname>perl</varname>. We use inherit again to use the
|
||||
attributes defined in the surrounding scope (we could also have
|
||||
written <literal>fetchurl = fetchurl;</literal>, etc.).</para>
|
||||
|
|
@ -805,20 +805,21 @@ to be enclosed in parentheses. If they had been omitted, e.g.,
|
|||
[ 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 an attribute set.</para>
|
||||
function and the fifth being a set.</para>
|
||||
|
||||
</simplesect>
|
||||
|
||||
|
||||
<simplesect><title>Attribute sets</title>
|
||||
<simplesect><title>Sets</title>
|
||||
|
||||
<para>Attribute sets are really the core of the language, since
|
||||
ultimately it's all about creating derivations, which are really just
|
||||
<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>Attribute sets are just a list of name/value pairs enclosed in
|
||||
curly brackets, where each value is an arbitrary expression terminated
|
||||
by a semicolon. For example:
|
||||
<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;
|
||||
|
|
@ -826,12 +827,12 @@ by a semicolon. For example:
|
|||
y = f { bla = 456; };
|
||||
}</programlisting>
|
||||
|
||||
This defines an attribute 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>
|
||||
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 an attribute set using the
|
||||
<para>Attributes can be selected from a set using the
|
||||
<literal>.</literal> operator. For instance,
|
||||
|
||||
<programlisting>
|
||||
|
|
@ -864,10 +865,10 @@ This will evaluate to <literal>123</literal>.</para>
|
|||
<section><title>Language constructs</title>
|
||||
|
||||
|
||||
<simplesect><title>Recursive attribute sets</title>
|
||||
<simplesect><title>Recursive sets</title>
|
||||
|
||||
<para>Recursive attribute sets are just normal attribute sets, but the
|
||||
attributes can refer to each other. For example,
|
||||
<para>Recursive sets are just normal sets, but the attributes can
|
||||
refer to each other. For example,
|
||||
|
||||
<programlisting>
|
||||
rec {
|
||||
|
|
@ -880,11 +881,11 @@ evaluates to <literal>123</literal>. Note that without
|
|||
<literal>rec</literal> the binding <literal>x = y;</literal> would
|
||||
refer to the variable <varname>y</varname> in the surrounding scope,
|
||||
if one exists, and would be invalid if no such variable exists. That
|
||||
is, in a normal (non-recursive) attribute set, attributes are not
|
||||
added to the lexical scope; in a recursive set, they are.</para>
|
||||
is, in a normal (non-recursive) set, attributes are not added to the
|
||||
lexical scope; in a recursive set, they are.</para>
|
||||
|
||||
<para>Recursive attribute sets of course introduce the danger of
|
||||
infinite recursion. For example,
|
||||
<para>Recursive sets of course introduce the danger of infinite
|
||||
recursion. For example,
|
||||
|
||||
<programlisting>
|
||||
rec {
|
||||
|
|
@ -918,16 +919,16 @@ evaluates to <literal>"foobar"</literal>.
|
|||
<literal>let { <replaceable>attrs</replaceable> }</literal>, which is
|
||||
translated to <literal>rec { <replaceable>attrs</replaceable>
|
||||
}.body</literal>. That is, the body of the let-expression is the
|
||||
<literal>body</literal> attribute of the attribute set.</para></note>
|
||||
<literal>body</literal> attribute of the set.</para></note>
|
||||
|
||||
</simplesect>
|
||||
|
||||
|
||||
<simplesect><title>Inheriting attributes</title>
|
||||
|
||||
<para>When defining an attribute set it is often convenient to copy
|
||||
variables from the surrounding lexical scope (e.g., when you want to
|
||||
propagate attributes). This can be shortened using the
|
||||
<para>When defining a set it is often convenient to copy variables
|
||||
from the surrounding lexical scope (e.g., when you want to propagate
|
||||
attributes). This can be shortened using the
|
||||
<literal>inherit</literal> keyword. For instance,
|
||||
|
||||
<programlisting>
|
||||
|
|
@ -936,10 +937,10 @@ let x = 123; in
|
|||
y = 456;
|
||||
}</programlisting>
|
||||
|
||||
evaluates to <literal>{ x = 123; y = 456; }</literal>. (Note that this
|
||||
works because <varname>x</varname> is added to the lexical scope by
|
||||
the <literal>let</literal> construct.) It is also possible to inherit
|
||||
attributes from another attribute set. For instance, in this fragment
|
||||
evaluates to <literal>{ x = 123; y = 456; }</literal>. (Note that
|
||||
this works because <varname>x</varname> is added to the lexical scope
|
||||
by the <literal>let</literal> construct.) It is also possible to
|
||||
inherit attributes from another set. For instance, in this fragment
|
||||
from <filename>all-packages.nix</filename>,
|
||||
|
||||
<programlisting>
|
||||
|
|
@ -958,13 +959,12 @@ from <filename>all-packages.nix</filename>,
|
|||
libjpg = ...;
|
||||
...</programlisting>
|
||||
|
||||
the attribute set used in the function call to the function defined in
|
||||
the set used in the function call to the function defined in
|
||||
<filename>../tools/graphics/graphviz</filename> inherits a number of
|
||||
variables from the surrounding scope (<varname>fetchurl</varname>
|
||||
... <varname>yacc</varname>), but also inherits
|
||||
<varname>libXaw</varname> (the X Athena Widgets) from the
|
||||
<varname>xlibs</varname> (X11 client-side libraries) attribute
|
||||
set.</para>
|
||||
<varname>xlibs</varname> (X11 client-side libraries) set.</para>
|
||||
|
||||
</simplesect>
|
||||
|
||||
|
|
@ -1003,11 +1003,11 @@ map (concat "foo") [ "bar" "bla" "abc" ]</programlisting>
|
|||
"fooabc" ]</literal>.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>An <emphasis>attribute set pattern</emphasis> of the
|
||||
form <literal>{ name1, name2, …, nameN }</literal>
|
||||
matches an attribute set containing the listed attributes, and binds
|
||||
the values of those attributes to variables in the function body.
|
||||
For example, the function
|
||||
<listitem><para>A <emphasis>set pattern</emphasis> of the form
|
||||
<literal>{ name1, name2, …, nameN }</literal> matches a set
|
||||
containing the listed attributes, and binds the values of those
|
||||
attributes to variables in the function body. For example, the
|
||||
function
|
||||
|
||||
<programlisting>
|
||||
{ x, y, z }: z + y + x</programlisting>
|
||||
|
|
@ -1174,9 +1174,8 @@ used in the Nix expression for Subversion.</para>
|
|||
<programlisting>
|
||||
with <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
|
||||
|
||||
introduces the attribute set <replaceable>e1</replaceable> into the
|
||||
lexical scope of the expression <replaceable>e2</replaceable>. For
|
||||
instance,
|
||||
introduces the set <replaceable>e1</replaceable> into the lexical
|
||||
scope of the expression <replaceable>e2</replaceable>. For instance,
|
||||
|
||||
<programlisting>
|
||||
let as = { x = "foo"; y = "bar"; };
|
||||
|
|
@ -1235,7 +1234,7 @@ weakest binding).</para>
|
|||
</entry>
|
||||
<entry>none</entry>
|
||||
<entry>Select attribute denoted by the attribute path
|
||||
<replaceable>attrpath</replaceable> from attribute set
|
||||
<replaceable>attrpath</replaceable> from set
|
||||
<replaceable>e</replaceable>. (An attribute path is a
|
||||
dot-separated list of attribute names.) If the attribute
|
||||
doesn’t exist, return <replaceable>def</replaceable> if
|
||||
|
|
@ -1251,8 +1250,8 @@ weakest binding).</para>
|
|||
<entry><replaceable>e</replaceable> <literal>?</literal>
|
||||
<replaceable>attrpath</replaceable></entry>
|
||||
<entry>none</entry>
|
||||
<entry>Test whether attribute set <replaceable>e</replaceable>
|
||||
contains the attribute denoted by <replaceable>attrpath</replaceable>;
|
||||
<entry>Test whether set <replaceable>e</replaceable> contains
|
||||
the attribute denoted by <replaceable>attrpath</replaceable>;
|
||||
return <literal>true</literal> or
|
||||
<literal>false</literal>.</entry>
|
||||
</row>
|
||||
|
|
@ -1275,10 +1274,11 @@ weakest binding).</para>
|
|||
<entry><replaceable>e1</replaceable> <literal>//</literal>
|
||||
<replaceable>e2</replaceable></entry>
|
||||
<entry>right</entry>
|
||||
<entry>Return an attribute set consisting of the attributes in
|
||||
<entry>Return a set consisting of the attributes in
|
||||
<replaceable>e1</replaceable> and
|
||||
<replaceable>e2</replaceable> (with the latter taking
|
||||
precedence over the former in case of equally named attributes).</entry>
|
||||
precedence over the former in case of equally named
|
||||
attributes).</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><replaceable>e1</replaceable> <literal>==</literal>
|
||||
|
|
@ -1322,9 +1322,9 @@ weakest binding).</para>
|
|||
<section xml:id="ssec-derivation"><title>Derivations</title>
|
||||
|
||||
<para>The most important built-in function is
|
||||
<function>derivation</function>, which is used to describe a
|
||||
single derivation (a build action). It takes as input an attribute
|
||||
set, the attributes of which specify the inputs of the build.</para>
|
||||
<function>derivation</function>, which is used to describe a single
|
||||
derivation (a build action). It takes as input a set, the attributes
|
||||
of which specify the inputs of the build.</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue