Function: expand_keywords

Function: expand_keywords

Usage

 expand_keywords(some_tagged_string, default_expand: {...}, combine: {...})

Find keywords and generate their reminder text.

The string is searched for keywords, when one is found its reminder text is generated. This is done by calling keyword.reminder(param1:.., param2:..., ...). Where the params are the matching keyword parameters.

The it is determined whether the reminder text should be shown. This is either because the user explicitly selected it, or when default_expand(mode: keyword.mode) returns true. Whether reminder text is shown is stored in a <kw-> tag around the keyword.

Tag Reminder text Changed by user
<kw-a> hidden no
<kw-A> shown no
<kw-0> hidden yes
<kw-1> shown yes

If the reminder text is shown the function combine is called which should combine the reminder text with (in the variable reminder) with the keyword and its parameters (in the variable keyword).

For example, in the case of magic:

 expand_keywords(
   default_expand: { set.automatic_reminder_text }
   combine:        { "{keyword}<atom-reminder-{mode}> ({reminder})</atom-reminder-{mode}>" }
 )

is used. This shows reminder text by default based on a set option, and it combined the keyword as "keyword (reminder)".

Parameters

Parameter Type Default Description
input tagged string String to expand keywords in.
condition function {true}
since 0.3.7
When should a keyword be recognized at all?
default_expand function {true} Should reminder text be shown by default?
combine function How to combine keywords with the reminder text?

Arguments

The condition, default_expand and combine functions will be called for each potential keyword match in the input.

Parameter Type Description
param1, param2, ... tagged strings The parameter values.
mode string The mode of the keyword.
used_placeholders boolean
since 0.3.7
Is a placeholder used for any of the parameters?
correct_case boolean
since 0.3.7
Is the keyword matched exactly, with the same case?
keyword tagged string In combine only: The full keyword text including parameters
reminder string In combine only: The expanded reminder text.

Examples

Assuming a keyword "mse" exists with reminder text "Magic Set Editor" exists.

 expand_keywords(default_expand: {true}, combine: { keyword + " (= " + reminder + ")" },  "mse is cool")
    == "<kw-A>mse (= Magic Set Editor) is cool</kw-A>"

 f := expand_keywords@(default_expand: {true}, combine: { keyword+" (= "+reminder+")" })
 f("mse is cool") == "<kw-A>mse (= Magic Set Editor) is cool</kw-A>"
since 0.3.7

Keyword matching is case insensitive, to get case sensitive matching use a condition that check for the correct case:

 expand_keywords(..., condition: { correct_case })

In prior MSE versions matching was always case sensitive.