xref: /dports/games/tads/tads-3.0.8/tads3/t3library/adv3/lister.t

#charset "us-ascii"

/* Copyright (c) 2000, 2002 Michael J. Roberts.  All Rights Reserved. */
/*
 *   TADS 3 Library - Lister class
 *
 *   This module defines the "Lister" class, which generates formatted
 *   lists of objects, and several subclasses of Lister that generate
 *   special kinds of lists.
 */

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


/* ------------------------------------------------------------------------ */
/*
 *   Lister.  This is the base class for formatting of lists of objects.
 *
 *   The external interface consists of the showList() method, which
 *   displays a formatted list of objects according to the rules of the
 *   lister subclass.
 *
 *   The rest of the methods are an internal interface which lister
 *   subclasses can override to customize the way that a list is shown.
 *   Certain of these methods are meant to be overridden by virtually all
 *   listers, such as the methods that show the prefix and suffix
 *   messages.  The remaining methods are designed to allow subclasses to
 *   customize detailed aspects of the formatting, so they only need to be
 *   overridden when something other than the default behavior is needed.
 */
class Lister: object
    /*
     *   Show a list, showing all items in the list as though they were
     *   fully visible, regardless of their actual sense status.
     */
    showListAll(lst, options, indent)
    {
        local infoTab;

        /* create a sense information table with each item in full view */
        infoTab = new LookupTable(16, 32);
        foreach (local cur in lst)
        {
            /* add a plain view sensory description to the info list */
            infoTab[cur] = new SenseInfo(cur, transparent, nil, 3);
        }

        /* show the list from the current global point of view */
        showList(getPOV(), nil, lst, options, indent, infoTab, nil);
    }

    /*
     *   Display a list of items, grouping according to the 'listWith'
     *   associations of the items.  We will only list items for which
     *   isListed() returns true.
     *
     *   'pov' is the point of view of the listing, which is usually an
     *   actor (and usually the player character actor).
     *
     *   'parent' is the parent (container) of the list being shown.  This
     *   should be nil if the listed objects are not all within a single
     *   object.
     *
     *   'lst' is the list of items to display.
     *
     *   'options' gives a set of ListXxx option flags.
     *
     *   'indent' gives the indentation level.  This is used only for
     *   "tall" lists (specified by including ListTall in the options
     *   flags).  An indentation level of zero indicates no indentation.
     *
     *   'infoTab' is a lookup table of SenseInfo objects for all of the
     *   objects that can be sensed from the perspective of the actor
     *   performing the action that's causing the listing.  This is
     *   normally the table returned from Thing.senseInfoTable() for the
     *   actor from whose point of view the list is being generated.  (We
     *   take this as a parameter rather than generating ourselves for two
     *   reasons.  First, it's often the case that the same information
     *   table will be needed for a series of listings, so we can save the
     *   compute time of recalculating the same table repeatedly by having
     *   the caller obtain the table and pass it to each lister.  Second,
     *   in some cases the caller will want to synthesize a special sense
     *   table rather than using the actual sense information; taking this
     *   as a parameter allows the caller to easily customize the table.)
     *
     *   'parentGroup' is the ListGroup object that is showing this list.
     *   We will not group the objects we list into the parent group, or
     *   into any group more general than the parent group.
     *
     *   This routine is not usually overridden in lister subclasses.
     *   Instead, this method calls a number of other methods that
     *   determine the listing style in more detail; usually those other,
     *   simpler methods are customized in subclasses.
     */
    showList(pov, parent, lst, options, indent, infoTab, parentGroup)
    {
        local groups;
        local groupTab;
        local singles;
        local origLst;
        local itemCount;

        /* remember the original list */
        origLst = lst;

        /* filter the list to get only the items we actually will list */
        lst = getFilteredList(lst, infoTab);

        /* create a lookup table to keep track of the groups we've seen */
        groupTab = new LookupTable();
        groups = new Vector(10);

        /* set up a vector to keep track of the singles */
        singles = new Vector(10);

        /* figure the groupings */
        itemCount = getListGrouping(groupTab, groups, singles,
                                    lst, parentGroup);

        /*
         *   Now that we've figured out what's in the list and how it's
         *   arranged into groups, show the list.
         */
        showArrangedList(pov, parent, lst, options, indent, infoTab,
                         itemCount, singles, groups, groupTab, origLst);

        /*
         *   If the list is recursive, mention the contents of any items
         *   that weren't listed in the main list, and of any contents
         *   that are specifically to be listed out-of-line.  Don't do
         *   this if we're already recursively showing such a listing,
         *   since if we did so we could show items at recursive depths
         *   more than once; if we're already doing a recursive listing,
         *   our caller will itself recurse through all levels of the
         *   tree, so we don't have to recurse any further ourselves.
         */
        if ((options & ListRecurse) != 0
            && indent == 0
            && (options & ListContents) == 0)
        {
            /* show the contents of each object we didn't list */
            showSeparateContents(pov, origLst,
                                 options | ListContents, infoTab);
        }
    }

    /*
     *   Filter a list to get only the elements we actually want to show.
     *   Returns a new list consisting only of the items that (1) pass the
     *   isListed() test, and (2) are represented in the sense information
     *   table (infoTab).  If infoTab is nil, no sense filtering is
     *   applied.
     */
    getFilteredList(lst, infoTab)
    {
        /* narrow the list down based on the isListed criteria */
        lst = lst.subset({x: isListed(x)});

        /*
         *   If we have an infoTab, build a new list consisting only of
         *   the items in 'lst' that have infoTab entries - we can't sense
         *   anything that doesn't have an infoTab entry, so we don't want
         *   to show any such objects.
         */
        if (infoTab != nil)
        {
            /* create a vector to contain the new filtered list */
            local filteredList = new Vector(lst.length());

            /*
             *   run through our original list and confirm that each one
             *   is in the infoTab
             */
            foreach (local cur in lst)
            {
                /*
                 *   if this item has an infoTab entry, add this item to
                 *   the filtered list
                 */
                if (infoTab[cur] != nil)
                    filteredList.append(cur);
            }

            /* forget the original list, and use the filtered list instead */
            lst = filteredList;
        }

        /* return the filtered list */
        return lst;
    }

    /*
     *   Get the groupings for a given listing.
     *
     *   'groupTab' is an empty LookupTable, and 'groups' is an empty
     *   Vector; we'll populate these with the grouping information.
     *   'singles' is an empty Vector that we'll populate with the single
     *   items not part of any group.
     */
    getListGrouping(groupTab, groups, singles, lst, parentGroup)
    {
        local cur;
        local i, cnt;

        /*
         *   First, scan the list to determine how we're going to group
         *   the objects.
         */
        for (i = 1, cnt = lst.length() ; i <= cnt ; ++i)
        {
            local curGroups;
            local parentIdx;

            /* get this object into a local for easy reference */
            cur = lst[i];

            /* if the item isn't part of this listing, skip it */
            if (!isListed(cur))
                continue;

            /* get the list of groups with which this object is listed */
            curGroups = listWith(cur);

            /* if there are no groups, we can move on to the next item */
            if (curGroups == nil)
                continue;

            /*
             *   If we have a parent group, and it appears in the list of
             *   groups for this item, eliminate everything in the item's
             *   group list up to and including the parent group.  If
             *   we're showing this list as part of a group to begin with,
             *   we obviously don't want to show this list grouped into
             *   the same group, and we also don't want to group it into
             *   anything broader than the parent group.  Groups are
             *   listed from most general to most specific, so we can
             *   eliminate anything up to and including the parent group.
             */
            if (parentGroup != nil
                && (parentIdx = curGroups.indexOf(parentGroup)) != nil)
            {
                /* eliminate everything up to and including the parent */
                curGroups = curGroups.sublist(parentIdx + 1);
            }

            /* if this item has no groups, skip it */
            if (curGroups.length() == 0)
                continue;

            /*
             *   This item has one or more group associations that we must
             *   consider.
             */
            foreach (local g in curGroups)
            {
                local itemsInGroup;

                /* find the group table entry for this group */
                itemsInGroup = groupTab[g];

                /* if there's no entry for this group, create a new one */
                if (itemsInGroup == nil)
                {
                    /* create a new group table entry */
                    itemsInGroup = groupTab[g] = new Vector(10);

                    /* add it to the group vector */
                    groups.append(g);
                }

                /*
                 *   add this item to the list of items that want to be
                 *   grouped with this group
                 */
                itemsInGroup.append(cur);
            }
        }

        /*
         *   We now have the set of all of the groups that could possibly
         *   be involved in this list display.  We must now choose the
         *   single group we'll use to display each grouped object.
         *
         *   First, eliminate any groups with insufficient membership.
         *   (Most groups require at least two members, but this can vary
         *   by group.)
         */
        for (i = 1, cnt = groups.length() ; i <= cnt ; ++i)
        {
            /* if this group has only one member, drop it */
            if (groupTab[groups[i]].length() < groups[i].minGroupSize)
            {
                /* remove this group from the group list */
                groups.removeElementAt(i);

                /*
                 *   adjust the list count, and back up to try the element
                 *   newly at this index on the next iteration
                 */
                --cnt;
                --i;
            }
        }

        /*
         *   Next, scan for groups with identical member lists, and for
         *   groups with subset member lists.  For each pair of identical
         *   elements we find, eliminate the more general of the two.
         */
        for (i = 1, cnt = groups.length() ; i <= cnt ; ++i)
        {
            local g1;
            local mem1;

            /* get the current group and its membership list */
            g1 = groups[i];
            mem1 = groupTab[g1];

            /* look for matching items in the list after this one */
            for (local j = i + 1 ; j <= cnt ; ++j)
            {
                local g2;
                local mem2;

                /* get the current item and its membership list */
                g2 = groups[j];
                mem2 = groupTab[g2];

                /*
                 *   Compare the membership lists for the two items.  Note
                 *   that we built these membership lists all in the same
                 *   order of objects, so if two membership lists have all
                 *   the same members, those members will be in the same
                 *   order in the two lists; hence, we can simply compare
                 *   the two lists to determine the membership order.
                 */
                if (mem1 == mem2)
                {
                    local ordList;

                    /*
                     *   The groups have identical membership, so
                     *   eliminate the more general group.  Groups are
                     *   ordered from most general to least general, so
                     *   keep the one with the higher index in the group
                     *   list for an object in the membership list.  Note
                     *   that we assume that each member has the same
                     *   ordering for the common groups, so we can pick a
                     *   member arbitrarily to find the way a member
                     *   orders the groups.
                     */
                    ordList = listWith(mem1[1]);
                    if (ordList.indexOf(g1) > ordList.indexOf(g2))
                    {
                        /*
                         *   group g1 is more specific than group g2, so
                         *   keep g1 and discard g2 - remove the 'j'
                         *   element from the list, and back up in the
                         *   inner loop so we reconsider the element newly
                         *   at this index on the next iteration
                         */
                        groups.removeElementAt(j);
                        --cnt;
                        --j;
                    }
                    else
                    {
                        /*
                         *   group g2 is more specific, so discard g1 -
                         *   remove the 'i' element from the list, back up
                         *   in the outer loop, and break out of the inner
                         *   loop, since the outer loop element is no
                         *   longer there for us to consider in comparing
                         *   more elements in the inner loop
                         */
                        groups.removeElementAt(i);
                        --cnt;
                        --i;
                        break;
                    }
                }
            }
        }

        /*
         *   Scan for subsets.  For each group whose membership list is a
         *   subset of another group in our list, eliminate the subset,
         *   keeping only the larger group.  The group lister will be able
         *   to show the subgroup as grouped within its larger list.
         */
        for (local i = 1, cnt = groups.length() ; i <= cnt ; ++i)
        {
            local g1;
            local mem1;

            /* get the current group and its membership list */
            g1 = groups[i];
            mem1 = groupTab[g1];

            /* look at the other elements to see if we have any subsets */
            for (local j = 1 ; j <= cnt ; ++j)
            {
                local g2;
                local mem2;

                /* don't bother checking the same element */
                if (j == i)
                    continue;

                /* get the current item and its membership list */
                g2 = groups[j];
                mem2 = groupTab[g2];

                /*
                 *   if g2's membership is a subset, eliminate g2 from the
                 *   group list
                 */
                if (isListSubset(mem2, mem1))
                {
                    /* remove g2 from the list */
                    groups.removeElementAt(j);

                    /* adjust the loop counters for the removal */
                    --cnt;
                    --j;

                    /*
                     *   adjust the outer loop counter if it's affected -
                     *   the outer loop is affected if it's already past
                     *   this point in the list, which means that its
                     *   index is higher than the inner loop index
                     */
                    if (i > j)
                        --i;
                }
            }
        }

        /*
         *   We now have a final accounting of the groups that we will
         *   consider using.  Reset the membership list for each group in
         *   the surviving list.
         */
        foreach (local g in groups)
        {
            local itemsInList;

            /* get this group's membership list vector */
            itemsInList = groupTab[g];

            /* clear the vector */
            itemsInList.removeRange(1, itemsInList.length());
        }

        /*
         *   Now, run through our item list again, and assign each item to
         *   the surviving group that comes earliest in the item's group
         *   list.
         */
        for (i = 1, cnt = lst.length() ; i <= cnt ; ++i)
        {
            local curGroups;
            local winningGroup;

            /* get this object into a local for easy reference */
            cur = lst[i];

            /* if the item isn't part of this listing, skip it */
            if (!isListed(cur))
                continue;

            /* get the list of groups with which this object is listed */
            curGroups = listWith(cur);
            if (curGroups == nil)
                curGroups = [];

            /*
             *   find the first element in the group list that is in the
             *   surviving group list
             */
            winningGroup = nil;
            foreach (local g in curGroups)
            {
                /* if this group is in the surviving list, it's the one */
                if (groups.indexOf(g) != nil)
                {
                    winningGroup = g;
                    break;
                }
            }

            /*
             *   if we have a group, add this item to the group's
             *   membership; otherwise, add it to the singles list
             */
            if (winningGroup != nil)
                groupTab[winningGroup].append(cur);
            else
                singles.append(cur);
        }

        /* eliminate any surviving group with too few members */
        for (i = 1, cnt = groups.length() ; i <= cnt ; ++i)
        {
            local mem;

            /* get this group's membership list */
            mem = groupTab[groups[i]];

            /*
             *   if this group's membership is too small, eliminate the
             *   group and add the member into the singles pile
             */
            if (mem.length() < groups[i].minGroupSize)
            {
                /* put the item into the singles list */
                if (mem.length() > 0)
                    singles.append(mem[1]);

                /* eliminate this item from the group list */
                groups.removeElementAt(i);

                /* adjust the loop counters */
                --cnt;
                --i;
            }
        }

        /* return the cardinality of the arranged list */
        return getArrangedListCardinality(singles, groups, groupTab);
    }

    /*
     *   Show the list.  This is called after we've figured out which items
     *   we intend to display, and after we've arranged the items into
     *   groups.  In rare cases, listers might want to override this, to
     *   customize the way the way the list is displayed based on the
     *   internal arrangement of the list.
     */
    showArrangedList(pov, parent, lst, options, indent, infoTab, itemCount,
                     singles, groups, groupTab, origLst)
    {
        /*
         *   We now know how many items we're listing (grammatically
         *   speaking), so we're ready to display the list prefix.  If
         *   we're displaying nothing at all, just display the "empty"
         *   message, and we're done.
         */
        if (itemCount == 0)
        {
            /* show the empty list */
            showListEmpty(pov, parent);
        }
        else
        {
            local i;
            local cnt;
            local sublists;
            local origOptions = options;
            local itemOptions;
            local groupOptions;
            local listCount;
            local dispCount;
            local cur;

            /*
             *   Check to see if we have one or more group sublists - if
             *   we do, we must use the "long" list format for our overall
             *   list, otherwise we can use the normal "short" list
             *   format.  The long list format uses semicolons to separate
             *   items.
             */
            for (i = 1, cnt = groups.length(), sublists = nil ;
                 i <= cnt ; ++i)
            {
                /*
                 *   if this group's lister item displays a sublist, we
                 *   must use the long format
                 */
                if (groups[i].groupDisplaysSublist)
                {
                    /* note that we are using the long format */
                    sublists = true;

                    /*
                     *   one is enough to make us use the long format, so
                     *   we need not look any further
                     */
                    break;
                }
            }

            /* generate the prefix message if we're in a 'tall' listing */
            if ((options & ListTall) != 0)
            {
                /* indent the prefix */
                showListIndent(options, indent);

                /*
                 *   Show the prefix.  If this is a contents listing, and
                 *   it's not at the top level, show the contents prefix;
                 *   otherwise show the full list prefix.  Note that we can
                 *   have a contents listing at the top level, since some
                 *   lists are broken out for separate listing.
                 */
                if ((options & ListContents) != 0 && indent != 0)
                    showListContentsPrefixTall(itemCount, pov, parent);
                else
                    showListPrefixTall(itemCount, pov, parent);

                /* go to a new line for the list contents */
                "\n";

                /* indent the items one level now, since we showed a prefix */
                ++indent;
            }
            else
            {
                /* show the prefix */
                showListPrefixWide(itemCount, pov, parent);
            }

            /*
             *   regardless of whether we're adding long formatting to the
             *   main list, display the group sublists with whatever
             *   formatting we were originally using
             */
            groupOptions = options;

            /* show each item with our current set of options */
            itemOptions = options;

            /*
             *   if we're using sublists, show "long list" separators in
             *   the main list
             */
            if (sublists)
                itemOptions |= ListLong;

            /*
             *   calculate the number of items we'll show in the list -
             *   each group shows up as one list entry, so the total
             *   number of list entries is the number of single items plus
             *   the number of groups
             */
            listCount = singles.length() + groups.length();

            /*
             *   Show the items.  Run through the (filtered) original
             *   list, so that we show everything in the original sorting
             *   order.
             */
            dispCount = 0;
            foreach (cur in lst)
            {
                local group;
                local displayedCur;

                /* presume we'll display this item */
                displayedCur = true;

                /*
                 *   Figure out how to show this item: if it's in the
                 *   singles list, show it as a single item; if it's in
                 *   the group list, show its group; if it's in a group
                 *   we've previously shown, show nothing, as we showed
                 *   the item when we showed its group.
                 */
                if (singles.indexOf(cur) != nil)
                {
                    /*
                     *   It's in the singles list, so show it as a single
                     *   item.
                     *
                     *   If the item has contents that we'll display in
                     *   'tall' mode, show the item with its contents - we
                     *   don't need to show the item separately, since it
                     *   will provide a 'tall' list prefix showing itself.
                     *   Otherwise, show the item singly.
                     */
                    if ((options & ListTall) != 0
                        && (options & ListRecurse) != 0
                        && contentsListed(cur)
                        && getListedContents(cur, infoTab) != [])
                    {
                        /* show the item with its contents */
                        showContentsList(pov, cur, origOptions | ListContents,
                                         indent, infoTab);
                    }
                    else
                    {
                        /* show the list indent if necessary */
                        showListIndent(itemOptions, indent);

                        /* show the item */
                        showListItem(cur, itemOptions, pov, infoTab);

                        /*
                         *   if we're in wide recursive mode, show the
                         *   item's contents as an in-line parenthetical
                         */
                        if ((options & ListTall) == 0
                            && (options & ListRecurse) != 0
                            && contentsListed(cur)
                            && !contentsListedSeparately(cur))
                        {
                            /* show the item's in-line contents */
                            showInlineContentsList(pov, cur,
                                origOptions | ListContents,
                                indent + 1, infoTab);
                        }
                    }
                }
                else if ((group = groups.valWhich(
                    {g: groupTab[g].indexOf(cur) != nil})) != nil)
                {
                    /* show the list indent if necessary */
                    showListIndent(itemOptions, indent);

                    /* we found the item in a group, so show its group */
                    group.showGroupList(pov, self, groupTab[group],
                                        groupOptions, indent, infoTab);

                    /*
                     *   Forget this group - we only need to show each
                     *   group once, since the group shows every item it
                     *   contains.  Since we'll encounter the groups other
                     *   members as we continue to scan the main list, we
                     *   want to make sure we don't show the group again
                     *   when we reach the other items.
                     */
                    groups.removeElement(group);
                }
                else
                {
                    /*
                     *   We didn't find the item in the singles list or in
                     *   a group - it must be part of a group that we
                     *   already showed previously, so we don't need to
                     *   show it again now.  Simply make a note that we
                     *   didn't display it.
                     */
                    displayedCur = nil;
                }

                /* if we displayed the item, show a suitable separator */
                if (displayedCur)
                {
                    /* count another list entry displayed */
                    ++dispCount;

                    /* show an appropriate separator */
                    showListSeparator(itemOptions, dispCount, listCount);
                }
            }

            /*
             *   if we're in 'wide' mode, finish the listing (note that if
             *   this is a 'tall' listing, we're already done, because a
             *   tall listing format doesn't make provisions for anything
             *   after the item list)
             */
            if ((options & ListTall) == 0)
            {
                /* show the wide-mode list suffix */
                showListSuffixWide(itemCount, pov, parent);
            }
        }
    }

    /*
     *   Get the cardinality of an arranged list.  Returns the number of
     *   items that will appear in the list, for grammatical agreement.
     */
    getArrangedListCardinality(singles, groups, groupTab)
    {
        local cnt;

        /* start with a count of zero; we'll add to it as we go */
        cnt = 0;

        /*
         *   Add up the cardinality of the single items.  Some individual
         *   items in the singles list might count as multiple items
         *   grammatically - in particular, if an item has a plural name,
         *   we need a plural verb to agree with it.
         */
        foreach (local s in singles)
        {
            /* add the grammatical cardinality of this single item */
            cnt += listCardinality(s);
        }

        /* add in the cardinality of each group */
        foreach (local g in groups)
        {
            /* add the grammatical cardinality of this group */
            cnt += g.groupCardinality(self, groupTab[g]);
        }

        /* return the total */
        return cnt;
    }

    /*
     *   Get the number of noun phrase elements in a list.  This differs
     *   from the cardinality in that we only count noun phrases, not the
     *   cardinality of each noun phrase.  So, for example, "five coins"
     *   has cardinality five, but has only one noun phrase.
     */
    getArrangedListNounPhraseCount(singles, groups, groupTab)
    {
        local cnt;

        /* each single item counts as one noun phrase */
        cnt = singles.length();

        /* add in the noun phrases from each group */
        foreach (local g in groups)
            cnt += g.groupNounPhraseCount(self, groupTab[g]);

        /* return the total */
        return cnt;
    }

    /*
     *   Service routine: show the separately-listed contents of the items
     *   in the given list, and their separately-listed contents, and so
     *   on.  This routine is not normally overridden in subclasses, and is
     *   not usually called except from the Lister implementation.
     *
     *   For each item in the given list, we show the item's contents if
     *   the item is either marked as unlisted, or it's marked as showing
     *   its contents separately.  In the former case, we know that we
     *   cannot have shown the item's contents in-line in the main list,
     *   since we didn't show the item at all in the main list.  In the
     *   latter case, we know that we didn't show the item's contents in
     *   the main list because it's specifically marked as showing its
     *   contents out-of-line.
     */
    showSeparateContents(pov, lst, options, infoTab)
    {
        /*
         *   show the separate contents list for each item in the list
         *   which isn't itself listable or which has its contents listed
         *   separately despite its being listed
         */
        foreach (local cur in lst)
        {
            /* only show the contents if the contents are listed */
            if (contentsListed(cur))
            {
                /*
                 *   if we didn't list this item, or if it specifically
                 *   wants its contents listed out-of-line, show its
                 *   listable contents
                 */
                if (!isListed(cur) || contentsListedSeparately(cur))
                {
                    /*
                     *   Show the item's contents.  Note that even though
                     *   we're showing this list recursively, it's actually
                     *   a new top-level list, so show it at indent level
                     *   zero.
                     */
                    showContentsList(pov, cur, options, 0, infoTab);
                }

                /* recursively do the same thing with its contents */
                showSeparateContents(pov, getContents(cur), options, infoTab);
            }
        }
    }

    /*
     *   Service routine: determine if list a is a subset of list b.  a is
     *   a subset of b if every element of a is in b.
     */
    isListSubset(a, b)
    {
        /* a can't be a subset if it has more elements than b */
        if (a.length() > b.length())
            return nil;

        /* check each element of a to see if it's also in b */
        foreach (local cur in a)
        {
            /* if this element of a is not in b, a is not a subset of b */
            if (b.indexOf(cur) == nil)
                return nil;
        }

        /*
         *   we didn't find any elements of a not in b, so a is a subset
         *   of b
         */
        return true;
    }

    /*
     *   Show a list indent if necessary.  If ListTall is included in the
     *   options, we'll indent to the given level; otherwise we'll do
     *   nothing.
     */
    showListIndent(options, indent)
    {
        /* show the indent only if we're in "tall" mode */
        if ((options & ListTall) != 0)
        {
            for (local i = 0 ; i < indent ; ++i)
                "\t";
        }
    }

    /*
     *   Show a newline after a list item if we're in a tall list; does
     *   nothing for a wide list.
     */
    showTallListNewline(options)
    {
        if ((options & ListTall) != 0)
            "\n";
    }

    /*
     *   Show a simple list, recursing into contents lists if necessary.
     *   We pay no attention to grouping; we just show the items
     *   individually.
     *
     *   'prevCnt' is the number of items already displayed, if anything
     *   has already been displayed for this list.  This should be zero if
     *   this will display the entire list.
     */
    showListSimple(pov, lst, options, indent, prevCnt, infoTab)
    {
        local i;
        local cnt;
        local dispCount;
        local totalCount;

        /* calculate the total number of items in the lis t*/
        totalCount = prevCnt + lst.length();

        /* display the items */
        for (i = 1, cnt = lst.length(), dispCount = prevCnt ; i <= cnt ; ++i)
        {
            local cur;

            /* get the item */
            cur = lst[i];

            /*
             *   If the item has contents that we'll display in 'tall'
             *   mode, show the item with its contents - we don't need to
             *   show the item separately, since it will provide a 'tall'
             *   list prefix showing itself.  Otherwise, show the item
             *   singly.
             */
            if ((options & ListTall) != 0
                && (options & ListRecurse) != 0
                && contentsListed(cur)
                && getListedContents(cur, infoTab) != [])
            {
                /* show the item with its contents */
                showContentsList(pov, cur, options | ListContents,
                                 indent + 1, infoTab);
            }
            else
            {
                /* show the list indent if necessary */
                showListIndent(options, indent);

                /* show the item */
                showListItem(cur, options, pov, infoTab);

                /*
                 *   if we're in wide recursive mode, show the item's
                 *   contents as an in-line parenthetical
                 */
                if ((options & ListTall) == 0
                    && (options & ListRecurse) != 0
                    && contentsListed(cur)
                    && !contentsListedSeparately(cur))
                {
                    /* show the item's in-line contents */
                    showInlineContentsList(pov, cur,
                                           options | ListContents,
                                           indent + 1, infoTab);
                }
            }

            /* count the item displayed */
            ++dispCount;

            /* show the list separator */
            showListSeparator(options, dispCount, totalCount);
        }
    }

    /*
     *   List the contents of an item.
     *
     *   'pov' is the point of view, which is usually an actor (and
     *   usually the player character actor).
     *
     *   'obj' is the item whose contents we are to display.
     *
     *   'options' is the set of flags that we'll pass to showList(), and
     *   has the same meaning as for that function.
     *
     *   'infoTab' is a lookup table of SenseInfo objects giving the sense
     *   information for all of the objects that the actor to whom we're
     *   showing the contents listing can sense.
     */
    showContentsList(pov, obj, options, indent, infoTab)
    {
        /*
         *   List the item's contents.  By default, use the contentsLister
         *   property of the object whose contents we're showing to obtain
         *   the lister for the contents.
         */
        obj.showObjectContents(pov, obj.contentsLister, options,
                               indent, infoTab);
    }

    /*
     *   Determine if an object's contents are listed separately from its
     *   own list entry for the purposes of our type of listing.  If this
     *   returns true, then we'll list the object's contents in a separate
     *   listing (a separate sentence following the main listing sentence,
     *   or a separate tree when in 'tall' mode).
     *
     *   Note that this only matters for objects listed in the top-level
     *   list.  We'll always show the contents separately for an object
     *   that isn't listed in the top-level list (i.e., an object for which
     *   isListed(obj) returns nil).
     */
    contentsListedSeparately(obj) { return obj.contentsListedSeparately; }

    /*
     *   Show an "in-line" contents list.  This shows the item's contents
     *   list as a parenthetical, as part of a recursive listing.  This is
     *   pretty much the same as showContentsList(), but uses the object's
     *   in-line contents lister instead of its regular contents lister.
     */
    showInlineContentsList(pov, obj, options, indent, infoTab)
    {
        /* show the item's contents using its in-line contents lister */
        obj.showObjectContents(pov, obj.inlineContentsLister,
                               options, indent, infoTab);
    }

    /*
     *   Show the prefix for a 'wide' listing - this is a message that
     *   appears just before we start listing the objects.  'itemCount' is
     *   the number of items to be listed; the items might be grouped in
     *   the listing, so a list that comes out as "three boxes and two
     *   books" will have an itemCount of 5.  (The purpose of itemCount is
     *   to allow the message to have grammatical agreement in number.)
     *
     *   This will never be called with an itemCount of zero, because we
     *   will instead use showListEmpty() to display an empty list.
     */
    showListPrefixWide(itemCount, pov, parent) { }

    /*
     *   show the suffix for a 'wide' listing - this is a message that
     *   appears just after we finish listing the objects
     */
    showListSuffixWide(itemCount, pov, parent) { }

    /*
     *   Show the list prefix for a 'tall' listing.  Note that there is no
     *   list suffix for a tall listing, because the format doesn't allow
     *   it.
     */
    showListPrefixTall(itemCount, pov, parent) { }

    /*
     *   Show the list prefix for the contents of an object in a 'tall'
     *   listing.  By default, we just show our usual tall list prefix.
     */
    showListContentsPrefixTall(itemCount, pov, parent)
        { showListPrefixTall(itemCount, pov, parent); }

    /*
     *   Show an empty list.  If the list to be displayed has no items at
     *   all, this is called instead of the prefix/suffix routines.  This
     *   can be left empty if no message is required for an empty list, or
     *   can display the complete message appropriate for an empty list
     *   (such as "You are empty-handed").
     */
    showListEmpty(pov, parent) { }

    /*
     *   Is this item to be listed in room descriptions?  Returns true if
     *   so, nil if not.  By default, we'll use the object's isListed
     *   method to make this determination.  We virtualize this into the
     *   lister interface to allow for different inclusion rules for the
     *   same object depending on the type of list we're generating.
     */
    isListed(obj) { return obj.isListed(); }

    /*
     *   Get the grammatical cardinality of this listing item.  This should
     *   return the number of items that this item appears to be
     *   grammatically, for noun-verb agreement purposes.
     */
    listCardinality(obj) { return obj.listCardinality(self); }

    /*
     *   Are this item's contents listable?
     */
    contentsListed(obj) { return obj.contentsListed; }

    /*
     *   Get all contents of this item.
     */
    getContents(obj) { return obj.contents; }

    /*
     *   Get the listed contents of an object.  'infoTab' is the sense
     *   information table for the enclosing listing.  By default, we call
     *   the object's getListedContents() method, but this is virtualized
     *   in the lister interface to allow for listing other hierarchies
     *   besides ordinary contents.
     */
    getListedContents(obj, infoTab)
    {
        return obj.getListedContents(self, infoTab);
    }

    /*
     *   Get the list of grouping objects for listing the item.  By
     *   default, we return the object's listWith result.  Subclasses can
     *   override this to specify different groupings for the same object
     *   depending on the type of list we're generating.
     *
     *   The group list returned is in order from most general to most
     *   specific.  For example, if an item is grouped with coins in
     *   general and silver coins in particular, the general coins group
     *   would come first, then the silver coin group, because the silver
     *   coin group is more specific.
     */
    listWith(obj) { return obj.listWith; }

    /* show an item in a list */
    showListItem(obj, options, pov, infoTab)
    {
        obj.showListItem(options, pov, infoTab);
    }

    /*
     *   Show a set of equivalent items as a counted item ("three coins").
     *   The listing mechanism itself never calls this directly; instead,
     *   this is provided so that ListGroupEquivalent can ask the lister
     *   how to describe its equivalent sets, so that different listers
     *   can customize the display of equivalent items.
     *
     *   'lst' is the full list of equivalent items.  By default, we pick
     *   one of these arbitrarily to show, since they're presumably all
     *   the same for the purposes of the list.
     */
    showListItemCounted(lst, options, pov, infoTab)
    {
        /*
         *   by defualt, show the counted name for one of the items
         *   (chosen arbitrarily, since they're all the same)
         */
        lst[1].showListItemCounted(lst, options, pov, infoTab);
    }

    /*
     *   Show a list separator after displaying an item.  curItemNum is
     *   the number of the item just displayed (1 is the first item), and
     *   totalItems is the total number of items that will be displayed in
     *   the list.
     *
     *   This generic routine is further parameterized by properties for
     *   the individual types of separators.  This default implementation
     *   distinguishes the following separators: the separator between the
     *   two items in a list of exactly two items; the separator between
     *   adjacent items other than the last two in a list of more than two
     *   items; and the separator between the last two elements of a list
     *   of more than two items.
     */
    showListSeparator(options, curItemNum, totalItems)
    {
        local useLong = ((options & ListLong) != 0);

        /* if this is a tall list, the separator is simply a newline */
        if ((options & ListTall) != 0)
        {
            "\n";
            return;
        }

        /* if that was the last item, there are no separators */
        if (curItemNum == totalItems)
            return;

        /* check to see if the next item is the last */
        if (curItemNum + 1 == totalItems)
        {
            /*
             *   We just displayed the penultimate item in the list, so we
             *   need to use the special last-item separator.  If we're
             *   only displaying two items total, we use an even more
             *   special separator.
             */
            if (totalItems == 2)
            {
                /* use the two-item separator */
                if (useLong)
                    longListSepTwo;
                else
                    listSepTwo;
            }
            else
            {
                /* use the normal last-item separator */
                if (useLong)
                    longListSepEnd;
                else
                    listSepEnd;
            }
        }
        else
        {
            /* in the middle of the list - display the normal separator */
            if (useLong)
                longListSepMiddle;
            else
                listSepMiddle;
        }
    }

    /*
     *   Show the specific types of list separators for this list.  By
     *   default, these will use the generic separators defined in the
     *   library messages object (libMessages).  For English, these are
     *   commas and semicolons for short and long lists, respectively; the
     *   word "and" for a list with only two items; and a comma or
     *   semicolon and the word "and" between the last two items in a list
     *   with more than two items.
     */

    /*
     *   normal and "long list" separator between the two items in a list
     *   with exactly two items
     */
    listSepTwo { libMessages.listSepTwo; }
    longListSepTwo { libMessages.longListSepTwo; }

    /*
     *   normal and long list separator between items in list with more
     *   than two items
     */
    listSepMiddle { libMessages.listSepMiddle; }
    longListSepMiddle { libMessages.longListSepMiddle; }

    /*
     *   normal and long list separator between second-to-last and last
     *   items in a list with more than two items
     */
    listSepEnd { libMessages.listSepEnd; }
    longListSepEnd { libMessages.longListSepEnd; }

    /*
     *   Get my "top-level" lister.  For a sub-lister, this will return
     *   the parent lister's top-level lister.  The default lister is a
     *   top-level lister, so we just return ourself.
     */
    getTopLister() { return self; }

    /*
     *   The last custom flag defined by this class.  Lister and each
     *   subclass are required to define this so that each subclass can
     *   allocate its own custom flags in a manner that adapts
     *   automatically to future additions of flags to base classes.  As
     *   the base class, we allocate our flags statically with #define's,
     *   so we simply use the fixed #define'd last flag value here.
     */
    nextCustomFlag = ListCustomFlag
;


/* ------------------------------------------------------------------------ */
/*
 *   Plain lister - this lister doesn't show anything for an empty list,
 *   and doesn't show a list suffix or prefix.
 */
plainLister: Lister
    /* show the prefix/suffix in wide mode */
    showListPrefixWide(itemCount, pov, parent) { }
    showListSuffixWide(itemCount, pov, parent) { }

    /* show the tall prefix */
    showListPrefixTall(itemCount, pov, parent) { }
;

/*
 *   Sub-lister for listing the contents of a group.  This lister shows a
 *   simple list with no prefix or suffix, and otherwise uses the
 *   characteristics of the parent lister.
 */
class GroupSublister: object
    construct(parentLister, parentGroup)
    {
        /* remember the parent lister and group objects */
        self.parentLister = parentLister;
        self.parentGroup = parentGroup;
    }

    /* no prefix or suffix */
    showListPrefixWide(itemCount, pov, parent) { }
    showListSuffixWide(itemCount, pov, parent) { }
    showListPrefixTall(itemCount, pov, parent) { }

    /* show nothing when empty */
    showListEmpty(pov, parent) { }

    /*
     *   Show an item in the list.  Rather than going through the parent
     *   lister directly, we go through the parent group, so that it can
     *   customize the display of items in the group.
     */
    showListItem(obj, options, pov, infoTab)
    {
        /* ask the parent group to handle it */
        parentGroup.showGroupItem(parentLister, obj, options, pov, infoTab);
    }

    /*
     *   Show a counted item in the group.  As with showListItem, we ask
     *   the parent group to do the work, so that it can customize the
     *   display if desired.
     */
    showListItemCounted(lst, options, pov, infoTab)
    {
        /* ask the parent group to handle it */
        parentGroup.showGroupItemCounted(
            parentLister, lst, options, pov, infoTab);
    }

    /* delegate everything we don't explicitly handle to our parent lister */
    propNotDefined(prop, [args])
    {
        return delegated (getTopLister()).(prop)(args...);
    }

    /* get the top-level lister - returns my parent's top-level lister */
    getTopLister() { return parentLister.getTopLister(); }

    /* my parent lister */
    parentLister = nil

    /* my parent list group */
    parentGroup = nil
;

/*
 *   Paragraph lister: this shows its list items separated by paragraph
 *   breaks, with a paragraph break before the first item.
 */
class ParagraphLister: Lister
    /* start the list with a paragraph break */
    showListPrefixWide(itemCount, pov, parent) { "<.p>"; }

    /* we show no list separators */
    showListSeparator(options, curItemNum, totalItems)
    {
        /* add a paragraph separator between items */
        if (curItemNum != totalItems)
            "<.p>";
    }
;

/*
 *   Lister for objects in a room description with special descriptions.
 *   Each special description gets its own paragraph, so this is based on
 *   the paragraph lister.
 */
specialDescLister: ParagraphLister
    /* list everything */
    isListed(obj) { return true; }

    /* show a list item */
    showListItem(obj, options, pov, infoTab)
    {
        /* show the object's special description */
        obj.showSpecialDescWithInfo(infoTab[obj], pov);
    }

    /* use the object's special description grouper */
    listWith(obj) { return obj.specialDescListWith; }
;

/*
 *   Special description lister for the contents of an item being examined.
 *   This is similar to the regular specialDescLister, but shows the
 *   special descriptions of the contents of an object being described with
 *   "examine" or "look in," rather than of the entire location.
 */
class SpecialDescContentsLister: ParagraphLister
    construct(cont)
    {
        /* remember the containing object being described */
        cont_ = cont;
    }

    /* list everything */
    isListed(obj) { return true; }

    /* show a list item */
    showListItem(obj, options, pov, infoTab)
    {
        /* show the object's special description in our container */
        obj.showSpecialDescInContentsWithInfo(infoTab[obj], pov, cont_);
    }

    /* use the object's special description grouper */
    listWith(obj) { return obj.specialDescListWith; }

    /* the containing object we're examining */
    cont_ = nil
;


/*
 *   Plain lister for actors.  This is the same as an ordinary
 *   plainLister, but ignores each object's isListed flag and lists it
 *   anyway.
 */
plainActorLister: plainLister
    isListed(obj) { return true; }
;

/*
 *   Grouper for actors in a common posture and in a common location.  We
 *   create one of these per room per posture when we discover actors in
 *   the room during "look around" (or "examine" on a nested room).  This
 *   grouper lets us group actors like so: "Dan and Jane are sitting on
 *   the couch."
 */
class RoomActorGrouper: ListGroup
    construct(location, posture)
    {
        self.location = location;
        self.posture = posture;
    }

    showGroupList(pov, lister, lst, options, indent, infoTab)
    {
        local cont;
        local outer;

        /* if the location isn't in the sense table, skip the whole list */
        if (infoTab[location] == nil)
            return;

        /* get the nominal posture container, if it's visible */
        cont = location.getNominalActorContainer(posture);
        if (cont != nil && !pov.canSee(cont))
            cont = nil;

        /* get the outermost visible enclosing location */
        outer = location.getOutermostVisibleRoom(pov);

        /*
         *   Only mention the outermost location if it's remote and it's
         *   not the same as the nominal container.  (If the remote outer
         *   room is the same as the nominal container, it would be
         *   redundant to mention it as both the nominal and remote
         *   container.)
         */
        if (outer == cont || pov.isIn(outer))
            outer = nil;

        /* create a sub-lister for the group */
        lister = createGroupSublister(lister);

        /*
         *   show the list prefix message - use the nominal container if
         *   we can see it, otherwise generate a generic message
         */
        if (cont != nil)
            cont.actorInGroupPrefix(pov, posture, outer, lst);
        else if (outer != nil)
            libMessages.actorThereGroupPrefix(pov, posture, outer, lst);
        else
            libMessages.actorHereGroupPrefix(posture, lst);

        /* list the actors' names as a plain list */
        plainActorLister.showList(pov, location, lst, options,
                                  indent, infoTab, self);

        /* add the suffix message */
        if (cont != nil)
            cont.actorInGroupSuffix(pov, posture, outer, lst);
        else if (outer != nil)
            libMessages.actorThereGroupSuffix(pov, posture, outer, lst);
        else
            libMessages.actorHereGroupSuffix(posture, lst);
    }
;

/*
 *   Base class for inventory listers.  This lister uses a special listing
 *   method to show the items, so that items can be shown with special
 *   notations in an inventory list that might not appear in other types
 *   of listings.
 */
class InventoryLister: Lister
    /* list items in inventory according to their isListedInInventory */
    isListed(obj) { return obj.isListedInInventory; }

    /*
     *   Show list items using the inventory name, which might differ from
     *   the regular nmae of the object.
     */
    showListItem(obj, options, pov, infoTab)
        { obj.showInventoryItem(options, pov, infoTab); }

    showListItemCounted(lst, options, pov, infoTab)
        { lst[1].showInventoryItemCounted(lst, options, pov, infoTab); }

    /*
     *   Show contents of the items in the inventory.  We customize this
     *   so that we can differentiate inventory contents lists from other
     *   contents lists.
     */
    showContentsList(pov, obj, options, indent, infoTab)
    {
        /* list the item's contents */
        obj.showInventoryContents(pov, obj.contentsLister, options,
                                  indent, infoTab);
    }

    /*
     *   Show the contents in-line, for an inventory listing.
     */
    showInlineContentsList(pov, obj, options, indent, infoTab)
    {
        /* list the item's contents using its in-line lister */
        obj.showInventoryContents(pov, obj.inlineContentsLister,
                                  options, indent, infoTab);
    }
;

/*
 *   Base class for worn-inventory listers.  This lister uses a special
 *   listing method to show the items, so that items being worn are shown
 *   *without* the special '(being worn)' notation that might otherwise
 *   appear in inventory listings.
 */
class WearingLister: InventoryLister
    /* show the list item using the "worn listing" name */
    showListItem(obj, options, pov, infoTab)
        { obj.showWornItem(options, pov, infoTab); }
    showListItemCounted(lst, options, pov, infoTab)
        { lst[1].showWornItemCounted(lst, options, pov, infoTab); }
;

/*
 *   "Divided" inventory lister.  In 'wide' mode, this shows inventory in
 *   two parts: the items being carried, and the items being worn.  (We use
 *   the standard single tree-style listing in 'tall' mode.)
 */
class DividedInventoryLister: InventoryLister
    /*
     *   Show the list.  We completely override the main lister method so
     *   that we can show our two lists.
     */
    showList(pov, parent, lst, options, indent, infoTab, parentGroup)
    {
        /*
         *   If this is a 'tall' listing, use the normal listing style; for
         *   a 'wide' listing, use our special segregated style.  If we're
         *   being invoked recursively to show a contents listing, we
         *   similarly want to use the base handling.
         */
        if ((options & (ListTall | ListContents)) != 0)
        {
            /* inherit the standard behavior */
            inherited(pov, parent, lst, options, indent, infoTab,
                      parentGroup);
        }
        else
        {
            local carryingLst, wearingLst;
            local carryingStr, wearingStr;

            /* divide the lists into 'carrying' and 'wearing' sublists */
            carryingLst = new Vector(32);
            wearingLst = new Vector(32);
            foreach (local cur in lst)
                (cur.isWornBy(parent) ? wearingLst : carryingLst).append(cur);

            /* generate and capture the 'carried' listing */
            carryingStr = outputManager.curOutputStream.captureOutput({:
                carryingLister.showList(pov, parent, carryingLst, options,
                                        indent, infoTab, parentGroup)});

            /* generate and capture the 'worn' listing */
            wearingStr = outputManager.curOutputStream.captureOutput({:
                wearingLister.showList(pov, parent, wearingLst, options,
                                       indent, infoTab, parentGroup)});

            /* generate the combined listing */
            showCombinedInventoryList(parent, carryingStr, wearingStr);

            /*
             *   Now show the out-of-line contents for the whole list, if
             *   appropriate.  We save this until after showing both parts
             *   of the list, to keep the direct inventory parts together
             *   at the beginning of the output.
             */
            if ((options & ListRecurse) != 0
                && indent == 0
                && (options & ListContents) == 0)
            {
                /* show the contents of each object we didn't list */
                showSeparateContents(pov, lst, options | ListContents,
                                     infoTab);
            }
        }
    }

    /*
     *   Show the combined listing.  This must be provided by each
     *   language-specific subclass.  The inputs are the results (strings)
     *   of the captured output of the sublistings of the items being
     *   carried and the items being worn.  These will be "raw" listings,
     *   without any prefix or suffix text.  This routine's job is to
     *   display the final output, adding the framing text.
     */
    showCombinedInventoryList(parent, carrying, wearing) { }

    /*
     *   The recommended maximum number of number of noun phrases to show
     *   in the single-sentence format.  This should be used by the
     *   showCombinedInventoryList() method to decide whether to display
     *   the combined listing as a single sentence or as two separate
     *   sentences.
     */
    singleSentenceMaxNouns = 7

    /*
     *   Our associated sub-listers for items begin carried and worn,
     *   respectively.  We'll use these to list our sublist of items being
     *   worn.
     */
    carryingLister = actorCarryingSublister
    wearingLister = actorWearingSublister
;

/*
 *   Base class for the inventory sub-lister for items being carried.  This
 *   is a minor specialization of the basic inventory lister; in this
 *   version, we omit any prefix, suffix, or empty messages, since we'll
 *   rely on the caller to combine our raw listing with the raw 'wearing'
 *   listing to form the full results.
 *
 *   This type of lister should normally only be used from within an
 *   inventory lister.  This type of lister assumes that it's part of a
 *   larger listing controlled externally; for example, we don't show
 *   out-of-line contents, since we assume the caller will be doing this.
 */
class InventorySublister: InventoryLister
    /* don't show any prefix, suffix, or 'empty' messages */
    showListPrefixWide(itemCount, pov, parent) { }
    showListSuffixWide(itemCount, pov, parent) { }
    showListEmpty(pov, parent) { }

    /* don't show out-of-line contents */
    showSeparateContents(pov, lst, options, infoTab) { }
;

/*
 *   Base class for the inventory sub-lister for items being worn.  We use
 *   a special listing method to show these items, so that items being
 *   shown explicitly in a worn list can be shown differently from the way
 *   they would in a normal inventory list.  (For example, a worn item in a
 *   normal inventory list might show a "(worn)" indication, whereas it
 *   would not want to show a similar indication in a list of objects
 *   explicitly being worn.)
 *
 *   This type of lister should normally only be used from within an
 *   inventory lister.  This type of lister assumes that it's part of a
 *   larger listing controlled externally; for example, we don't show
 *   out-of-line contents, since we assume the caller will be doing this.
 */
class WearingSublister: WearingLister
    /* don't show any prefix, suffix, or 'empty' messages */
    showListPrefixWide(itemCount, pov, parent) { }
    showListSuffixWide(itemCount, pov, parent) { }
    showListEmpty(pov, parent) { }

    /* don't show out-of-line contents */
    showSeparateContents(pov, lst, options, infoTab) { }
;

/*
 *   The standard inventory sublisters.
 */
actorCarryingSublister: InventorySublister;
actorWearingSublister: WearingSublister;

/*
 *   Base class for contents listers.  This is used to list the contents
 *   of the objects that appear in top-level lists (a top-level list is
 *   the list of objects directly in a room that appears in a room
 *   description, or the list of items being carried in an INVENTORY
 *   command, or the direct contents of an object being examined).
 */
class ContentsLister: Lister
;

/*
 *   Base class for description contents listers.  This is used to list
 *   the contents of an object when we examine the object, or when we
 *   explicitly LOOK IN the object.
 */
class DescContentsLister: Lister
    /*
     *   Use the explicit look-in flag for listing contents.  We might
     *   list items within an object on explicit examination of the item
     *   that we wouldn't list in a room or inventory list containing the
     *   item.
     */
    isListed(obj) { return obj.isListedInContents; }
;

/*
 *   Base class for sense listers, which list the items that can be sensed
 *   for a command like "listen" or "smell".
 */
class SenseLister: ParagraphLister
    /* show everything we're asked to list */
    isListed(obj) { return true; }

    /* show a counted list item */
    showListItemCounted(lst, options, pov, infoTab)
    {
        /*
         *   simply show one item, without the count - non-visual senses
         *   don't distinguish numbers of items that are equivalent
         */
        showListItem(lst[1], options, pov, infoTab);
    }
;

/*
 *   Room contents lister for things that can be heard.
 */
roomListenLister: SenseLister
    /* list an item in a room if its isSoundListedInRoom is true */
    isListed(obj) { return obj.isSoundListedInRoom; }

    /* list an item */
    showListItem(obj, options, pov, infoTab)
    {
        /* show the "listen" list name for the item */
        obj.soundHereDesc();
    }
;

/*
 *   Lister for explicit "listen" action
 */
listenActionLister: roomListenLister
    /* list everything in response to an explicit general LISTEN command */
    isListed(obj) { return true; }

    /* show an empty list */
    showListEmpty(pov, parent)
    {
        mainReport(&nothingToHearMsg);
    }

;

/*
 *   Room contents lister for things that can be smelled.
 */
roomSmellLister: SenseLister
    /* list an item in a room if its isSmellListedInRoom is true */
    isListed(obj) { return obj.isSmellListedInRoom; }

    /* list an item */
    showListItem(obj, options, pov, infoTab)
    {
        /* show the "smell" list name for the item */
        obj.smellHereDesc();
    }
;

/*
 *   Lister for explicit "smell" action
 */
smellActionLister: roomSmellLister
    /* list everything in response to an explicit general SMELL command */
    isListed(obj) { return true; }

    /* show an empty list */
    showListEmpty(pov, parent)
    {
        mainReport(&nothingToSmellMsg);
    }

;

/*
 *   Inventory lister for things that can be heard.
 */
inventoryListenLister: SenseLister
    /* list an item */
    showListItem(obj, options, pov, infoTab)
    {
        /* show the "listen" list name for the item */
        obj.soundHereDesc();
    }
;

/*
 *   Inventory lister for things that can be smelled.
 */
inventorySmellLister: SenseLister
    /* list an item */
    showListItem(obj, options, pov, infoTab)
    {
        /* show the "smell" list name for the item */
        obj.smellHereDesc();
    }
;


/* ------------------------------------------------------------------------ */
/*
 *   List Group Interface.  An instance of this object is created for each
 *   set of objects that are to be grouped together.
 */
class ListGroup: object
    /*
     *   Show a list of items from this group.  All of the items in the
     *   list will be members of this list group; we are to display a
     *   sentence fragment showing the items in the list, suitable for
     *   embedding in a larger list.
     *
     *   'options', 'indent', and 'infoTab' have the same meaning as they
     *   do for showList().
     *
     *   Note that we are not to display any separator before or after our
     *   list; the caller is responsible for that.
     */
    showGroupList(pov, lister, lst, options, indent, infoTab) { }

    /*
     *   Show an item in the group's sublist.  The sublister calls this to
     *   display each item in the group when the group calls the sublister
     *   to display the group list.  By default, we simply let the
     *   sublister handle the request, which gives items in our group
     *   sublist the same appearance they would have had in the sublist to
     *   begin with.  We can customize this behavior to give our list
     *   items a different appearance special to the group sublist.
     *
     *   Note that the same customization could be accomplished by
     *   creating a specialized subclass of GroupSublister in
     *   createGroupSublister(), and overriding showListItem() in the
     *   specialized GroupSublister subclass.  We use this mechanism as a
     *   convenience, so that a separate group sublister class doesn't
     *   have to be created simply to customize the display of group
     *   items.
     */
    showGroupItem(sublister, obj, options, pov, infoTab)
    {
        /* by default, list using the regular sublister */
        sublister.showListItem(obj, options, pov, infoTab);
    }

    /*
     *   Show a counted item in our group list.  This is the counted item
     *   equivalent of showGroupItem.
     */
    showGroupItemCounted(sublister, lst, options, pov, infoTab)
    {
        /* by default, list using the regular sublister */
        sublister.showListItemCounted(lst, options, pov, infoTab);
    }

    /*
     *   Determine if showing the group list will introduce a sublist into
     *   an enclosing list.  This should return true if we will show a
     *   sublist without some kind of grouping, so that the caller knows
     *   to introduce some extra grouping into its enclosing list.  This
     *   should return nil if the sublist we display will be clearly set
     *   off in some way (for example, by being enclosed in parentheses).
     */
    groupDisplaysSublist = true

    /*
     *   The minimum number of elements for which we should retain the
     *   group in a listing.  By default, we need two elements to display a
     *   group; any group with only one element is discarded, and the
     *   single element is moved into the 'singles' list.  This can be
     *   overridden to allow single-element groups to be retained.  In most
     *   cases, it's undesirable to retain single-element groups, but when
     *   grouping is used to partition a list into two or more fixed
     *   portions, single-element groups become desirable.
     */
    minGroupSize = 2

    /*
     *   Determine the cardinality of the group listing, grammatically
     *   speaking.  This is the number of items that the group seems to be
     *   for the purposes of grammatical agreement.  For example, if the
     *   group is displayed as "$1.38 in change", it would be singular for
     *   grammatical agreement, hence would return 1 here; if it displays
     *   "five coins (two copper, three gold)," it would count as five
     *   items for grammatical agreement.
     *
     *   For languages (like English) that grammatically distinguish
     *   number only between singular and plural, it is sufficient for
     *   this to return 1 for singular and anything higher for plural.
     *   For the sake of languages that make more elaborate number
     *   distinctions for grammatical agreement, though, this should
     *   return as accurate a count as is possible.
     *
     *   By default, we return the number of items to be displayed in the
     *   list group.  This should be overridden when necessary, such as
     *   when the group message is singular in usage even if the list has
     *   multiple items (as in "$1.38 in change").
     */
    groupCardinality(lister, lst) { return lst.length(); }

    /*
     *   Get the number of noun phrases this group will display.  This
     *   differs from the cardinality in that it doesn't matter how many
     *   *objects* the phrases represent; it only matters how many phrases
     *   are displayed.  For example, "five coins" has cardinality 5 but
     *   only displays one noun phrase.
     *
     *   By default, we simply return the number of items in the group,
     *   since most groups individually list their items.
     */
    groupNounPhraseCount(lister, lst) { return lst.length(); }

    /*
     *   Create the group sublister.
     *
     *   In most cases, when a group displays a list of the items in the
     *   group as a sublist, it will not want to use the same lister that
     *   was used to show the enclosing group, because the enclosing lister
     *   will usually have different prefix/suffix styles than the sublist.
     *   However, the group list and the enclosing list might share many
     *   other attributes, such as the style of name to use when displaying
     *   items in the list.  The default sublister we create,
     *   GroupSublister, is a hybrid that uses the enclosing lister's
     *   attributes except for a few, such as the prefix and suffix, that
     *   usually need to be changed for the sublist.
     *
     *   This can be overridden to use a completely customized Lister
     *   object for the group list, if desired.
     */
    createGroupSublister(parentLister)
    {
        /* create the standard group sublister by default */
        return new GroupSublister(parentLister, self);
    }
;

/*
 *   A "custom" List Group implementation.  This type of lister uses a
 *   completely custom message to show the group, without a need to
 *   recursively invoke a lister to list the individual elements.  The
 *   main difference between this and the base ListGroup is that the
 *   interface to the custom message generator is very simple - we can
 *   dispense with most of the numerous arguments that the base group
 *   message receives, since most of those arguments are there to allow
 *   recursive listing of the group list.
 */
class ListGroupCustom: ListGroup
    showGroupList(pov, lister, lst, options, indent, infoTab)
    {
        /* simply show the custom message for the list */
        showGroupMsg(lst);
    }

    /* show the custom group message - subclasses should override */
    showGroupMsg(lst) { }
;

/*
 *   Sorted group list.  This is a list that simply displays its members
 *   in a specific sorting order.
 */
class ListGroupSorted: ListGroup
    /*
     *   Show the group list
     */
    showGroupList(pov, lister, lst, options, indent, infoTab)
    {
        /* put the list in sorted order */
        lst = sortListGroup(lst);

        /* create a sub-lister for the group */
        lister = createGroupSublister(lister);

        /* show the list */
        lister.showList(pov, nil, lst, options & ~ListContents,
                        indent, infoTab, self);
    }

    /*
     *   Sort the group list.  By default, if we have a
     *   compareGroupItems() method defined, we'll sort the list using
     *   that method; otherwise, we'll just return the list unchanged.
     */
    sortListGroup(lst)
    {
        /*
         *   if we have a compareGroupItems method, use it to sort the
         *   list; otherwise, just return the list in its current order
         */
        if (propDefined(&compareGroupItems, PropDefAny))
            return lst.sort(SortAsc, {a, b: compareGroupItems(a, b)});
        else
            return lst;
    }

    /*
     *   Compare a pair of items from the group to determine their sorting
     *   order.  Returns 0 if the two items are at the same sorting order,
     *   1 if the first item sorts after the second item, -1 if the first
     *   item sorts before the second item.
     *
     *   We do not provide a default implementation of this method, so
     *   that sortListGroup will know not to bother sorting the list at
     *   all if the subclass doesn't provide a definition for this method.
     */
    // compareGroupItems(a, b) { return a > b ? 1 : a == b ? 0 : -1; }
;

/*
 *   List Group implementation: parenthesized sublist.  Displays the
 *   number of items collectively, then displays the list of items in
 *   parentheses.
 *
 *   Note that this is a ListGroupSorted subclass.  If our subclass
 *   defines a compareGroupItems() method, we'll show the list in the
 *   order specified by compareGroupItems().
 */
class ListGroupParen: ListGroupSorted
    /*
     *   show the group list
     */
    showGroupList(pov, lister, lst, options, indent, infoTab)
    {
        /* sort the list group, if we have an ordering method defined */
        lst = sortListGroup(lst);

        /* create a sub-lister for the group */
        lister = createGroupSublister(lister);

        /* show the collective count of the object */
        showGroupCountName(lst);

        /* show the tall or wide sublist */
        if ((options & ListTall) != 0)
        {
            /* tall list - show the items as a sublist */
            "\n";
            lister.showList(pov, nil, lst, options & ~ListContents,
                            indent, infoTab, self);
        }
        else
        {
            /* wide list - add a space and a paren for the sublist */
            " (";

            /* show the sublist */
            lister.showList(pov, nil, lst, options & ~ListContents,
                            indent, infoTab, self);

            /* end the sublist */
            ")";
        }
    }

    /*
     *   Show the collective count for the list of objects.  By default,
     *   we'll simply display the countName of the first item in the list,
     *   on the assumption that each object has the same plural
     *   description.  However, in most cases this should be overridden to
     *   provide a more general collective name for the group.
     */
    showGroupCountName(lst)
    {
        /* show the first item's countName */
        say(lst[1].countName(lst.length()));
    }

    /* we don't add a sublist, since we enclose our list in parentheses */
    groupDisplaysSublist = nil
;

/*
 *   List Group implementation: simple prefix/suffix lister.  Shows a
 *   prefix message, then shows the list, then shows a suffix message.
 *
 *   Note that this is a ListGroupSorted subclass.  If our subclass
 *   defines a compareGroupItems() method, we'll show the list in the
 *   order specified by compareGroupItems().
 */
class ListGroupPrefixSuffix: ListGroupSorted
    showGroupList(pov, lister, lst, options, indent, infoTab)
    {
        /* sort the list group, if we have an ordering method defined */
        lst = sortListGroup(lst);

        /* create a sub-lister for the group */
        lister = createGroupSublister(lister);

        /* show the prefix */
        showGroupPrefix(pov, lst);

        /* if we're in tall mode, start a new line */
        lister.showTallListNewline(options);

        /* show the list */
        lister.showList(pov, nil, lst, options & ~ListContents,
                        indent + 1, infoTab, self);

        /* show the suffix */
        showGroupSuffix(pov, lst);
    }

    /* show the prefix - we just show the groupPrefix message by default */
    showGroupPrefix(pov, lst) { groupPrefix; }

    /* show the suffix - we just show the groupSuffix message by default */
    showGroupSuffix(pov, lst) { groupSuffix; }

    /*
     *   The prefix and suffix messages.  The showGroupPrefix and
     *   showGroupSuffix methods simply show these message properties.  We
     *   go through this two-step procedure for convenience: if the
     *   subclass doesn't need the POV and list parameters, it's less
     *   typing to just override these parameterless properties.  If the
     *   subclass needs to vary the message according to the POV or what's
     *   in the list, it can override the showGroupXxx methods instead.
     */
    groupPrefix = ""
    groupSuffix = ""
;

/*
 *   Equivalent object list group.  This is the default listing group for
 *   equivalent items.  The Thing class creates an instance of this class
 *   during initialization for each set of equivalent items.
 */
class ListGroupEquivalent: ListGroup
    showGroupList(pov, lister, lst, options, indent, infoTab)
    {
        /* show a count of the items */
        lister.showListItemCounted(lst, options, pov, infoTab);
    }

    /*
     *   An equivalence group displays only a single noun phrase to cover
     *   the entire group.
     */
    groupNounPhraseCount(lister, lst) { return 1; }

    /* we display as a single item, so there's no sublist */
    groupDisplaysSublist = nil
;