From 5271944f9aa55bd559b6831749f1369fa4f26ba3 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sat, 1 Oct 2011 13:21:34 +0200 Subject: [PATCH] docs: updating rest documentationdocs: updating rest documentation.. --- docs/sphinx/source/wiki/Attributes.rst | 62 +++++++++++++++++++ .../sphinx/source/wiki/DefaultCommandHelp.rst | 54 ++++++++-------- 2 files changed, 88 insertions(+), 28 deletions(-) diff --git a/docs/sphinx/source/wiki/Attributes.rst b/docs/sphinx/source/wiki/Attributes.rst index 4700ddeb75..ed8d17868a 100644 --- a/docs/sphinx/source/wiki/Attributes.rst +++ b/docs/sphinx/source/wiki/Attributes.rst @@ -193,6 +193,68 @@ Example of non-supported save: bad.dbobj = myobj obj.db.test8 = bad # this will likely lead to a traceback +Storing nested data directly on the variable +-------------------------------------------- + +Evennia needs to do a lot of work behind the scenes in order to save and +retrieve data from the database. Most of the time, things work just like +normal Python, but there is one further exception except the one about +storing database objects above. It is related to updating already +existing attributes in-place. Normally this works just as it should. For +example, you can do + +:: + + # saving data + obj.db.mydict["key"] = "test1" + obj.db.mylist[34] = "test2" + obj.db.mylist.append("test3") + # retrieving data + obj.db.mydict["key"] # returns "test1" + obj.db.mylist[34] # returns "test2 + obj.db.mylist[-1] # returns "test3" + +and it will work fine, thanks to a lot of magic happening behind the +scenes. What will *not* work however is editing *nested* +lists/dictionaries in-place. This is due to the way Python referencing +works. Consider the following: + +:: + + obj.db.mydict = 1:2:3 + +This is a perfectly valid nested dictionary and Evennia will store it +just fine. + +:: + + obj.db.mydict[1][2] # correctly returns 3 + +However: + +:: + + obj.db.mydict[1][2] = "test" # fails! + +will not work - trying to edit the nested structure will fail silently +and nothing will have changed. No, this is not consistent with normal +Python operation, it's where the database magic fails. All is not lost +however. In order to change a nested structure, you simply need to use a +temporary variable: + +:: + + # retrieve old db data into temporary variable + mydict = obj.db.mydict + # update temporary variable + mydict[1][2] = "test" + # save back to database + obj.db.mydict = mydict + # test + obj.db.mydict[1][2] # now correctly returns "test" + +mydict was updated and recreated in the database. + Notes ----- diff --git a/docs/sphinx/source/wiki/DefaultCommandHelp.rst b/docs/sphinx/source/wiki/DefaultCommandHelp.rst index 1321542cec..aad8c61b7c 100644 --- a/docs/sphinx/source/wiki/DefaultCommandHelp.rst +++ b/docs/sphinx/source/wiki/DefaultCommandHelp.rst @@ -20,7 +20,7 @@ Admin ----- `Link to Python -module `_ +module `_ @boot ~~~~~ @@ -200,7 +200,7 @@ Building -------- `Link to Python -module `_ +module `_ @alias ~~~~~~ @@ -652,14 +652,13 @@ module [= ] Switches: - start - start a previously added script - stop - stop a previously added script Attaches the given script to the object and starts it. Script path - can be given from the base location for scripts as given in - settings. If stopping/starting an already existing script, the - script's key can be given instead (if giving a path, *all* scripts - with this path on will be affected). If no script name is given, - all scripts on the object is affected (or displayed if no start/stop - switch is set). + start - start all non-running scripts on object, or a given script only + stop - stop all scripts on objects, or a given script only If no script path/key is given, lists all scripts active on the given + object. + Script path can be given from the base location for scripts as given in + settings. If adding a new script, it will be started automatically (no /start + switch is needed). Using the /start or /stop switches on an object without + specifying a script key/path will start/stop ALL scripts on the object. @set ~~~~ @@ -804,7 +803,7 @@ Comms ----- `Link to Python -module `_ +module `_ @cboot ~~~~~~ @@ -1115,7 +1114,7 @@ General ------- `Link to Python -module `_ +module `_ @encoding ~~~~~~~~~ @@ -1459,7 +1458,7 @@ System ------ `Link to Python -module `_ +module `_ @objects ~~~~~~~~ @@ -1508,20 +1507,19 @@ module In this limited python environment, there are a - few variables made available to give access to - the system. available_vars: 'self','me' : caller - 'here' : caller.location - 'obj' : dummy obj instance - 'script': dummy script instance - 'config': dummy conf instance - 'ObjectDB' : ObjectDB class - 'ScriptDB' : ScriptDB class - 'ServerConfig' ServerConfig class - only two - variables are defined: 'self'/'me' which refers to one's - own object, and 'here' which refers to self's current - location. + @py Separate multiple commands by ';'. A few variables are made + available for convenience in order to offer access to the system + (you can import more at execution time). Available variables in @py environment: + self, me : caller + here : caller.location + obj : dummy obj instance + script : dummy script instance + config : dummy conf instance + ObjectDB : ObjectDB class + ScriptDB : ScriptDB class + ServerConfig : ServerConfig class + inherits_from(obj, parent) : check object inheritance rNote: In the wrong hands this command is a severe security risk. + It should only be accessible by trusted server admins/superusers.n @reload ~~~~~~~ @@ -1670,7 +1668,7 @@ Unloggedin ---------- `Link to Python -module `_ +module `_ connect ~~~~~~~