doc: shebang release notes, docs, tests

fix: release notes

doc/manual/src/release-notes/rl-next.md

@@ -1,5 +1,49 @@
 # Release X.Y (202?-??-??)
 
+- The experimental nix command is now a `#!-interpreter` by appending the
+  contents of any `#! nix` lines and the script's location to a single call.
+  Some examples:
+  ```
+  #!/usr/bin/env nix
+  #! nix shell --file "<nixpkgs>" hello --command bash
+
+  hello | cowsay
+  ```
+  or with flakes:
+  ```
+  #!/usr/bin/env nix
+  #! nix shell nixpkgs#bash nixpkgs#hello nixpkgs#cowsay --command bash
+
+  hello | cowsay
+  ```
+  or
+  ```bash
+  #! /usr/bin/env nix
+  #! nix shell --impure --expr
+  #! nix "with (import (builtins.getFlake ''nixpkgs'') {}); terraform.withPlugins (plugins: [ plugins.openstack ])"
+  #! nix --command bash
+
+  terraform "$@"
+  ```
+  or
+  ```
+  #!/usr/bin/env nix
+  //! ```cargo
+  //! [dependencies]
+  //! time = "0.1.25"
+  //! ```
+  /*
+  #!nix shell nixpkgs#rustc nixpkgs#rust-script nixpkgs#cargo --command rust-script
+  */
+  fn main() {
+      for argument in std::env::args().skip(1) {
+          println!("{}", argument);
+      };
+      println!("{}", std::env::var("HOME").expect(""));
+      println!("{}", time::now().rfc822z());
+  }
+  // vim: ft=rust
+  ```
 - [URL flake references](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references) now support [percent-encoded](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) characters.
 
 - [Path-like flake references](@docroot@/command-ref/new-cli/nix3-flake.md#path-like-syntax) now accept arbitrary unicode characters (except `#` and `?`).

src/nix/shell.md

@@ -51,4 +51,121 @@ R""(
 provides the specified [*installables*](./nix.md#installable). If no command is specified, it starts the
 default shell of your user account specified by `$SHELL`.
 
+# Use as a `#!`-interpreter
+
+You can use `nix` as a script interpreter to allow scripts written
+in arbitrary languages to obtain their own dependencies via Nix. This is
+done by starting the script with the following lines:
+
+```bash
+#! /usr/bin/env nix
+#! nix shell installables --command real-interpreter
+```
+
+where *real-interpreter* is the “real” script interpreter that will be
+invoked by `nix shell` after it has obtained the dependencies and
+initialised the environment, and *installables* are the attribute names of
+the dependencies in Nixpkgs.
+
+The lines starting with `#! nix` specify options (see above). Note that you
+cannot write `#! /usr/bin/env nix shell -i ...` because many operating systems
+only allow one argument in `#!` lines.
+
+For example, here is a Python script that depends on Python and the
+`prettytable` package:
+
+```python
+#! /usr/bin/env nix
+#! nix shell github:tomberek/-#python3With.prettytable --command python
+
+import prettytable
+
+# Print a simple table.
+t = prettytable.PrettyTable(["N", "N^2"])
+for n in range(1, 10): t.add_row([n, n * n])
+print t
+```
+
+Similarly, the following is a Perl script that specifies that it
+requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
+
+```perl
+#! /usr/bin/env nix
+#! nix shell github:tomberek/-#perlWith.HTMLTokeParserSimple.LWP --command perl -x
+
+use HTML::TokeParser::Simple;
+
+# Fetch nixos.org and print all hrefs.
+my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
+
+while (my $token = $p->get_tag("a")) {
+    my $href = $token->get_attr("href");
+    print "$href\n" if $href;
+}
+```
+
+Sometimes you need to pass a simple Nix expression to customize a
+package like Terraform:
+
+```bash
+#! /usr/bin/env nix
+#! nix shell --impure --expr
+#! nix "with (import (builtins.getFlake ''nixpkgs'') {}); terraform.withPlugins (plugins: [ plugins.openstack ])"
+#! nix --command bash
+
+terraform "$@"
+```
+
+> **Note**
+>
+> You must use double quotes (`"`) when passing a simple Nix expression
+> in a nix shell shebang.
+
+Finally, using the merging of multiple nix shell shebangs the following
+Haskell script uses a specific branch of Nixpkgs/NixOS (the 21.11 stable
+branch):
+
+```haskell
+#!/usr/bin/env nix
+#!nix shell --override-input nixpkgs github:NixOS/nixpkgs/nixos-21.11
+#!nix github:tomberek/-#haskellWith.download-curl.tagsoup --command runghc
+
+import Network.Curl.Download
+import Text.HTML.TagSoup
+import Data.Either
+import Data.ByteString.Char8 (unpack)
+
+-- Fetch nixos.org and print all hrefs.
+main = do
+  resp <- openURI "https://nixos.org/"
+  let tags = filter (isTagOpenName "a") $ parseTags $ unpack $ fromRight undefined resp
+  let tags' = map (fromAttrib "href") tags
+  mapM_ putStrLn $ filter (/= "") tags'
+```
+
+If you want to be even more precise, you can specify a specific revision
+of Nixpkgs:
+
+    #!nix shell --override-input nixpkgs github:NixOS/nixpkgs/eabc38219184cc3e04a974fe31857d8e0eac098d
+
+The examples above all used `-p` to get dependencies from Nixpkgs. You
+can also use a Nix expression to build your own dependencies. For
+example, the Python example could have been written as:
+
+```python
+#! /usr/bin/env nix
+#! nix shell --impure --file deps.nix -i python
+```
+
+where the file `deps.nix` in the same directory as the `#!`-script
+contains:
+
+```nix
+with import <nixpkgs> {};
+python3.withPackages (ps: with ps; [ prettytable ])
+```
+
+
+
+
 )""

tests/functional/flakes/flakes.sh

@@ -80,6 +80,18 @@ chmod +x "$nonFlakeDir/shebang.sh"
 git -C "$nonFlakeDir" add README.md shebang.sh
 git -C "$nonFlakeDir" commit -m 'Initial'
 
+cat > $nonFlakeDir/shebang-perl.sh <<EOF
+#! $(type -P env) nix
+#! nix run nixpkgs#perl
+## Modules used
+use strict;
+use warnings;
+
+# Print function
+print("Hello World\n");
+EOF
+chmod +x $nonFlakeDir/shebang-perl.sh
+
 # Construct a custom registry, additionally test the --registry flag
 nix registry add --registry "$registry" flake1 "git+file://$flake1Dir"
 nix registry add --registry "$registry" flake2 "git+file://$percentEncodedFlake2Dir"
@@ -526,3 +538,4 @@ expectStderr 1 nix flake metadata "$flake2Dir" --no-allow-dirty --reference-lock
 # Test shebang
 [[ $($nonFlakeDir/shebang.sh) = "foo" ]]
 [[ $($nonFlakeDir/shebang.sh "bar") = "foo"$'\n'"bar" ]]
+[[ $($nonFlakeDir/shebang-perl.sh ) = "Hello World!" ]]