Krakatau Assembly Syntax
For a list of previous changes to the assembly syntax, see changelog.txt

Note: This documents the officially supported syntax of the assembler. The assembler accepts some files that don't fully conform to this syntax, but this behavior may change without warning in the future.

Lexical structure
Comments: Comments begin with a semicolon and go to the end of the line. Since no valid tokens start with a semicolon, there is no ambiguity. Comments are ignored during parsing.

Whitespace: At least one consecutive space or tab character

Lines that are empty except for whitespace or a comment are ignored. Many grammar productions require certain parts to be separated by a newline (LF/CRLF/CR). This is represented below by the terminal EOL. Due to the rules above, EOL can represent an optional comment, followed by a newline, followed by any number of empty/comment lines. There are no line continuations.

Integer, Long, Float, and Double literals use the same syntax as Java with a few differences:
* No underscores are allowed
* Doubles cannot be suffixed with d or D.
* Decimal floating point literals with values that can’t be represented exactly in the target type aren’t guaranteed to round the same way as in Java. If the exact value is significant, you should use a hexidecimal floating point literal.
* If a decimal point is present, there must be at least one digit before and after it (0.5 is ok, but .5 is not. 5.0 is ok but 5. is not).
* A leading plus or minus sign is allowed.
* Only decimal and hexadecimal literals are allowed (no binary or octal)
* For doubles, special values can be represented by +Infinity, -Infinity, +NaN, and -NaN (case insensitive). For floats, these should be suffixed by f or F.
* NaNs with a specific binary representation can be represented by suffixing with the hexadecimal value in angle brackets. For example, -NaN<0x7ff0123456789abc> or +NaN<0xFFABCDEF>f

Note: NaN requires a leading sign, even though it is ignored. This is to avoid ambiguity with WORDs. The binary representation of a NaN with no explicit representation may be any valid encoding of NaN. If you care about the binary representation in the classfile, you should specify it explicitly as described above.

String literals use the same syntax as Java string literals with the following exceptions
* Non printable and non-ascii characters, including tabs, are not allowed. These can be represented by escape sequences as usual. For example \t means tab.
* Either single or double quotes can be used. If single quotes are used, double quotes can appear unescaped inside the string and vice versa.
* There are three additional types of escape sequences allowed: \xDD, \uDDDD, and \UDDDDDDDD where D is a hexadecimal digit. The later two are only allowed in unicode strings (see below). In the case of \U, the digits must correspond to a number less than 0x00110000. \x represents a byte or code point up to 255. \u represents a code point up to 65535. \U represents a code point up to 1114111 (0x10FFFF), which will be split into a surrogate pair when encoded if it is above 0xFFFF.
* There are two types of string literals - bytes and unicode. Unicode strings are the default and represent a sequence of code points which will be MUTF8 encoded when written to the classfile. A byte string, represented by prefixing with b or B, represents a raw sequence of bytes which will be written unchanged. For example, "\0" is encoded to a two byte sequence while b"\0" puts an actual null byte in the classfile (which is invalid, but potentially useful for testing).

Reference: The classfile format has a large number of places where an index is made into the constant pool or bootstrap methods table. The assembly format allows you to specify the definition inline, and the assembler will automatically add an entry as appropriate and fill in the index. However, this isn’t acceptable in cases where the exact binary layout is important or where a definition is large and you want to refer to it many times without copying the definition each time.

For the first case, there are numeric references, designated by a decimal integer in square brackets with no leading zeroes. For example, [43] refers to the index 43 in the constant pool. For the second case, there are symbolic references, which is a sequence of lowercase ascii, digits, and underscores inside square brackets, not beginning with a digit. For example, [foo_bar4].

Bootstrap method references are the same except preceded by "bs:". For example, [bs:43] or [bs:foo_bar4]. These are represented by the terminal BSREF. Bootstrap method references are only used in very specific circumstances so you probably won’t need them. All other references are constant pool references and have no prefix, designated by the terminal CPREF.

Note: Constant pools and bootstrap method tables are class-specific. So definitions inside one class do not affect any other classes assembled from the same source file.

Labels refer to a position within a method’s bytecode. The assembler will automatically fill in each label with the calculated numerical offset. Labels consist of a capital L followed by ascii letters, digits, and underscores. A label definition (LBLDEF) is a label followed by a colon (with no space). For example, "LSTART:". Label uses are included in the WORD token type defined below since they don’t have a colon.

Note: Labels refer to positions in the bytecode of the enclosing Code attribute where they appear. They may not appear outside of a Code attribute.

Word: A string beginning with a word_start_character, followed by zero or more word_start_character or word_rest_characters. Furthermore, if the first character is a [, it must be followed by another [ or a capital letter (A-Z).

word_start_character: a-z, A-Z, _, $, (, <, [
word_rest_character: 0-9, ), >, /, ;, *, +, -

Words are used to specify names, identifiers, descriptors, and so on. If you need to specify a name that can’t be represented as a word (such as using forbidden characters), a string literal can be used instead. Words are represented in the grammar by the terminal WORD.

For example, 42 is not a valid word because it begins with a digit. A class named 42 can be defined as follows:

.class "42"

In addition, when used in a context following flags, words cannot be any of the possible flag names. These are currently public, private, protected, static, final, super, synchronized, open, transitive, volatile, bridge, static_phase, transient, varargs, native, interface, abstract, strict, synthetic, annotation, enum, module, and mandated. In addition, strictfp is disallowed to avoid confusion. So if you wanted to have a string field named bridge, you’d have to do

.field "bridge" Ljava/lang/String;

Format of grammar rules
Nonterminals are specified in lowercase. Terminals with a specific value required are specified in quotes. e.g. "Foo" means that the exact text Foo (case sensitive) has to appear at that point. Terminals that require a value of a given token type are represented in all caps, e.g. EOL, INT_LITERAL, FLOAT_LITERAL, LONG_LITERAL, DOUBLE_LITERAL, STRING_LITERAL, CPREF, BSREF, WORD, LBLDEF.

*, +, ?, |, and () have their usual meanings in regular expressions.

Common constant rules
s8: INT_LITERAL
u8: INT_LITERAL
s16: INT_LITERAL
u16: INT_LITERAL
s32: INT_LITERAL
u32: INT_LITERAL

ident: WORD | STRING_LITERAL
utfref: CPREF | ident
clsref: CPREF | ident
natref: CPREF | ident utfref
fmimref: CPREF | fmim_tagged_const
bsref: BSREF | bsnotref
invdynref: CPREF | invdyn_tagged_const

handlecode: "getField" | "getStatic" | "putField" | "putStatic" | "invokeVirtual" | "invokeStatic" | "invokeSpecial" | "newInvokeSpecial" | "invokeInterface"
mhandlenotref: handlecode (CPREF | fmim_tagged_const)
mhandleref: CPREF | mhandlenotref

cmhmt_tagged_const: "Class" utfref | "MethodHandle" mhandlenotref | "MethodType" utfref
ilfds_tagged_const: "Integer" INT_LITERAL | "Float" FLOAT_LITERAL | "Long" LONG_LITERAL | "Double" DOUBLE_LITERAL | "String" STRING_LITERAL
simple_tagged_const: "Utf8" ident |  "NameAndType" utfref utfref
fmim_tagged_const: ("Field" | "Method" | "InterfaceMethod") clsref natref
invdyn_tagged_const: "InvokeDynamic" bsref natref

ref_or_tagged_const_ldc: CPREF | cmhmt_tagged_const | ilfds_tagged_const
ref_or_tagged_const_all: ref_or_tagged_ldconst | simple_tagged_const | fmim_tagged_const | invdyn_tagged_const

bsnotref: mhandlenotref ref_or_tagged_const_ldc* ":"
ref_or_tagged_bootstrap: BSREF | "Bootstrap" bsnotref

Note: The most deeply nested possible valid constant is 6 levels (InvokeDynamic -> Bootstrap -> MethodHandle -> Method -> NameAndType -> Utf8). It is possible to create a more deeply nested constant definitions in this grammar by using references with invalid types, but the assembler may reject them.

ldc_rhs: CPREF | INT_LITERAL | FLOAT_LITERAL | LONG_LITERAL | DOUBLE_LITERAL | STRING_LITERAL | cmhmt_tagged_const

flag: "public" | "private" | "protected" | "static" | "final" | "super" | "synchronized" | "volatile" | "bridge" | "transient" | "varargs" | "native" | "interface" | "abstract" | "strict" | "synthetic" | "annotation" | "enum" | "mandated"
Basic assembly structure

assembly_file: EOL? class_definition*
class_definition: version? class_start class_item* class_end

version: ".version" u16 u16 EOL
class_start: class_directive super_directive interface_directive*
class_directive: ".class" flag* clsref EOL
super_directive: ".super" clsref EOL
interface_directive: ".implements" clsref EOL
class_end: ".end" "class" EOL

class_item: const_def | bootstrap_def | field_def | method_def | attribute

const_def: ".const" CPREF "=" ref_or_tagged_const_all EOL
bootstrap_def: ".bootstrap" BSREF "=" ref_or_tagged_bootstrap EOL

Note: If the right hand side is a reference, the left hand side must be a symbolic reference. For example, the following two are valid.
.const [foo] = [bar]
.const [foo] = [42]

While these are not valid.
.const [42] = [foo]
.const [42] = [32]

field_def: ".field" flag* utfref utfref initial_value? field_attributes? EOL
initial_value: "=" ldc_rhs
field_attributes: ".fieldattributes" EOL attribute* ".end" ".fieldattributes"

method_def: method_start (method_body | legacy_method_body) method_end
method_start: ".method" flag* utfref ":" utfref EOL
method_end: ".end" "method" EOL

method_body: attribute*
legacy_method_body: limit_directive+ code_body
limit_directive: ".limit" ("stack" | "locals") u16 EOL

Attributes
attribute: (named_attribute | generic_attribute) EOL
generic_attribute: ".attribute" utfref length_override? attribute_data
length_override: "length" u32
attribute_data: named_attribute | STRING_LITERAL

named_attribute: annotation_default | bootstrap_methods | code | constant_value | deprecated | enclosing_method | exceptions | inner_classes | line_number_table | local_variable_table | local_variable_type_table | method_parameters | runtime_annotations | runtime_visible_parameter_annotations | runtime_visible_type_annotations | signature | source_debug_extension | source_file | stack_map_table | synthetic

annotation_default: ".annotationdefault" element_value

bootstrap_methods: ".bootstrapmethods"
Note: The content of a BootstrapMethods attribute is automatically filled in based on the implicitly and explicitly defined bootstrap methods in the class. If this attribute’s contents are nonempty and the attribute isn’t specified explicitly, one will be added implicitly. This means that you generally don’t have to specify it. It’s only useful if you care about the exact binary layout of the classfile.


code: code_start code_body code_end
code_start: ".code" "stack" code_limit_t "locals" code_limit_t EOL
code_limit_t: u8 | u16
code_end: ".end" "code"

Note: A Code attribute can only appear as a method attribute. This means that they cannot be nested.

constant_value: ".constantvalue" ldc_rhs

deprecated: ".deprecated"

enclosing_method: ".enclosing" "method" clsref natref

exceptions: ".exceptions" clsref*

inner_classes: ".innerclasses" EOL inner_classes_item* ".end" "innerclasses"
inner_classes_item: cpref cpref utfref flag* EOL

line_number_table: ".linenumbertable" EOL line_number* ".end" "linenumbertable"
line_number: label u16 EOL

local_variable_table: ".localvariabletable" EOL local_variable* ".end" "localvariabletable"
local_variable: u16 "is" utfref utfref code_range EOL

local_variable_type_table: ".localvariabletypetable" EOL local_variable_type* ".end" "localvariabletypetable"
local_variable_type: u16 "is" utfref utfref code_range EOL

method_parameters: ".methodparameters" EOL method_parameter_item* ".end" "methodparameters"
method_parameter_item: utfref flag* EOL

runtime_annotations: ".runtime" visibility (normal_annotations | parameter_annotations | type_annotations) ".end" "runtime"
visibility: "visible" | "invisible"
normal_annotations: "annotations" EOL annotation_line*
parameter_annotations:  "paramannotations" EOL parameter_annotation_line*
type_annotations: "typeannotations" EOL type_annotation_line*


signature: ".signature" utfref

source_debug_extension: ".sourcedebugextension" STRING_LITERAL

source_file: ".sourcefile" utfref

stack_map_table: ".stackmaptable"

Note: The content of a StackMapTable attribute is automatically filled in based on the stack directives in the enclosing code attribute. If this attribute’s contents are nonempty and the attribute isn’t specified explicitly, one will be added implicitly. This means that you generally don’t have to specify it. It’s only useful if you care about the exact binary layout of the classfile.

Note: The StackMapTable attribute depends entirely on the .stack directives specified. Krakatau will not calculate a new stack map for you from bytecode that does not have any stack information. If you want to do this, you should try using ASM.

synthetic: ".synthetic"

Code

code_body: (instruction_line | code_directive)* attribute*
code_directive: catch_directive | stack_directive | ".noimplicitstackmap"

catch_directive: ".catch" clsref code_range "using" label EOL
code_range: "from" label "to" label

stack_directive: ".stack" stackmapitem EOL
stackmapitem: stackmapitem_simple | stackmapitem_stack1 | stackmapitem_append | stackmapitem_full
stackmapitem_simple: "same" | "same_extended" | "chop" INT_LITERAL
stackmapitem_stack1: ("stack_1" | "stack_1_extended") verification_type
stackmapitem_append: "append" vt1to3
vt1to3: verification_type verification_type? verification_type?
stackmapitem_full: "full" EOL "locals" vtlist "stack" vtlist ".end" "stack"
vtlist: verification_type* EOL

verification_type: "Top" | "Integer" | "Float" | "Double" | "Long" | "Null" | "UninitializedThis" | "Object" clsref | "Uninitialized" label

instruction_line: (LBLDEF | LBLDEF? instruction) EOL
instruction: simple_instruction | complex_instruction
simple_instruction: op_none | op_short u8 | op_iinc u8 s8 | op_bipush s8 | op_sipush s16 | op_lbl label | op_fmim fmimref | on_invint fmimref u8? | op_invdyn invdynref | op_cls clsref | op_cls_int clsref u8 | op_ldc ldc_rhs

op_none: "nop" | "aconst_null" | "iconst_m1" | "iconst_0" | "iconst_1" | "iconst_2" | "iconst_3" | "iconst_4" | "iconst_5" | "lconst_0" | "lconst_1" | "fconst_0" | "fconst_1" | "fconst_2" | "dconst_0" | "dconst_1" | "iload_0" | "iload_1" | "iload_2" | "iload_3" | "lload_0" | "lload_1" | "lload_2" | "lload_3" | "fload_0" | "fload_1" | "fload_2" | "fload_3" | "dload_0" | "dload_1" | "dload_2" | "dload_3" | "aload_0" | "aload_1" | "aload_2" | "aload_3" | "iaload" | "laload" | "faload" | "daload" | "aaload" | "baload" | "caload" | "saload" | "istore_0" | "istore_1" | "istore_2" | "istore_3" | "lstore_0" | "lstore_1" | "lstore_2" | "lstore_3" | "fstore_0" | "fstore_1" | "fstore_2" | "fstore_3" | "dstore_0" | "dstore_1" | "dstore_2" | "dstore_3" | "astore_0" | "astore_1" | "astore_2" | "astore_3" | "iastore" | "lastore" | "fastore" | "dastore" | "aastore" | "bastore" | "castore" | "sastore" | "pop" | "pop2" | "dup" | "dup_x1" | "dup_x2" | "dup2" | "dup2_x1" | "dup2_x2" | "swap" | "iadd" | "ladd" | "fadd" | "dadd" | "isub" | "lsub" | "fsub" | "dsub" | "imul" | "lmul" | "fmul" | "dmul" | "idiv" | "ldiv" | "fdiv" | "ddiv" | "irem" | "lrem" | "frem" | "drem" | "ineg" | "lneg" | "fneg" | "dneg" | "ishl" | "lshl" | "ishr" | "lshr" | "iushr" | "lushr" | "iand" | "land" | "ior" | "lor" | "ixor" | "lxor" | "i2l" | "i2f" | "i2d" | "l2i" | "l2f" | "l2d" | "f2i" | "f2l" | "f2d" | "d2i" | "d2l" | "d2f" | "i2b" | "i2c" | "i2s" | "lcmp" | "fcmpl" | "fcmpg" | "dcmpl" | "dcmpg" | "ireturn" | "lreturn" | "freturn" | "dreturn" | "areturn" | "return" | "arraylength" | "athrow" | "monitorenter" | "monitorexit"

op_short: "iload" | "lload" | "fload" | "dload" | "aload" | "istore" | "lstore" | "fstore" | "dstore" | "astore" | "ret"

op_iinc: "iinc"
op_bipush: "bipush"
op_sipush: "sipush"

op_lbl: "ifeq" | "ifne" | "iflt" | "ifge" | "ifgt" | "ifle" | "if_icmpeq" | "if_icmpne" | "if_icmplt" | "if_icmpge" | "if_icmpgt" | "if_icmple" | "if_acmpeq" | "if_acmpne" | "goto" | "jsr" | "ifnull" | "ifnonnull" | "goto_w" | "jsr_w"

op_fmim: "getstatic" | "putstatic" | "getfield" | "putfield" | "invokevirtual" | "invokespecial" | "invokestatic"
on_invint: "invokeinterface"
op_invdyn: "invokedynamic"

op_cls: "new" | "anewarray" | "checkcast" | "instanceof"
op_cls_int: "multianewarray"

op_ldc: "ldc" | "ldc_w" | "ldc2_w"

complex_instruction: ins_newarr | ins_lookupswitch | ins_tableswitch | ins_wide

ins_newarr: "newarray" nacode
nacode: "boolean" | "char" | "float" | "double" | "byte" | "short" | "int" | "long"

ins_lookupswitch: "lookupswitch" EOL luentry* defaultentry
luentry: s32 ":" label EOL
defaultentry: "default:" label

ins_tableswitch: "tableswitch" s32 EOL tblentry* defaultentry
tblentry: label EOL

ins_wide: "wide" (op_short u16 | op_iinc u16 s16)

label: WORD
Annotations
element_value_line: element_value EOL
element_value: primtag ldc_rhs | "string" utfref | "class" utfref | "enum" utfref utfref | element_value_array | "annotation" annotation_contents annotation_end
primtag: "byte" | "char" | "double" | "int" | "float" | "long" | "short" | "boolean"
element_value_array: "array" EOL element_value_line* ".end" "array"

annotation_line: annotation EOL
annotation: ".annotation" annotation_contents annotation_end
annotation_contents: utfref key_ev_line*
key_ev_line: utfref "=" element_value_line
annotation_end: ".end" "annotation"

parameter_annotation_line: parameter_annotation EOL
parameter_annotation: ".paramannotation" EOL annotation_line* ".end" "paramannotation"

type_annotation_line: type_annotation EOL
type_annotation: ".typeannotation" u8 target_info EOL target_path EOL type_annotation_rest
target_info: type_parameter_target | supertype_target | type_parameter_bound_target | empty_target | method_formal_parameter_target | throws_target | localvar_target | catch_target | offset_target | type_argument_target

type_parameter_target: "typeparam" u8
supertype_target: "super" u16
type_parameter_bound_target: "typeparambound" u8 u8
empty_target: "empty"
method_formal_parameter_target: "methodparam" u8
throws_target: "throws" u16

localvar_target: "localvar" EOL localvarrange* ".end" "localvar"
localvarrange: (code_range | "nowhere") u16 EOL

catch_target: "catch" u16
offset_target: "offset" label
type_argument_target: "typearg" label u8

target_path: ".typepath" EOL type_path_segment* ".end" "typepath"
type_path_segment: u8 u8 EOL

type_annotation_rest: annotation_contents ".end" "typeannotation"