From 3e9d2038b46cc479a97f0c0e0f280b2f83b3c544 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 5 Nov 2004 15:39:30 +0000 Subject: [PATCH] * Start of language reference. --- doc/manual/writing-nix-expressions.xml | 228 +++++++++++++++++++++++++ 1 file changed, 228 insertions(+) diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index d3514b625..b6f426d66 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -499,6 +499,234 @@ run in parallel. Typically this should be the number of CPUs. +The generic builder + +TODO + + + + + + + + +The Nix expression language + +The Nix expression language is a pure, lazy, functional +language. Purity means that operations in the language don't have +side-effects (for instance, there is no variable assignment). +Laziness means that arguments to functions are evaluated only when +they are needed. Functional means that functions are +normal values that can be passed around and +manipulated in interesting ways. + +The language is not a full-featured, general purpose language. +It's main job is to describe components, compositions of components, +and the variability within components. For this a functional language +is perfectly suited. + +This section presents the various features of the +language. + + +Simple values + +Nix has the following basic datatypes: + + + + Strings, enclosed between + double quotes, e.g., "foo bar". + + Integers, e.g., + 123. + + URIs as defined in appendix B + of RFC + 2396, e.g., + https://svn.cs.uu.nl:12443/dist/trace/trace-nix-trunk.tar.bz2. + + 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 + pathIt's parsed as an expression that selects the + attribute sh from the variable + builder.. If the filename 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 absolutised path is + /foo/xyzzy/fnord.nix. + + + + + + + + +Lists + +Lists are formed by enclosing a whitespace-separated list of +values between square bracktes. 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 an attribute set. + + + + +Attribute sets + +Attribute sets are really the core of the language, since +ultimately it's all about creating derivations, which are really just +sets of attributes to be passed to build scripts. + +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: + + +{ x = 123; + text = "Hello"; + y = f { bla = 456; }; +} + +This defines an attribute set with attributes named +x, test, y. +The order of the attributes is irrelevant. An attribute name may only +occur once. + +Attributes can be selected from an attribute set using the +. operator. For instance, + + +{ a = "Foo"; b = "Bar"; }.a + +evaluates to "Foo". + + + + +Recursive attribute sets + +Recursive attribute sets are just normal attribute sets, but the +attributes can refer to each other. For example, + + +rec { + x = y; + y = 123; +}.x + + +evaluates to 123. Note that without +rec the binding x = y; would +refer to the variable y 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. + +Recursive attribute sets of course introduce the danger of +infinite recursion. For example, + + +rec { + x = y; + y = x; +}.x + +does not terminateActually, Nix detects infinite +recursion in this case and aborts (infinite recursion +encountered).. + + + + + + +Lets + +TODO + + + + +Inheriting attributes + +TODO + + + + +Functions + +TODO + +Higher-order functions; map + + + + +Conditionals + +TODO + + + + +<quote>With</quote> expressions + +TODO + + + + +Operators + +TODO + + + + +Derivations + +TODO + + + + +Miscelleneous built-in functions + +TODO + + + + + + + + +The standard environment + +TODO +