com.taco.text
Class StringListUtilities

java.lang.Object
  extended by com.taco.text.StringListUtilities

public class StringListUtilities
extends java.lang.Object

A utility class for converting strings to and from lists of objects.


Field Summary
static java.util.regex.Pattern CLOSE_BRACE_PATTERN
          A regex pattern for a close brace surrounded by optional whitespace.
static java.util.regex.Pattern CLOSE_BRACKET_PATTERN
          A regex pattern for a close bracket surrounded by optional whitespace.
static java.util.regex.Pattern CLOSE_PARENTHESIS_PATTERN
          A regex pattern for a closed parenthesis surrounded by optional whitespace.
static java.lang.String COLLECTION_FACTORY_KEY
          A key in the option map for convertering strings to lists, which is mapped to an instance of ICollectionFactory which creates an empty collection to be filled with the elements of the list.
static java.util.regex.Pattern COMMA_SEPARATOR_PATTERN
          A regex pattern for a comma surrounded by optional whitespace.
static java.util.regex.Pattern DOUBLE_QUOTE_PATTERN
          A regex pattern for a double quote mark prefixed by optional whitespace.
static java.util.regex.Pattern DOUBLE_QUOTE_SEPARATOR_PATTERN
           
static java.util.Map FROM_BRACKETED_STRING_OPTION_MAP
           
static java.util.Map FROM_DOUBLE_QUOTED_STRING_OPTION_MAP
           
static java.util.Map FROM_INSTANCE_LIST_OPTION_MAP
          An option map containing the key OBJECT_TO_STRING_CONVERTER_KEY mapped to ClassToStringConverter.instance.
static java.util.Map FROM_PATTERN_LIST_OPTION_MAP
           
static java.lang.String IGNORE_ELEMENT_CONVERSION_ERRORS_KEY
          A key in the option map for converting lists from/to strings, which is mapped to an instance of Boolean indicating whether or not errors converting each element are ignored.
static java.lang.String INTERPOLATING_STRING_TO_OBJECT_CONVERTER_KEY
          A key in the option map for converting strings to lists, which is mapped to an instance of IInterpolatingStringToObjectConverter that converts each element substring to an object in the list.
static java.lang.String OBJECT_TO_STRING_CONVERTER_KEY
          A key in the option map for converting lists to strings, which is mapped to an instance of IObjectToStringConverter that converts each element to a string.
static java.util.regex.Pattern OPEN_BRACE_PATTERN
          A regex pattern for an open brace surrounded by optional whitespace.
static java.util.regex.Pattern OPEN_BRACKET_PATTERN
          A regex pattern for an open bracket surrounded by optional whitespace.
static java.util.regex.Pattern OPEN_PARENTHESIS_PATTERN
          A regex pattern for an open parenthesis surrounded by optional whitespace.
static java.util.regex.Pattern PATH_SEPARATOR_PATTERN
           
static java.lang.String PREFIX_KEY
          A key in the option map for converting lists to strings, which is mapped to the prefix with which to start the string representation of the list.
static java.lang.String PREFIX_PATTERN_KEY
          A key in the option map for converting strings to lists, which is mapped to a instance of Pattern indicating the prefix with which string representation of the list begins.
static java.util.regex.Pattern REVERSED_DOUBLE_QUOTE_PATTERN
          A regex pattern for a double quote mark prefixed by optional whitespace.
static java.util.regex.Pattern REVERSED_SINGLE_QUOTE_PATTERN
          A regex pattern for a single quote mark prefixed by optional whitespace.
static java.lang.String REVERSED_SUFFIX_PATTERN_KEY
          A key in the option map for converting strings to lists, which is mapped to a instance of Pattern indicating the suffix with which string representation of the list ends.
static java.lang.String SEPARATOR_KEY
          A key in the option map for converting lists to strings, which is mapped to a separator between the string representations of elements in the list.
static java.lang.String SEPARATOR_PATTERN_KEY
          A key in the option map for converting strings to lists, which is mapped to a instance of Pattern indicating the separator between elements.
static java.util.regex.Pattern SINGLE_QUOTE_PATTERN
          A regex pattern for a single quote mark prefixed by optional whitespace.
static java.util.regex.Pattern SINGLE_QUOTE_SEPARATOR_PATTERN
           
static java.lang.String SMART_SEPARATE_KEY
          A key in the option map for converting strings to lists, which is mapped to a Boolean indicating whether substrings within a string representing a list should be parsed using C-style syntax, so that parentheses are matched.
static java.lang.String STRING_TO_OBJECT_CONVERTER_KEY
          A key in the option map for converting strings to lists, which is mapped to an instance of IStringToObjectConverter that converts each element substring to an object in the list.
static java.lang.String SUFFIX_KEY
          A key in the option map for converting lists to strings, which is mapped to the suffix with which to end the string representation of the list.
static java.util.Map TO_BRACKETED_STRING_OPTION_MAP
           
static java.util.Map TO_DOUBLE_QUOTED_STRING_OPTION_MAP
           
static java.util.Map TO_INSTANCE_LIST_OPTION_MAP
          An option map containing the key STRING_TO_OBJECT_CONVERTER_KEY mapped to StringToInstanceConverter.instance and the key SMART_SEPARATE_KEY mapped to Boolean.FALSE.
static java.util.Map TO_PATTERN_LIST_OPTION_MAP
           
 
Constructor Summary
protected StringListUtilities()
          This class is a static utility class, so its sole constructor is protected to allow subclassing but disallow instantiation.
 
Method Summary
protected static java.util.List _createObjectListCore(java.lang.String s, java.util.Map options, IStringToObjectConverter stringConverter, IInterpolatingStringToObjectConverter interpolatingConverter, java.util.ResourceBundle bundle, INoReturnMap argMap)
          Do the work of createObjectList().
protected static boolean _popChar(java.util.LinkedList charStack, char c)
          If the stack is empty, return false.
static java.lang.String createCollectionString(java.util.Collection c, java.util.Map options)
          Convert a collection into a string.
static java.util.List createInstanceList(java.lang.String s)
          Return a list of default instances of the classes specifed in the argument string, separated by commas.
static java.lang.String createIntArrayString(int[] array, java.util.Map options)
          Convert the array of integers to a list using ArrayUtilities.asList(), then call createCollectionString() with the created list.
static java.util.List createObjectList(java.lang.String s, java.util.Map options)
          Create a new list with elements converted from substrings of the argument string.
static java.util.List createObjectList(java.lang.String s, java.util.Map options, java.util.ResourceBundle bundle, INoReturnMap argMap)
          Create a new list with elements converted from substrings of the argument string.
static void main(java.lang.String[] args)
          A simple test program.
static java.util.List smartStringSeparate(java.lang.String s, java.util.regex.Pattern separatorPattern)
          Separate the argument string into a list of strings around the separator pattern when the context is appropriate.
static java.util.List split(java.lang.String s, java.util.Map options)
          Split the argument string into substrings to be converted to objects.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

IGNORE_ELEMENT_CONVERSION_ERRORS_KEY

public static final java.lang.String IGNORE_ELEMENT_CONVERSION_ERRORS_KEY
A key in the option map for converting lists from/to strings, which is mapped to an instance of Boolean indicating whether or not errors converting each element are ignored. Such an element will not appear in the returned list or string. If this mapped to a false Boolean, errors in element conversion will result in an exception being thrown immediately. By default, this key is mapped to Boolean.TRUE.

See Also:
Constant Field Values

PREFIX_KEY

public static final java.lang.String PREFIX_KEY
A key in the option map for converting lists to strings, which is mapped to the prefix with which to start the string representation of the list. If this key is unmapped, no prefix will be used.

See Also:
Constant Field Values

SUFFIX_KEY

public static final java.lang.String SUFFIX_KEY
A key in the option map for converting lists to strings, which is mapped to the suffix with which to end the string representation of the list. If this key is unmapped, no suffix will be used.

See Also:
Constant Field Values

SEPARATOR_KEY

public static final java.lang.String SEPARATOR_KEY
A key in the option map for converting lists to strings, which is mapped to a separator between the string representations of elements in the list. If this key is unmapped, a comma will be used.

See Also:
Constant Field Values

OBJECT_TO_STRING_CONVERTER_KEY

public static final java.lang.String OBJECT_TO_STRING_CONVERTER_KEY
A key in the option map for converting lists to strings, which is mapped to an instance of IObjectToStringConverter that converts each element to a string. If this key is unmapped, DefaultObjectToStringConverter.instance will be used.

See Also:
Constant Field Values

PREFIX_PATTERN_KEY

public static final java.lang.String PREFIX_PATTERN_KEY
A key in the option map for converting strings to lists, which is mapped to a instance of Pattern indicating the prefix with which string representation of the list begins. If this key is unmapped, no prefix will be matched.

See Also:
Constant Field Values

REVERSED_SUFFIX_PATTERN_KEY

public static final java.lang.String REVERSED_SUFFIX_PATTERN_KEY
A key in the option map for converting strings to lists, which is mapped to a instance of Pattern indicating the suffix with which string representation of the list ends. The pattern should be reversed so that the string can be matched from the end to the beginning. If this key is unmapped, no suffix will be matched.

See Also:
Constant Field Values

SEPARATOR_PATTERN_KEY

public static final java.lang.String SEPARATOR_PATTERN_KEY
A key in the option map for converting strings to lists, which is mapped to a instance of Pattern indicating the separator between elements. If this key is unmapped, COMMA_SEPARATOR_PATTERN will be used.

See Also:
Constant Field Values

SMART_SEPARATE_KEY

public static final java.lang.String SMART_SEPARATE_KEY
A key in the option map for converting strings to lists, which is mapped to a Boolean indicating whether substrings within a string representing a list should be parsed using C-style syntax, so that parentheses are matched.

See Also:
Constant Field Values

STRING_TO_OBJECT_CONVERTER_KEY

public static final java.lang.String STRING_TO_OBJECT_CONVERTER_KEY
A key in the option map for converting strings to lists, which is mapped to an instance of IStringToObjectConverter that converts each element substring to an object in the list. If this key is unmapped, DefaultStringtToObjectConverter.instance will be used.

See Also:
Constant Field Values

INTERPOLATING_STRING_TO_OBJECT_CONVERTER_KEY

public static final java.lang.String INTERPOLATING_STRING_TO_OBJECT_CONVERTER_KEY
A key in the option map for converting strings to lists, which is mapped to an instance of IInterpolatingStringToObjectConverter that converts each element substring to an object in the list. If this key is unmapped, the STRING_TO_OBJECT_CONVERTER_KEY will be checked instead.

See Also:
Constant Field Values

COLLECTION_FACTORY_KEY

public static final java.lang.String COLLECTION_FACTORY_KEY
A key in the option map for convertering strings to lists, which is mapped to an instance of ICollectionFactory which creates an empty collection to be filled with the elements of the list.

See Also:
Constant Field Values

OPEN_BRACKET_PATTERN

public static final java.util.regex.Pattern OPEN_BRACKET_PATTERN
A regex pattern for an open bracket surrounded by optional whitespace.


CLOSE_BRACKET_PATTERN

public static final java.util.regex.Pattern CLOSE_BRACKET_PATTERN
A regex pattern for a close bracket surrounded by optional whitespace.


OPEN_BRACE_PATTERN

public static final java.util.regex.Pattern OPEN_BRACE_PATTERN
A regex pattern for an open brace surrounded by optional whitespace.


CLOSE_BRACE_PATTERN

public static final java.util.regex.Pattern CLOSE_BRACE_PATTERN
A regex pattern for a close brace surrounded by optional whitespace.


OPEN_PARENTHESIS_PATTERN

public static final java.util.regex.Pattern OPEN_PARENTHESIS_PATTERN
A regex pattern for an open parenthesis surrounded by optional whitespace.


CLOSE_PARENTHESIS_PATTERN

public static final java.util.regex.Pattern CLOSE_PARENTHESIS_PATTERN
A regex pattern for a closed parenthesis surrounded by optional whitespace.


SINGLE_QUOTE_PATTERN

public static final java.util.regex.Pattern SINGLE_QUOTE_PATTERN
A regex pattern for a single quote mark prefixed by optional whitespace.


REVERSED_SINGLE_QUOTE_PATTERN

public static final java.util.regex.Pattern REVERSED_SINGLE_QUOTE_PATTERN
A regex pattern for a single quote mark prefixed by optional whitespace.


DOUBLE_QUOTE_PATTERN

public static final java.util.regex.Pattern DOUBLE_QUOTE_PATTERN
A regex pattern for a double quote mark prefixed by optional whitespace.


REVERSED_DOUBLE_QUOTE_PATTERN

public static final java.util.regex.Pattern REVERSED_DOUBLE_QUOTE_PATTERN
A regex pattern for a double quote mark prefixed by optional whitespace.


COMMA_SEPARATOR_PATTERN

public static final java.util.regex.Pattern COMMA_SEPARATOR_PATTERN
A regex pattern for a comma surrounded by optional whitespace.


SINGLE_QUOTE_SEPARATOR_PATTERN

public static final java.util.regex.Pattern SINGLE_QUOTE_SEPARATOR_PATTERN

DOUBLE_QUOTE_SEPARATOR_PATTERN

public static final java.util.regex.Pattern DOUBLE_QUOTE_SEPARATOR_PATTERN

PATH_SEPARATOR_PATTERN

public static final java.util.regex.Pattern PATH_SEPARATOR_PATTERN

TO_PATTERN_LIST_OPTION_MAP

public static final java.util.Map TO_PATTERN_LIST_OPTION_MAP

FROM_PATTERN_LIST_OPTION_MAP

public static final java.util.Map FROM_PATTERN_LIST_OPTION_MAP

TO_INSTANCE_LIST_OPTION_MAP

public static final java.util.Map TO_INSTANCE_LIST_OPTION_MAP
An option map containing the key STRING_TO_OBJECT_CONVERTER_KEY mapped to StringToInstanceConverter.instance and the key SMART_SEPARATE_KEY mapped to Boolean.FALSE. This is useful for converting strings of class names to lists of instances of objects.


FROM_INSTANCE_LIST_OPTION_MAP

public static final java.util.Map FROM_INSTANCE_LIST_OPTION_MAP
An option map containing the key OBJECT_TO_STRING_CONVERTER_KEY mapped to ClassToStringConverter.instance. This is useful for converting lists of instances of objects to a string of the class names of the objects.


FROM_DOUBLE_QUOTED_STRING_OPTION_MAP

public static final java.util.Map FROM_DOUBLE_QUOTED_STRING_OPTION_MAP

TO_DOUBLE_QUOTED_STRING_OPTION_MAP

public static final java.util.Map TO_DOUBLE_QUOTED_STRING_OPTION_MAP

FROM_BRACKETED_STRING_OPTION_MAP

public static final java.util.Map FROM_BRACKETED_STRING_OPTION_MAP

TO_BRACKETED_STRING_OPTION_MAP

public static final java.util.Map TO_BRACKETED_STRING_OPTION_MAP
Constructor Detail

StringListUtilities

protected StringListUtilities()
This class is a static utility class, so its sole constructor is protected to allow subclassing but disallow instantiation.

Method Detail

createCollectionString

public static final java.lang.String createCollectionString(java.util.Collection c,
                                                            java.util.Map options)

Convert a collection into a string. The string begins with the prefix, contains strings converted from each element in the collection by the converter, separated by the separator, and ends with the suffix.

Options:

PREFIX_KEY: The prefix to begin the string with. Default: "[".

SUFFIX_KEY: The suffix to end the string with. Default: "]".

SEPARATOR_KEY: The separator between elements. Default: ",".

OBJECT_TO_STRING_CONVERTER_KEY: The element to String converter. Default: DefaultObjectToStringConverter.instance.

IGNORE_ELEMENT_CONVERSION_ERRORS_KEY: If mapped to a true Boolean, exceptions thrown during the conversion of elements to strings will be ignored. Otherwise, such an exception will be rethrown to the caller. Default: Boolean.TRUE.


createIntArrayString

public static final java.lang.String createIntArrayString(int[] array,
                                                          java.util.Map options)
Convert the array of integers to a list using ArrayUtilities.asList(), then call createCollectionString() with the created list.


createObjectList

public static final java.util.List createObjectList(java.lang.String s,
                                                    java.util.Map options)
                                             throws java.text.ParseException

Create a new list with elements converted from substrings of the argument string. The string may begin with a prefix pattern and end with a suffix pattern. Split the string into substrings using the separator pattern. Then convert all substrings into objects and add them to the returned list.

Options:

PREFIX_PATTERN_KEY: A regex pattern specifying what the argument string must begin with. The matching substring is discarded. If null, don't try to match any prefix. Default: OPEN_BRACKET_PATTERN.

REVERSED_SUFFIX_PATTERN_KEY: A reversed regex pattern specifying what the argument string must end with. The matching substring is discarded. If null, don't try to match any prefix. Default: CLOSE_BRACKET_PATTERN.

SEPARATOR_PATTERN_KEY: A regex pattern specifying the filler characters between substrings used to create elements. Default: COMMA_SEPARATOR_PATTERN.

SMART_SEPARATE_KEY: If mapped to a true Boolean, separation of the argument string into substrings will be done "smartly", i.e. aware of parenthesis and quote context so that the separator pattern can appear in the elements of the return list, provided it is inside parentheses or quoted. Default: Boolean.TRUE.

STRING_TO_OBJECT_CONVERTER_KEY: The string to element converter. Default: DefaultStringToObjectConverter.instance.

IGNORE_ELEMENT_CONVERSION_ERRORS_KEY: If mapped to a true Boolean, instances of ParseException thrown during the conversion of strings elements will be ignored. Otherwise, these exception will be rethrown to the caller. Default: Boolean.TRUE.

Throws:
java.text.ParseException

createObjectList

public static java.util.List createObjectList(java.lang.String s,
                                              java.util.Map options,
                                              java.util.ResourceBundle bundle,
                                              INoReturnMap argMap)
                                       throws java.text.ParseException,
                                              java.util.MissingResourceException

Create a new list with elements converted from substrings of the argument string. The string may begin with a prefix pattern and end with a suffix pattern. Split the string into substrings using the separator pattern. Then convert all substrings (using interpolation) into objects and add them to the returned list.

Options:

PREFIX_PATTERN_KEY: A regex pattern specifying what the argument string must begin with. The matching substring is discarded. If null, don't try to match any prefix. Default: B.

REVERSED_SUFFIX_PATTERN_KEY: A reversed regex pattern specifying what the argument string must end with. The matching substring is discarded. If null, don't try to match any prefix. Default: null.

SEPARATOR_PATTERN_KEY: A regex pattern specifying the filler characters between substrings used to create elements. Default: COMMA_SEPARATOR_PATTERN.

SMART_SEPARATE_KEY: If mapped to a true Boolean, separation of the argument string into substrings will be done "smartly", i.e. aware of parenthesis and quote context so that the separator pattern can appear in the elements of the return list, provided it is inside parentheses or quoted. Default: Boolean.TRUE.

INTERPOLATING_STRING_TO_OBJECT_CONVERTER_KEY: The interpolating string to element converter. Default: InterpolatingConverter.DEFAULT_INSTANCE.

IGNORE_ELEMENT_CONVERSION_ERRORS_KEY: If mapped to a true Boolean, instances of ParseException and MissingResourceException thrown during the conversion of strings elements will be ignored. Otherwise, these exception will be rethrown to the caller. Default: Boolean.TRUE.

Throws:
java.text.ParseException
java.util.MissingResourceException

_createObjectListCore

protected static final java.util.List _createObjectListCore(java.lang.String s,
                                                            java.util.Map options,
                                                            IStringToObjectConverter stringConverter,
                                                            IInterpolatingStringToObjectConverter interpolatingConverter,
                                                            java.util.ResourceBundle bundle,
                                                            INoReturnMap argMap)
                                                     throws java.text.ParseException,
                                                            java.util.MissingResourceException
Do the work of createObjectList(). If interpolatingConverter is non-null, the it will be used to convert each element. Otherwise, stringConverter will be used to convert each element.

Throws:
java.text.ParseException
java.util.MissingResourceException

split

public static java.util.List split(java.lang.String s,
                                   java.util.Map options)
                            throws java.text.ParseException

Split the argument string into substrings to be converted to objects. Return a list of substrings.

Options:

PREFIX_PATTERN_KEY: A regex pattern specifying what the argument string must begin with. The matching substring is discarded. If null, don't try to match any prefix. Default: null.

REVERSED_SUFFIX_PATTERN_KEY: A reversed regex pattern specifying what the argument string must end with. The matching substring is discarded. If null, don't try to match any prefix. Default: null.

SEPARATOR_PATTERN_KEY: A regex pattern specifying the filler characters between substrings used to create elements. Default: COMMA_SEPARATOR_PATTERN.

SMART_SEPARATE_KEY: If mapped to a true Boolean, separation of the argument string into substrings will be done "smartly", i.e. aware of parenthesis and quote context so that the separator pattern can appear in the elements of the return list, provided it is inside parentheses or quoted. Default: Boolean.TRUE.

Throws:
java.text.ParseException

smartStringSeparate

public static java.util.List smartStringSeparate(java.lang.String s,
                                                 java.util.regex.Pattern separatorPattern)
                                          throws java.text.ParseException
Separate the argument string into a list of strings around the separator pattern when the context is appropriate. A context is appropriate if all parenthesis and quote characters ('(', '{', '[', """, "'") are matched. Appearances of these characters will change the context unless escaped with a backslash or inside quotes. By remembering the context, the separator pattern may appear as a substring an element of the returned list of strings. Return null if parenthesis and quote matching fails.

Throws:
java.text.ParseException

createInstanceList

public static final java.util.List createInstanceList(java.lang.String s)
                                               throws java.text.ParseException
Return a list of default instances of the classes specifed in the argument string, separated by commas.

Throws:
java.text.ParseException

main

public static void main(java.lang.String[] args)
A simple test program.


_popChar

protected static boolean _popChar(java.util.LinkedList charStack,
                                  char c)
If the stack is empty, return false. Otherwise, remove the last element from the stack. Return true if it is an instance of Character and matches c. NOTE: NOT CURRENTLY USED!