evennia.help.utils

Resources for indexing help entries and for splitting help entries into sub-categories.

This is used primarily by the default help command.

evennia.help.utils.wildcard_stemmer(token, i, tokens)

Custom LUNR stemmer that returns both the original and stemmed token if the token contains a leading wildcard (*).

Parameters

• token (str) – The input token to be stemmed

• i (int) – Index of current token. Unused here but required by LUNR.

• tokens (list) – List of tokens being processed. Unused here but required by LUNR.

Returns

list – A list containing the stemmed tokens and original token if it has leading ‘*’.

class evennia.help.utils.LunrSearch

Bases: object

Singleton class for managing Lunr search index configuration and initialization.

index(ref, fields, documents)

Creates a Lunr searchable index.

Parameters

• ref (str) – Unique identifier field within a document

• fields (list) – A list of Lunr field mappings **{“field_name”: str, “boost”: int}**. See the Lunr documentation for more details.

• documents (list[dict]) – This is the body of possible entities to search. Each dict should have all keys in the fields arg.

Returns: A lunr.Index object

evennia.help.utils.help_search_with_index(query, candidate_entries, suggestion_maxnum=5, fields=None)

Lunr-powered fast index search and suggestion wrapper. See https://lunrjs.com/.

Parameters

• query (str) – The query to search for.

• candidate_entries (list) – This is the body of possible entities to search. Each must have a property .search_index_entry that returns a dict with all keys in the fields arg.

• suggestion_maxnum (int) – How many matches to allow at most in a multi-match.

• fields (list, optional) – A list of Lunr field mappings **{“field_name”: str, “boost”: int}**. See the Lunr documentation for more details. The field name must exist in the dicts returned by .search_index_entry of the candidates. If not given, a default setup is used, prefering keys > aliases > category > tags.

Returns

tuple –

A tuple (matches, suggestions), each a list, where the suggestion_maxnum limits

how many suggestions are included.

evennia.help.utils.parse_entry_for_subcategories(entry)

Parse a command docstring for special sub-category blocks:

Parameters

entry (str) – A help entry to parse

Returns

dict –

The dict is a mapping that splits the entry into subcategories. This

will always hold a key None for the main help entry and zero or more keys holding the subcategories. Each is itself a dict with a key None for the main text of that subcategory followed by any sub-sub-categories down to a max-depth of 5.

Example:

'''
Main topic text

# SUBTOPICS

## foo

A subcategory of the main entry, accessible as **help topic foo**
(or using /, like **help topic/foo**)

## bar

Another subcategory, accessed as **help topic bar**
(or **help topic/bar**)

### moo

A subcategory of bar, accessed as **help bar moo**
(or **help bar/moo**)

#### dum

A subcategory of moo, accessed **help bar moo dum**
(or **help bar/moo/dum**)

'''

This will result in this returned entry structure:

{
   None: "Main topic text":
   "foo": {
        None: "main topic/foo text"
   },
   "bar": {
        None: "Main topic/bar text",
        "moo": {
            None: "topic/bar/moo text"
            "dum": {
                None: "topic/bar/moo/dum text"
            }
        }
   }
}