spunQ_SetType Class Reference

The set type. More...

Inheritance diagram for spunQ_SetType:

List of all members.

Public Member Functions

__construct (spunQ_Type $parameterType)

Constructor.

getKeyType ()

The key type of this collection.

getValueType ()

The value type of this collection.

getParameterType ()

Gets its parameter type.

getName ()

Overridden to generate the name on demand.

check ($value, spunQ_Map $options=NULL, $throwException=true)

Checks if a value is of the type described by this object.

__sleep ()

Replaces $parameterType with its string representation.

getDocumentation ()

Gets the documentation for this type.

getOptions ()

Gets the type options for this type.

__call ($functionName, $arguments)

Overloaded to provide automatic getters and setters.

_verifyMembers ($omittedMembers=array(), $throwException=true)

Verifies that all members are valid.

_getMember ($name)

Gets the value of a member of this object.

_setMember ($name, $value)

Sets the value of a member of this object.

_getType ($throwException=true)

Gets the type of this object.

Static Public Member Functions

static get (spunQ_Type $parameterType)

This factory method will reuse set types with the same parameter type.

static getByName ($string)

Overridden to only provide access to set types.

static stringDescribesSet ($string)

Whether a given string describes a set.

static extractParameterDescriptor ($string)

Returns the type description of the set parameter.

static stringDescribesCollection ($string)

static extractKeyOptions (spunQ_Map $options)

Extracts options for the key type.

static extractValueOptions (spunQ_Map $options)

Extracts options for the key type.

static convertToKeyOptions (spunQ_Map $options)

Prepends the string 'key.

static convertToValueOptions (spunQ_Map $options)

Prepends the string 'value.

static prependKey ($string)

Prepends the string 'key.

static prependValue ($string)

Prepends the string 'value.

static stringDescribesBuiltinType ($string)

Whether a given string is a type description for a builtin type.

static stringDescribesType ($string)

Checks whether a string is a valid type descriptor.

static getDescription ($value)

Returns the most appropriate textual representation of a value.

static getCommonDescription (array $values)

Finds the most suiting string description for multiple values.

static valueByProperty ($value, $path)

Transforms a value using a property path.

static propertyOfValue ($value, $property)

Gets a single property of a value.

Public Attributes

const SET_REGEX = '/^\h*set\h*<(.+)\h*>\h*$/'

The regex that will match set descriptions.

Protected Member Functions

handleGetUntranslated ($memberName, $arguments, $functionName)

Needed by __call().

handleGet ($memberName, $arguments, $functionName)

Needed by __call().

initLocalizedMember ($memberName)

Makes sure a localized member contains a spunQ_Map.

handleGetFromArray ($memberName, $arguments, $functionName)

Needed by __call().

handleSet ($memberName, $arguments, $functionName)

Needed by __call().

handleAdd ($memberName, $arguments, $functionName)

Needed by __call().

handleRemove ($memberName, $arguments, $functionName)

Needed by __call().

Protected Attributes

$parameterType

The type of the parameter of this set type.

$name

The name of this type.

$documentation

Documentation of this type as extracted from its doc comments.

$options

Additional options for this member.

$_type

The actual type of this object.

Static Protected Attributes

static $typeInstance = NULL

The one instance of this class that will describe all other instances.

Static Private Attributes

static $objectCache

Cache mapping user types to spunQ_SetType objects.

Detailed Description

The set type.

The only difference between the set type and the array type is currently merely a semantic one. Sets don't have an index.

See also:: spunQ_ArrayType

Definition at line 9 of file SetType.class.php.

Constructor & Destructor Documentation

spunQ_SetType::__construct ( spunQ_Type $ parameterType )

Constructor.

Parameters:

$parameterType

The parameter type of this type.

Definition at line 82 of file SetType.class.php.

Member Function Documentation

spunQ_DataObject::__call	(	$	functionName,
		$	arguments
	)			`[inherited]`

Overloaded to provide automatic getters and setters.

Parameters:

	$functionName	The function that was called.
	$arguments	Array containing the arguments that were passed to the function.

Exceptions:

spunQ_BadArgumentCountError

Definition at line 148 of file DataObject.type.php.

spunQ_SetType::__sleep ( )

Replaces $parameterType with its string representation.

Returns:: array<string> The members to export.

Reimplemented from spunQ_DataObject.

Definition at line 153 of file SetType.class.php.

spunQ_DataObject::_getMember ( $ name ) [inherited]

Gets the value of a member of this object.

Will check if the object has a getter for the member and will use that method for getting the value. Otherwise, the value of the object member is returned.

Parameters:

$name

The name of the member.

Returns:: any Whatever type the member has.

Definition at line 478 of file DataObject.type.php.

spunQ_DataObject::_getType ( $ throwException = true ) [inherited]

Gets the type of this object.

Returns:: spunQ_Type

Definition at line 507 of file DataObject.type.php.

spunQ_DataObject::_setMember	(	$	name,
		$	value
	)			`[inherited]`

Sets the value of a member of this object.

Will check if the object has a setter for the member and will use that method for setting the value. Otherwise, the object member is set directly.

Parameters:

	$name	The name of the member.
	$value	The value to set it to.

Returns:: spunQ_DataObject $this

Definition at line 495 of file DataObject.type.php.

spunQ_DataObject::_verifyMembers	(	$	omittedMembers = `array()`,
		$	throwException = `true`
	)			`[inherited]`

Verifies that all members are valid.

This function is called from various modules prior to critical actions requiring a complete object - like inserting into a database.

Parameters:

	$omittedMembers	Do not perform checks on these member names.
	$throwException	Whether an exception should be thrown if a member does not have a valid value.

Returns:: boolean

Exceptions:

spunQ_IllegalValueException

Definition at line 458 of file DataObject.type.php.

spunQ_SetType::check	(	$	value,
		spunQ_Map $	options = `NULL`,
		$	throwException = `true`
	)

Checks if a value is of the type described by this object.

Parameters:

	$value	The value to check
	$options	The type options to consider.
	$throwException	Whether an exception should be thrown if the type of the value differs.

Returns:: boolean Whether $value is of the type described by this object.

Exceptions:

spunQ_IllegalValueException

Reimplemented from spunQ_Type.

Definition at line 127 of file SetType.class.php.

static spunQ_CollectionType::convertToKeyOptions ( spunQ_Map $ options ) [static, inherited]

Prepends the string 'key.

' to all keys.

Parameters:

$options

An options map as explained by the docs of spunQ_Type.

Returns:: spunQ_Map A new options map.

Definition at line 45 of file CollectionType.class.php.

static spunQ_CollectionType::convertToValueOptions ( spunQ_Map $ options ) [static, inherited]

Prepends the string 'value.

' to all keys.

Parameters:

$options

An options map as explained by the docs of spunQ_Type.

Returns:: spunQ_Map A new options map.

Definition at line 59 of file CollectionType.class.php.

static spunQ_CollectionType::extractKeyOptions ( spunQ_Map $ options ) [static, inherited]

Extracts options for the key type.

Parameters:

$options

An options map as explained by the docs of spunQ_Type.

Returns:: spunQ_Map A new options map containing only keys that started with the string 'key.'.

Definition at line 18 of file CollectionType.class.php.

static spunQ_SetType::extractParameterDescriptor ( $ string ) [static]

Returns the type description of the set parameter.

Parameters:

$string

The string to extract type parameter description from.

Returns:: string

Exceptions:

spunQ_IllegalTypeDescriptorException

If the string does not describe a set.

Definition at line 63 of file SetType.class.php.

static spunQ_CollectionType::extractValueOptions ( spunQ_Map $ options ) [static, inherited]

Extracts options for the key type.

Parameters:

$options

An options map as explained by the docs of spunQ_Type.

Returns:: spunQ_Map A new options map containing only keys that started with the string 'value.'.

Definition at line 32 of file CollectionType.class.php.

static spunQ_SetType::get ( spunQ_Type $ parameterType ) [static]

This factory method will reuse set types with the same parameter type.

The created objects are all stored in the $objectCache for reuse.

Parameters:

$parameterType

The parameter type to get the spunQ_SetType for.

Returns:: spunQ_SetType

Definition at line 30 of file SetType.class.php.

static spunQ_Type::getCommonDescription ( array $ values ) [static, inherited]

Finds the most suiting string description for multiple values.

Parameters:

$values

The values to find string description for.

Returns:: string

Definition at line 373 of file Type.type.php.

static spunQ_Type::getDescription ( $ value ) [static, inherited]

Returns the most appropriate textual representation of a value.

Can be used to provide useful information about a value when debugging:

spunQ.DataObjects will be translated using their type names.
spunQ.Type will be translated using their names.
Normal objects will be translated to their class names.
arrays and maps will have their parameter types found recursively, substituting 'any' for undefined types (map<string,any>).
any other type is translated using gettype()

Parameters:

$value

The value to describe as a string.

Returns:: string

Definition at line 343 of file Type.type.php.

spunQ_Type::getDocumentation ( ) [inherited]

Gets the documentation for this type.

Returns:: string

Definition at line 458 of file Type.type.php.

spunQ_SetType::getKeyType ( )

The key type of this collection.

Use spunQ_IntegerType for numeric indexes.

Returns:: spunQ_Type

Reimplemented from spunQ_CollectionType.

Definition at line 92 of file SetType.class.php.

spunQ_Type::getOptions ( ) [inherited]

Gets the type options for this type.

Returns:: map<string,array<string>>

Definition at line 466 of file Type.type.php.

spunQ_SetType::getParameterType ( )

Gets its parameter type.

Returns:: spunQ_Type

Definition at line 107 of file SetType.class.php.

spunQ_SetType::getValueType ( )

The value type of this collection.

Returns:: spunQ_Type

Reimplemented from spunQ_CollectionType.

Definition at line 99 of file SetType.class.php.

spunQ_DataObject::handleAdd	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'add'.

Parameters:

	$memberName	The name of the member that is possibly being appended to. Merely the name of the function without the leading 'add', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: spunQ_DataObject $this

Exceptions:

	spunQ_BadArgumentCountError
	spunQ_InvalidArgumentError

Reimplemented in spunQ_StorableObject.

Definition at line 327 of file DataObject.type.php.

spunQ_DataObject::handleGet	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'get'.

Todo:: spunQ_CollectionType instead of spunQ_ArrayType(?)

Parameters:

	$memberName	The name of the member that was possibly requested. Merely the name of the function without the leading 'get', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The name of the function that was called.

Returns:: any Whatever type the member has.

Reimplemented in spunQ_StorableObject.

Definition at line 217 of file DataObject.type.php.

spunQ_DataObject::handleGetFromArray	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of getter functions, where the member has an array type.

See also:: handleGet()

Parameters:

	$memberName	The name of the member that was possibly requested. Merely the name of the function without the leading 'set', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: array

Reimplemented in spunQ_StorableObject.

Definition at line 264 of file DataObject.type.php.

spunQ_DataObject::handleGetUntranslated	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of functions requesting all translations available for a member.

Parameters:

	$memberName	The name of the member that was possibly requested.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The name of the function that was called.

Returns:: map<spunQ_Locale,any> Mapping locales to whatever type the member has. Note that not every locale needs to be present in this map.

Reimplemented in spunQ_StorableObject.

Definition at line 198 of file DataObject.type.php.

spunQ_DataObject::handleRemove	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'remove'.

Parameters:

	$memberName	The name of the member that is possibly being removed from. Merely the name of the function without the leading 'remove', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: spunQ_DataObject $this

Exceptions:

	spunQ_BadArgumentCountError
	spunQ_InvalidArgumentError

Reimplemented in spunQ_StorableObject.

Definition at line 399 of file DataObject.type.php.

spunQ_DataObject::handleSet	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'set'.

Parameters:

	$memberName	The name of the member that is possibly being set. Merely the name of the function without the leading 'set', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: spunQ_DataObject $this

Reimplemented in spunQ_StorableObject.

Definition at line 292 of file DataObject.type.php.

spunQ_DataObject::initLocalizedMember ( $ memberName ) [protected, inherited]

Makes sure a localized member contains a spunQ_Map.

Parameters:

$memberName The name of the member. This member must have the option 'localized'.

Returns:: void

Definition at line 245 of file DataObject.type.php.

static spunQ_CollectionType::prependKey ( $ string ) [static, inherited]

Prepends the string 'key.

' to a string. Required as a callback fucntion in convertToKeyOptions().

Parameters:

$string

The string to prepend.

Returns:: string

Definition at line 74 of file CollectionType.class.php.

static spunQ_CollectionType::prependValue ( $ string ) [static, inherited]

Prepends the string 'value.

' to a string. Required as a callback fucntion in convertToValueOptions().

Parameters:

$string

The string to prepend.

Returns:: string

Definition at line 84 of file CollectionType.class.php.

static spunQ_DataObject::propertyOfValue	(	$	value,
		$	property
	)			`[static, inherited]`

Gets a single property of a value.

See also:: valueByProperty()

Parameters:

	$value	The value to fetch property for.
	$property	The property to fetch.

Returns:: any

Definition at line 74 of file DataObject.type.php.

static spunQ_BuiltinType::stringDescribesBuiltinType ( $ string ) [static, inherited]

Whether a given string is a type description for a builtin type.

Parameters:

$string

The string to analyze.

Returns:: boolean

Definition at line 30 of file BuiltinType.class.php.

static spunQ_SetType::stringDescribesSet ( $ string ) [static]

Whether a given string describes a set.

Parameters:

$string

The set-descriptor wannabe.

Returns:: bool

Definition at line 52 of file SetType.class.php.

static spunQ_Type::stringDescribesType ( $ string ) [static, inherited]

Checks whether a string is a valid type descriptor.

Parameters:

$string

The string to check

Returns:: boolean

Definition at line 298 of file Type.type.php.

static spunQ_DataObject::valueByProperty	(	$	value,
		$	path
	)			`[static, inherited]`

Transforms a value using a property path.

Some types are considered to have properties within spunQ. These properties can be referred to using property path definitions. The most simple case for properties is the user type, for which every member is considered a property. Concatenations of these paths with dots as separators are called property path. The list of all users in the primary group of a given user can be described using this method in a string: 'primaryGroup.users'.
Different types have different properties:

UserType: As already mentioned, every member of a user type is a property of an object of that type.
Map:
- _keys: An array of the keys of the map.
- _values: An array of the values of the map. Note that _keys and _values are guaranteed to return arrays where the index of a key matches the index of its value in the according result.
- _key: The first entry of the _keys property. This is handy for referencing the key of single key/value pairs.
- _value: The first entry of the _values property.
- _count: The amount of items in the map.
Array:
- _keys: The array of keys of the array. Note that the difference between arrays and maps in spunQ is that arrays are always numerically indexed! So this will always return an array containing a range of integers.
- _values: Array of values in this array. This essentially returns the array as-is and is a NOOP.
- _key: The first entry of the _keys property.
- _value: The first entry of the _values property.
- _count: The amount of items in the array.
String:
- _length: The length of the string.

Parameters:

	$value	The value to transform
	$path	The property path to use for the transformation. This can either be a string as described, or an array, each entry holding a property name.

Returns:: any The described value.

Todo:: refactor

Definition at line 54 of file DataObject.type.php.

Member Data Documentation

spunQ_DataObject::$_type [protected, inherited]

The actual type of this object.

Type:: spunQ.Type

Definition at line 129 of file DataObject.type.php.

spunQ_Type::$documentation [protected, inherited]

Documentation of this type as extracted from its doc comments.

Type:: string

Definition at line 434 of file Type.type.php.

spunQ_Type::$name [protected, inherited]

The name of this type.

Type:: string

Definition at line 428 of file Type.type.php.

spunQ_SetType::$objectCache [static, private]

Cache mapping user types to spunQ_SetType objects.

The keys correspond to the parameter types.

Type:: map<string,spunQ.type.builtin.SetType>

Definition at line 16 of file SetType.class.php.

spunQ_Type::$options [protected, inherited]

Additional options for this member.

This map is extracted from the tags in the doc comment. The value is intentionally typed as array, since some options can have multiple values. A doc comment containing two author tags would result in a single entry with two values.

Type:: map<string,array<string>>

Definition at line 444 of file Type.type.php.

spunQ_SetType::$parameterType [protected]

The type of the parameter of this set type.

This is either a spunQ_Type object or a string representation of one and will be converted to a proper object on demand.

Type:: spunQ_Type

Definition at line 76 of file SetType.class.php.

spunQ_Type::$typeInstance = NULL [static, protected, inherited]

The one instance of this class that will describe all other instances.

Any type describing a type has itself a type (which is spunQ.Type). That instance describing types is stored in this static variable.

Type:: spunQ_Type

Definition at line 291 of file Type.type.php.

const spunQ_SetType::SET_REGEX = '/^\h*set\h*<(.+)\h*>\h*$/'

The regex that will match set descriptions.

XXX: The regex is almost the same as in spunQ_ArrayType

Definition at line 22 of file SetType.class.php.

The documentation for this class was generated from the following file:

SetType.class.php


Public Member Functions
	__construct (spunQ_Type $parameterType)
	Constructor.
	getKeyType ()
	The key type of this collection.
	getValueType ()
	The value type of this collection.
	getParameterType ()
	Gets its parameter type.
	getName ()
	Overridden to generate the name on demand.
	check ($value, spunQ_Map $options=NULL, $throwException=true)
	Checks if a value is of the type described by this object.
	__sleep ()
	Replaces $parameterType with its string representation.
	getDocumentation ()
	Gets the documentation for this type.
	getOptions ()
	Gets the type options for this type.
	__call ($functionName, $arguments)
	Overloaded to provide automatic getters and setters.
	_verifyMembers ($omittedMembers=array(), $throwException=true)
	Verifies that all members are valid.
	_getMember ($name)
	Gets the value of a member of this object.
	_setMember ($name, $value)
	Sets the value of a member of this object.
	_getType ($throwException=true)
	Gets the type of this object.
Static Public Member Functions
static	get (spunQ_Type $parameterType)
	This factory method will reuse set types with the same parameter type.
static	getByName ($string)
	Overridden to only provide access to set types.
static	stringDescribesSet ($string)
	Whether a given string describes a set.
static	extractParameterDescriptor ($string)
	Returns the type description of the set parameter.
static	stringDescribesCollection ($string)
static	extractKeyOptions (spunQ_Map $options)
	Extracts options for the key type.
static	extractValueOptions (spunQ_Map $options)
	Extracts options for the key type.
static	convertToKeyOptions (spunQ_Map $options)
	Prepends the string 'key.
static	convertToValueOptions (spunQ_Map $options)
	Prepends the string 'value.
static	prependKey ($string)
	Prepends the string 'key.
static	prependValue ($string)
	Prepends the string 'value.
static	stringDescribesBuiltinType ($string)
	Whether a given string is a type description for a builtin type.
static	stringDescribesType ($string)
	Checks whether a string is a valid type descriptor.
static	getDescription ($value)
	Returns the most appropriate textual representation of a value.
static	getCommonDescription (array $values)
	Finds the most suiting string description for multiple values.
static	valueByProperty ($value, $path)
	Transforms a value using a property path.
static	propertyOfValue ($value, $property)
	Gets a single property of a value.
Public Attributes
const	SET_REGEX = '/^\hset\h<(.+)\h>\h$/'
	The regex that will match set descriptions.
Protected Member Functions
	handleGetUntranslated ($memberName, $arguments, $functionName)
	Needed by __call().
	handleGet ($memberName, $arguments, $functionName)
	Needed by __call().
	initLocalizedMember ($memberName)
	Makes sure a localized member contains a spunQ_Map.
	handleGetFromArray ($memberName, $arguments, $functionName)
	Needed by __call().
	handleSet ($memberName, $arguments, $functionName)
	Needed by __call().
	handleAdd ($memberName, $arguments, $functionName)
	Needed by __call().
	handleRemove ($memberName, $arguments, $functionName)
	Needed by __call().
Protected Attributes
	$parameterType
	The type of the parameter of this set type.
	$name
	The name of this type.
	$documentation
	Documentation of this type as extracted from its doc comments.
	$options
	Additional options for this member.
	$_type
	The actual type of this object.
Static Protected Attributes
static	$typeInstance = NULL
	The one instance of this class that will describe all other instances.
Static Private Attributes
static	$objectCache
	Cache mapping user types to spunQ_SetType objects.