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)

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)

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)

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)

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)

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)

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')

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)

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()

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)

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.

func()

Run the dynamic help entry creator.

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)

Bases: evennia.commands.default.help.CmdHelp

Edit the help database.

Usage:

sethelp[/switches] <topic>[[;alias;alias][,category[,locks]] [= <text>]

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. 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

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

## about

Text for the ‘<topic>/about’ subtopic’

### more about-info

Text for the ‘<topic>/about/more about-info sub-subtopic

## extra

Text for the ‘<topic>/extra’ subtopic

key = 'sethelp'

aliases = []

switch_options = ('edit', 'replace', 'append', 'extend', 'delete')

locks = 'cmd:perm(Helper)'

help_category = 'building'

arg_regex = None

parse()

We want to use the default parser rather than the CmdHelp.parse

func()

Implement the function

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]] [= <text>]\n\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 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\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 "}