NAME

XML::AppleConfigProfile::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, 'XML::AppleConfigProfile::Payload::Tie::Array', $value_type

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

$value_type can be a scalar or a ref. If $value_type is a reference, it must be blessed. We keep a record of $value_type's class, and all values placed into the array must be of the same class. We let the class take responsibility for validating its contents.

If $value_type is a scalar, then $value_type must match one of the types from XML::AppleConfigProfile::Payload::Types, except for $ProfileClass. The standard type validation function from XML::AppleConfigProfile::Payload::Types::Validation will be used.

If $value_type is not a valid scalar or a valid reference, 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 XML::AppleConfigProfile 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.

cpanm XML::AppleConfigProfile

perl -MCPAN -e shell
install XML::AppleConfigProfile