From 942051d3b827a540a586f3a3f7684c413d6cd03f Mon Sep 17 00:00:00 2001 From: Kodi Arfer Date: Thu, 21 Mar 2024 15:04:18 -0400 Subject: [PATCH 1/4] Expand the docstring of `hy.REPL` --- hy/repl.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/hy/repl.py b/hy/repl.py index eaa0c03ff..22f012592 100644 --- a/hy/repl.py +++ b/hy/repl.py @@ -236,10 +236,16 @@ class REPL(code.InteractiveConsole): A convenient way to use this class to interactively debug code is to insert the following in the code you want to debug:: - (.run (hy.REPL :locals (locals))) + (.run (hy.REPL :locals {#** (globals) #** (locals)})) - Note that as with :func:`code.interact`, changes to ``(locals)`` inside the REPL are - not propagated back to the original scope.""" + Or in Python: + + .. code-block:: python + + import hy; hy.REPL(locals = {**globals(), **locals()}).run() + + Note that as with :func:`code.interact`, changes to local variables inside the + REPL are not propagated back to the original scope.""" def __init__(self, spy=False, spy_delimiter=('-' * 30), output_fn=None, locals=None, filename="", allow_incomplete=True): From 4bb1e186464ca73c56d1831ed5a9370ffbe8e378 Mon Sep 17 00:00:00 2001 From: Kodi Arfer Date: Thu, 21 Mar 2024 15:27:48 -0400 Subject: [PATCH 2/4] Fix documentation links to Hyrule --- docs/api.rst | 14 +++++++------- docs/macros.rst | 2 +- docs/tutorial.rst | 2 +- hy/core/macros.hy | 2 +- hy/core/util.hy | 2 +- hy/models.py | 4 ++-- hy/pyops.hy | 4 ++-- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 33239611a..cf1a72231 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -50,7 +50,7 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``. (defn #^ int add1 [#^ int x] (+ x 1)) (fn #^ int [#^ int y] (+ y 2)) - For annotating items with generic types, the :hy:func:`of ` + For annotating items with generic types, the :hy:func:`of ` macro will likely be of use. An issue with type annotations is that, as of this writing, we know of no Python type-checker that can work with :py:mod:`ast` objects or bytecode files. They all need Python source text. So you'll have to translate your Hy with ``hy2py`` in order to actually check the types. @@ -249,7 +249,7 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``. In a loop with multiple iteration clauses, such as ``(for [x xs y ys] …)``, ``break`` only breaks out of the innermost iteration, not the whole form. To jump out of the whole form, enclose it in a :hy:func:`block - ` and use ``block-ret`` instead of ``break``. In + ` and use ``block-ret`` instead of ``break``. In the case of :hy:func:`for`, but not :hy:func:`lfor` and the other comprehension forms, you may also enclose it in a function and use :hy:func:`return`. @@ -303,9 +303,9 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``. In a loop with multiple iteration clauses, such as ``(for [x xs y ys] …)``, ``continue`` applies to the innermost iteration, not the whole form. To jump to the next step of an outer iteration, try rewriting your loop as multiple - nested loops and interposing a :hy:func:`block `, as - in ``(for [x xs] (block (for [y ys] …)))``. You can then use ``block-ret`` - in place of ``continue``. + nested loops and interposing a :hy:func:`block `, as in + ``(for [x xs] (block (for [y ys] …)))``. You can then use ``block-ret`` in + place of ``continue``. .. hy:macro:: (do [#* body]) @@ -744,8 +744,8 @@ base names, such that ``hy.core.macros.foo`` can be called as just ``foo``. `_ construct, and retains all of Python's limitations on match patterns. For example, you can't match against the value of a variable. For more flexible branching - constructs, see Hyrule's :hy:func:`branch ` and - :hy:func:`case `, or simply use :hy:func:`cond + constructs, see Hyrule's :hy:func:`branch ` and + :hy:func:`case `, or simply use :hy:func:`cond `. .. hy:macro:: (defclass [arg1 #* args]) diff --git a/docs/macros.rst b/docs/macros.rst index c4ad7e40f..546cc9926 100644 --- a/docs/macros.rst +++ b/docs/macros.rst @@ -114,7 +114,7 @@ A better approach is to use :hy:func:`hy.gensym` to choose your variable name:: (setv ~g (.upper ~arg)) (+ ~g ~g))) -Hyrule provides some macros that make using gensyms more convenient, like :hy:func:`defmacro! ` and :hy:func:`with-gensyms `. +Hyrule provides some macros that make using gensyms more convenient, like :hy:func:`defmacro! ` and :hy:func:`with-gensyms `. Macro subroutines ~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 21ebdddea..def5ae1db 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -312,7 +312,7 @@ arbitrary Hy forms to be executed as code. There are several helper macros that make it easy to construct forms programmatically, such as :hy:func:`quote` (``'``), :hy:func:`quasiquote` (`````), :hy:func:`unquote` (``~``), :hy:func:`unquote-splice` (``~@``), and :hy:func:`defmacro! -`. The previous chapter has :ref:`a simple example +`. The previous chapter has :ref:`a simple example ` of using ````` and ``~@`` to define a new control construct ``do-while``. diff --git a/hy/core/macros.hy b/hy/core/macros.hy index 3732f65d5..069344993 100644 --- a/hy/core/macros.hy +++ b/hy/core/macros.hy @@ -41,7 +41,7 @@ (defmacro when [test #* body] - #[[Shorthand for ``(if test (do …) None)``. See :hy:func:`if`. For a logically negated version, see Hyrule's :hy:func:`unless `. + #[[Shorthand for ``(if test (do …) None)``. See :hy:func:`if`. For a logically negated version, see Hyrule's :hy:func:`unless `. :: (when panic diff --git a/hy/core/util.hy b/hy/core/util.hy index 217b6366b..c0758c520 100644 --- a/hy/core/util.hy +++ b/hy/core/util.hy @@ -104,7 +104,7 @@ (print (hy.repr (hy.macroexpand '(m 5)))) ; => '0 - Note that in general, macro calls in the arguments of the expression still won't expanded. To expand these, too, try Hyrule's :hy:func:`macroexpand-all `." + Note that in general, macro calls in the arguments of the expression still won't expanded. To expand these, too, try Hyrule's :hy:func:`macroexpand-all `." (_macroexpand model (or module (calling-module)) macros)) (defn macroexpand-1 [model [module None] [macros None]] diff --git a/hy/models.py b/hy/models.py index ad370d3f4..db3bdc016 100644 --- a/hy/models.py +++ b/hy/models.py @@ -381,8 +381,8 @@ class Sequence(Object, tuple): When you're recursively descending through a tree of models, testing a model with ``(isinstance x hy.models.Sequence)`` is useful for deciding whether to iterate over - ``x``. You can also use the Hyrule function :hy:func:`coll? ` - for this purpose. + ``x``. You can also use the Hyrule function :hy:func:`coll? ` for this + purpose. """ _extra_kwargs = () diff --git a/hy/pyops.hy b/hy/pyops.hy index 95941d13a..83c18b21d 100644 --- a/hy/pyops.hy +++ b/hy/pyops.hy @@ -240,8 +240,8 @@ is equivalent to ``(+= count (+ n1 n2 n3)).``" provides its own syntactic sugar for this with a different macro, :hy:func:`cut `. Note that ``.`` (:ref:`dot `) forms can also subscript. See also Hyrule's - :hy:func:`assoc ` to easily assign multiple elements of a - single collection.]] + :hy:func:`assoc ` to easily assign multiple elements of a single + collection.]] (setv coll (get coll key1)) (for [k keys] From 99c79c9f69c2371790578b48e36238a2adb61750 Mon Sep 17 00:00:00 2001 From: Kodi Arfer Date: Thu, 21 Mar 2024 15:34:08 -0400 Subject: [PATCH 3/4] Improve the documentation of `hy.R` --- docs/api.rst | 4 ++++ docs/syntax.rst | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index cf1a72231..d8e194355 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1350,6 +1350,10 @@ the following methods .. hy:autoclass:: hy.I +.. hy:class:: (hy.R) + + There is no actual object named ``hy.R``. Rather, this syntax is :ref:`recognized specially by the compiler ` as a shorthand for requiring and calling a macro. + Reader Macros ------------- diff --git a/docs/syntax.rst b/docs/syntax.rst index 9a3ab9a0d..104c202e1 100644 --- a/docs/syntax.rst +++ b/docs/syntax.rst @@ -407,7 +407,7 @@ first element. .. _hy.R: - - Exception: expressions like ``((. hy R module-name macro-name) …)``, or equivalently ``(hy.R.module-name.macro-name …)``, get special treatment. They import the module ``module-name`` and call its macro ``macro-name``, so ``(hy.R.foo.bar 1)`` is equivalent to ``(require foo) (foo.bar 1)``, but without bringing ``foo`` or ``foo.bar`` into scope. Thus ``hy.R`` is convenient syntactic sugar for macros you'll only call once in a file, or for macros that you want to appear in the expansion of other macros without having to call :hy:func:`require` in the expansion. As with :hy:class:`hy.I`, dots in the module name must be replaced with slashes. + - Exception: expressions like ``((. hy R module-name macro-name) …)``, or equivalently ``(hy.R.module-name.macro-name …)``, get special treatment. They :hy:func:`require` the module ``module-name`` and call its macro ``macro-name``, so ``(hy.R.foo.bar 1)`` is equivalent to ``(require foo) (foo.bar 1)``, but without bringing ``foo`` or ``foo.bar`` into scope. Thus ``hy.R`` is convenient syntactic sugar for macros you'll only call once in a file, or for macros that you want to appear in the expansion of other macros without having to call :hy:func:`require` in the expansion. As with :hy:class:`hy.I`, dots in the module name must be replaced with slashes. - Otherwise, the expression is compiled into a Python-level call, with the first element being the calling object. (So, you can call a function that has From 90982ff21a5509701b835a3373b79395d1591e3c Mon Sep 17 00:00:00 2001 From: Kodi Arfer Date: Thu, 21 Mar 2024 15:44:09 -0400 Subject: [PATCH 4/4] Remove the long-unmaintained cheatsheet --- docs/.gitignore | 1 - docs/cheatsheet.json | 153 ------------------------------------------- docs/conf.py | 68 ------------------- docs/index.rst | 1 - 4 files changed, 223 deletions(-) delete mode 100644 docs/cheatsheet.json diff --git a/docs/.gitignore b/docs/.gitignore index d57b3e89e..e35d8850c 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1 @@ _build -cheatsheet.rst diff --git a/docs/cheatsheet.json b/docs/cheatsheet.json deleted file mode 100644 index c3da83774..000000000 --- a/docs/cheatsheet.json +++ /dev/null @@ -1,153 +0,0 @@ -[ - { - "name": "Hy", - "categories": [ - { - "name": "IO", - "methods": [ - "hy.repr", - "hy.repr-register", - "hy.mangle", - "hy.unmangle", - "hy.read", - "hy.read-str" - ] - }, - { - "name": "Reader", - "methods": [ - "hy.eval", - "hy.gensym", - "hy.macroexpand", - "hy.macroexpand-1", - "hy.disassemble", - "hy.as-model" - ] - } - ] - }, - { - "name": "Core", - "categories": [ - { - "name": "Meta", - "methods": [ - "hy.core.macros.doc" - ] - }, - { - "name": "Macros", - "methods": [ - "hy.core.macros.when", - "hy.core.macros.cond" - ] - }, - { - "name": "Special Forms", - "methods": [ - "^", - { - "name": "\\.", - "uri": "dot", - "internal": true - }, - "annotate", - "fn", - "fn/a", - "defn", - "defn/a", - "defmacro", - "if", - "assert", - "get", - "global", - "import", - "eval-and-compile", - "eval-when-compile", - "await", - "break", - "chainc", - "continue", - "do", - "for", - "lfor", - "dfor", - "gfor", - "sfor", - "setv", - "setx", - "let", - "match", - "defclass", - "del", - "nonlocal", - "py", - "pys", - "quasiquote", - "quote", - "require", - "return", - "cut", - "raise", - "try", - "unpack-iterable/unpack-mapping", - "unquote", - "unquote-splice", - "while", - "with", - "with/a", - "yield", - "yield-from" - ] - }, - { - "name": "Arithmetic", - "methods": [ - "hy.pyops.@", - "hy.pyops.%", - "hy.pyops.+", - "hy.pyops.-", - "hy.pyops.*", - "hy.pyops.**", - "hy.pyops./", - "hy.pyops.//" - ] - }, - { - "name": "Comparison", - "methods": [ - "hy.core.macros.cond", - "hy.pyops.<", - "hy.pyops.>", - "hy.pyops.<=", - "hy.pyops.>=", - "hy.pyops.=", - "hy.pyops.\\!=", - "hy.pyops.is", - "hy.pyops.not?", - "hy.pyops.in", - "hy.pyops.not-in" - ] - }, - { - "name": "Bitwise", - "methods": [ - "hy.pyops.\\<\\<", - "hy.pyops.>>", - "hy.pyops.&", - "hy.pyops.|", - "hy.pyops.^", - "hy.pyops.~" - ] - }, - { - "name": "Logic", - "methods": [ - "hy.pyops.not", - "hy.pyops.and", - "hy.pyops.or" - ] - } - ] - } -] diff --git a/docs/conf.py b/docs/conf.py index e12278d77..818f17d82 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,74 +75,6 @@ import hy hy.I = type(hy.I) # A trick to enable `hy:autoclass:: hy.I` -# ** Generate Cheatsheet -import json -from itertools import zip_longest -from pathlib import Path - - -def refize(spec): - role = ":hy:func:" - if isinstance(spec, dict): - _name = spec["name"] - uri = spec["uri"] - if spec.get("internal"): - role = ":ref:" - else: - uri = spec - _name = str.split(uri, ".")[-1] - return "{}`{} <{}>`".format(role, _name, uri) - - -def format_refs(refs, indent): - args = [iter(map(refize, refs))] - ref_groups = zip_longest(*args, fillvalue="") - return str.join( - " \\\n" + " " * (indent + 3), - [str.join(" ", ref_group) for ref_group in ref_groups], - ) - - -def format_row(category, divider_loc): - return "{title: <{width}} | {methods}".format( - width=divider_loc, - title=category["name"], - methods=format_refs(category["methods"], divider_loc), - ) - - -def format_table(table_spec): - table_name = table_spec["name"] - categories = table_spec["categories"] - longest_cat_name = max(len(category["name"]) for category in categories) - table = [ - table_name, - "-" * len(table_name), - "", - "=" * longest_cat_name + " " + "=" * 25, - *(format_row(category, longest_cat_name) for category in categories), - "=" * longest_cat_name + " " + "=" * 25, - "", - ] - return "\n".join(table) - - -# Modifications to the cheatsheet should be added in `cheatsheet.json` -cheatsheet_spec = json.loads(Path("./docs/cheatsheet.json").read_text()) -cheatsheet = [ - "..", - " DO NOT MODIFY THIS FILE. IT IS AUTO GENERATED BY ``conf.py``", - " If you need to change or add methods, modify ``cheatsheet_spec`` in ``conf.py``", - "", - ".. _cheatsheet:", - "", - "Cheatsheet", - "==========", - "", - *map(format_table, cheatsheet_spec), -] -Path("./docs/cheatsheet.rst").write_text("\n".join(cheatsheet)) - # ** Sphinx App Setup diff --git a/docs/index.rst b/docs/index.rst index b6b855378..178614c1a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,5 @@ Linux and Windows), and on recent versions of PyPy and Pyodide. cli interop model_patterns - cheatsheet api hacking