Support Shebang style line comments (#469)

* Support Shebang style line comments

* Changelog

Author: chrisrink10

CHANGELOG.md

@@ -5,6 +5,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+ * Added support for Shebang-style line comments (#469)
+
 ### Changed
  * Change the default user namespace to `basilisp.user` (#466)
 

docs/conf.py

@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "Basilisp"
-copyright = "2018, Chris Rink"
+copyright = "2018-2020, Chris Rink"
 author = "Chris Rink"
 
 # The short X.Y version

docs/reader.rst

@@ -1,7 +1,7 @@
 Reader
 ======
 
-In most Lisps, the reader is the component responsible for reading in thet extual representation of the program into memory as data structures.
+In most Lisps, the reader is the component responsible for reading in the textual representation of the program into memory as data structures.
 Lisps are typically referred to as *homoiconic*, since that representation typically matches the syntax tree exactly in memory.
 This is in contrast to a non-homoiconic language such as Java or Python, which typically parses a textual program into an abstract syntax tree which captures the *meaning* of the textual program, but not necessarily the structure.
 
@@ -26,11 +26,11 @@ Integers
 
     basilisp.user=> 1
     1
-    basilisp.user=> (builtins/type 1)
+    basilisp.user=> (python/type 1)
     <class 'int'>
     basilisp.user=> 1N
     1
-    basilisp.user=> (builtins/type 1N)
+    basilisp.user=> (python/type 1N)
     <class 'int'>
 
 Integers are represented using numeric ``0-9`` and may be prefixed with any number of negative signs ``-``.
@@ -45,11 +45,11 @@ Floating Point
 
    basilisp.user=> 1.0
    1.0
-   basilisp.user=> (builtins/type 1.0)
+   basilisp.user=> (python/type 1.0)
    <class 'float'>
    basilisp.user=> 1M
    1
-   basilisp.user=> (builtins/type 1M)
+   basilisp.user=> (python/type 1M)
    <class 'decimal.Decimal'>
 
 Floating point values are represented using ``0-9`` and a trailing decimal value, separated by a ``.`` character.
@@ -65,11 +65,11 @@ Complex
 
     basilisp.user=> 1J
     1J
-    basilisp.user=> (builtins/type 1J)
+    basilisp.user=> (python/type 1J)
     <class 'complex'>
     basilisp.user=> 1.0J
     1J
-    basilisp.user=> (builtins/type 1.0J)
+    basilisp.user=> (python/type 1.0J)
     <class 'complex'>
 
 Basilisp includes support for complex literals to match the Python VM hosts it.
@@ -87,7 +87,7 @@ Strings
     ""
     basilisp.user=> "this is a string"
     "this is a string"
-    basilisp.user=> (builtins/type "")
+    basilisp.user=> (python/type "")
     <class 'str'>
 
 Strings are denoted as a series of characters enclosed by ``"`` quotation marks.
@@ -128,11 +128,11 @@ Boolean Values
 
     basilisp.user=> true
     true
-    basilisp.user=> (builtins/type true)
+    basilisp.user=> (python/type true)
     <class 'bool'>
     basilisp.user=> false
     false
-    basilisp.user=> (builtins/type false)
+    basilisp.user=> (python/type false)
     <class 'bool'>
 
 The special values ``true`` and ``false`` correspond to Python's ``True`` and ``False`` respectively.
@@ -146,7 +146,7 @@ nil
 
     basilisp.user=> nil
     nil
-    basilisp.user=> (builtins/type nil)
+    basilisp.user=> (python/type nil)
     <class 'NoneType'>
 
 The special value ``nil`` correspond's to Python's ``None``.
@@ -270,6 +270,8 @@ Line Comments
 Line comments are specified with the ``;`` character.
 All of the text to the end of the line are ignored.
 
+For a convenience in writing shell scripts with Basilisp, the standard *NIX `shebang <https://en.wikipedia.org/wiki/Shebang_(Unix)>` (``#!``) is also treated as a single-line comment.
+
 .. _metadata:
 
 Metadata
@@ -304,6 +306,7 @@ Reader macros are always dispatched using the ``#`` character.
 
 * ``#'form`` is rewritten as ``(var form)``.
 * ``#_form`` causes the reader to completely ignore ``form``.
+* ``#!form`` is treated as a single-line comment (like ``;form``) as a convenience to support `shebangs <https://en.wikipedia.org/wiki/Shebang_(Unix)>` at the top of Basilisp scripts.
 * ``#"str"`` causes the reader to interpret ``"str"`` as a regex and return a Python `re.pattern <https://docs.python.org/3/library/re.html>`_.
 * ``#(...)`` causes the reader to interpret the contents of the list as an anonymous function. Anonymous functions specified in this way can name arguments using ``%1``, ``%2``, etc. and rest args as ``%&``. For anonymous functions with only one argument, ``%`` can be used in place of ``%1``.
 
@@ -323,6 +326,18 @@ Basilisp supports a few builtin data readers:
 * ``#inst "2018-09-14T15:11:20.253-00:00"`` yields a Python `datetime <https://docs.python.org/3/library/datetime.html#datetime-objects>`_ object.
 * ``#uuid "c3598794-20b4-48db-b76e-242f4405743f"`` yields a Python `UUID <https://docs.python.org/3/library/uuid.html#uuid.UUID>`_ object.
 
+One of the benefits of choosing Basilisp is convenient built-in Python language interop.
+However, the immutable data structures of Basilisp may not always play nicely with code written for (and expecting to be used by) other Python code.
+Fortunately, Basilisp includes data readers for reading Python collection literals directly from the REPL or from Basilisp source.
+
+Python literals can be read by prefixing existing Basilisp data structures with a ``#py`` data reader tag.
+Python literals use the matching syntax to the corresponding Python data type, which does not always match the syntax for the same data type in Basilisp.
+
+* ``#py []`` produces a Python `list <https://docs.python.org/3/library/stdtypes.html#list>` type.
+* ``#py ()`` produces a Python `tuple <https://docs.python.org/3/library/stdtypes.html#tuple>` type.
+* ``#py {}`` produces a Python `dict <https://docs.python.org/3/library/stdtypes.html#dict>` type.
+* ``#py #{}`` produces a Python `set <https://docs.python.org/3/library/stdtypes.html#set>` type.
+
 .. _special_chars:
 
 Special Characters

src/basilisp/lang/compiler/analyzer.py

@@ -361,7 +361,7 @@ def current_macro_ns(self) -> Optional[runtime.Namespace]:
 
     @contextlib.contextmanager
     def macro_ns(self, ns: Optional[runtime.Namespace]):
-        """Set the transient namespace which is available to the analyer during a
+        """Set the transient namespace which is available to the analyzer during a
         macroexpansion phase.
 
         If set to None, prohibit the analyzer from using another namespace for symbol

src/basilisp/lang/reader.py

@@ -843,7 +843,7 @@ def _postwalk(f, form):
 def _read_function(ctx: ReaderContext) -> llist.List:
     """Read a function reader macro from the input stream."""
     if ctx.is_in_anon_fn:
-        raise SyntaxError(f"Nested #() definitions not allowed")
+        raise SyntaxError("Nested #() definitions not allowed")
 
     with ctx.in_anon_fn():
         form = _read_list(ctx)
@@ -1222,6 +1222,8 @@ def _read_reader_macro(ctx: ReaderContext) -> LispReaderForm:
         ctx.reader.advance()
         _read_next(ctx)  # Ignore the entire next form
         return COMMENT
+    elif token == "!":
+        return _read_comment(ctx)
     elif token == "?":
         return _read_reader_conditional(ctx)
     elif ns_name_chars.match(token):
@@ -1244,7 +1246,7 @@ def _read_comment(ctx: ReaderContext) -> LispReaderForm:
     Return the next form after the next line break."""
     reader = ctx.reader
     start = reader.advance()
-    assert start == ";"
+    assert start in {";", "!"}
     while True:
         token = reader.peek()
         if newline_chars.match(token):
@@ -1307,7 +1309,7 @@ def _read_next(ctx: ReaderContext) -> LispReaderForm:  # noqa: C901 MC0001
     elif token == "":
         return ctx.eof
     else:
-        raise SyntaxError("Unexpected token '{token}'".format(token=token))
+        raise SyntaxError(f"Unexpected token '{token}'")
 
 
 def read(  # pylint: disable=too-many-arguments

tests/basilisp/reader_test.py

@@ -839,6 +839,16 @@ def test_comment_line():
     )
 
 
+def test_shebang_line():
+    assert None is read_str_first("#! I'm a little shebang short and stout")
+    assert kw.keyword("kw2") == read_str_first("#!/usr/bin/env basilisp run\n:kw2")
+    assert llist.l(sym.symbol("form"), kw.keyword("keyword")) == read_str_first(
+        """#!/usr/bin/env basilisp run
+        (form :keyword)
+        """
+    )
+
+
 class TestReaderConditional:
     @pytest.mark.parametrize(
         "v",