Support shebangs with a single argument (#765)

Fixes #764

Author: chrisrink10

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
  * Fix issue with `(count nil)` throwing an exception (#759)
  * Fix issue with keyword fn not testing for test membership in sets (#762)
+ * Fix an issue for executing Basilisp scripts via a shebang where certain platforms may not support more than one argument in the shebang line (#764)
 
 ## [v0.1.0b0]
 ### Added

docs/gettingstarted.rst

@@ -125,3 +125,11 @@ Basilisp code will operate normally (calling into other Basilisp namespaces and
 
    Manual bootstrapping is designed to be as simple as possible, but it is not the long term goal of this project's maintainers that it should be necessary.
    Eventually, we plan to release a tool akin to Python's Poetry, or similar tools in other languages that helps facilitate both dependency management and packaging in such a way that bootstrapping is completely transparent to the developer.
+
+Basilisp can also be invoked as a script using a shebang line which would circumvent the need to bootstrap using the methods above.
+For systems where the shebang line allows arguments, you can use ``#!/usr/bin/env basilisp run``, but for those where only one argument is permitted ``#!/usr/bin/env basilisp-run`` will work.
+
+.. code-block:: clojure
+
+   #!/usr/bin/env basilisp
+   (println "Hello world!")

pyproject.toml

@@ -59,6 +59,7 @@ pytest = ["pytest"]
 
 [tool.poetry.scripts]
 basilisp = "basilisp.cli:invoke_cli"
+basilisp-run = "basilisp.cli:run_script"
 
 [tool.poetry.plugins.pytest11]
 basilisp_test_runner = "basilisp.contrib.pytest.testrunner"

src/basilisp/cli.py

@@ -5,6 +5,7 @@
 import sys
 import traceback
 import types
+from pathlib import Path
 from typing import Any, Callable, Optional, Sequence, Type
 
 from basilisp import main as basilisp
@@ -26,15 +27,6 @@
 DEFAULT_COMPILER_OPTS = {k.name: v for k, v in compiler.compiler_opts().items()}
 
 
-def eval_file(filename: str, ctx: compiler.CompilerContext, ns: runtime.Namespace):
-    """Evaluate a file with the given name into a Python module AST node."""
-    last = None
-    for form in reader.read_file(filename, resolver=runtime.resolve_alias):
-        assert not isinstance(form, reader.ReaderConditional)
-        last = compiler.compile_and_exec_form(form, ctx, ns)
-    return last
-
-
 def eval_stream(stream, ctx: compiler.CompilerContext, ns: runtime.Namespace):
     """Evaluate the forms in stdin into a Python module AST node."""
     last = None
@@ -53,6 +45,11 @@ def eval_str(s: str, ctx: compiler.CompilerContext, ns: runtime.Namespace, eof:
     return last
 
 
+def eval_file(filename: str, ctx: compiler.CompilerContext, ns: runtime.Namespace):
+    """Evaluate a file with the given name into a Python module AST node."""
+    return eval_str(f'(load-file "{filename}")', ctx, ns, eof=object())
+
+
 def bootstrap_repl(ctx: compiler.CompilerContext, which_ns: str) -> types.ModuleType:
     """Bootstrap the REPL with a few useful vars and returned the bootstrapped
     module so it's functions can be used by the REPL command."""
@@ -421,17 +418,11 @@ def run(
         ns.refer_all(core_ns)
 
         if args.code:
-            print(runtime.lrepr(eval_str(args.file_or_code, ctx, ns, eof)))
+            eval_str(args.file_or_code, ctx, ns, eof)
         elif args.file_or_code == STDIN_FILE_NAME:
-            print(
-                runtime.lrepr(
-                    eval_stream(
-                        io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8"), ctx, ns
-                    )
-                )
-            )
+            eval_stream(io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8"), ctx, ns)
         else:
-            print(runtime.lrepr(eval_file(args.file_or_code, ctx, ns)))
+            eval_file(args.file_or_code, ctx, ns)
 
 
 @_subcommand(
@@ -489,7 +480,21 @@ def _add_version_subcommand(_: argparse.ArgumentParser) -> None:
     pass
 
 
+def run_script():
+    """Entrypoint to run the Basilisp script named by `sys.argv[1]` as by the
+    `basilisp run` subcommand.
+
+    This is provided as a shim for platforms where shebang lines cannot contain more
+    than one argument and thus `#!/usr/bin/env basilisp run` would be non-functional.
+
+    The current process is replaced as by `os.execlp`."""
+    # os.exec* functions do not perform shell expansion, so we must do so manually.
+    script_path = Path(sys.argv[1]).resolve()
+    os.execlp("basilisp", "basilisp", "run", script_path)
+
+
 def invoke_cli(args: Optional[Sequence[str]] = None) -> None:
+    """Entrypoint to run the Basilisp CLI."""
     parser = argparse.ArgumentParser(
         description="Basilisp is a Lisp dialect inspired by Clojure targeting Python 3."
     )

tests/basilisp/cli_test.py

@@ -1,12 +1,17 @@
 import io
 import os
+import pathlib
+import platform
 import re
+import stat
+import subprocess
 import tempfile
 import time
 from threading import Thread
 from typing import Optional, Sequence
 from unittest.mock import patch
 
+import attr
 import pytest
 
 from basilisp.cli import BOOL_FALSE, BOOL_TRUE, invoke_cli
@@ -35,34 +40,53 @@ def isolated_filesystem():
             os.chdir(wd)
 
 
+@attr.frozen
+class CapturedIO:
+    out: str
+    err: str
+    lisp_out: str
+    lisp_err: str
+
+
 @pytest.fixture
-def run_cli(monkeypatch, capsys):
+def run_cli(monkeypatch, capsys, cap_lisp_io):
     def _run_cli(args: Sequence[str], input: Optional[str] = None):
         if input is not None:
             monkeypatch.setattr(
                 "sys.stdin", io.TextIOWrapper(io.BytesIO(input.encode("utf-8")))
             )
         invoke_cli([*args])
-        return capsys.readouterr()
+        python_io = capsys.readouterr()
+        lisp_out, lisp_err = cap_lisp_io
+        return CapturedIO(
+            out=python_io.out,
+            err=python_io.err,
+            lisp_out=lisp_out.getvalue(),
+            lisp_err=lisp_err.getvalue(),
+        )
 
     return _run_cli
 
 
 def test_debug_flag(run_cli):
-    result = run_cli(["run", "--disable-ns-cache", "true", "-c", "(+ 1 2)"])
-    assert "3\n" == result.out
+    result = run_cli(["run", "--disable-ns-cache", "true", "-c", "(println (+ 1 2))"])
+    assert "3\n" == result.lisp_out
     assert os.environ["BASILISP_DO_NOT_CACHE_NAMESPACES"].lower() == "true"
 
 
 class TestCompilerFlags:
     def test_no_flag(self, run_cli):
-        result = run_cli(["run", "--warn-on-var-indirection", "-c", "(+ 1 2)"])
-        assert "3\n" == result.out
+        result = run_cli(
+            ["run", "--warn-on-var-indirection", "-c", "(println (+ 1 2))"]
+        )
+        assert "3\n" == result.lisp_out
 
     @pytest.mark.parametrize("val", BOOL_TRUE | BOOL_FALSE)
     def test_valid_flag(self, run_cli, val):
-        result = run_cli(["run", "--warn-on-var-indirection", val, "-c", "(+ 1 2)"])
-        assert "3\n" == result.out
+        result = run_cli(
+            ["run", "--warn-on-var-indirection", val, "-c", "(println  (+ 1 2))"]
+        )
+        assert "3\n" == result.lisp_out
 
     @pytest.mark.parametrize("val", ["maybe", "not-no", "4"])
     def test_invalid_flag(self, run_cli, val):
@@ -141,20 +165,45 @@ def test_other_exception(self, run_cli):
 
 class TestRun:
     def test_run_code(self, run_cli):
-        result = run_cli(["run", "-c", "(+ 1 2)"])
-        assert "3\n" == result.out
+        result = run_cli(["run", "-c", "(println (+ 1 2))"])
+        assert "3\n" == result.lisp_out
 
     def test_run_file(self, isolated_filesystem, run_cli):
         with open("test.lpy", mode="w") as f:
-            f.write("(+ 1 2)")
+            f.write("(println (+ 1 2))")
         result = run_cli(["run", "test.lpy"])
-        assert "3\n" == result.out
+        assert "3\n" == result.lisp_out
 
     def test_run_stdin(self, run_cli):
-        result = run_cli(["run", "-"], input="(+ 1 2)")
-        assert "3\n" == result.out
+        result = run_cli(["run", "-"], input="(println (+ 1 2))")
+        assert "3\n" == result.lisp_out
 
 
 def test_version(run_cli):
     result = run_cli(["version"])
     assert re.compile(r"^Basilisp (\d+)\.(\d+)\.(\w*)(\d+)\n$").match(result.out)
+
+
+@pytest.mark.skipif(
+    platform.system().lower() == "windows",
+    reason=(
+        "Shebangs are only supported virtually by Windows Python installations, "
+        "so this doesn't work natively on Windows"
+    ),
+)
+def test_run_script(tmp_path: pathlib.Path):
+    script_path = tmp_path / "script.lpy"
+    script_path.write_text(
+        "\n".join(
+            [
+                "#!/usr/bin/env basilisp-run",
+                "(ns test-run-script-ns ",
+                "  (:import os))",
+                "",
+                '(println "Hello world from Basilisp!")',
+            ]
+        )
+    )
+    script_path.chmod(script_path.stat().st_mode | stat.S_IEXEC)
+    res = subprocess.run([script_path.resolve()], check=True, capture_output=True)
+    assert res.stdout == b"Hello world from Basilisp!\n"

tests/basilisp/conftest.py

@@ -1,9 +1,11 @@
+import io
 import sys
-from typing import Dict, Optional
+from typing import Dict, Optional, Tuple
 
 import pytest
 
 from basilisp.lang import compiler as compiler
+from basilisp.lang import map as lmap
 from basilisp.lang import reader as reader
 from basilisp.lang import runtime as runtime
 from basilisp.lang import symbol as sym
@@ -59,3 +61,14 @@ def _lcompile(
         return last
 
     return _lcompile
+
+
+@pytest.fixture
+def cap_lisp_io() -> Tuple[io.StringIO, io.StringIO]:
+    """Capture the values of `*out*` and `*err*` during test execution, returning
+    `io.StringIO` for each."""
+    with io.StringIO() as outbuf, io.StringIO() as errbuf:
+        stdout = runtime.resolve_var(sym.symbol("*out*", ns="basilisp.core"))
+        stderr = runtime.resolve_var(sym.symbol("*err*", ns="basilisp.core"))
+        with runtime.bindings(lmap.map({stdout: outbuf, stderr: errbuf})):
+            yield outbuf, errbuf