Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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-array`input.
`SList(InputStream input)` Build list object from `byte-array`input.
`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-array`input. 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-array`input. 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`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD