ReadTable

Overview

This topic discusses how the Common Lisp Readtable is implemented in CLforJava.

The ReadTable is used by the TheReader to determine what character TheReader has encountered. A ReadTable can also contain associations between macro characters and their macro functions. In addition to these requirments, the ReadTable must also record information about the case of a character which effects the TheReader.

Like ANSI Lisp, the CLforJava will allow the Lisp programmer to customize the macro characters and macro functions of the readtable. However, the Readtable is only responsible for storing these modifications during the execution of the CLforJava. That is to say that upon startup the Readtable will initialize to the default "Standard Readtable".

Current proposal

The current implementation proposal is to define an array containing the 96 ASCII characters in an array, more commonly refered to as the Standard Readtable. The character's numerical value will act as the indexing scheme for storage and look up within the array. The character syntax types are constitiuent, whitespace, terminating macro, non-terminating macro, single escape, multiple escape, and invalid**. The idea is to use an enumerated type to define these as constants in a seperate Java class. Details on enumeration can be found at Topic 21 of the book Effective Java and you can find more information about the syntax types in the Lisp Hyper Spec listing of Syntax Types.

**NOTE: For the initial implementation of the Readtable an Invalid macro type is not handled

Here is an example of the Enumerated character syntax type described above. Defining this class in this manner gives us a type safe implementation of the Character attributes necessary to both TheReader and ReadTable.

** NOTE: Still a few extraneous methods in the interface (removed). And some spelling mistakes. - JB ** SUGGESTION: In the implementation, it's fine to use Hashmaps. But you should declare the variables to be of type Map. That gives you leeway to change the implementation.

Interface Readtable

The following is a Readtable interface which will define the methods available to TheReader and Lisp Programmer for access to the readtable.

public interface Readtable extends Atom {
    /**
     * This is the Java definition of the Lisp type READTABLE
     */
    public static final Symbol typeName = Symbol.Factory.newInstance("READTABLE", "COMMON-LISP");

    /** 
     * An inner class that defines the Syntax Types of characters
     */
    public class SyntaxType {
       
        public static final SyntaxType CONSTITUENT     = new SyntaxType("CONSTITUENT");   
        public static final SyntaxType NON_TERMINATING = new SyntaxType("NON_TERMINATING");   
        public static final SyntaxType TERMINATING     = new SyntaxType("TERMINATING");   
        public static final SyntaxType WHITESPACE      = new SyntaxType("WHITESPACE");   
        public static final SyntaxType INVALID         = new SyntaxType("INVALID");   
        public static final SyntaxType SINGLE_ESCAPE   = new SyntaxType("SINGLE_ESCAPE");   
        public static final SyntaxType MUTIPLE_ESCAPE  = new SyntaxType("MUTIPLE_ESCAPE");    

        private String name;
    
        /** Creates a new instance of Readtable */
        private Readtable(String name) {
            this.name = name;
        }
    
        public String toString() {
            return name;
        }   
    }

    // These the public methods implemented by the Readtable implementation in another package

    public Object clone();   
    
    public Function2 getDispatchMacroCharacter(char rootChar,  char subChar); 
                                               
    public SyntaxType getMacroCharacter(char c);
    
    public boolean makeDispatchMacroCharacter(char c);   
               
    public Symbol setDispatchMacroCharacter(char rootChar, char subChar, Function2 newFunction);    
    
    public Symbol setMacroCharacter(char newFunction);    
        
    public boolean setSyntaxFromChar(char fromChar, char toChar);    
    
    public boolean setSyntaxFromChar(char fromChar, char toChar, Readtable fromReadtable);     
}

Next the ReadTable will need two objects similar to a Hashtable capable of storing function, names or values. This will be implemented using an Object known in Java as a Hashmap. This structure allows us to bind functions, values, or names to a paticular character as a pair set. In addition this structure contains similarities to and allows for future storage into Hashtables if the need arises in later implementations. There are two cases in which we will need to access these Hashmaps.

Case 1

When we encounter a syntax type equal to that of Non_Terminating character. Therefore we must look in the function hashmap for the function associated with the character returning the fucntion we found.

Case 2

In the event that the reader encounters a character not contained within the Standard Readtable array, then we must search for the character within the Unicode Block we will then store this character and its associated type in the exception hash map. The solution for this problem may be found by defining a method similar to the "of" method used in the Character.Subset class.

Combining these attributes of a ReadTable with the necassary functionality described in the Hyperspec Readtable we can begin to define an interface for the ReadTable.

Class ReadtableImplementation

The functional description for each of these methods follows.

Function2 getDispatchMacroCharacter(char rootChar,char subChar)

getDispatchMacroCharacter retrieves the dispatch function associated with rootChar and subChar in readtable. 

SyntaxType getMacroCharacter(char c, Readtable readtable)

getMacroCharacter returns the character SyntaxType associated with the character

boolean makeDispatchMacroCharacter(char c)

makeDispatchMacroCharacter makes char be a dispatching macro character in readtable.

Symbol setDispatchMacroCharacter(char rootChar, char subChar, Function2 newFunction)

setDispatchMacroCharacter sets the dispatching macro character for the Function2 argument.  Returns
a Symbol type.

***It is an error if sub-char is one of the ten decimal digits.

readtableCase(Readtable readtable)

**Note: The actual check for readtable-case is the value of a special variable in the Lisp environment.

Accesses the readtable case of readtable, which affects the way in which the Lisp Reader reads symbols and the way in which the Lisp Printer writes symbols.

setMacroCharacter(char newFunction)

setMacroCharacter causes char to be a macro character associated with the reader macro function newFunction (or the designator for new-function) in readtable. If the sytax type is equal to NON_TERMINATING, char becomes a non-terminating macro character; otherwise it becomes a terminating macro character.

boolean setSyntaxFromChar(char fromChar, char toChar)

setSyntaxFromChar copies the syntax types of fromChar. If fromChar is a macro character, its reader macro function is copied also. If the character is a dispatching macro character, its entire dispatch table of reader macro functions is copied. The constituent traits of fromChar are not copied. 

boolean setSyntaxFromChar(char fromChar, char toChar, Readtable fromReadtable)

setSyntaxFromChar makes the syntax of toChar in the fromReadtable the same as the syntax of the toChar.

---

After defining a Readtable Interface we now have the basis for implementing our Readtable.

public class ReadtableImpl implements lisp.common.Readtable { 
     
    private Hashmap functionHashMap = new Hashmap();
    private Hashmap exceptionHashMap = new Hashmap();

    public Readtable(){
        //intialize hashmaps and call the clone method method.          
    }
    //implement the Readtable methods...
}

References

• ReadtableAdapter

HyperSpec	CLtL
Character Syntax Types	Link 2

Implementation

Details of implementation

Core Java Classes	Javadoc Links

Discussions

Links to Blog issues

Test Suites

Links to JUnit results

Job Tracking

%ACTION{ closed="9-Dec-2003" due="8-Dec-2003" creator="Main.DottieChappell" uid="000169" state="closed" created="2-Dec-2003" who="Main.JamesCrawford" closer="" notify="Main.JamesCrawford" }% Clean up code per Jerry's code review R12

-- JerryBoetje - 11 Jul 2003

Current Status of ReadTable