/ 
Config-Apple-Profile-0.87-TRIAL
River stage zero No dependents
/ Config::Apple::Profile::Payload::Tie::Array

NAME

Config::Apple::Profile::Payload::Tie::Array - Tying class for arrays of things.

DESCRIPTION

This class is used to store an array of things. Exactly what things are being stored is specified at the time the tie is made.

There are several payload types that contain arrays of things. For example, the root profile has the all-important key PayloadContents, which is an array of payloads.

This class is used by payload classes to represent an array.

"CLASS" METHODS

tie @array, 'Config::Apple::Profile::Payload::Tie::Array', $validator

When this class is tied to an array, TIEARRAY will be called, with the class name as the first argument.

$validator is a reference to a function that will be able to validate values that are stored to the array. The validator will be passed the value as the only parameter, and an untained value is expected as the return value. If undef is returned by the validator, then the value was invalid, and the store attempt will fail.

It is suggested that the functions from Config::Apple::Profile::Payload::Types::Validation be used.

If $validator is not a valid coderef then an exception will be thrown.

FETCH

Works as one would expect with a Perl array. Returns the entry at the specified index. Since methods are in place to prevent storing undef, as long as the index is valid at the time of the call, you will get something back.

STORE

Storing items at a specific index is not allowed. This is to help prevent undef from appearing in the array. Instead, use push or unshift.

delete

Deleting items at a specific index is not allowed. Perl has deprecated this. Instead, use splice, pop, or shift.

scalar

Works as expected, returning the number of items in the array.

STORESIZE

Works almost as expected. Making an array smaller will delete items off of the end of the array. Making the array bigger (that is, presizing) has no effect.

EXTEND

If Perl attempts to pre-extend the array, nothing happens.

exists

Works as expected for a Perl array: Returns true if the specified index is still valid for the array.

CLEAR

Replacing the array with an empty list works to remove all of the entries from the array.

push

Works as expected for a Perl array, with two exceptions:

  • undef is not a valid array item.

  • If this is not an array of objects, then the value will be validated before being added to the array.

An exception will be thrown if either of the two points above fails.

pop

Works as expected for a Perl array.

shift

Works as expected for a Perl array.

unshift

Works as expected for a Perl array, with two exceptions:

  • undef is not a valid array item.

  • If this is not an array of objects, then the value will be validated before being added to the array.

An exception will be thrown if either of the two points above fails.

splice

Works as expected for a Perl array, but if you are using splice to add entries to the array, take note of these two exceptions:

  • undef is not a valid array item.

  • If this is not an array of objects, then the value will be validated before being added to the array.

An exception will be thrown if either of the two points above fails.

_validate

Given a list of items, each one will be validated, and the validated list will be returned.

An exception will be thrown if any of the list items is undef, or if any of the list items fails validation, or if the caller is not expecting an array.

ACKNOWLEDGEMENTS

Refer to Config::Apple::Profile for acknowledgements.

AUTHOR

A. Karl Kornel, <karl at kornel.us>

COPYRIGHT AND LICENSE

Copyright © 2014 A. Karl Kornel.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.