BNF Grammar - RetroGuard Documentation

Here is a BNF grammar (Backus-Naur Form) for the RetroGuard script file format.

1. <script> ::= <script_line>*
2. <script_line> ::= [<comment> | <exclusion> | <nowarn>] "\n"
3. <exclusion> ::= (<option_enable> | <attribute_exc> | <class_exc> | <method_exc> | <field_exc>) [<comment>]
4. <nowarn> ::= ".nowarn" <class_spec_wc> [<comment>]
5. <comment> ::= "#" <character>*
6. <character> ::= "\040"-"\176"
7. <option_enable> ::= ".option" ("Application" | "Applet" | "Serializable" | "RMI" | "MapClassString" | "DigestMD5" | "DigestSHA" | "RuntimeAnnotations" | "Annotations" | "Enumeration" | "Generic" | "LineNumberDebug" | "Trim" | "Repackage")
8. <attribute_exc> ::= ".attribute" ("SourceFile" | "LocalVariableTable" | "LineNumberTable" | "Deprecated" | "Signature" | "LocalVariableTypeTable" | "EnclosingMethod" | "RuntimeInvisibleAnnotations" | "RuntimeInvisibleParameterAnnotations" | "RuntimeVisibleAnnotations" | "RuntimeVisibleParameterAnnotations" | "AnnotationDefault")
9. <class_exc> ::= (".class" | "!class") [(";" <class_access_flag>)*] <class_spec_wc> [("public" | "protected" | "pub_prot_only") ["method" | "field"]] [<extends_clause>]
10. <method_exc> ::= (".method" | "!method") [(";" <method_access_flag>)*] <method_field_spec> <method_descriptor> ["and_class"] [<extends_clause>]
11. <field_exc> ::= (".field" | "!field") [(";" <field_access_flag>)*] <method_field_spec> <java_type> ["and_class"] [<extends_clause>]
12. <extends_clause> ::= "extends" <class_spec>
13. <class_access_flag> ::= ["!"]("public" | "final" | "interface" | "abstract" | "annotation" | "enum")
14. <method_access_flag> ::= ["!"]("public" | "private" | "protected" | "static" | "final" | "synchronized" | "bridge" | "varargs" | "native" | "abstract" | "strict")
15. <field_access_flag> ::= ["!"]("public" | "private" | "protected" | "static" | "final" | "volatile" | "transient" | "enum")
16. <method_field_spec> ::= <class_spec_wc>"/"<java_identifier>
17. <method_descriptor> ::= "("<java_type>*")"<java_type>
18. <java_type> ::= ("["<java_type>) | "B" | "C" | "D" | "F" | "I" | "J" | "S" | "V" | "Z" | ("L"<class_spec>";")
19. <class_spec> ::= ((<java_identifier>"/")*)((<java_identifier>"$")*)<java_identifier>
20. <class_spec_wc> ::= <class_spec> | (((<java_identifier>"/")*)("*" | "**"))
21. <java_identifier> ::= <java_letter><java_letter_or_digit>*
22. <java_letter> is a Unicode character for which java.lang.Character.isJavaIdentifierStart() is true
23. <java_letter_or_digit> is a Unicode character for which java.lang.Character.isJavaIdentifierPart() is true

Notes:

• Script grammar changes (backwards compatible with prior scripts) introduced in RetroGuard-v2.0.1 are:
  • '.option' entries 'Application', 'Applet', 'Serializable', 'RMI', 'MapClassString', 'DigestMD5', 'DigestSHA';
  • package-recursive wildcard '**';
  • inclusion commands '!class' and '!method' and '!field';
  • 'and_class' modifier to '.method', '!method', '.field', '!field';
  • 'extends' modifier to '.class', '!class', '.method', '!method', '.field', '!field';
  • access modifiers (for example, '.field;private;!final;!static') for commands '.class', '!class', '.method', '!method', '.field', '!field'.
• In RetroGuard-v2.0.1 and later, the default behavior is to include no message digests in the output jar manifest. Message digests can be included with the '.option DigestSHA' and '.option DigestMD5' commands. Prior to this (RetroGuard-v1.1.16 and earlier) the default was to create both MD5 and SHA-1 digests in the output jar manifest for all classes and resource files.
• Interfaces are not treated separately from classes. The '.class' token can also refer to an interface.
• The Java virtual machine syntax is used for specifying types. These types are:
  • 'B' = byte
  • 'C' = char
  • 'D' = double
  • 'F' = float
  • 'I' = int
  • 'J' = long
  • 'S' = short
  • 'V' = void
  • 'Z' = boolean
  • 'LCOM/widgetco/MyClass;' = the type of class MyClass in package COM.widgetco
  • '[B' = a 1-dimensional array of bytes
  • '[[Ljava/lang/String;' = a 2-dimensional array of Strings
  For a full description of this syntax, see The Java(TM) Virtual Machine Specification (2nd Edition) by Yellin and Lindholm.
• Fully qualified class, method and field identifiers are used. So, for a class 'MyClass' with method 'void aMethod(boolean isSet)' and field 'float aField' in a package 'COM.widgetco', the script entries to reserve these identifiers would be:
  • .class COM/widgetco/MyClass
  • .method COM/widgetco/MyClass/aMethod (Z)V
  • .field COM/widgetco/MyClass/aField F