/ 
XML-AppleConfigProfile-0.00_002
/ XML::AppleConfigProfile::Payload::Tie::Root

NAME

XML::AppleConfigProfile::Payload::Tie::Root - Tying class for payload storage.

DESCRIPTION

This class is used to store the payload keys, and their values, for each of the payload classes under XML::AppleConfigProfile::Payload::.

In the configuration profile XML, each payload is represented by a series of keys and their values. This matches up fairly well with a Perl hash, so that is the mechanism that was chosen for actually getting (and messing with) the data in a payload class!

This class is used directly only by XML::AppleConfigProfile::Payload::Common, and acts as storage for the payload keys. Subclasses are involved indirectly, by providing their own list of payload keys, either replacing or supplementing the list from XML::AppleConfigProfile::Payload::Common.

"CLASS" METHODS

tie %hash, 'XML::AppleConfigProfile::Payload::Tie::Root', $self

This method is not useful in client code, but it is documented for future developers of this software.

When this class is used to tie a hash, TIEHASH will be called, with the class name as the first argument. The second argument is expected to be a reference to the object that will be containing this tied hash. The containing object needs to implement two methods:

_validate($key, $value)

_validate needs to return, if the value is valid, the de-tainted value. If the value is not valid, then undef must be returned.

keys()

keys needs to return a reference to the hash of payload keys, as defined in XML::AppleConfigProfile::Payload::Common. No attempts will be made to modify the hash, so it can (and should) be read-only.

Since the second argument is a reference pointing back to the object which contains us, we are introducing a circular reference. We take responsibility for "weakening" the reference provided to us.

FETCH

Works as one would expect with a Perl hash. Either the value is returned, or undef is returned. Exactly what you get depends on the payload class and the key you are accessing. For more details, check the payload class documentation, as well as XML::AppleConfigProfile::Payload::Types.

STORE

Works almost as one would expect with a Perl hash. When setting a value to a key, two checks are performed:

  • The key must be a valid payload key name for this payload class.

  • The value must be a valid value for the given payload key.

Exactly what validation is performed depends first on the type of value (be it a string, a boolean, data, etc.), and next on any special validation performed by the payload class itself. For more details, check the payload class documentation, as well as XML::AppleConfigProfile::Payload::Types.

If the validation fails, the program dies.

delete

Deleting a key works as one would expect with a Perl hash. Once deleted, unless a new value is set, attempts to access the key will return undef.

clear

Clearing a hash works as one would expect with a Perl hash. Unless new values are set, attempts to access keys will return undef.

exists

The operation of exists is a little different from what is normally expected.

exists will return true iff the key provided is a valid payload key for this payload class.

To check if a payload key actually has a value, use defined. Of course, you should continue to use exists if you do not know if a payload has a particular key.

keys

keys returns a list of keys only for payload keys that have been set.

To get the a list of all keys that exist for this payload class, don't look at the payload. Instead, use keys on the hash returned by keys().

each

each returns the key/value pairs only for payload keys that have been set.

scalar

scalar returns the number of payload keys that have values set.

To get the total number of keys that exist for this payload class, don't look at the payload. Instead, use scalar on the hash returned by keys().

ACKNOWLEDGEMENTS

Refer to the 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.