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

Superclass Tree   (in declaration order)


Subclass Tree  


Global Objects  

aboardVehicleLister  darkRoomLister  equivalentStateLister  finishOptionsLister  fullScoreLister  otherExitLister  plainLister  roomLister 

Summary of Properties  


Summary of Methods  

contentsListed  contentsListedSeparately  getArrangedListCardinality  getArrangedListNounPhraseCount  getContents  getFilteredList  getListedContents  getListGrouping  getTopLister  isListed  listCardinality  listSepEnd  listSepMiddle  listSepTwo  listWith  longListSepEnd  longListSepMiddle  longListSepTwo  showArrangedList  showContentsList  showInlineContentsList  showList  showListAll  showListContentsPrefixTall  showListEmpty  showListIndent  showListItem  showListItemCounted  showListPrefixTall  showListPrefixWide  showListSeparator  showListSimple  showListSuffixWide  showSeparateContents  showTallListNewline 



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.


contentsListed (obj)lister.t[1088]

Are this item's contents listable?

contentsListedSeparately (obj)lister.t[1008]
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).

getArrangedListCardinality (singles, groups, groupTab)lister.t[769]
Get the cardinality of an arranged list. Returns the number of items that will appear in the list, for grammatical agreement.

getArrangedListNounPhraseCount (singles, groups, groupTab)lister.t[805]
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.

getContents (obj)lister.t[1093]
Get all contents of this item.

getFilteredList (lst, infoTab)lister.t[148]
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.

getListedContents (obj, infoTab)lister.t[1102]
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.

getListGrouping (groupTab, groups, singles, lst, parentGroup)lister.t[194]
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.

getTopLister ( )lister.t[1248]
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.

isListed (obj)lister.t[1076]
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.

listCardinality (obj)lister.t[1083]
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.

listSepEnd ( )lister.t[1240]
normal and long list separator between second-to-last and last items in a list with more than two items

listSepMiddle ( )lister.t[1233]
normal and long list separator between items in list with more than two items

listSepTwo ( )lister.t[1226]
normal and "long list" separator between the two items in a list with exactly two items

listWith (obj)lister.t[1119]
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.

longListSepEnd ( )lister.t[1241]
no description available

longListSepMiddle ( )lister.t[1234]
no description available

longListSepTwo ( )lister.t[1227]
no description available

showArrangedList (pov, parent, lst, options, indent, infoTab, itemCount, singles, groups, groupTab, origLst)lister.t[533]
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.

showContentsList (pov, obj, options, indent, infoTab)lister.t[985]
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.

showInlineContentsList (pov, obj, options, indent, infoTab)lister.t[1016]
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.

showList (pov, parent, lst, options, indent, infoTab, parentGroup)lister.t[95]
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.

showListAll (lst, options, indent)lister.t[38]
Show a list, showing all items in the list as though they were fully visible, regardless of their actual sense status.

showListContentsPrefixTall (itemCount, pov, parent)lister.t[1057]
Show the list prefix for the contents of an object in a 'tall' listing. By default, we just show our usual tall list prefix.

showListEmpty (pov, parent)lister.t[1067]
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").

showListIndent (options, indent)lister.t[874]
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.

showListItem (obj, options, pov, infoTab)lister.t[1122]
show an item in a list

showListItemCounted (lst, options, pov, infoTab)lister.t[1138]
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.

showListPrefixTall (itemCount, pov, parent)lister.t[1051]
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.

showListPrefixWide (itemCount, pov, parent, lst, :)lister.t[1038]
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.)

'lst' is the entire list, which some languages need for grammatical agreement. This is passed as a named argument, so an overrider can omit it from the parameter list if it's not needed.

This will never be called with an itemCount of zero, because we will instead use showListEmpty() to display an empty list.

showListSeparator (options, curItemNum, totalItems)lister.t[1161]
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.

showListSimple (pov, lst, options, indent, prevCnt, infoTab)lister.t[903]
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.

showListSuffixWide (itemCount, pov, parent)lister.t[1044]
show the suffix for a 'wide' listing - this is a message that appears just after we finish listing the objects

showSeparateContents (pov, lst, options, infoTab)lister.t[835]
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.

showTallListNewline (options)lister.t[888]
Show a newline after a list item if we're in a tall list; does nothing for a wide list.

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3