net.wotonomy.foundation.internal
Class PropertyListParser

java.lang.Object
  net.wotonomy.foundation.internal.PropertyListParser

public class PropertyListParser
extends java.lang.Object

PropertyListParser can parse a property list (plist) file or string, and return the top-level object represented by the plist.

A property list is a heirarchical data structure containing only Maps, Lists, and Strings -- nothing else. In other words, a property list is either a Map, List, or String instance, with the restrictions that the collections may only contain Map, List, or String instances.

This class can read a particularly-formatted string or file, and create the property list structure described. It provides a convenient means for having a structured data file, letting programs simply deal with the structure rather than having to do a lot of string parsing work as well. The concept is similar to Properties files, except that the values can be nested Maps or Lists instead of only Strings.

A Map is specified in a file by key/value pairs surrounded by brace characters. An equal sign (=) must be between the key and value, and there must be a semicolon (;) following the value.

     {
         key1 = value1;
         key2 = value2;
         etc...
     }
 

A List is specified by a comma-separated list of values surrounded by parentheses, like:

     ( value1, value2, value3, etc... )
 

A String can either be quoted in the manner of a constant string in Java, or unquoted. If unquoted, the string can only contain alphanumerics, underscores (_), periods (.), dollar signs ($), colons (:), or forward slashes (/). If any other character appears in the string, it must be quoted (i.e., surrounded by " characters). Quoted strings may also contain \n, \t, \f, \v, \b, and \a escapes, octal escapes of the form \000, and unicode escapes of the form of \U followed by four hexadecimal characters. Any other character escaped by a backslash will be treated as that character, and the escaping backslash character will be omitted. Thus, to represent an actual backslash, it must appear as \\ in the quoted string.

All whitespace between elements is ignored, and both //-style and /*-style comments are allowed to appear anywhere between elements.

If there are any syntax errors encountered while parsing, RuntimeExceptions are thrown with the line number and column of the problem.

Currenty, HashMaps and ArrayLists are the actual Map and List classes used when creating the property list.

Examples:

   // This plist file represents a Map, since it starts with a '{'.
   {
       Map1 = { subkey1 = "foo"; };
       Map2 =
       {
           "key1"  = "This is a quoted string.";
           "key 2" = "bar\nbaz";    // the value has a newline in it
           key3    = ("a", b, c, "quux quux");   // a List of four Strings
       };  // We need a semicolon here, since it's following the value of the "Map2" key

       List1 = (foobar,foobaz,"foo,baz", (aa, ab, ac)); // a List of 3 Strings and a List

       // And now a List of two Maps
       List2 = (
           {
               key1 = value1;
               key2 = "value 2";
               key3 = (a,b,c,d);
               key4 = ();
           },  // We need the comma here
           {
               key1 = {};  // an empty Map
               key2 = "another String value";
           }
       );
   }
 

For those wondering, this is essentially a re-implementation of NeXT/Apple's property lists, except that data values are not supported.

Version:

$Revision: 899 $

Author:

clindberg@blacksmith.com

Constructor Summary

PropertyListParser(char[] charArray)
Creates a new PropertyListParser to parse the specified char array.

PropertyListParser(java.lang.String plistString)
Creates a new PropertyListParser to parse the contents of the specified String.

Method Summary

static void	main(java.lang.String[] args)
static java.lang.Object	propertyListFromFile(java.lang.String filename) Reads the contents of the specified file, and parses the contents.
static java.lang.Object	propertyListFromReader(java.io.Reader reader) Reads all remaining characters from the Reader, and returns the result of propertyListFromString().
static java.lang.Object	propertyListFromString(java.lang.String plistString) Reads an object (String, List, or Map) from plistString and returns it.
java.lang.Object	readTopLevelObject()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PropertyListParser

public PropertyListParser(java.lang.String plistString)

Creates a new PropertyListParser to parse the contents of the specified String.

PropertyListParser

public PropertyListParser(char[] charArray)

Creates a new PropertyListParser to parse the specified char array.

Method Detail

propertyListFromString

public static java.lang.Object propertyListFromString(java.lang.String plistString)

Reads an object (String, List, or Map) from plistString and returns it. RuntimeExceptions are raised if there are parse problems.

propertyListFromReader

public static java.lang.Object propertyListFromReader(java.io.Reader reader)
                                               throws java.io.IOException

Reads all remaining characters from the Reader, and returns the result of propertyListFromString(). RuntimeExceptions are raised if there are parse problems

Throws:

java.io.IOException

propertyListFromFile

public static java.lang.Object propertyListFromFile(java.lang.String filename)

Reads the contents of the specified file, and parses the contents. If any error occurs, prints out a message using System.out.println() and returns null.

readTopLevelObject

public java.lang.Object readTopLevelObject()

main

public static void main(java.lang.String[] args)