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.eSome 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 = '/'

msg_help(text)

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)

This visually formats the help entry. This method can be overriden to customize the way a help entry is displayed.

Parameters

• title (str) – The title of the help entry.

• help_text (str) – Text of the help entry.

• aliases (list) – List of help-aliases (displayed in header).

• suggested (list) – Strings suggested reading (based on title).

• subtopics (list) – A list of strings - the subcategories available for this entry.

Returns the formatted string, ready to be sent.

format_help_index(cmd_help_dict=None, db_help_dict=None, title_lone_category=False)

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.

Returns

str – The help index organized into a grid.

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.

check_show_help(cmd, caller)

Helper method. If this return True, the given cmd auto-help will be viewable in the help listing. Override this to easily select what is shown to the account. Note that only commands available in the caller’s merged cmdset are available.

Parameters

• cmd (Command) – Command class from the merged cmdset

• caller (Character, Account or Session) – The current caller executing the help command.

should_list_cmd(cmd, 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 ‘check_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 – the command to be tested.

• caller – the caller of the help system.

Returns

True – the command should appear in the table. False: the command shouldn’t appear in the table.

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.

func()

Run the dynamic help entry creator.

help_category = 'general'

lock_storage = 'cmd:all()'

search_index_entry = {'aliases': '?', 'category': 'general', 'key': 'help', '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.eSome big topics may offer additional sub-topics.\n\n "}

class evennia.commands.default.help.CmdSetHelp(**kwargs)

Bases: evennia.commands.default.muxcommand.MuxCommand

Edit the help database.

Usage:

help[/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'

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

locks = 'cmd:perm(Helper)'

help_category = 'building'

func()

Implement the function

aliases = []

lock_storage = 'cmd:perm(Helper)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': 'sethelp', 'tags': '', 'text': "\n Edit the help database.\n\n Usage:\n help[/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 "}