Text Parser - multi-words

[mausimus]

Hi, I'd like to add below section to the Text Parser page to clarify usage of multi-words in the parser; please kindly advise the best way to go about it. https://adventuregamestudio.github.io/ags-manual/TextParser.html

Multi-words

Multi-words are words which contain spaces, for example "blue key". While you can use them in the same way as regular words in your Said commands, keep in mind the parser will always match the longest word it finds which can lead to complications if you have words that prefix each other:

• Imagine you have the words "red", "blue" and "key" in your parser Said("take red,blue key") will match both "take red key" and "take blue key" inputs
• Now you add "blue key" to the parser as well Said("take red,blue key") will now only match "take red" and "take blue key" (and won't match "take red key") since the parser will recognize "blue key" as a single word and an alternative to "red"; this is likely not what you'd want

To avoid this risk prefer using one-word synonyms for your multi-words (for example add "blue-key" as a synonym of "blue key" and use it in your Said commands to avoid accidental ambiguity).

[mausimus]

I just found there's an issue with handling dashes in words, one place in the parser doesn't properly handle them. I will need to raise a new PR in the main repo so that my advice above is actually sound.

[morganwillcock]

Are multi-words a concept that is already in AGS and aren't documented, or is this an example of one technique which can be used with the default Parser object to disambiguate the input?

If you are just looking to build a simple verb-noun parser, it should possible to structure it so that both red and blue keys can be identified using generic tests for a red "thing" and a blue "thing".

bool parsed_blue()
{
    return Parser.Said("anyword blue rol");
}

bool parsed_red()
{
    return Parser.Said("anyword red rol");
}

void parse_line(String line)
{
    Parser.ParseText(line);

    if (Parser.Said("get [blue,red] key"))
    {
        if (parsed_blue())
        {
            Display("You take the blue key");
        }
        else if (parsed_red())
        {
            Display("You take the red key");
        }
        else
        {
            Display("Do you mean the blue key or the red key?");

            // For a fancier parser that will disambiguate using the
            // next input, store the dictionary ID of the word.
            //parser_context = Parser.FindWordID("key");
        }
    }
}

I don't know why it isn't documented, but the comma syntax appears to be valid within the square brackets, and that allows the scope of later checks to assume the context of "key", potentially storing that context for the next input.

[mausimus]

Hello, multi-words are already supported by AGS. I was fixing a few bugs around their implementation in https://github.com/adventuregamestudio/ags/pull/2442 and it came to light this functionality isn't documented or well understood.

The purpose of adding this section to the manual is to:

1. Confirm multi-words are supported and acceptable in parser commands
2. Alert game developers to potential gotchas when using them

The red/blue key example I listed is a synthetic one to make it easier to explain the rule that parser matches the longest word so just adding a new word to the dictionary can break existing parser commands, something to watch out for. In reality, multi-words are most useful for words like "match box", "box of matches" which would be difficult to account for with just square brackets syntax.

[ivan-mogilko]

@mausimus if you like, i may invite you to "manual contributors", which will give you access enough to edit the manual source (through Wiki page). I closed the wiki from editing by non-collaborators to prevent malicious and random wrong edits.

Alternatively, you may make a PR here too; there's just a caveat that the doc pages are not in master branch, but in "gh-pages" branch.

[mausimus]

I had a look at gh-pages branch but it seems to contain .html files generated off the Markdown wiki? Not sure I should be editing those. And PRs in this repo seem to relate to the documentation building system rather than the content. I cloned the wiki and made the edit in my private copy, perhaps you'd be able to incorporate that? Here's a patch file, and also a link to my version (just added the section at the bottom). textparser-multi-words.zip https://github.com/mausimus/ags-manual/wiki/TextParser

[ericoporto]

In theory you just edit the wiki here in this repository through the web interface.

https://github.com/adventuregamestudio/ags-manual/wiki/TextParser

Just clicking the Edit button doesn't work?

(I can apply the patch this is more a question of what is the person)

[ivan-mogilko]

My apologies, I forgot what gh-pages are... The repository address for wiki pages is https://github.com/adventuregamestudio/ags-manual.wiki.git , and it may be possible to clone, but I do not know if it's possible to make PRs for this. (https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#cloning-wikis-to-your-computer)

Editing wiki is currently restricted to collaborators to prevent unwanted edits from random people (as I mentioned above). I will send an invite to let edit wiki directly. This may be easier, since you seem to have a better knowledge of text parser.

[ivan-mogilko]

Or maybe it's better to open free wiki editing for everyone again?

[ericoporto]

ok, removed the check that restricted the wiki. I may still restrict back at some point, temporarily, when doing some moving around of files.

[mausimus]

Many thanks, I was able to edit the wiki directly now and have added my new section. Yes I don't think GitHub supports properly PRing wikis even though it stores them as git repos internally.

https://github.com/adventuregamestudio/ags-manual/wiki/TextParser

[morganwillcock]

Sorry to re-open the issue, but I think maybe what was added may be wrong (or at least I am having trouble understanding it).

In this section:

If you later add the word "blue key" to the parser, the same command

Parser.Said("take red,blue key")

will only match "take red" and "take blue key" (and won't match "take red key" anymore!) since the parser will recognize "blue key" as a single word and a synonym (via the comma syntax) to "red"; this is likely not what you'd want.

...this seems to imply that "blue key" is a synonym to "red" because of the comma, but I don't think this is correct. The definition of "blue key" in the dictionary, and whether it re-uses an existing numeric ID or not, would determine whether it is a synonym - I don't think the comma syntax defines a synonym.

[mausimus]

I see, yes of course comma doesn't add a proper parser synonym (i.e. word with the same ID), only a temporary synonym for this one parser input. Perhaps I should've used the word "alternative" instead to clear this up, the current documentation doesn't state a term for comma-separated words but in the code they are called alternatives.

...will only match "take red" and "take blue key" (and won't match "take red key" anymore!) since the parser will recognize "blue key" as a single word and a synonym an alternative (via the comma syntax) to "red"; this is likely not what you'd want.