Utility routines for dealing with bytecode-level names. Includes universal mangling rules for the JVM.

Avoiding Dangerous Characters

The JVM defines a very small set of characters which are illegal in name spellings. We will slightly extend and regularize this set into a group of dangerous characters. These characters will then be replaced, in mangled names, by escape sequences. In addition, accidental escape sequences must be further escaped. Finally, a special prefix will be applied if and only if the mangling would otherwise fail to begin with the escape character. This happens to cover the corner case of the null string, and also clearly marks symbols which need demangling.

Dangerous characters are the union of all characters forbidden or otherwise restricted by the JVM specification, plus their mates, if they are brackets ([ and ], < and >), plus, arbitrarily, the colon character :. There is no distinction between type, method, and field names. This makes it easier to convert between mangled names of different types, since they do not need to be decoded (demangled).

The escape character is backslash \ (also known as reverse solidus). This character is, until now, unheard of in bytecode names, but traditional in the proposed role.

Replacement Characters

Every escape sequence is two characters (in fact, two UTF8 bytes) beginning with the escape character and followed by a replacement character. (Since the replacement character is never a backslash, iterated manglings do not double in size.)

Each dangerous character has some rough visual similarity to its corresponding replacement character. This makes mangled symbols easier to recognize by sight.

The dangerous characters are / (forward slash, used to delimit package components), . (dot, also a package delimiter), ; (semicolon, used in signatures), $ (dollar, used in inner classes and synthetic members), < (left angle), > (right angle), [ (left square bracket, used in array types), ] (right square bracket, reserved in this scheme for language use), and : (colon, reserved in this scheme for language use). Their replacements are, respectively, | (vertical bar), , (comma), ? (question mark), % (percent), ^ (caret), _ (underscore), and { (left curly bracket), } (right curly bracket), ! (exclamation mark). In addition, the replacement character for the escape character itself is - (hyphen), and the replacement character for the null prefix is = (equal sign).

An escape character \ followed by any of these replacement characters is an escape sequence, and there are no other escape sequences. An equal sign is only part of an escape sequence if it is the second character in the whole string, following a backslash. Two consecutive backslashes do not form an escape sequence.

Each escape sequence replaces a so-called original character which is either one of the dangerous characters or the escape character. A null prefix replaces an initial null string, not a character.

All this implies that escape sequences cannot overlap and may be determined all at once for a whole string. Note that a spelling string can contain accidental escapes, apparent escape sequences which must not be interpreted as manglings. These are disabled by replacing their leading backslash with an escape sequence (\-). To mangle a string, three logical steps are required, though they may be carried out in one pass:

1. In each accidental escape, replace the backslash with an escape sequence (\-).
2. Replace each dangerous character with an escape sequence (\| for /, etc.).
3. If the first two steps introduced any change, and if the string does not already begin with a backslash, prepend a null prefix (\=).

To demangle a mangled string that begins with an escape, remove any null prefix, and then replace (in parallel) each escape sequence by its original character.

Spelling strings which contain accidental escapes must have them replaced, even if those strings do not contain dangerous characters. This restriction means that mangling a string always requires a scan of the string for escapes. But then, a scan would be required anyway, to check for dangerous characters.

Nice Properties

If a bytecode name does not contain any escape sequence, demangling is a no-op: The string demangles to itself. Such a string is called self-mangling. Almost all strings are self-mangling. In practice, to demangle almost any name “found in nature”, simply verify that it does not begin with a backslash.

Mangling is a one-to-one function, while demangling is a many-to-one function. A mangled string is defined as validly mangled if it is in fact the unique mangling of its spelling string. Three examples of invalidly mangled strings are \=foo, \-bar, and baz\!, which demangle to foo, \bar, and baz\!, but then remangle to foo, \bar, and \=baz\-!. If a language back-end or runtime is using mangled names, it should never present an invalidly mangled bytecode name to the JVM. If the runtime encounters one, it should also report an error, since such an occurrence probably indicates a bug in name encoding which will lead to errors in linkage. However, this note does not propose that the JVM verifier detect invalidly mangled names.

As a result of these rules, it is a simple matter to compute validly mangled substrings and concatenations of validly mangled strings, and (with a little care) these correspond to corresponding operations on their spelling strings.

• Any prefix of a validly mangled string is also validly mangled, although a null prefix may need to be removed.
• Any suffix of a validly mangled string is also validly mangled, although a null prefix may need to be added.
• Two validly mangled strings, when concatenated, are also validly mangled, although any null prefix must be removed from the second string, and a trailing backslash on the first string may need escaping, if it would participate in an accidental escape when followed by the first character of the second string.

If languages that include non-Java symbol spellings use this mangling convention, they will enjoy the following advantages:

• They can interoperate via symbols they share in common.
• Low-level tools, such as backtrace printers, will have readable displays.
• Future JVM and language extensions can safely use the dangerous characters for structuring symbols, but will never interfere with valid spellings.
• Runtimes and compilers can use standard libraries for mangling and demangling.
• Occasional transliterations and name composition will be simple and regular, for classes, methods, and fields.
• Bytecode names will continue to be compact. When mangled, spellings will at most double in length, either in UTF8 or UTF16 format, and most will not change at all.

Suggestions for Human Readable Presentations

For human readable displays of symbols, it will be better to present a string-like quoted representation of the spelling, because JVM users are generally familiar with such tokens. We suggest using single or double quotes before and after mangled symbols which are not valid Java identifiers, with quotes, backslashes, and non-printing characters escaped as if for literals in the Java language.

For example, an HTML-like spelling <pre> mangles to \^pre\_ and could display more cleanly as '<pre>', with the quotes included. Such string-like conventions are not suitable for mangled bytecode names, in part because dangerous characters must be eliminated, rather than just quoted. Otherwise internally structured strings like package prefixes and method signatures could not be reliably parsed.

In such human-readable displays, invalidly mangled names should not be demangled and quoted, for this would be misleading. Likewise, JVM symbols which contain dangerous characters (like dots in field names or brackets in method names) should not be simply quoted. The bytecode names \=phase\,1 and phase.1 are distinct, and in demangled displays they should be presented as 'phase.1' and something like 'phase'.1, respectively.