diff --git a/docs/0.9.5/_modules/evennia/utils/evmenu.html b/docs/0.9.5/_modules/evennia/utils/evmenu.html
index 1b467091ad..b61a72acbe 100644
--- a/docs/0.9.5/_modules/evennia/utils/evmenu.html
+++ b/docs/0.9.5/_modules/evennia/utils/evmenu.html
@@ -40,14 +40,12 @@
"""
-EvMenu
-
-This implements a full menu system for Evennia.
+The EvMenu is a full in-game menu system for Evennia.
To start the menu, just import the EvMenu class from this module.
-Example usage:
-```python
+Example usage:
+::
from evennia.utils.evmenu import EvMenu
@@ -55,11 +53,10 @@
startnode="node1",
cmdset_mergetype="Replace", cmdset_priority=1,
auto_quit=True, cmd_on_exit="look", persistent=True)
-```
Where `caller` is the Object to use the menu on - it will get a new
-cmdset while using the Menu. The menu_module_path is the python path
-to a python module containing function definitions. By adjusting the
+cmdset while using the Menu. The `menu_module_path` is the python path
+to a python module containing function definitions. By adjusting the
keyword options of the Menu() initialization call you can start the
menu at different places in the menu definition file, adjust if the
menu command should overload the normal commands or not, etc.
@@ -73,8 +70,7 @@
The menu is defined in a module (this can be the same module as the
command definition too) with function definitions:
-
-```python
+::
def node1(caller):
# (this is the start node if called like above)
@@ -88,9 +84,8 @@
def another_node(caller, input_string, **kwargs):
# code
return text, options
-```
-Where caller is the object using the menu and input_string is the
+Where `caller` is the object using the menu and input_string is the
command entered by the user on the *previous* node (the command
entered to get to this node). The node function code will only be
executed once per node-visit and the system will accept nodes with
@@ -107,42 +102,42 @@
menu is immediately exited and the default "look" command is called.
- `text` (str, tuple or None): Text shown at this node. If a tuple, the
- second element in the tuple is a help text to display at this
- node when the user enters the menu help command there.
+ second element in the tuple is a help text to display at this
+ node when the user enters the menu help command there.
- `options` (tuple, dict or None): If `None`, this exits the menu.
If a single dict, this is a single-option node. If a tuple,
- it should be a tuple of option dictionaries. Option dicts have the following keys:
+ it should be a tuple of option dictionaries. Option dicts have
+ the following keys:
- `key` (str or tuple, optional): What to enter to choose this option.
- If a tuple, it must be a tuple of strings, where the first string is the
- key which will be shown to the user and the others are aliases.
- If unset, the options' number will be used. The special key `_default`
- marks this option as the default fallback when no other option matches
- the user input. There can only be one `_default` option per node. It
- will not be displayed in the list.
+ If a tuple, it must be a tuple of strings, where the first string is the
+ key which will be shown to the user and the others are aliases.
+ If unset, the options' number will be used. The special key `_default`
+ marks this option as the default fallback when no other option matches
+ the user input. There can only be one `_default` option per node. It
+ will not be displayed in the list.
- `desc` (str, optional): This describes what choosing the option will do.
- `goto` (str, tuple or callable): If string, should be the name of node to go to
- when this option is selected. If a callable, it has the signature
- `callable(caller[,raw_input][,**kwargs])`. If a tuple, the first element
- is the callable and the second is a dict with the `**kwargs` to pass to
- the callable. Those kwargs will also be passed into the next node if possible.
- Such a callable should return either a str or a (str, dict), where the
- string is the name of the next node to go to and the dict is the new,
- (possibly modified) kwarg to pass into the next node. If the callable returns
- None or the empty string, the current node will be revisited.
+ when this option is selected. If a callable, it has the signature
+ `callable(caller[,raw_input][,**kwargs])`. If a tuple, the first element
+ is the callable and the second is a dict with the kwargs to pass to
+ the callable. Those kwargs will also be passed into the next node if possible.
+ Such a callable should return either a str or a (str, dict), where the
+ string is the name of the next node to go to and the dict is the new,
+ (possibly modified) kwarg to pass into the next node. If the callable returns
+ None or the empty string, the current node will be revisited.
- `exec` (str, callable or tuple, optional): This takes the same input as `goto` above
- and runs before it. If given a node name, the node will be executed but will not
- be considered the next node. If node/callback returns str or (str, dict), these will
- replace the `goto` step (`goto` callbacks will not fire), with the string being the
- next node name and the optional dict acting as the kwargs-input for the next node.
- If an exec callable returns the empty string (only), the current node is re-run.
+ and runs before it. If given a node name, the node will be executed but will not
+ be considered the next node. If node/callback returns str or (str, dict), these will
+ replace the `goto` step (`goto` callbacks will not fire), with the string being the
+ next node name and the optional dict acting as the kwargs-input for the next node.
+ If an exec callable returns `None`, the current node is re-run.
-If `key` is not given, the option will automatically be identified by
+If key is not given, the option will automatically be identified by
its number 1..N.
Example:
-
-```python
+::
# in menu_module.py
@@ -178,11 +173,8 @@
text = "This ends the menu since there are no options."
return text, None
-```
-
When starting this menu with `Menu(caller, "path.to.menu_module")`,
the first node will look something like this:
-
::
This is a node text
@@ -201,8 +193,9 @@
reaching a node without any options.
-For a menu demo, import `CmdTestMenu` from this module and add it to
-your default cmdset. Run it with this module, like `testmenu evennia.utils.evmenu`.
+For a menu demo, import CmdTestMenu from this module and add it to
+your default cmdset. Run it with this module, like `testmenu
+evennia.utils.evmenu`.
## Menu generation from template string
@@ -218,13 +211,10 @@
For maximum flexibility you can inject normally-created nodes in the menu tree
before passing it to EvMenu. If that's not needed, you can also create a menu
in one step with:
-
-```python
+::
evmenu.template2menu(caller, menu_template, goto_callables)
-```
-
The `goto_callables` is a mapping `{"funcname": callable, ...}`, where each
callable must be a module-global function on the form
`funcname(caller, raw_string, **kwargs)` (like any goto-callable). The
@@ -302,9 +292,9 @@
key:values will be converted to strings/numbers with literal_eval before passed
into the callable.
-The \\> option takes a glob or regex to perform different actions depending
-on user input. Make sure to sort these in increasing order of generality since
-they will be tested in sequence.
+The "> " option takes a glob or regex to perform different actions depending on user
+input. Make sure to sort these in increasing order of generality since they
+will be tested in sequence.
----
@@ -583,7 +573,9 @@
by default in all nodes of the menu. This will print out the current state of
the menu. Deactivate for production use! When the debug flag is active, the
`persistent` flag is deactivated.
- **kwargs: All kwargs will become initialization variables on `caller.ndb._menutree`,
+
+ Keyword Args:
+ any (any): All kwargs will become initialization variables on `caller.ndb._evmenu`,
to be available at run.
Raises:
@@ -783,6 +775,30 @@
Call a node-like callable, with a variable number of raw_string, *args, **kwargs, all of
which should work also if not present (only `caller` is always required). Return its result.
+ Viable node-like callable forms:
+ ::
+
+ _callname(caller)
+ _callname(caller, raw_string)
+ _callname(caller, **kwargs)
+ _callname(caller, raw_string, **kwargs)
+
+ If this is a node:
+
+ - `caller` is the one using the menu.
+ - `raw_string` is the users exact input on the *previous* node.
+ - `**kwargs` is either passed through the previous node or returned
+ along with the node name from the goto-callable leading to this node.
+
+ If this is a goto-callable:
+
+ - `caller` is the one using the menu.
+ - `raw_string` is the user's exact input when chosing the option that triggered
+ this goto-callable.
+ - `**kwargs` is any extra dict passed to the callable in the option
+ definition, or (if no explit kwarg was given to the callable) the
+ previous node's kwarg, if any.
+
"""
try:
try:
@@ -987,7 +1003,8 @@
raw_string (str): The raw default string entered on the
previous node (only used if the node accepts it as an
argument)
- **kwargs: Extra arguments to goto callables.
+ Keyword Args:
+ any: Extra arguments to goto callables.
"""
@@ -1360,29 +1377,33 @@
option_generator (callable or list): A list of strings indicating the options, or a callable
that is called as option_generator(caller) to produce such a list.
select (callable or str, optional): Node to redirect a selection to. Its `**kwargs` will
- contain the `available_choices` list and `selection` will hold one of the elements in
- that list. If a callable, it will be called as
- `select(caller, menuchoice, **kwargs)` where menuchoice is the chosen option as a
- string and `available_choices` is a kwarg mapping the option keys to the choices
- offered by the option_generator. The callable whould return the name of the target node
- to goto after this selection (or None to repeat the list-node). Note that if this is not
- given, the decorated node must itself provide a way to continue from the node!
+ contain the `available_choices` list and `selection` will hold one
+ of the elements in that list. If a callable, it will be called as
+ `select(caller, menuchoice, **kwargs)` where menuchoice is the
+ chosen option as a string and `available_choices` is the list of available
+ options offered by the option_generator. The callable whould return
+ the name of the target node to goto after this selection (or None to repeat the
+ list-node). Note that if this is not given, the decorated node
+ must itself provide a way to continue from the node!
pagesize (int): How many options to show per page.
Example:
+ ::
- ```python
- list_node(['foo', 'bar'], select)
- def node_index(caller):
- text = "describing the list"
- return text, []
- ```
+ def _selectfunc(caller, menuchoice, **kwargs):
+ # menuchoice would be either 'foo' or 'bar' here
+ # kwargs['available_choices'] would be the list ['foo', 'bar']
+ return "the_next_node_to_go_to"
+
+ @list_node(['foo', 'bar'], _selectfunc)
+ def node_index(caller):
+ text = "describing the list"
+ return text, []
Notes:
- All normal `goto` or `exec` callables returned from the decorated nodes
- will, if they accept `**kwargs`, get a new kwarg 'available_choices'
- injected. These are the ordered list of named options (descs) visible
- on the current node page.
+ All normal `goto` or `exec` callables returned from the decorated nodes will, if they accept
+ `**kwargs`, get a new kwarg `available_choices` injected. This is the ordered list of named
+ options (descs) visible on the current node page.
"""
@@ -1603,51 +1624,60 @@