nix-instantiate: Add a flag --expr / -E to read expressions from the command line

This is basically a shortcut for ‘echo 'expr...' | nix-instantiate -’.
Also supported by nix-build and nix-shell.

4 files changed, 126 insertions, 86 deletions

diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 969faf9d1..3832f5fc3 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -164,6 +164,16 @@ $ nix-build '<nixpkgs>' -A openssl.man
 </screen>
 This will create a symlink <literal>result-man</literal>.</para>
 
+<para>Build a Nix expression given on the command line:
+
+<screen>
+$ nix-build -E 'with import &lt;nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
+$ cat ./result
+bar
+</screen>
+
+</para>
+
 </refsection>
 
 
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index a3d67debe..a780302e1 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -2,7 +2,7 @@
           xmlns:xlink="http://www.w3.org/1999/xlink"
           xmlns:xi="http://www.w3.org/2001/XInclude"
           xml:id="sec-nix-instantiate">
-  
+
 <refmeta>
   <refentrytitle>nix-instantiate</refentrytitle>
   <manvolnum>1</manvolnum>
@@ -18,7 +18,15 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-instantiate</command>
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
+    <group>
+      <arg choice='plain'><option>--parse-only</option></arg>
+      <arg choice='plain'>
+        <option>--eval-only</option>
+        <arg><option>--strict</option></arg>
+        <arg><option>--xml</option></arg>
+      </arg>
+    </group>
+    <arg><option>--read-write-mode</option></arg>
     <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
     <arg>
       <group choice='req'>
@@ -29,18 +37,14 @@
     </arg>
     <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
     <arg><option>--indirect</option></arg>
-    <arg>
-      <group choice='req'>
-        <arg choice='plain'><option>--parse-only</option></arg>
-        <arg choice='plain'>
-          <option>--eval-only</option>
-          <arg><option>--strict</option></arg>
-          <arg><option>--read-write-mode</option></arg>
-        </arg>
-        <arg choice='plain'><option>--find-file</option></arg>
-      </group>
-      <arg><option>--xml</option></arg>
-    </arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--expr</option></arg>
+      <arg choice='plain'><option>-E</option></arg>
+    </group>
+    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
+    <sbr/>
+    <command>nix-instantiate</command>
+    <arg choice='plain'><option>--file-file</option></arg>
     <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
@@ -50,8 +54,8 @@
 
 <para>The command <command>nix-instantiate</command> generates <link
 linkend="gloss-derivation">store derivations</link> from (high-level)
-Nix expressions.  It loads and evaluates the Nix expressions in each
-of <replaceable>files</replaceable> (which defaults to
+Nix expressions.  It evaluates the Nix expressions in each of
+<replaceable>files</replaceable> (which defaults to
 <replaceable>./default.nix</replaceable>).  Each top-level expression
 should evaluate to a derivation, a list of derivations, or a set of
 derivations.  The paths of the resulting store derivations are printed
@@ -61,12 +65,6 @@ on standard output.</para>
 <literal>-</literal>, then a Nix expression will be read from standard
 input.</para>
 
-<para>Most users and developers don’t need to use this command
-(<command>nix-env</command> and <command>nix-build</command> perform
-store derivation instantiation from Nix expressions automatically).
-It is most commonly used for implementing new deployment
-policies.</para>
-
 <para condition="manual">See also <xref linkend="sec-common-options"
 /> for a list of common options.</para>
 
@@ -86,25 +84,24 @@ policies.</para>
 
   </varlistentry>
 
-    
   <varlistentry><term><option>--parse-only</option></term>
-  
+
     <listitem><para>Just parse the input files, and print their
     abstract syntax trees on standard output in ATerm
     format.</para></listitem>
-    
+
   </varlistentry>
-      
+
   <varlistentry><term><option>--eval-only</option></term>
-  
+
     <listitem><para>Just parse and evaluate the input files, and print
     the resulting values on standard output.  No instantiation of
     store derivations takes place.</para></listitem>
-    
+
   </varlistentry>
 
   <varlistentry><term><option>--find-file</option></term>
-  
+
     <listitem><para>Look up the given files in Nix’s search path (as
     specified by the <envar>NIX_PATH</envar> environment variable).
     If found, print the corresponding absolute paths on standard
@@ -113,9 +110,9 @@ policies.</para>
     <literal>nix-instantiate --find-file nixpkgs/default.nix</literal>
     will print
     <literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem>
-    
+
   </varlistentry>
-      
+
   <varlistentry><term><option>--xml</option></term>
 
     <listitem><para>When used with <option>--parse-only</option> and
@@ -180,19 +177,34 @@ dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
 
 </para>
 
+<para>You can also give a Nix expression on the command line:
+
+<screen>
+$ nix-instantiate -E 'with import &lt;nixpkgs> { }; hello'
+/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
+</screen>
+
+This is equivalent to:
+
+<screen>
+$ nix-instantiate '&lt;nixpkgs>' -A hello
+</screen>
+
+</para>
+
 <para>Parsing and evaluating Nix expressions:
 
 <screen>
-$ echo '"foo" + "bar"' | nix-instantiate --parse-only -
-OpPlus(Str("foo"),Str("bar"))
+$ nix-instantiate --parse-only -E '1 + 2'
+1 + 2
 
-$ echo '"foo" + "bar"' | nix-instantiate --eval-only -
-Str("foobar")
+$ nix-instantiate --eval-only -E '1 + 2'
+3
 
-$ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml -
+$ nix-instantiate --eval-only --xml -E '1 + 2'
 <![CDATA[<?xml version='1.0' encoding='utf-8'?>
 <expr>
-  <string value="foobar" />
+  <int value="3" />
 </expr>]]></screen>
 
 </para>
@@ -200,28 +212,28 @@ $ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml -
 <para>The difference between non-strict and strict evaluation:
 
 <screen>
-$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml -
+$ nix-instantiate --eval-only --xml -E 'rec { x = "foo"; y = x; }'
 <replaceable>...</replaceable><![CDATA[
-    <attr name="x">
-      <string value="foo" />
-    </attr>
-    <attr name="y">
-      <unevaluated />
-    </attr>]]>
+  <attr name="x">
+    <string value="foo" />
+  </attr>
+  <attr name="y">
+    <unevaluated />
+  </attr>]]>
 <replaceable>...</replaceable></screen>
 
 Note that <varname>y</varname> is left unevaluated (the XML
 representation doesn’t attempt to show non-normal forms).
 
 <screen>
-$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict -
+$ nix-instantiate --eval-only --xml --strict -E 'rec { x = "foo"; y = x; }'
 <replaceable>...</replaceable><![CDATA[
-    <attr name="x">
-      <string value="foo" />
-    </attr>
-    <attr name="y">
-      <string value="foo" />
-    </attr>]]>
+  <attr name="x">
+    <string value="foo" />
+  </attr>
+  <attr name="y">
+    <string value="foo" />
+  </attr>]]>
 <replaceable>...</replaceable></screen>
 
 </para>
@@ -236,6 +248,6 @@ $ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict
 </variablelist>
 
 </refsection>
-  
+
 
 </refentry>
diff --git a/doc/manual/nix-shell.xml b/doc/manual/nix-shell.xml
index 4b369662e..8178cea69 100644
--- a/doc/manual/nix-shell.xml
+++ b/doc/manual/nix-shell.xml
@@ -61,11 +61,11 @@ the derivation attribute
 <programlisting>
 shellHook =
   ''
-    echo "Hello shell!"
+    echo "Hello shell"
   '';
 </programlisting>
 
-will cause <command>nix-shell</command> to print <literal>Hello shell!</literal>.</para>
+will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para>
 
 </refsection>
 
@@ -132,11 +132,11 @@ interactive shell in which to build it:
 
 <screen>
 $ nix-shell '&lt;nixpkgs>' -A pan
-$ unpackPhase
-$ cd pan-*
-$ configurePhase
-$ buildPhase
-$ ./pan/gui/pan
+[nix-shell]$ unpackPhase
+[nix-shell]$ cd pan-*
+[nix-shell]$ configurePhase
+[nix-shell]$ buildPhase
+[nix-shell]$ ./pan/gui/pan
 </screen>
 
 To clear the environment first, and do some additional automatic
@@ -147,6 +147,14 @@ $ nix-shell '&lt;nixpkgs>' -A pan --pure \
     --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
 </screen>
 
+Nix expressions can also be given on the command line.  For instance,
+the following starts a shell containing the packages
+<literal>sqlite</literal> and <literal>libX11</literal>:
+
+<screen>
+$ nix-shell -E 'with import &lt;nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
+</screen>
+
 </para>
 
 </refsection>
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index a877b536a..f8584f4d6 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -8,15 +8,15 @@
 <variablelist xml:id="opt-common">
 
 <varlistentry><term><option>--help</option></term>
-  
+
   <listitem><para>Prints out a summary of the command syntax and
   exits.</para></listitem>
-  
+
 </varlistentry>
 
 
 <varlistentry><term><option>--version</option></term>
-  
+
   <listitem><para>Prints out the Nix version number on standard output
   and exits.</para></listitem>
 </varlistentry>
@@ -26,7 +26,7 @@
   <term><option>-v</option></term>
 
   <listitem>
-    
+
   <para>Increases the level of verbosity of diagnostic messages
   printed on standard error.  For each Nix operation, the information
   printed on standard output is well-defined; any diagnostic
@@ -37,18 +37,18 @@
   following verbosity levels exist:</para>
 
   <variablelist>
-    
+
     <varlistentry><term>0</term>
     <listitem><para>“Errors only”: only print messages
     explaining why the Nix invocation failed.</para></listitem>
     </varlistentry>
-      
+
     <varlistentry><term>1</term>
     <listitem><para>“Informational”: print
     <emphasis>useful</emphasis> messages about what Nix is doing.
     This is the default.</para></listitem>
     </varlistentry>
-      
+
     <varlistentry><term>2</term>
     <listitem><para>“Talkative”: print more informational
     messages.</para></listitem>
@@ -68,11 +68,11 @@
     <listitem><para>“Vomit”: print vast amounts of debug
     information.</para></listitem>
     </varlistentry>
-    
+
   </variablelist>
 
   </listitem>
-  
+
 </varlistentry>
 
 
@@ -85,7 +85,7 @@
   builder's standard output and error are always written to a log file
   in
   <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -99,7 +99,7 @@
   configuration setting, which itself defaults to
   <literal>1</literal>.  A higher value is useful on SMP systems or to
   exploit I/O latency.</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -117,7 +117,7 @@
   configuration setting, if set, or <literal>1</literal> otherwise.
   The value <literal>0</literal> means that the builder should use all
   available CPU cores in the system.</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -151,7 +151,7 @@
   derivation itself.  Without this option, Nix stops if any build
   fails (except for builds of substitutes), possibly killing builds in
   progress (in case of parallel or distributed builds).</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -188,7 +188,7 @@
   resources).</para>
 
   </listitem>
-  
+
 </varlistentry>
 
 
@@ -197,7 +197,7 @@
   <listitem><para>When this option is used, no attempt is made to open
   the Nix database.  Most Nix operations do need database access, so
   those operations will fail.</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -247,12 +247,12 @@
 
     </varlistentry>
 
-  </variablelist>    
-  
+  </variablelist>
+
   </para>
 
   </listitem>
-  
+
 </varlistentry>
 
 
@@ -310,10 +310,10 @@
 <varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option>
 <replaceable>attrPath</replaceable></term>
 
-  <listitem><para>In <command>nix-env</command>,
-  <command>nix-instantiate</command> and <command>nix-build</command>,
-  <option>--attr</option> allows you to select an attribute from the
-  top-level Nix expression being evaluated.  The <emphasis>attribute
+  <listitem><para>Select an attribute from the top-level Nix
+  expression being evaluated.  (<command>nix-env</command>,
+  <command>nix-instantiate</command>, <command>nix-build</command> and
+  <command>nix-shell</command> only.)  The <emphasis>attribute
   path</emphasis> <replaceable>attrPath</replaceable> is a sequence of
   attribute names separated by dots.  For instance, given a top-level
   Nix expression <replaceable>e</replaceable>, the attribute path
@@ -333,8 +333,18 @@
 </varlistentry>
 
 
+<varlistentry><term><option>--expr</option> / <option>-E</option></term>
+
+  <listitem><para>Interpret the command line arguments as a list of
+  Nix expressions to be parsed and evaluated, rather than as a list
+  of file names of Nix expressions.
+  (<command>nix-instantiate</command>, <command>nix-build</command>
+  and <command>nix-shell</command> only.)</para></listitem>
+
+</varlistentry>
+
 <varlistentry><term><option>--show-trace</option></term>
-  
+
   <listitem><para>Causes Nix to print out a stack trace in case of Nix
   expression evaluation errors.</para></listitem>
 
@@ -342,23 +352,23 @@
 
 
 <varlistentry><term><option>-I</option> <replaceable>path</replaceable></term>
-  
+
   <listitem><para>Add a path to the Nix expression search path.  This
   option may be given multiple times.  See the <envar>NIX_PATH</envar>
   environment variable for information on the semantics of the Nix
   search path.  Paths added through <option>-I</option> take
   precedence over <envar>NIX_PATH</envar>.</para></listitem>
-  
+
 </varlistentry>
 
 
 <varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
-  
+
   <listitem><para>Set the Nix configuration option
   <replaceable>name</replaceable> to <replaceable>value</replaceable>.
   This overrides settings in the Nix configuration file (see
   <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem>
-  
+
 </varlistentry>