evennia.commands.default.help¶
The help command. The basic idea is that help texts for commands are best written by those that write the commands - the developers. So command-help is all auto-loaded and searched from the current command set. The normal, database-tied help system is used for collaborative creation of other help topics such as RP help or game-world aides. Help entries can also be created outside the game in modules given by **settings.FILE_HELP_ENTRY_MODULES**.
-
class
evennia.commands.default.help.
CmdHelp
(**kwargs)[source]¶ Bases:
evennia.commands.default.muxcommand.MuxCommand
Get help.
- Usage:
help help <topic, command or category> help <topic>/<subtopic> help <topic>/<subtopic>/<subsubtopic> …
Use the ‘help’ command alone to see an index of all help topics, organized by category. Some big topics may offer additional sub-topics.
-
key
= 'help'¶
-
aliases
= ['?']¶
-
locks
= 'cmd:all()'¶
-
arg_regex
= re.compile('\\s|$', re.IGNORECASE)¶
-
return_cmdset
= True¶
-
help_more
= True¶
-
index_type_separator_clr
= '|w'¶
-
index_category_clr
= '|W'¶
-
index_topic_clr
= '|G'¶
-
suggestion_cutoff
= 0.6¶
-
suggestion_maxnum
= 5¶
-
subtopic_separator_char
= '/'¶
-
clickable_topics
= True¶
-
msg_help
(text, **kwargs)[source]¶ messages text to the caller, adding an extra oob argument to indicate that this is a help command result and could be rendered in a separate help window.
-
format_help_entry
(topic='', help_text='', aliases=None, suggested=None, subtopics=None, click_topics=True)[source]¶ This visually formats the help entry. This method can be overridden to customize the way a help entry is displayed.
- Parameters
title (str, optional) – The title of the help entry.
help_text (str, optional) – Text of the help entry.
aliases (list, optional) – List of help-aliases (displayed in header).
suggested (list, optional) – Strings suggested reading (based on title).
subtopics (list, optional) – A list of strings - the subcategories available for this entry.
click_topics (bool, optional) – Should help topics be clickable. Default is True.
- Returns
help_message (str) – Help entry formated for console.
-
format_help_index
(cmd_help_dict=None, db_help_dict=None, title_lone_category=False, click_topics=True)[source]¶ Output a category-ordered g for displaying the main help, grouped by category.
- Parameters
cmd_help_dict (dict) – A dict {“category”: [topic, topic, …]} for command-based help.
db_help_dict (dict) – A dict {“category”: [topic, topic], …]} for database-based help.
title_lone_category (bool, optional) – If a lone category should be titled with the category name or not. While pointless in a general index, the title should probably show when explicitly listing the category itself.
click_topics (bool, optional) – If help-topics are clickable or not (for webclient or telnet clients with MXP support).
- Returns
str – The help index organized into a grid.
Notes
The input are the pre-loaded help files for commands and database-helpfiles respectively. You can override this method to return a custom display of the list of commands and topics.
-
can_read_topic
(cmd_or_topic, caller)[source]¶ Helper method. If this return True, the given help topic be viewable in the help listing. Note that even if this returns False, the entry will still be visible in the help index unless should_list_topic is also returning False.
- Parameters
cmd_or_topic (Command, HelpEntry or FileHelpEntry) – The topic/command to test.
caller – the caller checking for access.
- Returns
bool – If command can be viewed or not.
Notes
This uses the ‘read’ lock. If no ‘read’ lock is defined, the topic is assumed readable by all.
-
can_list_topic
(cmd_or_topic, caller)[source]¶ Should the specified command appear in the help table?
This method only checks whether a specified command should appear in the table of topics/commands. The command can be used by the caller (see the ‘should_show_help’ method) and the command will still be available, for instance, if a character type ‘help name of the command’. However, if you return False, the specified command will not appear in the table. This is sometimes useful to “hide” commands in the table, but still access them through the help system.
- Parameters
cmd_or_topic (Command, HelpEntry or FileHelpEntry) – The topic/command to test.
caller – the caller checking for access.
- Returns
bool – If command should be listed or not.
Notes
The .auto_help propery is checked for commands. For all help entries, the ‘view’ lock will be checked, and if no such lock is defined, the ‘read’ lock will be used. If neither lock is defined, the help entry is assumed to be accessible to all.
-
collect_topics
(caller, mode='list')[source]¶ Collect help topics from all sources (cmd/db/file).
- Parameters
caller (Object or Account) – The user of the Command.
mode (str) – One of ‘list’ or ‘query’, where the first means we are collecting to view the help index and the second because of wanting to search for a specific help entry/cmd to read. This determines which access should be checked.
- Returns
tuple – A tuple of three dicts containing the different types of help entries in the order cmd-help, db-help, file-help:
({key: cmd,…}, {key: dbentry,…}, {key: fileentry,…}
-
do_search
(query, entries, search_fields=None)[source]¶ Perform a help-query search, default using Lunr search engine.
- Parameters
query (str) – The help entry to search for.
entries (list) – All possibilities. A mix of commands, HelpEntries and FileHelpEntries.
search_fields (list) – A list of dicts defining how Lunr will find the search data on the elements. If not given, will use a default.
- Returns
tuple – A tuple (match, suggestions).
-
parse
()[source]¶ input is a string containing the command or topic to match.
The allowed syntax is
help <topic>[/<subtopic>[/<subtopic>[/...]]]
The database/command query is always for <topic>, and any subtopics is then parsed from there. If a <topic> has spaces in it, it is always matched before assuming the space begins a subtopic.
-
strip_cmd_prefix
(key, all_keys)[source]¶ Conditional strip of a command prefix, such as @ in @desc. By default this will be hidden unless there is a duplicate without the prefix in the full command set (such as @open and open).
- Parameters
key (str) – Command key to analyze.
all_cmds (list) – All command-keys (and potentially aliases).
- Returns
str – Potentially modified key to use in help display.
-
help_category
= 'general'¶
-
lock_storage
= 'cmd:all()'¶
-
search_index_entry
= {'aliases': '?', 'category': 'general', 'key': 'help', 'no_prefix': ' ?', 'tags': '', 'text': "\n Get help.\n\n Usage:\n help\n help <topic, command or category>\n help <topic>/<subtopic>\n help <topic>/<subtopic>/<subsubtopic> ...\n\n Use the 'help' command alone to see an index of all help topics, organized\n by category. Some big topics may offer additional sub-topics.\n\n "}¶
-
class
evennia.commands.default.help.
CmdSetHelp
(**kwargs)[source]¶ Bases:
evennia.commands.default.help.CmdHelp
Edit the help database.
- Usage:
- sethelp[/switches] <topic>[[;alias;alias][,category[,locks]]
[= <text or new value>]
- Switches:
edit - open a line editor to edit the topic’s help text. replace - overwrite existing help topic. append - add text to the end of existing topic with a newline between. extend - as append, but don’t add a newline. category - change category of existing help topic. locks - change locks of existing help topic. delete - remove help topic.
Examples
sethelp lore = In the beginning was … sethelp/append pickpocketing,Thievery = This steals … sethelp/replace pickpocketing, ,attr(is_thief) = This steals … sethelp/edit thievery sethelp/locks thievery = read:all() sethelp/category thievery = classes
If not assigning a category, the settings.DEFAULT_HELP_CATEGORY category will be used. If no lockstring is specified, everyone will be able to read the help entry. Sub-topics are embedded in the help text.
Note that this cannot modify command-help entries - these are modified in-code, outside the game.
Subtopics helps to break up a long help entry into sub-sections. Users can access subtopics with |whelp topic/subtopic/…|n Subtopics are created and stored together with the main topic.
To start adding subtopics, add the text ‘# SUBTOPICS’ on a new line at the end of your help text. After this you can now add any number of subtopics, each starting with ‘## <subtopic-name>’ on a line, followed by the help-text of that subtopic. Use ‘### <subsub-name>’ to add a sub-subtopic and so on. Max depth is 5. A subtopic’s title is case-insensitive and can consist of multiple words - the user will be able to enter a partial match to access it.
For example:
Main help text for <topic># SUBTOPICS## aboutText for the ‘<topic>/about’ subtopic’### more about-infoText for the ‘<topic>/about/more about-info sub-subtopic## extraText for the ‘<topic>/extra’ subtopic-
key
= 'sethelp'¶
-
aliases
= []¶
-
switch_options
= ('edit', 'replace', 'append', 'extend', 'category', 'locks', 'delete')¶
-
locks
= 'cmd:perm(Helper)'¶
-
help_category
= 'building'¶
-
arg_regex
= None¶
-
lock_storage
= 'cmd:perm(Helper)'¶
-
search_index_entry
= {'aliases': '', 'category': 'building', 'key': 'sethelp', 'no_prefix': ' ', 'tags': '', 'text': "\n Edit the help database.\n\n Usage:\n sethelp[/switches] <topic>[[;alias;alias][,category[,locks]]\n [= <text or new value>]\n Switches:\n edit - open a line editor to edit the topic's help text.\n replace - overwrite existing help topic.\n append - add text to the end of existing topic with a newline between.\n extend - as append, but don't add a newline.\n category - change category of existing help topic.\n locks - change locks of existing help topic.\n delete - remove help topic.\n\n Examples:\n sethelp lore = In the beginning was ...\n sethelp/append pickpocketing,Thievery = This steals ...\n sethelp/replace pickpocketing, ,attr(is_thief) = This steals ...\n sethelp/edit thievery\n sethelp/locks thievery = read:all()\n sethelp/category thievery = classes\n\n If not assigning a category, the `settings.DEFAULT_HELP_CATEGORY` category\n will be used. If no lockstring is specified, everyone will be able to read\n the help entry. Sub-topics are embedded in the help text.\n\n Note that this cannot modify command-help entries - these are modified\n in-code, outside the game.\n\n # SUBTOPICS\n\n ## Adding subtopics\n\n Subtopics helps to break up a long help entry into sub-sections. Users can\n access subtopics with |whelp topic/subtopic/...|n Subtopics are created and\n stored together with the main topic.\n\n To start adding subtopics, add the text '# SUBTOPICS' on a new line at the\n end of your help text. After this you can now add any number of subtopics,\n each starting with '## <subtopic-name>' on a line, followed by the\n help-text of that subtopic.\n Use '### <subsub-name>' to add a sub-subtopic and so on. Max depth is 5. A\n subtopic's title is case-insensitive and can consist of multiple words -\n the user will be able to enter a partial match to access it.\n\n For example:\n\n | Main help text for <topic>\n |\n | # SUBTOPICS\n |\n | ## about\n |\n | Text for the '<topic>/about' subtopic'\n |\n | ### more about-info\n |\n | Text for the '<topic>/about/more about-info sub-subtopic\n |\n | ## extra\n |\n | Text for the '<topic>/extra' subtopic\n\n "}¶