From 2df31370618b8895a3bcf41213d82992925b740d Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <progval@gmail.com>
Date: Mon, 20 Jan 2014 10:58:19 +0100
Subject: [PATCH] Document dynamicScope.

---
 develop/events.rst      | 15 ++++++++++-----
 develop/using_utils.rst | 25 +++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/develop/events.rst b/develop/events.rst
index 57ba839..feb5f8d 100644
--- a/develop/events.rst
+++ b/develop/events.rst
@@ -1,9 +1,9 @@
-***************
-Catching events
-***************
+***********************************
+Special methods and catching events
+***********************************
 
-This page is a non-exhaustive list of catchable
-events via plugin methods (other events include
+This page is a non-exhaustive list of special plugin method names and
+events catchable via those methods (other events include
 :ref:`configuration hooks <configuration-hooks>` and
 :ref:`HTTP server callbacks <http_plugins>`)
 
@@ -18,3 +18,8 @@ Those command take two commands: an :ref:`Irc object <supybot-irclib-irc>`
 and a :ref:`IrcMsg object <supybot-ircmsgs>`.
 
 To get a list of all possible messages, check IRC RFCs.
+
+.. _commands_handling:
+
+Commands handling
+=================
diff --git a/develop/using_utils.rst b/develop/using_utils.rst
index 802d64f..34150b7 100644
--- a/develop/using_utils.rst
+++ b/develop/using_utils.rst
@@ -377,3 +377,28 @@ supybot.utils.iter - iterable utilities
   predicate p
 
 * choice(iterable) - Returns a random element from the iterable
+
+
+supybot.dynamicScope / dynamic - accessing variables in the stack
+-----------------------------------------------------------------
+
+This feature is not in `supybot.utils` but still deserves to be documented
+as a utility.
+
+Althrough you should avoid using this feature as long as you can, it is
+sometimes necessary to access variables the Supybot API does not provide you.
+
+For instance, the `Aka` plugin provides per-channel aliases by overriding
+:ref:`getCommandMethod <commands_handling>`. However, the channel where the
+command is called is not passed to this functions, so when writing `Aka` I
+could either add this parameter (and thus break all plugins all plugins
+already overriding this method) or use this hack. I choosed this hack.
+
+How does it work? This is quite simple: ``dynamic.channel`` is a shortcut
+for ``supybot.dynamicScope.DynamicScope.__getattr__('channel')``, which
+browse the call stack backwards, looking for a variable named ``channel``,
+and then returns is as far as it finds it (and returns ``None`` if there
+is no such variale).
+
+Note that you don't have to import ``dynamicScope``, the ``dynamic`` object
+is automatically set as a global variable when Supybot starts.