SourceTransform

Utilities to deal with java source code.

What it can do:

• Read inheritance and member information from class files and create an inheritance map.
• Read a json transformer and some mappings to produce additional mappings for the source code.
• Rename local variables according to the json transformer.
• Custom inspections (These are not really functional yet)
• Sanitizing Parchment exports for the use with given source code, so the source code will stay compilable after the Parchment data has been applied.

SourceTransform is meant to be used together with Srg2Source.

Create an inheritance map

An inheritance map is created from bytecode. For some source code, it contains inheritance information for each class used, all fields, methods and parameters that exist in the source and information about which methods override other methods. This also scans synthetic methods that are generated by the compiler for overrides when using generics. It will also contain information about each lambda and which method is used tom implement the lambda logic.

To create an inheritance map, use sourcetransform inheritance. It accepts the following options:

• -c, --classes: Folder with compiled classes from your source code.
• -l, --locals: When this is set, inheritance information will be added for all locals, not just types used in fields and method return or parameter types.
• -o, --output: Output file to write the inheritance map to.
• -p, --classpath: The classpath used to compile the classes. This must also include the jars / jmods for the java platform libraries

Remap an inheritance map

With sourcetransform remap, you can remap an inheritance map with a given mapping file. It accepts the following options:

• -i, --input: The input inheritance map
• -m, --mappings: The mappings to apply
• -o, --output: The output inheritance map

Apply a transformer

SourceTransform can apply a transformer to a set of mappings using an inheritance map. This will create additional mappings. A transformer specifies rules on how to rename things. This was created to easily change names from MCP to official when updating forge mods to 1.17. SourceTransform will make sure that methods overriding other methods are renamed correctly.

A transformer is a json object with two elements:

• api: This should be 1
• transformers is a list of transformers to apply. Each name is checked against all of them and the first matching will be applied.

A transformer is a json object with the following elements:

• transformer: A transformer string. See below
• type or types: A type or a list of types that must match an element. For classes, it must match the class type. For members or parameters and variables it must match their descriptor (or one of the types from their descriptor). Declaring primitives here, will implicitly declare their wrapper types.
• targets: A list of targets to apply the transformer to. These are child_class, utility_class, field, method, parameter and local. child_class precedes over utility_class and will match if the class is a subtype of one of the types from type/types. utility_class will match when a majority of members matches the types from type/types.
• member or members: A member definition or a list of member definitions that must match the old name. There are two types of member definitions. Fields and Method member definitions. A field member definition is just a simple name. A method member definition is a simple name followed by a hash (#) and optionally an integer for the amount of parameters.
• exact_type: A boolean that, when set, will make the elements types only match exactly to the ones declared in type/types instead of matching for subtypes.

A transformer string can be one of these:

• old->new: Replace old with new
• -str: Remove str from the name. Use this instead of str-> as the latter might produce weird results regarding case.
• >str: If the name contains str, move it to the end of the name.
• <str: If the name contains str, move it to the start of the name.

The names in the transformer string should use lower snake case. They are changed to the matching case when the transformer is applied.

sourcetransform transform accepts the following arguments:

• -i, --inheritance: The inheritance map to use.
• -m, --mappings: The mappings that will be applied to the source code. Required if --transformer is not set.
• --noparam: When this is set, parameters won't be transformed.
• -o, --output: Output file for additional mappings.
• -r, --remap: Reverse-remap the transformer. This should be set, if the transformer uses the target names instead of the source names.
• -t, --transformer: The transformer that will be applied on the source code. Required if --mappings is not set.

Create renames for local variables

With sourcetransform local you can create a replacement map for local variables using a transformer. This stores position, length and replacement for each occurrence of locals. It accepts the following arguments:

• -i, --inheritance: The inheritance map to use.
• -l, --level: Java source level of the source code. One of java_8, java_10 or java_16. Defaults to java_16.
• -m, --mappings: The mappings that will be applied to the source code. Required if --transformer is not set.
• -o, --output: Output file for the local rename map.
• -p, --classpath: classpath required to compile the source code. This must also include the jars / jmods for the java platform libraries
• -r, --remap: Reverse-remap the transformer. This should be set, if the transformer uses the target names instead of the source names.
• -s, --sources: The folder that contains the java source files to process.
• -t, --transformer: The transformer that will be applied on the source code. Required if --mappings is not set.

Apply renames for local variables

Using sourcetransform apply you can appyl a local rename map to source code. You can also apply the local rename map to comments in the source code. This is useful to then run Srg2Source over it and apply the replacements afterwards. You can't just apply the local rename map after running Srg2Source as the indices in source code will have changed.

• -c, --comments: Add comments instead of applying the local rename map.
• -r, --rename: The local rename map to apply.
• -s, --sources: The folder that contains the java source files to process.

Apply local renames previously staged as comments

Using sourcetransform comments you can apply local rename comments previously added with sourcetransform apply.

• -s, --sources: The folder that contains the java source files to process.

Sanitize a parchment export to be usable with some source code

sourcetransform sanitize will change parameter names from a parchment export, so they can be applied to source code while leaving it compilable.

For this it needs a parchment export json, an inheritance map and the compile classpath.

• -i, --inheritance: An inheritance map created from the source code that the parchment mappings should be applied to.
• -l, --level: Java source level of the source code. One of java_8, java_10 or java_16. Defaults to java_16.
• -m, --input: The parchment export json to read.
• -o, --output: Where to write the new sanitized export json.
• -p, --classpath: classpath required to compile the source code. This must also include the jars / jmods for the java platform libraries
• -s, --sources: The folder that contains the java source files to process.
• -q, --quiet: Suppress warning messages when reading the source code.