# The Quilt Mapping Format

## Example

QUILT_MAPPING <from_namespace> [to_namespace]
EXTENSIONS <extension, >
CLASS <from_name> [to_name]
	FIELD <from_name> <from_descriptor> [to_name]   
	METHOD <from_name> <from_descriptor> [to_name]	
		ARG <index> [name]
		RETURN
	CLASS <from_name> [to_name]

## Specification

<- header ->
<- classes ->

`<- header ->`: [Header Declaration](#Header-Declaration) seperated by linebreaks. (See below)
`<- classes ->`: [Class Declarations](#Class-Declaration) seperated by linebreaks. (See below)

Each line is a mapping. Mappings can be children of other mappings, and are indented an extra level in from their parent.

### Header Declaration

QUILT_MAPPING <from_namespace> [to_namespace]
EXTENSIONS <extension, >

Defines the `from_namespace`, such as hashed or obfuscated and an optional `to_namespace`, such as named or hashed. In addition, `<extensions, >` is a tab seperated list of extension names. Must be at the beginning of the file.

### Class Declaration

CLASS <from_name> [to_name]
	<- fields ->
	<- methods ->
	<- classes ->

Defines the `from_name` in `from_namespace`. The `to_name` field is optional indicating that the class is not mapped.

`<- fields ->`: [Field Declarations](#Field-Declaration) seperated by linebreaks. (See below)
`<- methods ->`: [Method Declarations](#Method-Declaration) seperated by linebreaks. (See below)
`<- classes ->`: [Class Declarations](#Class-Declaration) seperated by linebreaks.

### Field Declaration

FIELD <from_name> <from_descriptor> [to_name]

Defines the `from_name` and `from_descriptor` in `from_namespace`. The `to_name` field is optional indicating that the field is not mapped.

### Method Declaration

METHOD <from_name> <from_descriptor> [to_name]
	<- args ->
	<- return ->

Defines the `from_name` and `from_descriptor` in `from_namespace`. The `to_name` field is optional indicating that the method is not mapped.

`<- args ->`: An optional mapping in the format `ARG <index> [name]` that maps paramters. `<index>` corresponds to the LVT index, and `[name]` is an optional mapping that sets the parameter name.

`<- return ->`: An optional mapping that allows extensions to be attached to the return value. Formatted as `RETURN`

## Extensions

Extensions are additional mappings that can be attached to the entries above. The available targets are: `CLASS`, `FIELD`, `METHOD`, `ARG`, and `RETURN`.

Multiple of the same extension can be applied to the same target, and the parsed mappings will be returned as a list.

### Builtin Extensions

Types of extensions provided by Quilt.

#### Annotation
Can be applied to all targets.

Example:

ANNOTATION	REMOVE	Lorg/quiltmc/annotation_replacement/test/NestedAnnotation;
ANNOTATION	ADD	Lorg/quiltmc/annotation_replacement/test/TestAnnotation;
	VALUE	value	1	I
	VALUE	extra	"test string"	Ljava/lang/String;
	VALUE	array	true	false	true	[Z
	VALUE	clazz	Lorg/quiltmc/annotation_replacement/test/TestClass;	Ljava/lang/Class;
	ENUM_VALUE	enumValue	VALUE	Lorg/quiltmc/annotation_replacement/test/TestEnum;
	ANNOTATION_VALUE	nestedAnnotation	Lorg/quiltmc/annotation_replacement/test/NestedAnnotation;
		VALUE	value	1.0	F

TODO: Explain annotation mapping

#### Comment

Can be applied to all targets. Comments can be multiple lines, and are raw javadoc text. Each newline is a new line in the javadoc comment

Format: `COMMENT <comment>`

Example:

CLASS NamespaceA NamespaceB
	COMMENT This is a javadoc comment on {@link NamespaceB}

#### Transitive

TODO: Example and explain transitive mappings

#### Unpick

Can be applied to all `ARG`, `RETURN`, and `FIELD`.

`FIELD`: `UNPICK <group_name> <CONSTANT|FLAG>`. Adds this field to `<group_name>`. Also specifies the type of `<group_name>`.

`ARG`, `RETURN`: `UNPICK <group_name>`. Unpicks the parameter or return with `<group_name>`

Example:

CLASS NamespaceA NamespaceB
	FIELD fieldA fieldB I
		UNPICK CONSTANT unpick_group
	METHOD methodA methodB (I)I
		ARG 0 parameter
			UNPICK unpick_group
		RETURN
			UNPICK unpick_group