Class: GeneralInventory

.Inventory~ GeneralInventory

The GeneralInventory is the base class from which all other types of Inventory are derived. It can contain any type of PersistentObject (or subclass thereof), and the contents are sorted alphabetically based on their .name fields.


new GeneralInventory(id)

You should never instantiate a PersistentObject directly! Instead, you must define it with PersistentObject.define(), and then instantiate it with the obj() function when you want to use it. You must also never store PersistentObjects in Sugarcube variables! Just store their ids, instantiate them with obj() as needed, and then let them be garbage-collected.

Parameters:
Name Type Description
id string

The id of the Persistence defaults entry to be associated with this instance.

Source:

Extends

Members


<readonly> id :string

The Persistence id of the object.

Most of the time you'll only be interacting with the Persistence id when you define your object at initialization time in PersistentObject.define(), and when you fetch it with obj(). This field is generally only used internally by derived classes. You probably won't need to use this field unless you are actually extending the library itself.

Type:
  • string
Inherited From:
Overrides:
Source:

<readonly> parent :LibEcho.Persistence.PersistentObject

The fully instantiated parent of this object, or undefined if it is a toplevel object (has no parent).

This field is generally only used internally by derived classes. You probably won't need to use this field unless you are actually extending the library itself.

Type:
Inherited From:
Overrides:
Source:

name :string

The display name of the object, without any article. For example: "Joe", "ancient relic", "pair of gloves". Will be undefined if the object has no name.

Type:
  • string
Inherited From:
Overrides:
Source:
Example
var someDude = obj("joe");
alert( "someDude's name is " + someDude.name + "." );

<readonly> aName :string

The display name of the object, with the correct article prepended. For example: "Joe", "an ancient relic", "a pair of gloves". Will be undefined if the object has no name.

If the first character of the .name field is capitalized, the name will be treated as proper, and no article will be prepended. Ie. "Joe". Otherwise, if the first character of the .name field is a vowel, the "an" article will be prepended. Ie. "an ancient relic". Otherwise, the "a" article will be prepended. Ie. "a pair of gloves".

These rules do not always work. For example, "an honorable man" or "a European swallow". In these cases, the .nameIsProper and .nameIrregularArticle fields may be used to manually specify the behavior of this field.

Type:
  • string
Inherited From:
Overrides:
Source:
Example
alert( "You are carrying " + obj("some_item").aName + "." );

<readonly> AName :string

Identical to .aName, but with the first character capitalized.

Type:
  • string
Inherited From:
Overrides:
Source:

<readonly> aGenericName :string

Same as .aName, but operates on the genericName instead.

Type:
  • string
Inherited From:
Overrides:
Source:

<readonly> AGenericName :string

Same as .AName, but operates on the genericName instead.

Type:
  • string
Inherited From:
Overrides:
Source:

<readonly> theName :string

The display name of the object, with the "the" prepended unless the object is proper. For example: "Joe", "the ancient relic", "the pair of gloves". Will be undefined if the object has no name.

These rules do not always work. For example, "the European swallow". In this case, the .nameIsProper field may be used to manually specify the behavior of this field.

Type:
  • string
Inherited From:
Overrides:
Source:
Example
alert( "You place " + obj("some_item").theName + " in the large box." );

<readonly> TheName :string

Identical to .theName, but with the first character capitalized.

Type:
  • string
Inherited From:
Overrides:
Source:

<readonly> theGenericName :string

Same as .theName, but operates on the genericName instead.

Type:
  • string
Inherited From:
Overrides:
Source:

<readonly> TheGenericName :string

Same as .TheName, but operates on the genericName instead.

Type:
  • string
Inherited From:
Overrides:
Source:

nameIsProper :boolean

Set this field to True to suppress the printing of an article in the .aName and .theName fields. Useful for proper names, book titles, etc.

You'll generally want to set this field with Persistence.define(), and then never touch it again. The only time you may need to change this field at runtime is if you change something's name to something that doesn't work with the usual rules.

Type:
  • boolean
Inherited From:
Overrides:
Source:
Example
var book = obj("atlas_shrugged");
// book.name is "\"Atlas Shrugged\" (a novel by Ayn Rand)"
// With the " being the first character, it won't be recognized as proper.
// So .aName will return: a "Atlas Shrugged" (a novel by Ayn Rand).
book.nameIsProper = true;
// Now .aName will properly return just: "Atlas Shrugged" (a novel by Ayn Rand).

nameIrregularArticle :string

Set this field to override the default article choice in .aName. Setting it back to null will return things back to normal.

You'll generally want to set this field with Persistence.define(), and then never touch it again. The only time you may need to change this field at runtime is if you change something's name to something that doesn't work with the usual rules.

Type:
  • string
Inherited From:
Overrides:
Source:
Example
obj("honorable_man").nameIrregularArticle = "an";
obj("european_swallow").nameIrregularArticle = "a";

genericNameIsProper :boolean

Same as .nameIsProper, but operates on the genericName instead.

Type:
  • boolean
Inherited From:
Overrides:
Source:

genericNameIrregularArticle :string

Same as .nameIrregularArticle, but operates on the genericName instead.

Type:
  • string
Inherited From:
Overrides:
Source:

thumbnail :string

A thumbnail image name for the object (used in inventory displays). If a thumbnail image is not defined, it returns the value of .image instead.

FIXME Make this work with external images instead of just image passages.

Type:
  • string
Inherited From:
Overrides:
Source:
Example
FIXME Add an example.

image :string

A detail image name for the object (used in object details displays).

FIXME Make this work with external images instead of just image passages.

Type:
  • string
Inherited From:
Overrides:
Source:
Example
FIXME Add an example.

inventoryCategory :string

The inventory category of this object. Used for inventory sorting. Case-sensitive. If falsy, then category is assumed to be "Other".

Type:
  • string
Inherited From:
Overrides:
Source:
Example
FIXME Add an example.

Methods


add(itemOrId, runPre, runPost)

This method adds the given itemOrId to the Inventory. It does not remove it from any other inventories that might also contain it. itemOrId may be a Persistence id string, or a fully instantiated PersistentObject (or subclass thereof).

Parameters:
Name Type Description
itemOrId string

the thing to be added to the Inventory.

runPre string

if false, preAdd() is skipped and the thing is forcibly added.

runPost string

if false, postAdd() is skipped.

Source:
Throws:

Error if itemOrId is invalid or malformed, or if the preAdd() callback does not return a proper Boolean value.

Returns:

False if the itemOrId could not be added (due to preAdd returning false), or if the add was successful then an array containing any objects that might have been removed from this Inventory to 'make room' for the added object (via postAdd), or undefined if runPost was false and postAdd() was not run.

Example
obj("joe").inventory.add( "some_widget" );

remove(itemOrId, runPre, runPost)

This method removes the given itemOrId from the Inventory. itemOrId may be a Persistence id string, or a fully instantiated PersistentObject (or subclass thereof).

Parameters:
Name Type Description
itemOrId string

the thing to be removed from the Inventory.

runPre string

if false, preRemove() is skipped and the thing is forcibly removed.

runPost string

if false, postRemove() is skipped.

Source:
Throws:

Error if itemOrId is invalid or malformed, or if the preRemove() callback does not return a proper Boolean value.

Returns:

@returns False if the itemOrId could not be removed (due to preRemove returning false), or if the remove was successful then an array containing any objects that might have been added to this Inventory via postRemove(), or undefined if runPost was false and postRemove() was not run.

Example
obj("joe").inventory.remove( "some_widget" );

has(itemOrId)

This method checks to see if the Inventory contains the given itemOrId. itemOrId may be a Persistence id string, or a fully instantiated PersistentObject (or subclass thereof).

Parameters:
Name Type Description
itemOrId string

the thing to be checked for in the Inventory.

Source:
Throws:

Error if itemOrId is invalid or malformed.

Returns:

True if the Inventory contains the specified thing, or False if not.

Type
boolean
Example
if( obj("joe").inventory.has("some_widget") )
	alert( "Joe has a widget!" );

isEmpty()

FIXME

Source:

contents(filterClass, filterFunction, returnIds)

Returns the fully-instantiated contents of the Inventory.

If a class is passed to filterClass, only items that are of that class (or a subclass thereof) will be included in the returned array.

If a function is passed to filterFunction, that function will be called once for every item in the inventory. If this function returns true, the item will be included in the returned array. If the function returns false, the item will not be included.

Parameters:
Name Type Description
filterClass Class

a filter class.

filterFunction function

a filter function.

returnIds boolean

if true, ids are returned instead of fully instantiated objects.

Source:
Throws:

Error if itemOrId is invalid or malformed.

Returns:

An array containing the fully instantiated contents of the inventory, less those filtered out. Or an array of ids, if returnIds is true.

Type
Array.<LibEcho.Persistence.PersistentObject>
Example
FIXME add example

toString()

Overridden.

Overrides:
Source:
Returns:

a serial-comma-separated-list of the Inventory's contents' .aName fields.

Type
string

theString()

Like toString(), but using .theName instead.

Source:
Returns:

a serial-comma-separated-list of the Inventory's contents' .theName fields.

Type
string

sort(a, b)

This is the function used by .get() to sort the Inventory. It follows the rules of Javascript's (Array).sort(). The default implementation sorts alphabetically, ignoring case.

This function is generally only used by derived classes that need to sort the Inventory differently. Unless you are extending the library, you'll probably never need to use it.

Parameters:
Name Type Description
a LibEcho.Persistence.PersistentObject

a thing in the Inventory.

b LibEcho.Persistence.PersistentObject

another thing in the Inventory.

Source:
Returns:

<0 if a<b, >0 if a>b, or 0 if a==b.

Type
number

preAdd(id)

This callback method is called before id is added to the Inventory. Returning True allows the add to continue, while False will cancel it.

This method is meant to be overridden by derived classes that can only contain certain sorts of things or exhibit special behaviors. Unless you are extending the library, you'll probably never need to use this method.

Parameters:
Name Type Description
id string

the Persistence id of the thing being added to the Inventory.

Source:
Returns:

True to allow the item to be added, False to deny it.

Type
boolean

postAdd(id)

This callback method is called after id has been added to the Inventory.

This method is meant to be overridden by derived classes that can only contain certain sorts of things or exhibit special behaviors. Unless you are extending the library, you'll probably never need to use this method.

Parameters:
Name Type Description
id string

the Persistence id of the thing that was added to the Inventory.

Source:
Returns:

A list of any objects that might have been removed from this Inventory to 'make room' for the new one (GeneralInventory always returns []).


preRemove(id)

This callback method is called before id is removed from the Inventory. Returning True allows the removal to continue, while False will cancel it.

This method is meant to be overridden by derived classes that can only contain certain sorts of things or exhibit special behaviors. Unless you are extending the library, you'll probably never need to use this method.

Parameters:
Name Type Description
id string

the Persistence id of the thing being removed from the Inventory.

Source:
Returns:

True to allow the item to be removed, False to deny it.

Type
boolean

postRemove(id)

This callback method is called after id has been removed from the Inventory.

This method is meant to be overridden by derived classes that can only contain certain sorts of things or exhibit special behaviors. Unless you are extending the library, you'll probably never need to use this method.

Parameters:
Name Type Description
id string

the Persistence id of the thing that was removed from the Inventory.

Source:
Returns:

A list of any objects that might have been added to this Inventory during the execution of this method (GeneralInventory always returns []).