From af39229c2aa61a350ab7a03c112f790c943778b5 Mon Sep 17 00:00:00 2001 From: gilch Date: Thu, 18 Jul 2024 13:45:23 -0600 Subject: [PATCH] Update docs and tests for new shorthand --- README.md | 2 +- docs/macro_tutorial.rst | 20 +++++++++++--------- src/hissp/__init__.py | 19 +++++++++++++++++-- src/hissp/macros.lissp | 1 + tests/argv.lissp | 4 ++-- tests/test_macros.lissp | 4 ++-- 6 files changed, 34 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index eea780766..0d55f663f 100644 --- a/README.md +++ b/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))) diff --git a/docs/macro_tutorial.rst b/docs/macro_tutorial.rst index 1ad14cb77..c748dde15 100644 --- a/docs/macro_tutorial.rst +++ b/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` 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` + 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`, 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` expansion for a hint. You can use the resulting macro as a shorter lambda for higher-order functions: diff --git a/src/hissp/__init__.py b/src/hissp/__init__.py index 2b6f1f85b..aa3bb514f 100644 --- a/src/hissp/__init__.py +++ b/src/hissp/__init__.py @@ -57,9 +57,16 @@ 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)``. - Expands to ``(hissp.macros.._macro_.prelude ns)`` + + See `hissp.macros._macro_.prelude`. """ return "hissp.macros.._macro_.prelude", *([] if ns == ":" else [ns]) @@ -69,6 +76,14 @@ def alias(abbreviation, qualifier="hissp.macros.._macro_"): Usage: ``hissp..alias## abbreviation qualifier``, which expands to - ``(hissp.macros.._macro_.alias abbreviation qualifier)`` + + .. 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 diff --git a/src/hissp/macros.lissp b/src/hissp/macros.lissp index 9911247f5..b0c33ed28 100644 --- a/src/hissp/macros.lissp +++ b/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. diff --git a/tests/argv.lissp b/tests/argv.lissp index 05c16c0a8..08d404488 100644 --- a/tests/argv.lissp +++ b/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__=}'") diff --git a/tests/test_macros.lissp b/tests/test_macros.lissp index cdd769bee..8f169710d 100644 --- a/tests/test_macros.lissp +++ b/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)))