NAME

Data::PropertyList - Convert arbitrary objects to/from strings

SYNOPSIS

  use Data::PropertyList qw(astext fromtext);
  
  $hash_ref = { 'items' => [ 7 .. 11 ], 'key' => 'value' };
  $string = astext($hash_ref);
  # ...
  $hash_ref = fromtext($string);
  print $hash_ref->{'items'}[0];
  
  $array_ref = [ 1, { 'key' => 'value' }, 'Omega' ];
  $string = astext($array_ref);
  # ...
  $array_ref = fromtext($string, '-array'=>1 );
  print $array_ref->[1]{'key'};

DESCRIPTION

Data::Propertylist provides functions that turn data structures with nested references into NeXT's Property List text format and back again.

You may find this useful for saving and loading application information in text files, or perhaps for generating error messages while debugging.

astext( $reference ) : $propertylist_string;

Writes out a nested Perl data structure in NeXT property list format.

fromtext( $propertylist_string ) : $hash_ref

fromtext( $propertylist_string, '-array'=>1 ) : $array_ref

Reconstructs a Perl data structure of nested references and scalars from a NeXT property list. Use the -array flag if the string encodes an array rather than a hash.

The Property List Format

The below is excerpted from a draft of the NeXT PropertyList(5) man page:

A property list organizes data into named values and lists of values. Property lists are used by the NEXTSTEP user defaults system (among other things).

In simple terms, a property list contains strings, binary data, arrays of items, and dictionaries. These four kinds of items can be combined in various ways, as described below.

A string is enclosed in double quotation marks; for example, "This is a string." (The period is included in this string.) The quotation marks can be omitted if the string is composed strictly of alphanumeric characters and contains no white space (numbers are handled as strings in property lists). Though the property list format uses ASCII for strings, note that NEXTSTEP uses Unicode. You may see strings containing unreadable sequences of ASCII characters; these are used to represent Unicode characters.

Binary data is enclosed in angle brackets and encoded in hexadecimal ASCII; for example, <0fbd777 1c2735ae>. Spaces are ignored.

An array is enclosed in parentheses, with the elements separated by commas; for example, ("San Francisco", "New York", "London"). The items don't all have to be of the same type (for example, all strings) - but they normally should be. Arrays can contain strings, binary data, other arrays, or dictionaries.

A dictionary is enclosed in curly braces, and contains a list of keys with their values. Each key-value pair ends with a semicolon. Here's a sample dictionary: { user = maryg; "error string" = "core dump"; code = <fead0007>; }. (Note the omission of quotation marks for single-word alphanumeric strings.) Values don't all have to be the same type, since their types are usually defined by whatever pro- gram uses them (in this example, the program using the dic- tionary knows that user is a string and code is binary data). Dictionaries can contain strings, binary data, arrays, and other dictionaries.

Below is a sample of a more complex property list, taken from a user's defaults system (see defaults(1)). The pro- perty list itself is a dictionary with keys "Clock," "NSGlobalDomain," and so on; each value is also a diction- ary, which contains the individual defaults.

    {
        Clock = {ClockStyle = 3; };
        NSGlobalDomain = {24HourClock = Yes; Language = English; };
        NeXT1 = {Keymap = /NextLibrary/Keyboards/NeXTUSA; };
        Viewer = {NSBrowserColumnWidth = 145; "NSWindow Frame 
    Preferences" = "5 197 395 309 "; };
        Workspace = {SelectedTabIndex = 0; WindowOrigin = "-75.000000"; };
        pbs = {};
    }

Please note that the above documentation is incomplete, and that the current implementation does not support all of the features discussed above.

EXAMPLE

Here's an example of a PropertyList-encoded data structure:

  my $produce_info = {
    'red' =>     { 'fruit' => [ { 'name' => 'apples', 
                                  'source' => 'Washington' } ],
                  'tubers' => [ { 'name' => 'potatoes', 
                                  'source' => 'Idaho' } ] },
    'orange' =>  { 'fruit' => [ { 'name' => 'oranges', 
                                  'source' => 'Florida' } ] }
  };
  print astext( $produce_info);

Examine STDOUT, et voila!

  orange = { 
    fruit = ( 
      { 
        name = oranges;
        source = Florida;
      },
    );
  };
  red = { 
    fruit = ( 
      { 
        name = apples;
        source = Washington;
      },
    );
    tubers = ( 
      { 
        name = potatoes;
        source = Washington;
      },
    );
  };

PREREQUISITES AND INSTALLATION

This package requires the String::Escape module. It should run on any standard Perl 5 installation.

To install this package, download and unpack the distribution archive from http://www.evoscript.com/dist/ and execute the standard "perl Makefile.PL", "make test", "make install" sequence.

STATUS AND SUPPORT

This release of Data::PropertyList is intended for public review and feedback. It has been tested in several environments and used in commercial production, but it should be considered "alpha" pending that feedback and fixes for some of the below bugs.

  Name            DSLI  Description
  --------------  ----  ---------------------------------------------
  Data::
  ::PropertyList  adpf  Convert arbitrary objects to/from strings

Further information and support for this module is available at <www.evoscript.com>.

Please report bugs or other problems to <bugs@evoscript.com>.

The following changes are in progress or under consideration:

Better Whitespace Parsing

Code is currently picky about parsing whitespace, and stilted about printing it. In particular, a newline is required after each item in an array or hash.

Restore Classes During Parsing

The class of blessed objects is indicated in /* ... */ comments embedded in the output, but are not yet restored when reading.

Restore Circular References During Parsing

Circular references are indicated in /* ... */ comments embedded in the output, but are not yet restored when reading.

NeXT Binary Format

Doesn't currently parse or write NeXT's <FFFF> binary format.

SEE ALSO

Similar to PropertyList.pm by Markus Felten <markus@arlac.rhein-main.de>.

The packages Data::Dumper and FreezeThaw (available from CPAN) also stream and destream data structures.

AUTHORS AND COPYRIGHT

Copyright 1996, 1997, 1998 Evolution Online Systems, Inc.

You may use this software for free under the terms of the Artistic License

Contributors: M. Simon Cavalletto <simonm@evolution.com>, Eleanor J. Evans <piglet@evolution.com>, Jeremy G. Bishop <jeremy@evolution.com>, Eric Schneider <roark@evolution.com>

cpanm Data::PropertyList

perl -MCPAN -e shell
install Data::PropertyList