has

Documentation

Overview

Package has provides interfaces for Attributes. All interfaces defined in this package should use either standard Go types or other interfaces. This package should not import other packages, especially the attr package. This helps in avoiding cyclic imports.

For each interface defined in the has package there is usually a default implementation of it in the attr package with the same name. For example has.Inventory has the implementation attr.Inventory.

This package does not use the 'er' naming convention for interfaces such as Reader and Writer. It uses the actual attribute names such as Name and Description. This makes sense for WolfMUD when attributes are qualified with the has package name: has.Name, has.Description, has.Inventory.

Index

• type Alias
• type Attribute
• type Cleanup
• type Description
• type Door
• type Exits
• type Inventory
• type Locate
• type Marshaler
• type Name
• type Narrative
• type Player
• type PromptStyle
• type Reset
• type Start
• type Thing
• type Veto
• type Vetoes
• type Writing

Types

type Alias

type Alias interface {
	Attribute

	// HasAlias returns true if the alias passed is a valid alias, otherwise
	// false.
	HasAlias(alias string) (found bool)

	// Aliases returns all of the aliases as a []string or am empty slice if
	// there are no aliases.
	Aliases() []string
}

Alias provides aliases that can be used to refer to a Thing.

Its default implementation is the attr.Alias type.

type Attribute

type Attribute interface {
	Dump() []string

	// Attributes need to be able to marshal and unmarshal themselves. Marshaler
	// has no default implementation and should be implemented by each Attribute.
	Marshaler

	// Found returns false if the receiver is nil otherwise true. Found has no
	// default implementation and should be implemented by each Attribute as it
	// is based on the receiver type.
	Found() bool

	// Parent returns the Thing to which the Attribute has been added.
	Parent() Thing

	// SetParent sets the Thing to which the Attribute has been added.
	SetParent(Thing)

	// Copy produces another, possibly inexact, instance of an Attribute. The
	// differences may be due to unique IDs, locks and other data that should not
	// be copied between instances.
	//
	// NOTE: The default implementation attr.Attribute does NOT implement Copy.
	// See main interface comments and attr.Attribute.
	Copy() Attribute

	// Free releases resources used by an attribute. It main use is to
	// disentangle cyclic pointers to assist in garbage collection. Attributes
	// that implement their own Free method should also call Attribute.Free.
	Free()
}

Attribute provides a minimal, common interface for implementing any type of Attribute. The interface provides a way for an Attribute to associate itself with the parent Thing it is being added to - or disassociate if removed. This allows any Attribute to access its parent Thing or other Attribute associated with the parent Thing.

Its default implementation is the attr.Attribute type. For the different attributes available see the attr package.

NOTE: the default implementation attr.Attribute does NOT provide a default Copy implementation. Each attribute must implement its own Copy method. This is due to the fact that other attributes will know best how to create copies based on their own implementation.

type Cleanup

type Cleanup interface {
	Attribute

	// Cleanup causes the parent Thing to be scheduled for clean up.
	Cleanup()

	// Abort cancels any outstanding clean up events.
	Abort()

	// Active returns true if any of the Inventories the parent Thing is in
	// already have a clean up scheduled, otherwise false.
	Active() bool
}

Cleanup provides information on how often a Thing should be cleaned up when left laying around.

The default implementation is the attr.Cleanup type.

type Description

type Description interface {
	Attribute

	// Description returns the descriptive text for the attribute.
	Description() string
}

Description provides descriptive text for a Thing.

Its default implementation is the attr.Description type.

type Door

type Door interface {
	Attribute

	// Open is used to change the state of a Door to open.
	Open()

	// Opened returns true if the state of a Door is open, otherwise false.
	Opened() bool

	// Close is used to change the state of a Door to closed.
	Close()

	// Closed returns true if the state of a Door is closed, otherwise false.
	Closed() bool

	// Direction returns the direction the door is blocking when closed. The
	// return values match the constants defined in attr.Exits.
	Direction() byte

	// OtherSide creates the opposing side of a Door.
	OtherSide()
}

Door provides a way of blocking travel in a specified direction when closed. A Door can also be used to implement door-like items such as a gate, a panel or a bookcase.

Its default implementation is the attr.Door type.

type Exits

type Exits interface {
	Attribute

	// AutoLink links two opposing exits. Autolink links the passed Inventory to
	// the receiver's exit for the given direction. It then links the passed
	// Inventory's Exits to the receiver's Inventory in the opposite direction.
	AutoLink(direction byte, to Inventory)

	// AutoUnlink unlinks two opposing exits. Autounlink unlinks the receiver's
	// exit for the given direction. It then unlinks the passed Inventory's Exits
	// in the opposite direction.
	AutoUnlink(direction byte)

	// LeadsTo returns the Inventory of the location reached by taking the exit
	// in the given direction. If the exit does not leads nowhere nil returned.
	LeadsTo(direction byte) Inventory

	// Link links the receiver's exit for the given direction to the passed
	// Inventory.
	Link(direction byte, to Inventory)

	// List returns a string describing the exits available for the receiver.
	List() string

	// NormalizeDirection takes a direction name such as 'North', 'north',
	// 'NoRtH' or 'N' and returns the direction's index. If the name cannot be
	// normalized a non-nil error will be returned.
	NormalizeDirection(name string) (byte, error)

	// Surrounding returns a slice of Inventory, one Inventory for each location
	// reachable via the receiver's Exits. If no locations are reachable an empty
	// slice is returned.
	Surrounding() []Inventory

	// ToName takes a direction index and returns the long lowercased name such
	// as 'north' or 'northwest'.
	ToName(direction byte) string

	// Unlink unlinks the Inventory from the receiver for the given direction.
	Unlink(direction byte)

	// Within returns all location Inventories within the given number of moves
	// from the receiver's location. The inventories are returned as a slice of
	// Inventory slices. The first slice is the number of moves from the current
	// location. The second slice is a list of the Inventory reachable for that
	// number of moves.
	Within(moves int) [][]Inventory
}

Exits coordinate linkages and movement between location Inventory attributes.

Its default implementation is the attr.Exits type.

type Inventory

type Inventory interface {
	Attribute
	sync.Locker

	// Add puts a Thing into the Inventory. On success Add will return the Thing
	// that was actually added to the Inventory which may be a copy of the passed
	// Thing. On failure Add returns nil.
	Add(Thing) Thing

	// Contents returns a []Thing representing the contents of the Inventory.
	Contents() []Thing

	// Narratives returns a []Thing representing the narratives of the Inventory.
	Narratives() []Thing

	// Crowded returns true if the Inventory is considered crowded otherwise
	// false. Definition of crowded is implementation dependant.
	Crowded() bool

	// Empty returns true if the Inventory is empty else false. What empty means
	// is up to the individual Inventory implementation. It may mean that the
	// Inventory is really empty or it may mean that there is nothing available
	// to be removed for example.
	Empty() bool

	// List returns a textual description of the Inventory content.
	List() string

	// LockID returns the unique locking ID for an Inventory.
	LockID() uint64

	// Remove takes a Thing out of the Inventory. On success Remove will return
	// the Thing that was actually removed from the Inventory which may be a copy
	// of the passed Thing. On failure Remove returns nil.
	Remove(Thing) Thing

	// Search returns the first Thing in an Inventory that has a matching Alias.
	// If there are no matches nil is returned.
	Search(alias string) Thing

	// Move removes a Thing from the receiver Inventory and places it into the
	// passed Inventory. On success Move will return the Thing that was actually
	// moved which may be a copy of the passed Thing. On failure Move returns
	// nil.
	Move(Thing, Inventory) Thing

	// Carried return true if putting an item in an Inventory results in it being
	// carried by a player, otherwise false.
	Carried() bool
}

Inventory are used to implement containers that can contain any type of Thing.

Its default implementation is the attr.Inventory type.

type Locate

type Locate interface {
	Attribute

	// Origin returns the initial starting Inventory that a Thing is placed into.
	Origin() Inventory

	// SetOrigin is used to specify the initial starting Inventory that a Thing
	// is placed into.
	SetOrigin(Inventory)

	// SetWhere is used to set the current Inventory.
	SetWhere(Inventory)

	// Where returns the Inventory currently set.
	Where() Inventory
}

Locate is used by any Thing that needs to know where it is. Locate has a reference to the Inventory that contains the parent Thing of this attribute. When using the default attr.Inventory type this reference is kept up to date automatically as the Thing is moved from Inventory to Inventory. Remember: A location in WolfMUD can be any Thing with an Inventory Attribute, not just conventional 'rooms'.

Its default implementation is the attr.Locate type.

type Marshaler

type Marshaler interface {

	// Unmarshal takes the []byte and returns an Attribute for the []byte data.
	// If the returned Attribute is an untyped nil it should be ignored.
	Unmarshal([]byte) Attribute

	// Marshaler takes the Attribute and returns a []byte that represents the
	// Attribute.
	Marshal(Attribute) []byte
}

Marshaler provides the ability to marshal and unmarshal fields for a .wrj (WolfMUD Record Jar) file to and from Attributes. It should be implemnted by all Attribute types.

type Name

type Name interface {
	Attribute

	// Name returns the short name for a Thing. If the name cannot be returned
	// the preset can be used as a default.
	Name(preset string) string
}

Name provides a short textual name for a Thing. Short names are usually of the form 'a bag', 'an apple', 'some rocks'.

Its default implementation is the attr.Name type.

type Narrative

type Narrative interface {
	Attribute

	// ImplementsNarrative is a marker until we have a fuller implementation of
	// Narrative and we don't accidentally fulfil another interface.
	ImplementsNarrative()
}

Narrative is used to mark a Thing as being for narrative purposes. Any Thing can be a Narrative by adding a Narrative attribute.

Its default implementation is the attr.Narrative type.

type Player

type Player interface {
	Attribute

	// Player should implement a standard Write method to send data back to the
	// associated client.
	io.Writer

	// SetPromptStyle is used to set the current prompt style and returns the
	// previous prompt style. This is so the previous prompt style can be
	// restored if required later on.
	SetPromptStyle(new PromptStyle) (old PromptStyle)
}

Player is used to represent an actual player.

Its default implementation is the attr.Player type.

type PromptStyle

type PromptStyle int

const (
	StyleNone PromptStyle = iota
	StyleBrief
	StyleShort
	StyleLong
)

type Reset

type Reset interface {
	Attribute

	// Reset causes the parent Thing to be scheduled for a reset.
	Reset()

	// Spawn returns a non-spawnable copy of the parent Thing and schedules the
	// original to be respawned.
	Spawn() Thing
}

Reset provides information on how often a Thing should reset and whether the Thing is respawned when picked up or not.

The default implementation is the attr.Reset type.

type Start

type Start interface {
	Attribute

	// Pick returns an Inventory for a starting location. The location is picked
	// at random from all of the registered starting locations.
	Pick() Inventory
}

Start is used to mark a Thing as being a starting location.

Its default implementation is the attr.Start type.

type Thing

type Thing interface {

	// Add is used to add one or more Attribute to a Thing.
	Add(...Attribute)

	// Attrs returns a []Attribute of all the Attribute for a Thing.
	Attrs() []Attribute

	Dump() []string

	// Remove is used to remove one or more Attribute from a Thing.
	Remove(...Attribute)

	// Free is used to clean-up/release references to all Attribute for a Thing.
	Free()

	// Copy produces another, possibly inexact, instance of a Thing. The
	// differences may be due to unique IDs, locks and other data that should not
	// be copied between instances. The copy will contain a copy of all of the
	// attributes and possibly other Things associated with the Thing as well.
	Copy() Thing

	// SetOrigins updates the origin for the Thing to its containing Inventory and
	// recursivly sets the origins for the content of a Thing's Inventory if it has
	// one.
	SetOrigins()

	// Dispose will either reset or discard a Thing when it is finished with.
	Dispose()

	// UID returns the unique identifier for a Thing or an empty string if the
	// unique ID is unavailable.
	UID() string
}

Thing is used to create everything and anything in a WolfMUD world. In WolfMUD everything is created by creating a Thing and adding Attributes to it. Attribute define the behaviour and characteristics of specific Things. Attributes may be added and removed at runtime to dynamically affect a Thing.

Its default implementation is the attr.Thing type. For the different attributes available see the attr package.

type Veto

type Veto interface {

	// Command returns the command as an uppercased string that this Veto is for.
	Command() string

	Dump() []string

	// Message returns the details of why the associated command was vetoed.
	Message() string
}

Veto provides a way for a specific command to be vetoed for a specific Thing. Each Veto can veto a single command and provide a message detailing why the command was vetoed. Veto should be added to a Vetoes attribute for a Thing.

Its default implementation is the attr.Veto type.

type Vetoes

type Vetoes interface {
	Attribute

	// Check compares the passed commands with any registered Veto commands.
	// If a command for a Thing is vetoed the first matching Veto found is
	// returned. If no matching Veto are found nil is returned.
	Check(cmd ...string) Veto
}

Vetoes represent one or more Veto allowing commands to be vetoed for a Thing. Multiple Veto can be added to veto multiple commands for different reasons.

Its default implementation is the attr.Vetoes type.

type Writing

type Writing interface {
	Attribute

	// Writing returns the text for what has been written.
	Writing() string
}

Writing allows text to be added to any Thing that can then be read to reveal what is written.

Its default implementation is the attr.Writing type.