# messages.t | documentation

    #charset "us-ascii"
    #include "advlite.h"

    /*
     *   ***************************************************************************
     *   messages.t
     *
     *   This module forms part of the adv3Lite library (c) 2012-13 Eric Eve, but is
     *   based substantially on the Mercury Library (c) 2012 Michael J. Roberts
     */

    /* ------------------------------------------------------------------------ */
    /*
     *   Global narration parameters.  This object's properties control the way
     *   parameter-based messages are generated.  The message generator
     *   consults the narration parameters each time it generates a message, so
     *   you can change the settings on the fly, and subsequent output will
     *   automatically adapt to the latest settings.
     */
    Narrator: object
        /*
         *   The verb tense of the narration.  This is one of the VerbTense
         *   objects (Present, Past, Perfect, Past Perfect, Future, Future
         *   Perfect).  This controls the way {verb} substitution parameters
         *   are generated, which in turn affects most library messages.  The
         *   default is Present, which is the conventional tense for most IF.
         *
         *   Examples of the English tenses:
         *
         *.    Present: Bob opens the box.
         *.    Past: Bob opened the box.
         *.    Perfect: Bob has opened the box.
         *.    Past Perfect: Bob had opened the box.
         *.    Future: Bob will open the box.
         *.    Future Perfect: Bob will have opened the box.
         *
         *   (Language modules are free to add their own tenses if the target
         *   language has others that would be of interest to IF authors.
         *   They're also free to ignore any of the "standard" tenses we
         *   define.  At a minimum, though, some form of present tense should
         *   always be provided, since most IF is narrated in the present.  If
         *   you need to differentiate among different present tenses, you
         *   might prefer to define your own IDs instead of using the generic
         *   Present, but you should still support *some* present tense that's
         *   suitable for narration.  Some type of past tense usable in
         *   narration is also nice to have.  The others are probably of
         *   marginal value; in English, at least, other tenses are rare in any
         *   kind of narrative fiction, and are mostly limited to experimental
         *   or novelty use.)
         */
        tense = (gameMain.usePastTense ? Past : Present)
    ;

    /*
     *   Root class for verb tenses
     */
    class VerbTense: object
        /*
         *   Tense name.  This is just an identifier for internal and degugging
         *   purposes, so we don't bother farming it out to the language module
         *   for translation.
         */
        name = nil
    ;

    Present: VerbTense
        name = 'present'
    ;
    Past: VerbTense
        name = 'past'
    ;
    Perfect: VerbTense
        name = 'perfect'
    ;
    PastPerfect: VerbTense
        name = 'past perfect'
    ;
    Future: VerbTense
        name = 'future'
    ;
    FuturePerfect: VerbTense
        name = 'future perfect'
    ;

    /* ------------------------------------------------------------------------ */
    /*
     *   Show a message.
     *
     *   This looks for a customized version of the message text, as defined in
     *   CustomMessages objects.  If we don't find one, we use the provided default
     *   message text.
     *
     *   Substitution parameters take the form {x y z} - curly braces with one or
     *   more space-delimited tokens.  The first token is the parameter name, and
     *   any additional tokens are arguments.  The parameter names and their
     *   arguments are up to the language module to define.
     *
     *   In addition to the parameters, the string itself can have two sections,
     *   separated by a vertical bar, '|'.  The first section (before the bar) is
     *   the "terse" string, which is for a straightforward acknowledgment of a
     *   simple, ordinary action: "Taken", "Dropped", etc. The terse string is used
     *   only if the Command argument's actor is the player character, AND the
     *   command doesn't have any disambiguated objects.  If these conditions aren't
     *   met, the second half of the string, the "verbose" version, is used.
     *
     *   Once we have the message text, we perform parameter substitutions.
     *   Parameters can be provided as strings, which are substituted in literally;
     *   or as objects, whose names are inserted according to the grammar in the
     *   template text.
     */

    message(id, txt, [args])
        {

            txt = buildMessage(id, txt, args...);

            /*
             *   use the oSay function to output the text to avoid an infinite
             *   recursive call through say.
             */
            oSay(txt);
        }

    /*
     *   Build a message to be shown by message()
     *
     *   We put this in a separate function to make it easy to obtain the text of a
     *   message for subsequent use without first displaying it.
     */
    buildMessage(id, txt, [args])
    {

        /* look for a customized version of the message */
        local cm = nil;
        foreach (local c in CustomMessages.all)
        {
            /*
             *   if this customizer is active and defines the message, and it
             *   has a higher priority than any previous customizer we've
             *   already found, remember it as the best candidate so far
             */
            if (c.active && c.msgTab[id] != nil
                && (cm == nil || c.priority > cm.priority))
                cm = c;
        }

        /* show debugging information, if desired */
        IfDebug(messages, debugMessage(id, txt, cm, args));

        /* if we found an override, use it instead of the provided text */
        if (cm != nil)
            txt = cm.msgTab[id];

        /* if txt is a function pointer, retrieve the value it returns */
        if(dataType(txt) == TypeFuncPtr)
            txt = txt();

        /* set up a sentence context for the expansion */
        local ctx = new MessageCtx(args);

        /*
         *   Carry out any language-specific adjustments to the text prior to any
         *   further processing
         */
        txt = langAdjust(txt);

        /*
         *   First look for a tense-swithing message substitution of the form
         *   {present-string|past-string} and choose whichever is appropriate to the
         *   tense of the game.
         */
        local bar, openBrace = 0, closeBrace = 0, newTxt = txt;
        for(;;)
        {
            /* Find the next opening brace */
            openBrace = txt.find('{', closeBrace + 1);

            /* If there isn't one, we're done, so leave the loop. */
            if(openBrace == nil)
                break;

            /* Find the next vertical bar that follows the opening brace */
            bar = txt.find('|', openBrace);

            /* If there isn't one, we're done, so leave the loop. */
            if(bar == nil)
                break;

            /* Find the next closing brace that follows the opening brace */
            closeBrace = txt.find('}', openBrace);

            /* If there isn't one, we're done, so leave the loop. */
            if(closeBrace == nil)
                break;

            /*
             *   If the bar doesn't come before the closing brace, then it's not
             *   between the two braces, so we don't want to process it in this
             *   circuit of the loop. Instead we need to see if there's another
             *   opening brace on the next iteration.
             */
            if(bar > closeBrace)
                continue;

            /*
             *   Extract the string that starts with the opening brace we found and
             *   ends with the closing brace we found.
             */
            local pString = txt.substr(openBrace, closeBrace - openBrace + 1);

            /*
             *   If the game is in the past tense, extract the second part of this
             *   above string (that following the bar up to but not including the
             *   closing brace). Otherwise extract the first part (that following
             *   but not including the opening brace up to but not including the
             *   bar)
             */
            local subString = (gameMain.usePastTense || Narrator.tense == Past) ?
                txt.substr(bar + 1, closeBrace - bar - 1) : txt.substr(openBrace +
                    1, bar - openBrace - 1);

            /*
             *   In the copy of our original text string, replace the string in
             *   braces with the substring we just extracted from it.
             */
            newTxt = newTxt.findReplace(pString, subString, ReplaceOnce);

        }

        /* Copy our adjusted string back to our original string */
        txt = newTxt;

        /* check for separate PC and NPC messages */
        bar = txt.find('|');
        if (bar != nil)
        {
            /* there's a bar - check to see if the terse format can be used */
            if (ctx.cmd != nil && ctx.cmd.terseOK())
                txt = txt.left(bar - 1);
            else
                txt = txt.substr(bar + 1);
        }

        /* get the message object */
        local mo = MessageParams.langObj;

        /* apply substitutions */
        for (local i = 1 ; i <= txt.length() ; )
        {
            /* find the end of the current sentence */
            local eos = txt.find(R'<.|!|?><space>', i) ?? txt.length() + 1;

            /*
             *   Build a list of the parameters in the sentence, and preprocess
             *   each one.  We need to preprocess the entire sentence before we
             *   can expand any of it, because some parameters can depend upon
             *   other parameters later in the sentence.  For example, some
             *   languages generally place the subject after the verb; to
             *   generate the verb with proper agreement, we need to know the
             *   subject when we expand the verb, which means we need to have
             *   scanned the entire sentence before we expand the verb.
             */
            ctx.startSentence();
            local plst = new Vector(10);
            for (local j = i ; ; )
            {
                /* find the next parameter */
                local lb = txt.find('{', j);
                if (lb == nil || lb >= eos)
                    break;

                /* find the end of the parameter */
                local rb = txt.find('}', lb + 1);
                if (rb == nil)
                    break;

                /* pull out the parameter string */
                local param = txt.substr(lb + 1, rb - lb - 1);

                /* turn it into a space-delimited token list */
                param = param.trim().split(' ');

                /*
                 *   do the preliminary expansion, but discard the result -
                 *   this gives the expander a chance to update any effect on
                 *   the sentence context
                 */
                mo.expand(ctx, param);

                /* add it to the list */
                plst.append([lb, rb, param]);

                /* move past this item */
                j = rb + 1;
            }

            /* restart the sentence */
            ctx.endPreScan();

            /* do the actual expansion */
            local delta = 0;
            for (local j = 1 ; j <= plst.length() ; ++j)
            {
                /* pull out this item */
                local cur = plst[j];
                local lb = cur[1], rb = cur[2], param = cur[3];
                local paramLen = rb - lb + 1;

                /* get the expansion */
                local sub = mo.expand(ctx, param);

                /*
                 *   if it starts with a "backspace" character ('\010', which
                 *   is a ^H character, the standard ASCII backspace), delete
                 *   any spaces immediate preceding the substitution parameter
                 */
                if (sub.startsWith('\010'))
                {
                    /* count spaces immediately preceding the parameter */
                    local m = lb + delta - 1, spCnt = 0;
                    while (m >= 1 && txt.toUnicode(m) == 32)
                        --m, ++spCnt;

                    /* if we found any spaces, splice them out */
                    if (spCnt != 0)
                    {
                        /* splice out the spaces */
                        txt = txt.splice(m + 1, spCnt, '');

                        /* adjust our delta for the deletion */
                        delta -= spCnt;
                    }

                    /* remove the backspace from the replacement text */
                    sub = sub.substr(2);
                }

                /* splice the replacement text into the string */
    //            txt = txt.splice(lb + delta, paramLen, sub);
                txt = txt.substr(1, lb + delta -1) + sub + txt.substr(lb + delta
                    + paramLen );

                /* adjust our delta to the next item for the splice */
                delta += sub.length() - paramLen;
            }

            /* move to the end of the sentence */
            i = eos + delta + 1;
        }

        return txt;
    }

    /*
     *   Message debugging.  This shows the message before processing: the ID,
     *   the default source text with the {...} parameters, the overriding
     *   custom source text, and the arguments.
     */
    #ifdef __DEBUG
    debugMessage(id, txt, cm, args)
    {
        if(id is in (nil,'','command results prefix', 'command prompt', 'command
            results suffix')
           || outputManager.curOutputStream != mainOutputStream)
            return;

        local idchk = [id, libGlobal.totalTurns];

        if(DebugCtl.messageIDs[idchk] != nil)
            return;
        else
            DebugCtl.messageIDs[idchk] = true;

        oSay('\nmessage(id=<<id>>, default text=\'<<txt>>\' ');
        if (cm != nil)
            oSay('custom text=\'<<cm.msgTab[id]>>\'');

        if (args.length() != 0)
        {
            oSay(', args={ ');
            for (local i = 1 ; i <= args.length() ; ++i)
            {
                local a = args[i];
                if (i > 1)
                    oSay(', ');
                if (dataType(a) == TypeSString)
                    oSay(''''<<args[i]>>'''');
                else
                    oSay('object(name=<<a.name>>)');
            }
            oSay(' }');
        }
        oSay(')\n');
    }
    #endif

    /* ------------------------------------------------------------------------ */
    /*
     *   Noun parameter roles for MessageCtx.noteObj()
     */

    /* the noun is the subject of the sentence */
    enum vSubject;

    /* the noun is an object of the verb */
    enum vObject;

    /*
     *   the role is ambiguous (it's not marked clearly in the case or
     *   position, for example)
     */
    enum vAmbig;

    /* the noun is a possessive, not the subject or the object */
    enum vPossessive;
    /* ------------------------------------------------------------------------ */
    /*
     *   Message expansion sentence context.  This keeps track of the parts of
     *   the sentence we've seen so far in the substitution parameters.
     *
     *   The sentence context is important for expanding certain items.  For
     *   verbs, it tells us which object is the subject, so that we can
     *   generate the agreeing conjugation of the verb (in number and
     *   grammatical person).  For direct and indirect objects, it lets us
     *   generate a reflexive when the same object appears in a second role
     *   ("You can't put the box in itself").
     */
    class MessageCtx: object
        construct(args)
        {
            /* remember the message arguments */
            self.args = args;

            /* if there's a Command among the arguments, note it */
            cmd = gCommand;

            /* if there's no command, use the placeholder */
            if (cmd == nil)
                cmd = messageDummyCommand;
        }

        /* start a new sentence */
        startSentence()
        {
            /* forget any subject/object information */
            subj = nil;
            vobj = nil;
            gotVerb = nil;
            reflexiveAnte.clear();

            /* note that we're on the initial scan */
            prescan = true;

            /* we're starting a new scan, so reset the previous parameter */
            lastParam = nil;
        }

        /*
         *   End the pre-expansion scan.  The expander makes two passes over
         *   each sentence.  The first scan doesn't actually do any
         *   substitutions, but merely invokes each parameter to give it a
         *   chance to exert its side effects on the sentence context.  The
         *   second scan actually applies the substitutions.  At the end of the
         *   first pass, the expander calls this to let us finalize the initial
         *   scan and prepare for the second scan.
         */
        endPreScan()
        {
            /*
             *   Forget the reflexive antecedent.  Reflexives are generally
             *   anaphoric (i.e., they refer back to earlier clauses in the
             *   same sentence), so we generally don't care about anything we
             *   found later in the same sentence.
             */
            reflexiveAnte.clear();

            /* we're no longer on the initial scan */
            prescan = nil;

            /* we're starting a new scan, so reset the previous parameter */
            lastParam = nil;
        }

        /*
         *   Note a parameter value.  Some parameters refer back to the
         *   immediately preceding parameter, so it's useful to have the most
         *   recent value stashed away.  Returns the parameter value as given.
         */
        noteParam(val)
        {
            /* remember the value */
            return lastParam = val;
        }

        /*
         *   Convert a parameter value to a string representation suitable for
         *   message substitution.
         */
        paramToString(val)
        {
            switch (dataType(val))
            {
            case TypeSString:
                return val;

            case TypeInt:
                return toString(val);

            case TypeObject:
                if (val.ofKind(Mentionable) || val.ofKind(Pronoun))
                    return val.name;
                else if (val.ofKind(List) || val.ofKind(Vector))
                    return val.mapAll({ x: paramToString(x) }).join(', ');
                else if (val.ofKind(BigNumber))
                    return toString(val);
                else
                    return '(object)';

            case true:
                return 'true';

            case nil:
                return '';

            default:
                return '(?)';
            }
        }

        /*
         *   Convert a parameter value to a numeric representation.  If the
         *   value is an integer or BigNumber, we return it as is; if a list or
         *   vector, we return the number of elements; if nil, 0; if a string,
         *   the parsed numeric value of the string; otherwise we simply return
         *   1.
         */
        paramToNum(val)
        {
            switch (dataType(val))
            {
            case TypeSString:
                return toInteger(val);

            case TypeInt:
                return val;

            case TypeObject:
                if (val.ofKind(BigNumber))
                    return val;
                if (val.ofKind(List) || val.ofKind(Vector))
                    return val.length();
                return 1;

            case TypeList:
                return val.length();

            case nil:
                return 0;

            default:
                return 1;
            }
        }

        /*
         *   Note an object being used as a parameter in the given sentence
         *   role.  The role is one of the noun role enums defined above:
         *   vSubject, vObject, or vAmbig.  If the object is a subject, we'll
         *   save it as the sentence subject, so that we can generate an
         *   agreeing verb.  Regardless of role, we'll also save it as a
         *   reflexive antecedent, so that we can generate a reflexive pronoun
         *   if we see the same object again in another role in the same
         *   sentence.
         */
        noteObj(obj, role)
        {
            /* remember the object as the last parameter value */
            noteParam(obj);

            /*
             *   If the role is ambiguous, guess at the role based on the
             *   general sentence order.
             */
            if (role == vAmbig && MessageParams.langObj.sentenceOrder != nil)
            {
                /* get the sentence order flags */
                local so = MessageParams.langObj.sentenceOrder;

                /* figure whether the subject/object is before/after the verb */
                local ssv = (so.find(R'S.*V') != nil ? -1 : 1);
                local osv = (so.find(R'O.*V') != nil ? -1 : 1);

                /* figure whether the subject or object comes first */
                local fo = (so.find(R'S.*O') != nil ? vSubject : vObject);

                /* figure which side of the verb we're on (-1 before, 1 after) */
                local sv = (gotVerb ? 1 : -1);

                /*
                 *   If we're on the right side of the verb for both subject
                 *   and object: if we have an object, this is the subject; if
                 *   we have a subject, this is the object; if we have neither
                 *   this is the first role in sentence order.
                 *
                 *   Otherwise, if we're on the subject side of the verb, and
                 *   we don't have a subject, this is the subject.
                 *
                 *   Otherwise, if we're on the object side of the verb, and we
                 *   don't have an object, this is an object.
                 */
                if (ssv == sv && osv == sv)
                    role = (subj != nil ? vObject :
                            vobj != nil ? vSubject : fo);
                else if (ssv == sv && subj == nil)
                    role = vSubject;
                else if (osv == sv && vobj == nil)
                    role = vObject;
            }

            /* if it's the subject, remember it as such */
            if (role == vSubject)
                subj = obj;
            else if (role == vObject)
                vobj = obj;

            /*
             *   Only record the reflexive antecent for the subject, so that the
             *   reflexive pronoun is used when an actor or object tries to act on
             *   itself.
             */
            if(role != vSubject)
                return;

            /*
             *   If there's nothing in the reflexive antecedent list that uses
             *   the same pronoun, add this to the list.  Otherwise, replace
             *   the object that used the same antecedent.
             */
    //        local p = obj.pronoun();
    //        local idx = reflexiveAnte.indexWhich({ o: o.pronoun() == p });

            /*
             *   The foregoing rule seems to generate false positives (that is, it
             *   can result in reflexive pronouns where they're not appropriate), so
             *   we'll try the different strategy of looking for anything in the
             *   reflexive ante list. The reason for this is that if a new
             *   subject is introduced into the sentence, it doesn't have to be the
             *   same gender as the previous subject to become the most likely
             *   antecedent for a reflexive.
             */
            local idx = reflexiveAnte.indexWhich({ o: o.ofKind(Thing) });

            if (idx == nil)
            {
                /*
                 *   There's no object with this pronoun yet - add it.  We want
                 *   to keep earlier antecedents with different pronouns
                 *   because we can still refer back to earlier objects
                 *   reflexively as long as it's clear which one we're talking
                 *   about.  The distinct pronouns provide that clarity.
                 */
                reflexiveAnte.append(obj);
            }
            else
            {
                /*
                 *   We already have an object with this pronoun, so replace it
                 *   with the new one.  Reflexives generally bind to the prior
                 *   noun phrase that matches the pronoun *and* is closest in
                 *   terms of word order.  Once another noun phrase intervenes
                 *   in word order, we can only refer back to an earlier one by
                 *   reflexive pronoun if the earlier noun is distinguishable
                 *   from the later one by its use of a distinct pronoun from
                 *   the later one.  For example, we can say "Bob asked Sue
                 *   about himself", because "himself" could only refer to Bob,
                 *   but most people would take "Bob asked Sam about himself"
                 *   to mean that Bob is asking about Sam.
                 */
                reflexiveAnte[idx] = obj;
            }
        }

        /*
         *   Note a verb parameter.
         */
        noteVerb()
        {
            /* note that we got a verb */
            gotVerb = true;
        }

        /*
         *   Was the last parameter value plural?  If the value is numeric, 1
         *   is singular and anything else is plural.  If it's a list, a
         *   one-element list is singular and anything else is plural.  If it's
         *   a Mentionable, the 'plural' property determines it.
         */
        lastParamPlural()
        {
            switch (dataType(lastParam))
            {
            case TypeInt:
                return lastParam != 1;

            case TypeObject:
                if (lastParam.ofKind(Mentionable) || lastParam.ofKind(Pronoun))
                    return lastParam.plural;
                else if (lastParam.ofKind(List) || lastParam.ofKind(Vector))
                    return lastParam.length() != 1;
                else if (lastParam.ofKind(BigNumber))
                    return lastParam != 1;
                else
                    return nil;

            case TypeList:
                return lastParam.length() != 1;

            default:
                return nil;
            }
        }

        /*
         *   Is the actor involved in the Command the PC?  If there's a Command
         *   with an actor, we check to see if it's the PC.  If there's no
         *   Command or no actor, we assume that the PC is the relevant actor
         *   (since there's nothing else specified anywhere) and return true.
         */
        actorIsPC()
        {
            return cmd == nil || cmd.actor == nil
                || cmd.actor == gPlayerChar;
        }

        /* the last parameter value */
        lastParam = nil

        /* are we on the initial pre-expansion scan? */
        prescan = nil

        /* the subject of the sentence (as a Mentionable object) */
        subj = nil

        /* the last object of the verb we saw */
        vobj = nil

        /* have we seen a verb parameter in this sentence yet? */
        gotVerb = nil

        /* the message argument list */
        args = nil

        /* the Command object among the arguments, if any */
        cmd = nil

        /*
         *   The reflexive antecedents.  Each time we see an object in a
         *   non-subject role, and the object has different pronoun usage from
         *   any previous entry, we'll add it to this list.  If we see the same
         *   object subsequently in another non-subject role, we'll know that
         *   we should generate a reflexive pronoun for the object rather than
         *   the name or a regular pronoun:
         *
         *   You can't put the tongs in the box with the tongs -> with
         *   themselves
         */
        reflexiveAnte = perInstance(new Vector(5))
    ;

    /*
     *   Dummy command placeholder for messages generated without a command.
     */
    messageDummyCommand: object
        /* use the player character as the actor */
        actor = (gPlayerChar)

    ;

    /*
     *    Use the message builder to format a message without supplying a key
     *    to look up at alternative message. We can use this with library
     *    messages that employ object properties (e.g. cannotTakeMsg) or user
     *    code.
     *
     *    dmsg() displays the resultant message.
     */
    dmsg(txt, [args])
    {
        message('', txt, args...);
    }

    /* bmsg returns the text of a message formatted by the message formatter. */
    bmsg(txt, [args])
    {
        return buildMessage('', txt, args...);
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   Message customizer object.  Language extensions and games can use this
     *   class to define their own custom messages that override the default
     *   English messages used throughout the library.
     *
     *   Each CustomMessages object can define a list of messages to be
     *   customized.  This lets you centrally locate all of your custom
     *   messages by putting them all in a single object, if you wish.
     *   Alternatively, you can create separate objects, if you prefer to keep
     *   them with some other body of code they apply to.  In either case, the
     *   library gathers them all up during preinit.
     */
    class CustomMessages: object
        /*
         *   The priority determines the precedence of a message defined in
         *   this object, if the same message is defined in more than one
         *   CustomMessages object.  The message with the highest priority is
         *   the one that's actually displayed.
         *
         *   The library defines one standard priority level: 100 is the
         *   priority for language module overrides.  Each language module
         *   provides a translated set of the standard library messages, via a
         *   CustomMessages object with priority 100.  (The default English
         *   messages defined in-line throughout the library via DMsg() macros
         *   effectively have a priority of negative infinity, since any custom
         *   message of any priority overrides a default.)
         *
         *   Games will generally want to override all library messages,
         *   including translations, so we set the default here to 200.
         */
        priority = 200

        /*
         *   Is this customizer active?  If you want to change the messages at
         *   different points in the course of the game, you can use this to
         *   turn sets of messages on and off.  For example, if your game
         *   includes narrator changes at certain points, you can create
         *   separate sets of messages per narrator.  By default, we make all
         *   customizations active, but you can override this to turn selected
         *   messages on and off as needed.  Note that the library consults
         *   this every time it looks up a message, so you can change the value
         *   dynamically, or use a method whose return value changes
         *   dynamically.
         */
        active = true

        /*
         *   The message list.  This can contain any number of messages; the
         *   order isn't important.  Each message is defined with a Msg()
         *   macro:
         *
         *.     Msg(id key, 'Message text'),  ...
         *
         *   The "id key" is the message ID that the library uses in the DMsg()
         *   message that you're customizing.  (DON'T use quotes around the ID
         *   key.)  The message text is a single-quoted string giving the
         *   message text.  This can contain curly-brace replacement
         *   parameters.
         */
        messages = []

        /*
         *   Construction.  Build the lookup table of our messages for fast
         *   access at run-time.
         */
        construct()
        {
            /* add me to the master list of message customizers */
            CustomMessages.all += self;

            /* create the lookup table */
            msgTab = new LookupTable(64, 128);

            /* populate it with our key->string mappings */
            for (local i = 1, local len = messages.length() ; i <= len ; i += 2)
                msgTab[messages[i]] = messages[i+1];
        }

        /* message lookup table - this maps ID keys to message text strings */
        msgTab = nil

        /*
         *   class property: the master list of CustomMessages objects defined
         *   throughout the game
         */
        all = []
    ;

    /* ------------------------------------------------------------------------ */
    /*
     *   Message Parameter Handler.  This object defines and handles parameter
     *   expansion for '{...}' strings in displayed messages.
     *
     *   The language module must provide one instance of this class.  The name
     *   of the instance doesn't matter - we'll find it at preinit time.  The
     *   object must provide the 'params' property giving the language-specific
     *   list of substitution parameter names and handler functions.
     */
    class MessageParams: object
        /*
         *   Expand a parameter string.  'ctx' is a MessageCtx object with the
         *   current sentence context.  This contains the message expansion
         *   arguments (ctx.args), the Command object from the arguments
         *   (ctx.cmd), and information on the grammar elements of the
         *   sentence.  'params' is the list of space-delimited tokens within
         *   the curly-brace parameter string.  Returns the string to
         *   substitute for the parameter in the message output.
         */
        expand(ctx, params)
        {
            /* look up the parameter name */
            local pname = params[1].trim();
            local t = paramTab[pname.toLower()];

            /*
             *   If we found an entry, let the entry handle it.  If there's no
             *   matching entry, it's basically an error: return the original
             *   parameter source text, with the braces restored, so that it'll
             *   be obvious in the output.
             */
            local txt = nil;
            if (t != nil)
            {
                /*
                 *   If we have not previously identified a subject for this
                 *   context, use the dummy_ object, which provides a dummy third
                 *   person singular noun as a default subject for the verb.
                 */
                if(ctx.subj == nil)
                    ctx.subj = dummy_;

                /* we found the parameter - get the translation */
                txt = t[2](ctx, params);

                /*
                 *   if this isn't a pre-scan, and the parameter name starts
                 *   with a capital, mimic that pattern in the result
                 */
                if (txt != nil && !ctx.prescan && rexMatch(R'<upper>', pname) != nil)
                    txt = txt.firstChar().toUpper() + txt.delFirst();
            }

            /*
             *   if we failed to find an expansion, and this isn't just a
             *   pre-scan, return the source text as an error indication
             */
            if (txt == nil && !ctx.prescan)
                txt = '{' + params.join(' ') + '}';

            /* return the result */
            return txt;
        }

        /*
         *   Parameter mapping list.  This is a list of lists: [name, func],
         *   where 'name' is the parameter name (as a string), and 'func' is
         *   the expansion handler function.
         *
         *   The parameter name must be all lower case.  During expansion, we
         *   convert the first space-delimited token within the {curly brace}
         *   parameter string to lower case, then look for an entry in the list
         *   with the matching parameter name.  If we find an entry, we call
         *   its handler function.
         *
         *   The handler function is a pointer to a function that takes two
         *   arguments: func(params, ctx), where 'params' is the list of tokens
         *   within the {curly braces} of the substitution string, as a list of
         *   strings, where each string is a space-delimited token in the
         *   original {curly brace} string; and 'ctx' is the MessageCtx object
         *   for the expansion.  The function returns a string giving the
         *   expansion of the parameter.
         *
         *   The parameter list must be provided by the language module, since
         *   each language's list of parameters and expansions will vary.
         */
        params = [ ]

        /*
         *   Some parameters expand to properties of objects involved in the
         *   command.  cmdInfo() makes it easier to define the expansion
         *   functions for such parameters.  We search the parameters for a
         *   Command object, and if we find it, we retrieve a particular source
         *   object and evaluate a particular property on the source object to
         *   get the result string.
         *
         *   For example, {the dobj} could be handled via cmdInfo('ctx, dobj',
         *   &theName, vSubject): we find the current 'dobj' object in the
         *   Command, then evaluate the &theName property on that object.
         *
         *   'ctx' is the MessageCtx object with the current sentence context.
         *
         *   'src' is the source object in the Command.  This can be given as a
         *   property pointer (&actor, say), in which case we simply evaluate
         *   that property of the Command object (cmd.(src)) to get the source
         *   object.  Or, it can be a string giving a NounRole name (dobj,
         *   iobj, acc), in which case we'll retrieve the current object for
         *   the noun role from the Command.  Or, it can be a string with a
         *   number, in which case we'll use the number as an index into the
         *   argument list.
         *
         *   'objProp' is the property of the source object to evaluate to get
         *   the expansion string.
         *
         *   'role' is vSubject if this is a noun phrase with subject usage (in
         *   most languages, this is a noun phrase in the nominative case; in
         *   English this is called subjective case).  It's vObject for any
         *   other noun phrase role (direct object, prepositional object, etc).
         *   If the role isn't clear from the context (the case marking of the
         *   parameter, or the position), use vAmbig to mark it as ambiguous.
         */
        cmdInfo(ctx, src, objProp, role)
        {
            try
            {
                /* we don't have a source object yet */
                local srcObj = nil;

                /* if the source is a role name, get the corresponding property */
                if (dataType(src) == TypeSString)
                {
                    /* check for a number */
                    if (rexMatch(R'<digit>+', src) != nil)
                    {
                        /* it's an argument index */
                        src = ctx.args[toInteger(src)];
                    }
                    else
                    {
                        /* Find the source object corresponding to the string */
                        src = findStrParam(src, role);

                    /*
                     *   If we didn't find an object, return nil to the caller to
                     *   indicate an error
                     */

                        if(src == nil)
                            return nil;

                    }

                }

                /* retrieve the source object from the command */
                if (dataType(src) == TypeProp)
                    srcObj = ctx.cmd.(src);
                else if (dataType(src) == TypeObject
                         && (src.ofKind(Mentionable) || src.ofKind(Pronoun)
                             || src.ofKind(LiteralObject) ||
                             src.ofKind(ResolvedTopic)))
                    srcObj = src;

                /* check for reflexivity */
                if (srcObj != nil && role == vObject && !ctx.prescan)
                {
                    local r = cmdInfoReflexive(ctx, srcObj, objProp);
                    if (r != nil)
                        return r;
                }

                /* note the object's role in the sentence context */
                if (srcObj != nil)
                    ctx.noteObj(srcObj, role);

                /*
                 *   if we're in pre-scan mode, skip the actual expansion;
                 *   otherwise evaluate the target property on the source
                 *   object to get the expansion text
                 */
                return ctx.prescan ? nil : srcObj.(objProp);
            }
            catch (Exception e)
            {
                /*
                 *   if anything went wrong, return nil to indicate we failed
                 *   to find an expansion
                 */
                return nil;
            }
        }

        findStrParam(src, role)
        {
            local targetObj;

            if (gAction != nil)
            {
                /* get the target object by name through the action */
                targetObj = gAction.getMessageParam(src);
            }
            else
            {
                /* there's no action, so we don't have a value yet */
                targetObj = nil;
            }

            if (targetObj == nil)
            {
                /* look up the name */
                targetObj = libGlobal.nameTable_[src];

                /*
                 *   if we found it, and the result is a function pointer or an
                 *   anonymous function, invoke the function to get the result
                 */
                if (dataTypeXlat(targetObj) == TypeFuncPtr)
                {
                    /* evaluate the function */
                    targetObj = (targetObj)();
                }
            }

            /*
             *   If we still haven't found a targetObj, try getting it from the
             *   role's object property.
             */

            if (targetObj == nil && role != nil)
            {
                /* it's a role name - look up the role */
                local role = NounRole.all.valWhich({ r: r.name == src });

                /* get the role's object property */
                if(role != nil)
                   targetObj = role.objProp;
            }

            /*
             *   If we still haven't found a targetObj, there's probably an error in
             *   the way the object parameter was specified, but rather than
             *   allowing this to cause a run-time error down the track, substitute
             *   a dummy object and note the offending src parameter on an
             *   appropiate property so that the text presented should make it clear
             *   where the problem lies.
             */

            if(targetObj == nil)
            {
                targetObj = dummy_;
                dummy_.noteName('[' + src + ']');
            }

            return targetObj;
        }

        /*
         *   Parameter lookup table.  This maps a parameter name to its handler
         *   function.
         */
        paramTab = nil

        /* the language module's instance of the class */
        langObj = nil

        /* construction - build the lookup table */
        construct()
        {
            /* remember the instance */
            MessageParams.langObj = self;

            /* create the parameter table */
            paramTab = new LookupTable(64, 128);
            foreach (local p in params)
                paramTab[p[1]] = p;
        }
    ;

    /* Dummy object to use as a fallback when a parameter can't be identified */

    dummy_: Thing
        noteName(src) { }
    ;

    pluralDummy_: Thing
        noteName(src) { }
    ;

    /*----------------------------------------------------------------------------*/

Adv3Lite Library Reference Manual
Generated on 01/03/2024 from adv3Lite version 1.6.2