An Oolong program is a set of directives. A directive is marked by a period (.) at the beginning of the line, followed by a keyword. Most directives take up exactly one line; the .method directive spans multiple lines and is terminated with the .end method. B.4.1 CommentsFormat ; any text DescriptionAn Oolong comment is written with a semicolon (;), and it lasts until the end of the line. Comments may appear by themselves on a line or in the middle of a directive or instruction. Examples; This is a comment .field count I ; Declare the field count as int new Foo ; Create a new instance of the Foo class invokevirtual Foo/bar ; Invoke the bar method on class Foo (I)V ; which takes an int and returns void B.4.2 .sourceFormat .source filename DescriptionCauses the assembler to generate a SourceFile attribute to the class file. This allows a debugger to locate the original source code when debugging the class file. The filename should be just the file name; it should not contain any directory information. ExamplesSuppose you translate a file called Hello.java into an Oolong class Hello.j. Add the following line to Hello.j: .source Hello.java B.4.3 .classFormat .class [public] [super] [abstract] [interface] [final] classname DescriptionDeclares the name of the class being created. The name includes the package name, separated by slashes (/). All directives following the .class declaration apply to this class. The meanings of the keywords are:
Examples.class Foo ; Declare Foo in the default ; package with default protection. ; The ACC_SUPER bit is not set. .class public super Moe/Bar ; Declare Bar in the package Moe ; to be public and with the ; ACC_SUPER bit set. .class super COM/sootNsmoke/oolong/Oolong ; Declare the class Oolong in the ; package COM/sootNsmoke/oolong ; with the ACC_SUPER bit set .class public super abstract java/io/Socket ; Declare the abstract class Socket .class public interface java/util/Enumeration ; Declare the interface Enumeration ; in the java/util package B.4.4 .interfaceFormat .interface classname DescriptionDeclares an interface class. The .interface directive is an abbreviation for .class public abstract interface Example.interface java/util/Enumeration ; Declare the interface ; Enumeration in the ; java/util package. B.4.5 .end classFormat.end class DescriptionOptional; marks the end of the class declaration. Example.class public super Foo ;; A set of field and method declarations of the class Foo. .end class ; End the declaration of class Foo B.4.6 .superFormat .super classname DescriptionDeclares the superclass of a class. If this declaration is not present, the superclass java/lang/Object is assumed. There may be at most one .super directive per class. Examples.super java/lang/Object ; Explicitly declare Object to be ; the superclass ; Declare this class to be a ; subclass of COM.sootNsmoke. ; instseq.instruction .super COM/sootNsmoke/instseq/Instruction B.4.7 .implementsFormat .implements interface-classname DescriptionDeclares the name of an interface that the class implements. The name interface-classname should name a class with the interface parameter set. This class should provide implementations for all methods declared in interface-classname. Examples.implements java/util/Enumeration ; This class should define ; hasMoreElements()Z and ; nextElement()Ljava/lang/ ; Object; B.4.8 .fieldFormat .field [public] [private] [protected] [static] [final] [volatile] [transient] fieldname descriptor DescriptionAdds a new field to the class file. The descriptor gives the type of the field. In the class file the bits corresponding to the keywords will be set. The meanings of the keywords follow.
ExamplesA static boolean field: .field static isEmpty Z A field that holds an array of arrays of ints: .field public matrix [[I A static transient field that holds an array of Strings: .field static transient cachedValues [Ljava/lang/String; B.4.9 .methodFormat .method [public] [private] [protected] [static] [final] [synchronized] [native] [abstract] methodname descriptor DescriptionAdds a new method to the class file. The descriptor describes the arguments and return types of the method. For each of the optional keywords in front of the method name, the corresponding bit is set in the access_flags of the method. Following the method description is a collection of instructions that form the implementation of the method (these instructions are described in section B.5). These instructions are compiled into a Code attribute that is added to the method. If the method is marked native or abstract, then the list of instructions should be empty and no Code attribute is generated. The method is terminated with the .end method directive, as described in section B.4.16. The meanings of the keywords follow.
ExamplesA static method that takes an array of Strings as an argument, returning void: .method public static main([Ljava/lang/String;)V return .end method An abstract method that takes no arguments and returns an Object: .method public nextElement()Ljava/lang/Object; ; No method body, since this is an abstract method .end method A constructor that takes two arguments, a String and a boolean: .method public <init>(Ljava/lang/String;Z)V ;; Body of the method goes here .end method A synchronized method: .method synchronized write(Ljava/lang/String;)V ;; In here, the thread has a lock on the object in variable 0 .end method B.4.10 .limit localsFormat .limit locals limit DescriptionSets the limit on local variables. If not given, the assembler will try to compute it. Examples.method add(II)I .limit locals 5 ; Use up to 5 local variables ; Variable 0 is this ; Variables 1 and 2 are the arguments ; Variables 3 and 4 may be used for any ; purpose B.4.11 .limit stackFormat .limit stack limit DescriptionSets the limit on the amount of stack that may be used in the execution of the method. If not given, the assembler will try to compute it. Examples.method public static main([Ljava/lang/String;)V .limit stack 2 ; This method uses at most ; 2 stack entries ; Stack height is initially 0 getstatic java/lang/System/out Ljava/io/PrintStream; ; Stack height is now 1 ldc "Hello, world" ; Stack height is now 2 invokevirtual java/io/PrintStream/println(Ljava/lang/String;)V ; Stack height is now 0 return .end method B.4.12 .lineFormat .line number DescriptionInstructs the assembler to generate an entry in the LineNumberTable attribute for the method. The instruction after the .line directive is marked as the first instruction corresponding to the line numbered number in the original source code. This information is used by debuggers to match bytecodes to the original source if the Oolong program is generated as an intermediate result from some other language. ExampleIf you have the Java program in Hello.java: class Hello // Line 1 { // Line 2 public static void main(String a[]) // Line 3 { // Line 4 System.out.println("Hello, world"); // Line 5 return; // Line 6 } // Line 7 } // Line 8 If this were translated into Oolong, but you want to use the resulting class file to debug the original source, the .line directives would look like this: .source Hello.java .method static main([Ljava/lang/String;)V .line 5 getstatic java/lang/System/out Ljava/io/PrintStream; aload "Hello, world" invokevirtual java/io/PrintStream/println (Ljava/lang/String;)V .line 6 return .end method B.4.13 .varFormat.var number is name type [from begin to end] DescriptionFor debugging purposes, assigns the name to the local variable numbered number. That variable is expected to have a value that conforms to the type specified by type. If begin and end are given, then the name applies to that local variable only in that range. Otherwise, it applies to the entire method. ExampleIn this example, the class Foo has a field called temperatures, which is an array of floats. In the find_temp method, variable 0 is called this through the entire range of the method. Variable 1 is passed in as an argument. Variable 1 is an int called i from range1 to range2. After i is used as an index into the temperatures array, it is no longer necessary. Variable 1 is now used to store temp, which is a float value. .class Foo .field temperatures [F .method find_temp(I)F .var 0 is this LFoo; .var 1 is i I from range1 to range2 .var 1 is temp F from range2 to range3 range1: aload_0 ; Get this, which should be a Foo ; Get the temperatures field getfield Foo/temperatures [F ; Here, variable 1 should be an int. The debugger will know ; it by the name i iload_1 ; push i faload ; Get a temperature fstore_1 ; Store the temperature in 1 range2: ; Variable 1 no longer contains i. Now it contains ; temp, which is a float fload_1 ; Retrieve temp freturn ; Return it range3: .end method B.4.14 .throwsFormat .throws classname DescriptionAdds classname to the Exceptions attribute for the method, letting a Java compiler know that the method may throw the exception named classname. Several .throws directives may appear in each method. The effect is cumulative; the method may throw any of the listed exceptions. Examples.throws java/lang/Throwable ; May throw anything .throws java/io/SecurityException ; This method may throw a .throws java/lang/InterruptedException ; SecurityException or an ; InterruptedException B.4.15 .catchFormat.catch classname from label1 to label2 using label3 DescriptionDesignates label3 as an exception handler for the class classname in the range of instructions from label1 to label2. Includes the instruction after label1 but does not include the instruction after label2. If classname is all, then all exceptions will be caught. This corresponds to a catch_type entry of 0 in the method's exception_table. Examples.catch java/lang/NullPointerException from begin to end using handler ;; Code here is not in the exception handler begin: ;; If a NullPointerException is thrown from here to end, then ;; control will pass to handler end: ;; This is outside the exception range again handler: ;; If a NullPointerException is thrown from begin to end, then ;; control passes here. The top of the stack will contain ;; the caught exception The .catch all is used for something that absolutely must be done. For example, in this piece of code, the OutputStream in variable 1 must be closed, even if an exception is thrown: .var 1 is out java/io/OutputStream .catch all from try_begin to try_end using finally try_begin: ;; Write some stuff to out ; If the write was successful, then close out aload_1 invokevirtual java/io/OutputStream/close ()V return try_end: finally: ; Even if the write was unsuccessful, ; make sure that the stream is closed aload_1 invokevirtual java/io/OutputStream/close ()V return B.4.16 .end methodFormat.end method DescriptionMarks the end of a method. There should be one .end method directive for each .method directive. Examples.method public toString()Ljava/lang/String; ;; Body of the toString method .end method |