sexp
Class SList

java.lang.Object
  |
  +--sexp.BaseSexp
        |
        +--sexp.SList

public class SList

extends BaseSexp

implements SExpression

This class implements the list-aspect of a SExpression. All S-Expressions are lists. A list's components are either:

• an octet-string, or
• a finite list of simpler S-Expressions.

This class is now able to take an S-Expression in its Advanced representation and construct an SList object from it, although it's not particularly good at it, even if it should be as good as Rivest's SEXP tool.

This class underwent some major changes from version 1.8, after which the toAdvanced() method changed return type from String to byte[].

NOTE II: Regarding serialization: an initial test showed that a SList with a transport size of 125 bytes expanded to 2016 bytes when serialized. This size includes all the internal hashtables and whatnots. Do we really want that? Why not implement the java.io.Serializable interface and provide the read-/writeObject methods, and let these write the list in transport format? Hmmm...

TODO: Straighten out javadoc see-references

Version:

$Id: SList.java,v 1.4 2002/05/06 07:19:53 tep Exp $

Author:

Per Harald Myrvang <perm@pasta.cs.uit.no>

See Also:

SExpression, Sexp

Field Summary

private static String	__me
String	byte_encoding Encoding used when converting from a byte array to whatever.
private static boolean	debug
protected static String	default_encoding
protected Hashtable	hash Hashtable that's created if needed.
protected Vector	list The list is kept in a Vector object.
String	string_encoding Encoding used when converting from a String to whatever.

Fields inherited from class sexp.BaseSexp

__me

Fields inherited from interface sexp.SExpression

versionString

Constructor Summary

SList()
Default constructor just initializes default values and stuff.

SList(byte[] input)
Build list object from byte-arrayinput.

SList(InputStream input)
Build list object from byte-arrayinput.

SList(String input)
Build list object from String input.

Method Summary

SList	add(BigInteger bi) Add a BigInteger to the end of this list.
SList	add(byte[] ba) Add a byte array to the end of this list.
SList	add(SExpression sexp) Add an S-Expression object to the end of this list.
SList	add(String s) Add a String object to the end of this list.
Enumeration	elements() Return this' list elements as an Enumeration.
Enumeration	elementsOfListMatching(String regexp) Recursively search this for the first sublist mathing the Regular Expression name.
Enumeration	elementsOfListNamed(String name) Recursively search this for the first sublist starting with name.
boolean	equals(Object that) See if this list is equal to the given list.
SExpression	fetchAt(int index) Retrieve a indexed of S-Expressions from this list.
void	finalize()
void	free() Destructive resource deallocation.
SList	getListMatching(String regexp) Recursively search list for first sublist which first element matches a regular expression.
private void	getListsMatching(gnu.regexp.RE re, Vector matches, boolean singlematch)
Vector	getListsMatching(String regexp) Recursively search list for any sublists which first element matches a regular expression.
Vector	getListsStartingWith(String name) Recursively search list for any sublists starting with name.
private void	getListsStartingWith(String name, Vector matches)
int	indexOf(SExpression obj) Searches for the first occurence of the given argument, starting at the beginning of this list.
int	indexOf(SExpression obj, int index) Searches for the first occurence of the given argument, beginning the search at the given index.
void	insertAt(SExpression obj, int index) Inserts the specified object as a component in this list at the specified index.
boolean	isList() Returns true if this S-Expression is a list of simpler S-Expressions, or false if this object is an octet-string object.
SExpression	item(int index) Retrieve a indexed of S-Expressions from this list.
int	lastIndexOf(SExpression obj) Searches for the last occurence of the given argument.
SList	lookup(String name) Recursively look up S-Expressions starting with name.
int	makeLookupHash() Make lookup hashtable.
SList	nr_lookup(String name) Non-recursively look up S-Expressions starting with name.
private void	readNew(InputStream input)
int	size() Number of S-Expressions in this list.

Methods inherited from class sexp.BaseSexp

toAdvanced, toAdvanced, toCanonical, toCanonical, toString, toTransport, toTransport

Methods inherited from class java.lang.Object

, clone, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait

Field Detail

__me

private static final String __me

default_encoding

protected static String default_encoding

string_encoding

public String string_encoding

Encoding used when converting from a String to whatever.

byte_encoding

public String byte_encoding

Encoding used when converting from a byte array to whatever.

debug

private static boolean debug

list

protected Vector list

The list is kept in a Vector object.

hash

protected Hashtable hash

Hashtable that's created if needed.

See Also:

makeLookupHash(), SList#lookup()

Constructor Detail

SList

public SList()

Default constructor just initializes default values and stuff.

SList

public SList(InputStream input)
      throws SexpException

Build list object from byte-arrayinput. This is how you read a stored, canonical/transport representation and make an object out of it.

Parameters:

input - byte-array input

SList

public SList(byte[] input)
      throws SexpException

Build list object from byte-arrayinput. This is how you read a stored, canonical/transport representation and make an object out of it.

Parameters:

input - byte-array input

SList

public SList(String input)
      throws SexpException

Build list object from String input. This is how you read a stored, canonical/transport representation and make an object out of it.

Parameters:

input - string input

Method Detail

finalize

public void finalize()
              throws Throwable

Overrides:

finalize in class Object

readNew

private void readNew(InputStream input)
              throws IOException

isList

public boolean isList()

Returns true if this S-Expression is a list of simpler S-Expressions, or false if this object is an octet-string object.

Specified by:

isList in interface SExpression

free

public void free()

Destructive resource deallocation. Zeroes out data when possible.

Specified by:

free in interface SExpression

equals

public boolean equals(Object that)

See if this list is equal to the given list. The comparison is postitional, i.e. ((a) (b)) is not equal to ((b) (a)).

Specified by:

equals in interface SExpression

Overrides:

equals in class Object

Parameters:

that - Object to compare this list with. If the object is of some other class than sexp.SList, that's toString() method is called and the comparison done agains this list's first element.

Returns:

true if both objects are equal, false if they're not.

add

public SList add(SExpression sexp)

Add an S-Expression object to the end of this list. null values are silently ignored. The return value allows for chaining. Example:

System.out.println(new SList().add("Foo:").add(new SList().add("Bar").add("871326".getBytes())).toAdvanced()); Would print out:

 (Foo:
    (Bar "871326"))

Parameters:

sexp - object to add to this list

Returns:

reference to this list.

add

public SList add(String s)
          throws SexpException

Add a String object to the end of this list. The string s CANNOT be a list per se. The return value allows for chaining. See above for an example.

Parameters:

s - String object to add to this list

Returns:

reference to this list.

Throws:

SexpException - if something went wrong

add

public SList add(byte[] ba)
          throws SexpException

Add a byte array to the end of this list. The byte array ba CANNOT be a list per se. Use this method to add binary data to a list. The return value allows for chaining. See above for an example.

Parameters:

ba - Byte array to add to this list.

Returns:

reference to this list.

Throws:

SexpException - if something went wrong

add

public SList add(BigInteger bi)
          throws SexpException

Add a BigInteger to the end of this list. null-values are silently ignored. The return value allows for chaining. See above for an example.

Parameters:

bi - BigInteger to add to this list.

Returns:

reference to this list.

Throws:

SexpException - if something went wrong

insertAt

public void insertAt(SExpression obj,
                     int index)

Inserts the specified object as a component in this list at the specified index. Each element in this list with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously. The semantics are the same as those of java.util.Vector.insertElementAt().

Parameters:

obj - SExpression object to insert into this list

index - index to insert object at

Throws:

ArrayIndexOutOfBoundsException - if the index was invalid.

indexOf

public int indexOf(SExpression obj,
                   int index)

Searches for the first occurence of the given argument, beginning the search at the given index. The search uses the java.lang.Object.equals() method.

Parameters:

obj - SExpression to look for

index - starting index (0 = first element)

Returns:

index of SExpression, or -1 if not found.

indexOf

public int indexOf(SExpression obj)

Searches for the first occurence of the given argument, starting at the beginning of this list. The search uses the java.lang.Object.equals() method.

Parameters:

obj - SExpression to look for

Returns:

index of SExpression, or -1 if not found.

lastIndexOf

public int lastIndexOf(SExpression obj)

Searches for the last occurence of the given argument. The search uses the java.lang.Object.equals() method.

Parameters:

obj - SExpression to look for

Returns:

index of SExpression, or -1 if not found.

size

public int size()

Number of S-Expressions in this list. A list contains at least a single S-Expression. A sub-list is a single S-Expression.

Returns:

number of S-Expressions in this list

fetchAt

public SExpression fetchAt(int index)

Retrieve a indexed of S-Expressions from this list.

Returns:

the S-Expression at index in this list.

Throws:

ArrayIndexOutOfBoundsException - if index is out of range

item

public SExpression item(int index)

Retrieve a indexed of S-Expressions from this list. Syntactic sugar for fetchAt().

Returns:

the S-Expression at index in the list.

Throws:

ArrayIndexOutOfBoundsException - if index is out of range

See Also:

SList#fetchAt()

elements

public Enumeration elements()

Return this' list elements as an Enumeration. The Enumeration will contain only SExpression objects.

Returns:

Enumeration of this list.

getListsStartingWith

public Vector getListsStartingWith(String name)

Recursively search list for any sublists starting with name. A case-sensitive comparison is performed on the Advanced representation of the first S-Expression (ie. non-list) of this list and all sublists.

Parameters:

name - String to search for.

Returns:

Vector containing all matches (may be empty). All elements will be of the SLists class.

See Also:

SList#getListsMatching(), SList#lookup()

getListsStartingWith

private void getListsStartingWith(String name,
                                  Vector matches)

elementsOfListNamed

public Enumeration elementsOfListNamed(String name)

Recursively search this for the first sublist starting with name. A case-sensitive comparison is performed on the Advanced representation of the first S-Expression (ie. non-list) of this list and all sublists. An enumeration of the first matching list is returned. This enumeration will contain only SExpression objects. This differs from getListsStartingWith() in that the returned object is not a SList object, but an Enumeration of the components of the first matching list.

Parameters:

name - String to search for.

Returns:

Enumeration containing only SExpression objects of the first matching sublist, or null if there were no matches.

getListsMatching

public Vector getListsMatching(String regexp)

Recursively search list for any sublists which first element matches a regular expression. A PERL5-style regular-expression match is performed on the Advanced representation of the first S-Expression (ie. non-list) of this list and all sublists.

Parameters:

name - Regular expression to use.

Returns:

Vector containing all matches (may be empty). All elements will be of the SLists class.

See Also:

SList#getListsStartingWith(), SList#lookup()

getListsMatching

private void getListsMatching(gnu.regexp.RE re,
                              Vector matches,
                              boolean singlematch)

elementsOfListMatching

public Enumeration elementsOfListMatching(String regexp)

Recursively search this for the first sublist mathing the Regular Expression name. A PERL5-style regular-expression match is performed on the Advanced representation of the first S-Expression (ie. non-list) of this list and all sublists. An enumeration of the first matching list is returned. This enumeration will contain only SExpression objects. This differs from getListMatching() in that what's returned is not a SList object, but an Enumeration of the components of the matching list.

Parameters:

name - String to search for.

Returns:

Enumeration containing only SExpression objects of the first matching sublist, or null if there were no matches.

getListMatching

public SList getListMatching(String regexp)

Recursively search list for first sublist which first element matches a regular expression. A PERL5-style regular-expression match is performed on the Advanced representation of the first S-Expression (ie. non-list) of this list and all sublists. This method differs from getListsMatching in that this method stops at first match.

Parameters:

name - Regular expression to use.

Returns:

Matched SList, or null.

See Also:

SList#getListsStartingWith(), SList#getListsMatching(), SList#lookup()

makeLookupHash

public int makeLookupHash()

Make lookup hashtable. Make hash of list entries of the form (name S-Expression).

TODO: keep first or last value if some key already exist in the hashtable? Currently we keep the first. This should prehaps be otherwise, or even configurable.

Returns:

number of clashes, if any.

See Also:

SList#lookup()

lookup

public SList lookup(String name)

Recursively look up S-Expressions starting with name. Will call makeLookupHash() if neccessary.

Returns:

SList matching lookup criteritum, or null.

See Also:

makeLookupHash(), SList#getListsStartingWith(), SList#getListsMatching()

nr_lookup

public SList nr_lookup(String name)

Non-recursively look up S-Expressions starting with name. It simply iterates through the items and returns the first SList whoose first element matches the given String.

Parameters:

name - the name to look for.

Returns:

SList matching lookup criteritum, or null.