# exits.t | documentation

    #charset "us-ascii"

    /*
     *   Copyright (c) 2002, 2006 by Michael J. Roberts
     *
     *   Based on exitslister.t, copyright 2002 by Steve Breslin and
     *   incorporated by permission.
     *
     *   TADS 3 Library - Exits Lister
     *
     *   This module provides an automatic exit lister that shows the apparent
     *   exits from the player character's location.  The automatic exit lister
     *   can optionally provide these main features:
     *
     *   - An "exits" verb lets the player explicitly show the list of apparent
     *   exits, along with the name of the room to which each exit connects.
     *
     *   - Exits can be shown automatically as part of the room description.
     *   This extra information can be controlled by the player through the
     *   "exits on" and "exits off" command.
     *
     *   - Exits can be shown automatically when an actor tries to go in a
     *   direction where no exit exists, as a helpful reminder of which
     *   directions are valid.
     */

    /* include the library header */
    #include "adv3.h"

    /* ------------------------------------------------------------------------ */
    /*
     *   The main exits lister.
     */
    exitLister: PreinitObject
        /* preinitialization */
        execute()
        {
            /* install myself as the global exit lister object */
            gExitLister = self;
        }

        /*
         *   Flag: use "verbose" listing style for exit lists in room
         *   descriptions.  When this is set to true, we'll show a
         *   sentence-style list of exits ("Obvious exits lead east to the
         *   living room, south, and up.").  When this is set to nil, we'll use
         *   a terse style, enclosing the message in the default system
         *   message's brackets ("[Obvious exits: East, West]").
         *
         *   Verbose-style room descriptions tend to fit well with a room
         *   description's prose, but at the expense of looking redundant with
         *   the exit list that's usually built into each room's custom
         *   descriptive text to begin with.  Some authors prefer the terse
         *   style precisely because it doesn't look like more prose
         *   description, but looks like a separate bit of information being
         *   offered.
         *
         *   This is an author-configured setting; the library does not provide
         *   a command to let the player control this setting.
         */
        roomDescVerbose = nil

        /*
         *   Flag: show automatic exit listings on attempts to move in
         *   directions that don't allow travel.  Enable this by default,
         *   since most players appreciate having the exit list called out
         *   separately from the room description (where any mention of exits
         *   might be buried in lots of other text) in place of an unspecific
         *   "you can't go that way".
         *
         *   This is an author-configured setting; the library does not provide
         *   a command to let the player control this setting.
         */
        enableReminder = true

        /*
         *   Flag: enable the automatic exit reminder even when the room
         *   description exit listing is enabled.  When this is nil, we will
         *   NOT show a reminder with "can't go that way" messages when the
         *   room description exit list is enabled - this is the default,
         *   because it can be a little much to have the list of exits shown so
         *   frequently.  Some authors might prefer to show the reminder
         *   unconditionally, though, so this option is offered.
         *
         *   This is an author-configured setting; the library does not provide
         *   a command to let the player control this setting.
         */
        enableReminderAlways = nil

        /*
         *   Flag: use hyperlinks in the directions mentioned in room
         *   description exit lists, so that players can click on the direction
         *   name in the listing to enter the direction command.
         */
        enableHyperlinks = true

        /* flag: we've explained how the exits on/off command works */
        exitsOnOffExplained = nil

        /*
         *   Determine if the "reminder" is enabled.  The reminder is the list
         *   of exits we show along with a "can't go that way" message, to
         *   reminder the player of the valid exits when an invalid one is
         *   attempted.
         */
        isReminderEnabled()
        {
            /*
             *   The reminder is enabled if enableReminderAlways is true, OR if
             *   enableReminder is true AND exitsMode.inRoomDesc is nil.
             */
            return (enableReminderAlways
                    || (enableReminder && !exitsMode.inRoomDesc));
        }

        /*
         *   Get the exit lister we use for room descriptions.
         */
        getRoomDescLister()
        {
            /* use the verbose or terse lister, according to the configuration */
            return roomDescVerbose
                ? lookAroundExitLister
                : lookAroundTerseExitLister;
        }

        /* perform the "exits" command to show exits on explicit request */
        showExitsCommand()
        {
            /* show exits for the current actor */
            showExits(gActor);

            /*
             *   if we haven't explained how to turn exit listing on and off,
             *   do so now
             */
            if (!exitsOnOffExplained)
            {
                gLibMessages.explainExitsOnOff;
                exitsOnOffExplained = true;
            }
        }

        /*
         *   Perform an EXITS ON/OFF/STATUS/LOOK command.  'stat' indicates
         *   whether we're turning on (true) or off (nil) the statusline exit
         *   listing; 'look' indicates whether we're turning the room
         *   description listing on or off.
         */
        exitsOnOffCommand(stat, look)
        {
            /* set the new status */
            exitsMode.inStatusLine = stat;
            exitsMode.inRoomDesc = look;

            /* confirm the new status */
            gLibMessages.exitsOnOffOkay(stat, look);

            /*
             *   If we haven't already explained how the EXITS ON/OFF command
             *   works, don't bother explaining it now, since they obviously
             *   know how it works if they've actually used it.
             */
            exitsOnOffExplained = true;
        }

        /* show the list of exits from an actor's current location */
        showExits(actor)
        {
            /* show exits from the actor's location */
            showExitsFrom(actor, actor.location);
        }

        /* show an exit list display in the status line, if desired */
        showStatuslineExits()
        {
            /* if statusline exit displays are enabled, show the exit list */
            if (exitsMode.inStatusLine)
                showExitsWithLister(gPlayerChar, gPlayerChar.location,
                                    statuslineExitLister,
                                    gPlayerChar.location
                                    .wouldBeLitFor(gPlayerChar));
        }

        /*
         *   Calculate the contribution of the exits list to the height of the
         *   status line, in lines of text.  If we're not configured to display
         *   the exits list in the status line, then the contribution is zero;
         *   otherwise, we'll estimate how much space we need to display the
         *   exit list.
         */
        getStatuslineExitsHeight()
        {
            /*
             *   if we're enabled, our standard display takes up one line; if
             *   we're disabled, we don't contribute anything to the status
             *   line's vertical extent
             */
            if (exitsMode.inStatusLine)
                return 1;
            else
                return 0;
        }

        /* show exits as part of a room description */
        lookAroundShowExits(actor, loc, illum)
        {
            /* if room exit displays are enabled, show the exits */
            if (exitsMode.inRoomDesc)
                showExitsWithLister(actor, loc, getRoomDescLister, illum);
        }

        /* show exits as part of a "cannot go that way" error */
        cannotGoShowExits(actor, loc)
        {
            /* if we want to show the reminder, show it */
            if (isReminderEnabled())
                showExitsWithLister(actor, loc, explicitExitLister,
                                    loc.wouldBeLitFor(actor));
        }

        /* show the list of exits from a given location for a given actor */
        showExitsFrom(actor, loc)
        {
            /* show exits with our standard lister */
            showExitsWithLister(actor, loc, explicitExitLister,
                                loc.wouldBeLitFor(actor));
        }

        /*
         *   Show the list of exits using a specific lister.
         *
         *   'actor' is the actor for whom the display is being generated.
         *   'loc' is the location whose exit list is to be shown; this need
         *   not be the same as the actor's current location.  'lister' is the
         *   Lister object that will show the list of DestInfo objects that we
         *   create to represent the exit list.
         *
         *   'locIsLit' indicates whether or not the ambient illumination, for
         *   the actor's visual senses, is sufficient that the actor would be
         *   able to see if the actor were in the new location.  We take this
         *   as a parameter so that we don't have to re-compute the
         *   information if the caller has already computed it for other
         *   reasons (such as showing a room description).  If the caller
         *   hasn't otherwise computed the value, it can be easily computed as
         *   loc.wouldBeLitFor(actor).
         */
        showExitsWithLister(actor, loc, lister, locIsLit)
        {
            local destList;
            local showDest;
            local options;

            /*
             *   Ask the lister if it shows the destination names.  We need to
             *   know because we want to consolidate exits that go to the same
             *   place if and only if we're going to show the destination in
             *   the listing; if we're not showing the destination, there's no
             *   reason to consolidate.
             */
            showDest = lister.listerShowsDest;

            /* we have no option flags for the lister yet */
            options = 0;

            /* run through all of the directions used in the game */
            destList = new Vector(Direction.allDirections.length());
            foreach (local dir in Direction.allDirections)
            {
                local conn;

                /*
                 *   If the actor's location has a connector in this
                 *   direction, and the connector is apparent, add it to the
                 *   list.
                 *
                 *   If the actor is in the dark, we can only see the
                 *   connector if the connector is visible in the dark.  If
                 *   the actor isn't in the dark, we can show all of the
                 *   connectors.
                 */
                if ((conn = loc.getTravelConnector(dir, actor)) != nil
                    && conn.isConnectorApparent(loc, actor)
                    && conn.isConnectorListed
                    && (locIsLit || conn.isConnectorVisibleInDark(loc, actor)))
                {
                    local dest;
                    local destName = nil;
                    local destIsBack;

                    /*
                     *   We have an apparent connection in this direction, so
                     *   add it to our list.  First, check to see if we know
                     *   the destination.
                     */
                    dest = conn.getApparentDestination(loc, actor);

                    /* note if this is the "back to" connector for the actor */
                    destIsBack = (conn == actor.lastTravelBack);

                    /*
                     *   If we know the destination, and they want to include
                     *   destination names where possible, get the name.  If
                     *   there's a name to show, include the name.
                     */
                    if (dest != nil
                        && showDest
                        && (destName = dest.getDestName(actor, loc)) != nil)
                    {
                        local orig;

                        /*
                         *   we are going to show a destination name for this
                         *   item, so set the special option flag to let the
                         *   lister know that this is the case
                         */
                        options |= ExitLister.hasDestNameFlag;

                        /*
                         *   if this is the back-to connector, note that we
                         *   know the name of the back-to location
                         */
                        if (destIsBack)
                            options |= ExitLister.hasBackNameFlag;

                        /*
                         *   If this destination name already appears in the
                         *   list, don't include this one in the list.
                         *   Instead, add this direction to the 'others' list
                         *   for the existing entry, so that we will show each
                         *   known destination only once.
                         */
                        orig = destList.valWhich({x: x.dest_ == dest});
                        if (orig != nil)
                        {
                            /*
                             *   this same destination name is already present
                             *   - add this direction to the existing entry's
                             *   list of other directions going to the same
                             *   place
                             */
                            orig.others_ += dir;

                            /*
                             *   if this is the back-to connector, note it in
                             *   the original destination item
                             */
                            if (destIsBack)
                                orig.destIsBack_ = true;

                            /*
                             *   don't add this direction to the main list,
                             *   since we don't want to list the destination
                             *   redundantly
                             */
                            continue;
                        }
                    }

                    /* add it to our list */
                    destList.append(new DestInfo(dir, dest, destName,
                                                 destIsBack));
                }
            }

            /* show the list */
            lister.showListAll(destList.toList(), options, 0);
        }
    ;

    /*
     *   A destination tracker.  This keeps track of a direction and the
     *   apparent destination in that direction.
     */
    class DestInfo: object
        construct(dir, dest, destName, destIsBack)
        {
            /* remember the direction, destination, and destination name */
            dir_ = dir;
            dest_ = dest;
            destName_ = destName;
            destIsBack_ = destIsBack;
        }

        /* the direction of travel */
        dir_ = nil

        /* the destination room object */
        dest_ = nil

        /* the name of the destination */
        destName_ = nil

        /* flag: this is the "back to" destination */
        destIsBack_ = nil

        /* list of other directions that go to our same destination */
        others_ = []
    ;

    /*
     *   Settings item - show defaults in status line
     */
    exitsMode: SettingsItem
        /* our ID */
        settingID = 'adv3.exits'

        /* show our description */
        settingDesc =
            (gLibMessages.currentExitsSettings(inStatusLine, inRoomDesc))

        /* convert to text */
        settingToText()
        {
            /* just return the two binary variables */
            return (inStatusLine ? 'on' : 'off')
                + ','
                + (inRoomDesc ? 'on' : 'off');
        }

        settingFromText(str)
        {
            /* parse out our format */
            if (rexMatch('<space>*(<alpha>+)<space>*,<space>*(<alpha>+)',
                         str.toLower()) != nil)
            {
                /* pull out the two variables from the regexp groups */
                inStatusLine = (rexGroup(1)[3] == 'on');
                inRoomDesc = (rexGroup(2)[3] == 'on');
            }
        }

        /*
         *   Our value is in two parts.  inStatusLine controls whether or not
         *   we show the exit list in the status line; inRoomDesc controls the
         *   exit listing in room descriptions.
         */
        inStatusLine = true
        inRoomDesc = nil
    ;

TADS 3 Library Manual
Generated on 8/21/2012 from TADS version 3.1.2