Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated docstrings for a few modules, adopting to styles as per #709.

Browse source
This commit is contained in:
Griatch 2015-05-15 18:43:04 +02:00
parent 809116aabc
commit ae88d67548
2 changed files with 190 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

157
evennia/commands/cmdhandler.py
View file

@ -2,35 +2,35 @@
Command handler Command handler
This module contains the infrastructure for accepting commands on the This module contains the infrastructure for accepting commands on the
command line. The process is as follows: command line. The processing of a command works as follows:
1) The calling object (caller) inputs a string and triggers the command parsing system. 1. The calling object (caller) is analyzed based on its callertype.
2) The system checks the state of the caller - loggedin or not 2. Cmdsets are gathered from different sources:
3) If no command string was supplied, we search the merged cmdset for system command CMD_NOINPUT - channels: all available channel names are auto-created into a cmdset, to allow
and branches to execute that. --> Finished for giving the channel name and have the following immediately
4) Cmdsets are gathered from different sources (in order of dropping priority): sent to the channel. The sending is performed by the CMD_CHANNEL
channels - all available channel names are auto-created into a cmdset, to allow system command.
for giving the channel name and have the following immediately - object cmdsets: all objects at caller's location are scanned for non-empty
sent to the channel. The sending is performed by the CMD_CHANNEL cmdsets. This includes cmdsets on exits.
system command. - caller: the caller is searched for its own currently active cmdset.
object cmdsets - all objects at caller's location are scanned for non-empty - player: lastly the cmdsets defined on caller.player are added.
cmdsets. This includes cmdsets on exits. 3. The collected cmdsets are merged together to a combined, current cmdset.
caller - the caller is searched for its own currently active cmdset. 4. If the input string is empty -> check for CMD_NOINPUT command in
player - lastly the cmdsets defined on caller.player are added. current cmdset or fallback to error message. Exit.
5) All the gathered cmdsets (if more than one) are merged into one using the cmdset priority rules. 5. The Command Parser is triggered, using the current cmdset to analyze the
6) If merged cmdset is empty, raise NoCmdSet exception (this should not happen, at least the input string for possible command matches.
player should have a default cmdset available at all times). --> Finished 6. If multiple matches are found -> check for CMD_MULTIMATCH in current
7) The raw input string is parsed using the parser defined by settings.COMMAND_PARSER. It cmdset, or fallback to error message. Exit.
uses the available commands from the merged cmdset to know which commands to look for and 7. If no match was found -> check for CMD_NOMATCH in current cmdset or
returns one or many matches. fallback to error message. Exit.
8) If match list is empty, branch to system command CMD_NOMATCH --> Finished 8. A single match was found. If this is a channel-command (i.e. the
9) If match list has more than one element, branch to system command CMD_MULTIMATCH --> Finished ommand name is that of a channel), --> check for CMD_CHANNEL in
10) A single match was found. If this is a channel-command (i.e. the command name is that of a channel), current cmdset or use channelhandler default. Exit.
branch to CMD_CHANNEL --> Finished 9. At this point we have found a normal command. We assign useful variables to it that
11) At this point we have found a normal command. We assign useful variables to it that will be available to the command coder at run-time.
will be available to the command coder at run-time. 12. We have a unique cmdobject, primed for use. Call all hooks:
12) We have a unique cmdobject, primed for use. Call all hooks: `at_pre_cmd()`, `cmdobj.parse()`, `cmdobj.func()` and finally `at_post_cmd()`.
at_pre_cmd(), cmdobj.parse(), cmdobj.func() and finally at_post_cmd(). 13. Return deferred that will fire with the return from `cmdobj.func()` (unused by default).
""" """
@ -128,24 +128,37 @@ def get_and_merge_cmdsets(caller, session, player, obj,
""" """
Gather all relevant cmdsets and merge them. Gather all relevant cmdsets and merge them.
callertype is one of "session", "player" or "object" dependin Args:
on which level the cmdhandler is invoked. Session includes the caller (Session, Player or Object): The entity executing the command. Which
cmdsets available to Session, Player and its eventual puppeted Object. type of object this is depends on the current game state; for example
Player-level include cmdsets on Player and Object, while calling when the user is not logged in, this will be a Session, when being OOC
the handler on an Object only includes cmdsets on itself. it will be a Player and when puppeting an object this will (often) be
a Character Object. In the end it depends on where the cmdset is stored.
session (Session or None): The Session associated with caller, if any.
player (Player or None): The calling Player associated with caller, if any.
obj (Object or None): The Object associated with caller, if any.
callertype (str): This identifies caller as either "player", "object" or "session"
to avoid having to do this check internally.
sessid (int, optional): Session ID. This is not used at the moment.
The cdmsets are merged in order generality, so that the Object's Returns:
cmdset is merged last (and will thus take precedence over cmdset (Deferred): This deferred fires with the merged cmdset
same-named and same-prio commands on Player and Session). result once merger finishes.
Notes:
The cdmsets are merged in order or generality, so that the
Object's cmdset is merged last (and will thus take precedence
over same-named and same-prio commands on Player and Session).
Note that this function returns a deferred!
""" """
try: try:
local_obj_cmdsets = [None] local_obj_cmdsets = [None]
@inlineCallbacks @inlineCallbacks
def _get_channel_cmdsets(player, player_cmdset): def _get_channel_cmdsets(player, player_cmdset):
"Channel-cmdsets" """
Helper-method; Get channel-cmdsets
"""
# Create cmdset for all player's available channels # Create cmdset for all player's available channels
try: try:
channel_cmdset = None channel_cmdset = None
@ -159,7 +172,9 @@ def get_and_merge_cmdsets(caller, session, player, obj,
@inlineCallbacks @inlineCallbacks
def _get_local_obj_cmdsets(obj, obj_cmdset): def _get_local_obj_cmdsets(obj, obj_cmdset):
"Object-level cmdsets" """
Helper-method; Get Object-level cmdsets
"""
# Gather cmdsets from location, objects in location or carried # Gather cmdsets from location, objects in location or carried
try: try:
local_obj_cmdsets = [None] local_obj_cmdsets = [None]
@ -202,7 +217,10 @@ def get_and_merge_cmdsets(caller, session, player, obj,
@inlineCallbacks @inlineCallbacks
def _get_cmdset(obj): def _get_cmdset(obj):
"Get cmdset, triggering all hooks" """
Helper method; Get cmdset while making sure to trigger all
hooks safely.
"""
try: try:
yield obj.at_cmdset_get() yield obj.at_cmdset_get()
except Exception: except Exception:
@ -307,43 +325,54 @@ def get_and_merge_cmdsets(caller, session, player, obj,
@inlineCallbacks @inlineCallbacks
def cmdhandler(called_by, raw_string, _testing=False, callertype="session", sessid=None, **kwargs): def cmdhandler(called_by, raw_string, _testing=False, callertype="session", sessid=None, **kwargs):
""" """
This is the main function to handle any string sent to the engine. This is the main mechanism that handles any string sent to the engine.
called_by - object on which this was called from. This is either a Session, a Player or an Object. Args:
raw_string - the command string given on the command line called_by (Session, Player or Object): Object from which this
_testing - if we should actually execute the command or not. command was called. which this was called from. What this is
if True, the command instance will be returned instead. depends on the game state.
callertype - this is one of "session", "player" or "object", in decending raw_string (str): The command string as given on the command line.
order. So when the Session is the caller, it will merge its _testing (bool, optional): Used for debug purposes and decides if we
own cmdset into cmdsets from both Player and eventual puppeted should actually execute the command or not. If True, the
Object (and cmdsets in its room etc). A Player will only command instance will be returned.
include its own cmdset and the Objects and so on. Merge order callertype (str, optional): One of "session", "player" or
is the same order, so that Object cmdsets are merged in last, "object". These are treated in decending order, so when the
giving them precendence for same-name and same-prio commands. Session is the caller, it will merge its own cmdset into
sessid - Relevant if callertype is "player" - the session id will help cmdsets from both Player and eventual puppeted Object (and
retrieve the correct cmdsets from puppeted objects. cmdsets in its room etc). A Player will only include its own
**kwargs - other keyword arguments will be assigned as named variables on the cmdset and the Objects and so on. Merge order is the same
retrieved command object *before* it is executed. This is unuesed order, so that Object cmdsets are merged in last, giving them
in default Evennia but may be used by code to set custom flags or precendence for same-name and same-prio commands.
special operating conditions for a command as it executes. sessid (int, optional): Relevant if callertype is "player" - the session id will help
retrieve the correct cmdsets from puppeted objects.
Kwargs:
kwargs (any): other keyword arguments will be assigned as named variables on the
retrieved command object *before* it is executed. This is unused
in default Evennia but may be used by code to set custom flags or
special operating conditions for a command as it executes.
Returns:
deferred (Deferred): This deferred is fired with the return
value of the command's `func` method. This is not used in
default Evennia.
Note that this function returns a deferred!
""" """
@inlineCallbacks @inlineCallbacks
def _run_command(cmd, cmdname, args): def _run_command(cmd, cmdname, args):
""" """
This initializes and runs the Command instance once the parser Helper function: This initializes and runs the Command
has identified it as either a normal command or one of the instance once the parser has identified it as either a normal
system commands. command or one of the system commands.
Args: Args:
cmd (Command): command object cmd (Command): command object
cmdname (str): name of command cmdname (str): name of command
args (str): extra text entered after the identified command args (str): extra text entered after the identified command
Returns: Returns:
deferred (Deferred): this will fire when the func() method deferred (Deferred): this will fire with the return of the
returns. command's `func` method.
""" """
try: try:
# Assign useful variables to the instance # Assign useful variables to the instance

159
evennia/commands/cmdparser.py
View file

@ -1,8 +1,9 @@
""" """
The default command parser. Use your own by assigning The default command parser. Use your own by assigning
settings.COMMAND_PARSER to a Python path to a module containing the `settings.COMMAND_PARSER` to a Python path to a module containing the
replacing cmdparser function. The replacement parser must matches replacing cmdparser function. The replacement parser must accept the
on the sme form as the default cmdparser. same inputs as the default one.
""" """
from django.utils.translation import ugettext as _ from django.utils.translation import ugettext as _
@ -13,32 +14,50 @@ def cmdparser(raw_string, cmdset, caller, match_index=None):
This function is called by the cmdhandler once it has This function is called by the cmdhandler once it has
gathered and merged all valid cmdsets valid for this particular parsing. gathered and merged all valid cmdsets valid for this particular parsing.
raw_string - the unparsed text entered by the caller. Args:
cmdset - the merged, currently valid cmdset raw_string (str): The unparsed text entered by the caller.
caller - the caller triggering this parsing cmdset (CmdSet): The merged, currently valid cmdset
match_index - an optional integer index to pick a given match in a caller (Session, Player or Object): The caller triggering this parsing.
list of same-named command matches. match_index (int, optional): Index to pick a given match in a
list of same-named command matches. If this is given, it suggests
this is not the first time this function was called: normally
the first run resulted in a multimatch, and the index is given
to select between the results for the second run.
The cmdparser understand the following command combinations (where Notes:
[] marks optional parts. The cmdparser understand the following command combinations (where
[] marks optional parts.
[cmdname[ cmdname2 cmdname3 ...] [the rest] ```
[cmdname[ cmdname2 cmdname3 ...] [the rest]
```
A command may consist of any number of space-separated words of any A command may consist of any number of space-separated words of any
length, and contain any character. It may also be empty. length, and contain any character. It may also be empty.
The parser makes use of the cmdset to find command candidates. The
parser return a list of matches. Each match is a tuple with its
first three elements being the parsed cmdname (lower case),
the remaining arguments, and the matched cmdobject from the cmdset.
The parser makes use of the cmdset to find command candidates. The
parser return a list of matches. Each match is a tuple with its
first three elements being the parsed cmdname (lower case),
the remaining arguments, and the matched cmdobject from the cmdset.
""" """
def create_match(cmdname, string, cmdobj): def create_match(cmdname, string, cmdobj):
""" """
Evaluates the quality of a match by counting how many chars of cmdname Builds a command match by splitting the incoming string and
matches string (counting from beginning of string). We also calculate evaluating the quality of the match.
a ratio from 0-1 describing how much cmdname matches string.
We return a tuple (cmdname, count, ratio, args, cmdobj). Args:
cmdname (str): Name of command to check for.
string (str): The string to match against.
cmdobj (str): The full Command instance.
Returns:
match (tuple): This is on the form (cmdname, args, cmdobj, cmdlen, mratio), where
`cmdname` is the command's name and `args` the rest of the incoming string,
without said command name. `cmdobj` is the Command instance, the cmdlen is
the same as len(cmdname) and mratio is a measure of how big a part of the
full input string the cmdname takes up - an exact match would be 1.0.
""" """
cmdlen, strlen = len(cmdname), len(string) cmdlen, strlen = len(cmdname), len(string)
@ -126,27 +145,31 @@ def at_search_result(msg_obj, ostring, results, global_search=False,
nofound_string=None, multimatch_string=None, quiet=False): nofound_string=None, multimatch_string=None, quiet=False):
""" """
Called by search methods after a result of any type has been found. Called by search methods after a result of any type has been found.
Takes a search result (a list) and formats eventual errors.
Takes a search result (a list) and Args:
formats eventual errors. msg_obj (Object): Object to receive feedback.
ostring (str): Original search string
msg_obj - object to receive feedback. results (list): List of found matches (0, 1 or more)
ostring - original search string global_search (bool, optional): I this was a global_search or not (if it
results - list of found matches (0, 1 or more) is, there might be an idea of supplying dbrefs instead of only
global_search - if this was a global_search or not numbers)
(if it is, there might be an idea of supplying nofound_string (str, optional): Custom string for not-found error message.
dbrefs instead of only numbers) multimatch_string (str, optional): Custom string for multimatch error header
nofound_string - optional custom string for not-found error message. quiet (bool, optional): Work normally, but don't echo to caller, just return the
multimatch_string - optional custom string for multimatch error header
quiet - work normally, but don't echo to caller, just return the
results. results.
Multiple matches are returned to the searching object Returns:
as result (Object or None): The filtered object. If None, it suggests a
1-object nofound/multimatch error and the error message was sent directly to `msg_obj`. If
2-object the `multimatch_strin` was not given, the multimatch error will be returned as
3-object
etc ```
1-object
2-object
3-object
etc
```
""" """
string = "" string = ""
@ -202,33 +225,36 @@ def at_multimatch_input(ostring):
if the user wants to differentiate between multiple matches if the user wants to differentiate between multiple matches
(usually found during a previous search). (usually found during a previous search).
This method should separate out any identifiers from the search Args:
string used to differentiate between same-named objects. The ostring (str): The search criterion. The parser will specifically
result should be a tuple (index, search_string) where the index understand input on a form like `2-object` to separate
gives which match among multiple matches should be used (1 being multimatches from each other.
the lowest number, rather than 0 as in Python).
This parser version will identify search strings on the following Returns:
forms selection (tuple): This is on the form (index, ostring).
2-object Notes:
This method should separate out any identifiers from the search
string used to differentiate between same-named objects. The
result should be a tuple (index, search_string) where the index
gives which match among multiple matches should be used (1 being
the lowest number, rather than 0 as in Python).
This will be parsed to (2, "object") and, if applicable, will tell This will be parsed to (2, "object") and, if applicable, will tell
the engine to pick the second from a list of same-named matches of the engine to pick the second from a list of same-named matches of
objects called "object". objects called "object".
Ex for use in a game session: Example:
> look
> look You see: ball, ball, ball and ball.
You see: ball, ball, ball and ball. > get ball
> get ball There where multiple matches for ball:
There where multiple matches for ball: 1-ball
1-ball 2-ball
2-ball 3-ball
3-ball 4-ball
4-ball > get 3-ball
> get 3-ball You get the ball.
You get the ball.
""" """
@ -250,6 +276,15 @@ def at_multimatch_input(ostring):
def at_multimatch_cmd(caller, matches): def at_multimatch_cmd(caller, matches):
""" """
Format multiple command matches to a useful error. Format multiple command matches to a useful error.
Args:
caller (Object): Calling object.
matches (list): A list of matchtuples `(num, Command)`.
Returns:
formatted (str): A nicely formatted string, including
eventual errors.
""" """
string = "There were multiple matches:" string = "There were multiple matches:"
for num, match in enumerate(matches): for num, match in enumerate(matches):