Add alias and prelude shorthand tags

README.md

@@ -240,7 +240,7 @@ which demonstrates a number of language features.
 Run as the main script or enter it into the Lissp REPL.
 Requires [Bottle.](https://bottlepy.org/docs/dev/)
 ```Racket
-(hissp.._macro_.prelude)
+hissp..prelude#:
 
 (define enjoin en#X#(.join "" (map str X)))
 

docs/macro_tutorial.rst

@@ -1,4 +1,4 @@
-.. Copyright 2020, 2021, 2022, 2023 Matthew Egan Odendahl
+.. Copyright 2020, 2021, 2022, 2023, 2024 Matthew Egan Odendahl
    SPDX-License-Identifier: CC-BY-SA-4.0
 
 .. All Source Code Examples in this file are licensed "Apache-2.0 OR CC-BY-SA-4.0"
@@ -218,18 +218,18 @@ Fire up the Lissp REPL in a terminal,
 or in your editor if it does that,
 in the same directory as your Lissp file.
 
-Add the prelude to the top of the file:
+Add the `prelude<hissp.prelude>` shorthand to the top of the file:
 
 .. code-block:: Lissp
 
-   (hissp.._macro_.prelude)
+   hissp..prelude#:
 
 And push it to the REPL as well:
 
 .. code-block:: REPL
 
-   #> (hissp.._macro_.prelude)
-   >>> # hissp.._macro_.prelude
+   #> hissp..prelude#:
+   >>> # hissp.macros.._macro_.prelude
    ... __import__('builtins').exec(
    ...   ('from functools import partial,reduce\n'
    ...    'from itertools import *;from operator import *\n'
@@ -253,7 +253,9 @@ And push it to the REPL as well:
 
 .. caution::
 
-   The `prelude` macro overwrites your ``_macro_`` namespace with a copy of the bundled one.
+   The ``:`` directs it to dump into the module's global namespace.
+   The `prelude<hissp.macros._macro_.prelude>`
+   macro overwrites your ``_macro_`` namespace (if any) with a copy of the bundled one.
    Any macros you've defined in there are lost.
    In Lissp files, the prelude is meant to be used before any definitions,
    when it is used at all.
@@ -1787,7 +1789,7 @@ Let's review. The code you need to make the version we have so far is
 
 .. code-block:: Lissp
 
-   (hissp.._macro_.prelude)
+   hissp..prelude#:
 
    (defmacro L (: :* expr)
      `(lambda ,(map (lambda (i)
@@ -1838,11 +1840,11 @@ rather than pasting them all in again.
 
 To use your macros from other Lissp modules,
 use their fully-qualified names,
-abbreviate the qualifier with `alias`,
+abbreviate the qualifier with `alias<hissp.macros._macro_.alias>`,
 or (if you must) `attach` them to your current module's ``_macro_`` object.
 That last one would require that your macros also be available at run time,
 although there are ways to avoid that if you need to.
-See the `prelude` expansion for a hint.
+See the `prelude<hissp.macros._macro_.alias>` expansion for a hint.
 
 You can use the resulting macro as a shorter lambda for higher-order functions:
 

src/hissp/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2020, 2022 Matthew Egan Odendahl
+# Copyright 2020, 2022, 2024 Matthew Egan Odendahl
 # SPDX-License-Identifier: Apache-2.0
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -46,13 +46,44 @@
 from hissp.reader import transpile
 from hissp.repl import interact
 
-from contextlib import suppress
-
-# Hissp must be importable to compile macros.lissp in the first place.
-with suppress(ImportError):
-    # noinspection PyUnresolvedReferences
+try:  # Hissp must be importable to compile macros.lissp the first time.
     from hissp.macros import _macro_
-del suppress
-
+except ImportError:  # Print warning, but continue.
+    print("Unable to import hissp macros.", file=__import__("sys").stderr)
 
 VERSION = "0.5.dev"
+
+
+def prelude(ns):
+    """Lissp prelude shorthand tag.
+
+    Usage: ``hissp..prelude#ns``, which expands to
+
+    .. code-block:: Lissp
+
+       (hissp.macros.._macro_.prelude ns)
+
+    ``hissp..prelude#:`` is short for
+    ``hissp..prelude#(builtins..globals)``.
+
+    See `hissp.macros._macro_.prelude`.
+    """
+    return "hissp.macros.._macro_.prelude", *([] if ns == ":" else [ns])
+
+
+def alias(abbreviation, qualifier="hissp.macros.._macro_"):
+    """Lissp alias shorthand tag.
+
+    Usage: ``hissp..alias## abbreviation qualifier``,
+    which expands to
+
+    .. code-block:: Lissp
+
+       (hissp.macros.._macro_.alias abbreviation qualifier)
+
+    The single-argument form
+    ``hissp..alias#abbreviation`` aliases the bundled macro qualifier.
+
+    See `hissp.macros._macro_.alias`.
+    """
+    return "hissp.macros.._macro_.alias", abbreviation, qualifier

src/hissp/macros.lissp

@@ -1978,6 +1978,7 @@ Hidden doctest adds bundled macros for REPL-consistent behavior.
   ;; or similarly constrained environments (e.g. embedded, readerless).
   ;; There, the first form should be ``(hissp.._macro_.prelude)``,
   ;; which is also implied in ``$ lissp -c`` commands.
+  ;; (See the `hissp.prelude` shorthand for Lissp.)
   ;;
   ;; Larger projects with access to functional and macro libraries need not
   ;; use this prelude at all.

tests/argv.lissp

@@ -1,6 +1,6 @@
-;;; Copyright 2020 Matthew Egan Odendahl
+;;; Copyright 2020, 2024 Matthew Egan Odendahl
 ;;; SPDX-License-Identifier: Apache-2.0
-(hissp.._macro_.prelude)
+hissp..prelude#:
 
 (print sys..argv)
 (print .#"f'{__name__=} {__package__=}'")

tests/test_macros.lissp

@@ -1,8 +1,8 @@
 #! Transpiler should ignore the shebang line!
-;;; Copyright 2019, 2020 Matthew Egan Odendahl
+;;; Copyright 2019, 2020, 2024 Matthew Egan Odendahl
 ;;; SPDX-License-Identifier: Apache-2.0
 
-(hissp.._macro_.alias * hissp.._macro_)
+hissp..alias#*
 
 (*#define enlist
   (lambda (: :* a) (list a)))