inf.compilers
Interface SyntaxAdaptable

public interface SyntaxAdaptable

This interface declares an instance to have one or more external syntactical representations, which is given by a sequence of characters. A SyntaxAdaptor must be used bridge between the internal representation, i.e. the Java Object, and the external representation, i.e. the sequence of characters. For a class to implement this interface effectively means it can be written to a Writer and read (or parsed) from a Reader.

Normally, Java Objects can be written out using their toString() function and then printing the result. However there is no functionality at the Object level for the reverse process, converting the String back to an Object. Furthermore, the toString() method produces output adhering one fixed syntax only.

This interface addresses these issues in the following ways: two methods, write(...) and prettyPrint(...), are similar to the toString() method in that they generate printable output. However, instead of producing a String they take a Writer to which the generated output is written. This may be useful if the output is very long, in which case there is no need to hold it in memory at any one time. A String can still be produced using a StringWriter and defining the toString() method of the class implementing SyntaxAdaptable as follows:

 public String toString() {
        StringWriter w = new StringWriter();
        this.write(w, adaptor);
        w.close();
        return w.toString();
 }
 

The second argument taken by the write-method is a SyntaxAdaptor. A SyntaxAdaptor handles the translation between an instance of a SyntaxAdaptable, i.e. a Java object in the heap, and a sequence of characters that represent this instance in human-readable form. By explicitly providing a SyntaxAdaptor to the write-method it is possible to produce different syntaxes for the external representation, depending on which SyntaxAdaptor is supplied.

Reading should be implemented through a static function that cannot be defined in this interface. The signature for this function should look as follows:

 static public SyntaxAdaptable read(Reader r, SyntaxAdaptor adaptor)
         throws ExpressivenessException, ParseException, IOException;
 

Implementing a SyntaxAdaptable is quite simple as most of the interesting work is usually performed by the SyntaxAdaptor. Thus, the following code is all that is required to implement this interface:

 public void write(Writer w, SyntaxAdaptor adaptor)
         throws ExpressivenessException, IOException {
     adaptor.write(this, w);
 }
 
 public void prettyPrint(int indent, Writer w, SyntaxAdaptor adaptor)
         throws ExpressivenessException, IOException {
     adaptor.prettyPrint(indent, this, w);
 }
 
 static public R read(Reader r, SyntaxAdaptor<R> adaptor)
         throws ExpressivenessException, ParseException, IOException {
     return (R) adaptor.read(r);
 }
 

Note that, in the static read(...) method, the class parameter R must be replaced by the class implementing the SyntaxAdaptable interface. The warnings given by the two output methods can be safely ignored (or suppressed).

Author:

Gerhard Wickler

See Also:

SyntaxAdaptor

Method Summary

void	prettyPrint(int indent, java.io.Writer w, SyntaxAdaptor<? extends SyntaxAdaptable> adaptor) This function can be used to write this SyntaxAdaptable object to the given Writer.
void	write(java.io.Writer w, SyntaxAdaptor<? extends SyntaxAdaptable> adaptor) This function can be used to write this SyntaxAdaptable object to the given Writer.

Method Detail

write

void write(java.io.Writer w,
           SyntaxAdaptor<? extends SyntaxAdaptable> adaptor)
           throws ExpressivenessException,
                  java.io.IOException

This function can be used to write this SyntaxAdaptable object to the given Writer. The syntax in which it is written is defined by the SyntaxAdaptor that is also given to this function.

Parameters:

w - the Writer to which this SyntaxAdaptable is written

adaptor - the SyntaxAdaptor that determines the syntax

Throws:

ExpressivenessException - if the syntax does not support every construct occurring in this SyntaxAdaptable

java.io.IOException - if writing to the Writer fails

prettyPrint

void prettyPrint(int indent,
                 java.io.Writer w,
                 SyntaxAdaptor<? extends SyntaxAdaptable> adaptor)
                 throws ExpressivenessException,
                        java.io.IOException

This function can be used to write this SyntaxAdaptable object to the given Writer. The syntax is the same as for normal writing. The only difference is the inclusion of extra space and newlines for better readability.

Parameters:

indent - the amount of indentation for the first line

w - the Writer to which this SyntaxAdaptable is written

adaptor - the SyntaxAdaptor that determines the syntax

Throws:

ExpressivenessException - if the syntax does not support every construct occurring in this SyntaxAdaptable

java.io.IOException - if writing to the Writer fails