Crate java_signatures

Validates/Parses Java Type Signatures according to the syntax specified by the JVM speicification.

This crate does not attempt to parse entire java classfiles. Instead, it focuses merely on parsing signature strings located as attributes in classfiles. For parse classfiles themselves we do already have a number of very nice crates on crates.io. Only some of them do parse the signature string and provide a model over them. This crate is supposed to supplement those classfile parsers which reveal the signatures as pure strings.

The signature parsers provided by this create are strinct in the sense thaat the entirely input string must be matched according to the syntax rules. Leaing (whitespace) to trailing characters are not tolerated.

Example:

use java_signatures::{parse_class_signature, ReferenceType, ClassType, SimpleClassType};

// ~ a signature corresponding to a `class Bar<T extends Serializable & Comparable<T>> {..}`
// ~ to be obtained from a classfile using a corresponding parser, for example `cafebabe`
let s = "<T::Ljava/io/Serializable;:Ljava/lang/Comparable<TT;>;>Ljava/lang/Object;";
match parse_class_signature(s) {
    Ok(parsed) => {
        // ~ access to the individual parts of the signature
        assert_eq!(1, parsed.type_params.len());
        assert_eq!("T", parsed.type_params[0].name);
        assert!(parsed.type_params[0].class_bound.is_none());
        assert_eq!(2, parsed.type_params[0].iface_bounds.len());
        assert!(matches!(
            &parsed.type_params[0].iface_bounds[0],
            ReferenceType::Class(ClassType {
                base: SimpleClassType {
                    name: "java/io/Serializable",
                    ..
                },
                ..
            })
        ));
        // ...

        // ~ the `Display` implementation of the parsed
        // signature will produce the original signature
        // string again
        assert_eq!(s, format!("{parsed}"));
    }
    Err(e) => {
        eprintln!("invalid class signature:");
        eprintln!("> {}", e.signature());
        eprintln!("> {}^-- {e}", " ".repeat(e.position()));
    }
}

Structs

ArrayType

Represents an array type.

ClassSignature

A parse class signature; encodes type information about a (possibly generic) class or interface declaration. It describes any type parameters of the class or interface, and lists its (possibly parameterized) direct superclass and direct superinterfaces, if any. A type parameter is described by its name, followed by any class bound and interface bounds.

ClassType

Represents (a possibly nested, and possible type-parameterized) class type.

FieldSignature

A parsed field signature; encodes the (possibly parameterized) type of a field, formal parameter, local variable, or record component declaration.

MethodSignature

A parsed method signature; encodes type information about a (possibly generic) method declaration. It describes any type parameters of the method; the (possibly parameterized) types of any formal parameters; the (possibly parameterized) return type, if any; and the types of any exceptions declared in the method’s throws clause.

ParseError

Error signaling a signature parse failure. The error references the originally parsed string providing convenience methods to inspect where the error occurred.

SimpleClassType

Represents a simple (ie. not nested) and possibly type-parametrized class type.

TypeParameter

Represents type variables in declaration position, e.g. as part of a class or method declaration which introduces variable types.

Enums

BaseType

Represents a primitive java type.

JavaType

Represents a primitive or reference type.

ReferenceType

Represents a reference type, ie. a class, an array, or a type variable.

ResultType

Represents the type in method return position.

ThrowsType

Represents (exception) types in method “throws” declaration position.

TypeArgument

Represents type variables in argument position, e.g. as part of method parameters.

Functions

is_class_signature

Convenience method to parse the given string as a class signature returning true upon success, false otherwise.

is_field_signature

Convenience method to parse the given string as a field signature returning true upon success, false otherwise.

is_method_signature

Convenience method to parse the given string as a method signature returning true upon success, false otherwise.

parse_class_signature

Attempts to parse the given string as a class signature.

parse_field_signature

Attempts to parse the given string as a field signature.

parse_method_signature

Attempts to parse the given string as a method signature.

Type Aliases

Result

An alias for std::result::Result<T, ParseError>