From 9ed9bc5e1153d434b217a328287252984f4f3987 Mon Sep 17 00:00:00 2001 From: Gregor Best Date: Mon, 11 May 2015 23:38:02 +0200 Subject: [PATCH 1/4] Add documentation for the (nonlocal ...) directive Signed-off-by: Gregor Best --- docs/language/api.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/language/api.rst b/docs/language/api.rst index bbc2868..9a285d5 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -1008,6 +1008,29 @@ conditional expression. Some examples: [0, 2, 4, 6, 8] +nonlocal +-------- + +``nonlocal`` can be used to mark a symbol as not local to the current scope. +The parameters are the names of symbols to mark as nonlocal. This is necessary +to modify variables through nested ``let`` scopes: + +.. code-block:: clj + + (let [[x 0]] + (for [y (range 10)] + (let [[z (inc y)]] + (nonlocal x) ; allow the setv to "jump scope" to resolve x + (setv x (+ x y)))) + x) + +Without the call to ``(nonlocal x)``, this code would result in an +UnboundLocalError being raised during the call to ``setv``. This is the result +of the way Python handles scoping for nested functions, which are used by Hy to +implement ``let``. See `PEP3104 `_ +for further information. + + not --- From e4ed5cc357fa7380965cfddfceb6277a37cbc7c7 Mon Sep 17 00:00:00 2001 From: Gregor Best Date: Tue, 12 May 2015 00:00:54 +0200 Subject: [PATCH 2/4] Mention that `nonlocal` is for Python3.0 and up only --- docs/language/api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/language/api.rst b/docs/language/api.rst index 9a285d5..8a10a88 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -1011,6 +1011,8 @@ conditional expression. Some examples: nonlocal -------- +**PYTHON 3.0 AND UP ONLY!** + ``nonlocal`` can be used to mark a symbol as not local to the current scope. The parameters are the names of symbols to mark as nonlocal. This is necessary to modify variables through nested ``let`` scopes: From 5743f6ae78cf0e000da7cf103085981444d2eb86 Mon Sep 17 00:00:00 2001 From: Gregor Best Date: Tue, 12 May 2015 09:29:55 +0200 Subject: [PATCH 3/4] Add `versionadded` tag to nonlocal doc --- docs/language/api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/language/api.rst b/docs/language/api.rst index 8a10a88..238f7d3 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -1011,6 +1011,8 @@ conditional expression. Some examples: nonlocal -------- +.. versionadded:: 0.11.1 + **PYTHON 3.0 AND UP ONLY!** ``nonlocal`` can be used to mark a symbol as not local to the current scope. From 802ef0cd0d1215b4697abd776d87335bfb9bac15 Mon Sep 17 00:00:00 2001 From: Gregor Best Date: Tue, 12 May 2015 09:30:22 +0200 Subject: [PATCH 4/4] reword nonlocal doc a bit to mention nested fn scopes as well --- docs/language/api.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/language/api.rst b/docs/language/api.rst index 238f7d3..c84745c 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -1017,7 +1017,7 @@ nonlocal ``nonlocal`` can be used to mark a symbol as not local to the current scope. The parameters are the names of symbols to mark as nonlocal. This is necessary -to modify variables through nested ``let`` scopes: +to modify variables through nested ``let`` or ``fn`` scopes: .. code-block:: clj @@ -1028,11 +1028,22 @@ to modify variables through nested ``let`` scopes: (setv x (+ x y)))) x) -Without the call to ``(nonlocal x)``, this code would result in an -UnboundLocalError being raised during the call to ``setv``. This is the result -of the way Python handles scoping for nested functions, which are used by Hy to -implement ``let``. See `PEP3104 `_ -for further information. + (defn some-function [] + (let [[x 0]] + (register-some-callback + (fn [stuff] + (nonlocal x) + (setv x stuff))))) + +In the first example, without the call to ``(nonlocal x)``, this code would +result in an UnboundLocalError being raised during the call to ``setv``. + +In the second example, without the call to ``(nonlocal x)``, the inner function +would redefine ``x`` to ``stuff`` inside its local scope instead of overwriting +the ``x`` in the outer function + +See `PEP3104 `_ for further +information. not