001    package sexp;
002    
003    import java.util.Iterator;
004    
005    /**
006     * SList represents an expression consisting of a list of subexpressions, e.g. (a b c).
007     * The methods of SList offer three patterns for iterating over the subexpressions:
008     * <ul>
009     * <li>By removing the first element: use first(), rest(), and isEmpty().
010     * <li>By indexing down the list: use get() and size().
011     * <li>By Iterator: use iterator() or the for(var:list) {...} syntax.
012     * </ul> 
013     */
014    public interface SList extends SExp, Iterable<SExp> {    
015        /**
016         * @return 
017         */
018        boolean isEmpty();
019    
020        /**
021         * @requires this list is not empty
022         * @return first expression in this list
023         */
024        SExp first();
025        
026        /**
027         * @requires this list is not empty
028         * @return remaining expressions after removing the first
029         */
030        SList rest();
031        
032        /**
033         * @return number of subexpressions, i.e. elements in this list 
034         */
035        int size();
036    
037        /**
038         * @requires 0 <= i < size()
039         * @return ith element of this list, numbered from 0
040         */
041        SExp get(int i);
042    
043        /**
044         * @return iterator that yields the subexpressions of this list
045         * in order from left to right
046         */
047        Iterator<SExp> iterator();
048    }