-
Notifications
You must be signed in to change notification settings - Fork 53
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Java.Interop.Tools.Generator] Create a v2 version of map.csv (#646)
For ages, `generator --enumfields` has supported a `map.csv` format,
which was used within xamarin-android to "enumify" `Mono.Android.dll`.
This format was entirely undocumented.
Add `Documentation/EnumMappingFile.md` and document the format.
The previous `map.csv` line is 5-6 "columns", comma-delimited:
* API level the field was added in
* C# namespace and type of the C# enum to create.
* C# enum member name to create.
* C# enum member value
* JNI field to convert to the C# enum member, in the format
`{JNI type reference}.{Java field name}`.
* Flags? If (1) present, and (2) has the value `flags`, the
created C# enum has the `[Flags]` attribute.
Add support for a new 7-8 column line format, also documented in
`EnumMappingFile.md`:
* Action: `E`num, `A`dd, `R`emove, `I`gnore, `?` (decide later)
* API level
* JNI field to convert to the C# enum member, in the format
`{JNI type reference}.{Java field name}`.
* C# enum member value (which is the Java field value)
* C# namespace and type of C# enum to create
* C# enum member name to create.
* What to do with the Java field: `remove` it or `keep` it.
Replaces the previous `- ENTER TRANSIENT MODE -` "command".
* Flags? If (1) present, and (2) has the value `flags`, the
created C# enum has the `[Flags]` attribute.
Note that the column ordering for the 7-8 column format differs from
the previous 5-6 column format. This change in ordering is done for
improved "enumification workflow" support: future tooling will
generate the 7-8 column output *without* knowing what the C# enum type
and members will be. Placing the JNI information "leftmost" allows
the output to be "sensibly grouped" by tooling:
?,0,com/example/Class.FIELD,0,,,remove,
Support for parsing `map.csv` has been moved out of `generator.exe`
and into the new `Java.Interop.Tools.Generator.dll` assembly, in
`src/Java.Interop.Tools.Generator`. This new assembly will also be
used by a forthcoming `generator-utilities` app.- Loading branch information
Showing
18 changed files
with
1,041 additions
and
58 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| # Enumeration Mapping File Documentation | ||
|
|
||
| ## Background | ||
|
|
||
| In order to help with binding enumification (the process of converting groups | ||
| of Java constant int fields into C# enums), a file can be created that defines | ||
| a map between the fields and the enums to be created. | ||
|
|
||
| There is a CSV format and an XML format of this file. In practice, users are | ||
| guided to the XML format via our [documentation][0] and templates. The CSV format | ||
| is mainly used internally for `Mono.Android.dll`, as it converts thousands of | ||
| constants into hundreds of enums. | ||
|
|
||
| ## CSV Format | ||
|
|
||
| The basic format since the beginning of Xamarin contains up to 6 fields: | ||
|
|
||
| * **API Level** - This is generally only used by `Mono.Android.dll` to denote | ||
| the Android level the constant was introduced in. For other uses this | ||
| is generally `0`. | ||
| * **Enum Type** - C# namespace and type of the enum to create. For example: | ||
| `Android.Views.WindowProgress`. | ||
| * **Enum Member** - C# name of the enum to create. For example: | ||
| `Start` | ||
| * **Enum Value** - The value of the enum. For example: `0`. | ||
| * **JNI Signature** - The JNI signature of the Java constant to convert. For example: | ||
| `android/view/Window.PROGRESS_START`. | ||
| * **Flags** - If this field contains `flags` the enum will be created with the | ||
| `[Flags]` attribute. (Any member will `flags` will make the whole enum `[Flags]`.) | ||
|
|
||
| Full example: | ||
| ``` | ||
| 10,Android.Views.WindowProgress,Start,android/view/Window.PROGRESS_START,0,flags | ||
| ``` | ||
|
|
||
| --- | ||
| **NOTE** | ||
|
|
||
| Our CSV files also allow comments using `//`. Lines beginning with this | ||
| sequence are ignored. | ||
|
|
||
| --- | ||
|
|
||
| ### Transient Mode | ||
|
|
||
| By default, Java constants referenced in this format are kept. However the | ||
| file can contain a line like this at any point: | ||
| ``` | ||
| - ENTER TRANSIENT MODE - | ||
| ``` | ||
|
|
||
| Any v1 constants referenced *AFTER* this line will be removed from the bindings. | ||
| (This will not affect v2 constants.) | ||
|
|
||
| ## CSV Format v2 | ||
|
|
||
| Over time we have found some limitations to the format, such as being able | ||
| to specify if the Java constant field should be removed. Additionally, since the | ||
| format only specifies constants that *SHOULD* be mapped, we cannot use this | ||
| to track constants that we have examined and determined *SHOULD NOT* be mapped. | ||
| This has led to various blacklists and tooling of varying success to prevent | ||
| us from needing to continually re-audit those constants. | ||
|
|
||
| There is now a "v2" version of defining constants. This is a line-level change | ||
| and you can mix "v1" and "v2" lines in the same file for backwards compatibility, | ||
| but for consistency it's probably better to stick to one style. | ||
|
|
||
| A "v2" line contains up to 8 fields: | ||
|
|
||
| * **Action** - The action to perform. This is what denotes a "v2" line, if the first | ||
| character is not one of the following it will be treated as "v1". | ||
| * `E` - Create a C# enum from a Java constant | ||
| * `A` - Create a C# enum not mapped to a Java constant | ||
| * `R` - Remove a Java constant but do not create a C# enum | ||
| * `I` - Explicitly ignore this Java constant | ||
| * `?` - Unknown, an explicit action has not been decided yet, will be ignored | ||
| * **API Level** - This is generally only used by `Mono.Android.dll` to denote | ||
| the Android level the constant was introduced in. For other uses this | ||
| is generally `0`. | ||
| * **JNI Signature** - The JNI signature of the Java constant to convert. For example: | ||
| `android/view/Window.PROGRESS_START`. | ||
| * **Enum Value** - The value of the enum. For example: `0`. | ||
| * **Enum Type** - C# namespace and type of the enum to create. For example: | ||
| `Android.Views.WindowProgress`. | ||
| * **Enum Member** - C# name of the enum to create. For example: | ||
| `Start` | ||
| * **Field Action** - Action to take on the Java constant. (This replaces Transient mode.) | ||
| * `remove` - Remove the Java constant | ||
| * `keep` - Keeps the Java constant | ||
| * **Flags** - If this field contains `flags` the enum will be created with the | ||
| `[Flags]` attribute. (Any member will `flags` will make the whole enum `[Flags]`.) | ||
|
|
||
| Full example: | ||
| ``` | ||
| E,10,android/view/Window.PROGRESS_START,0,Android.Views.WindowProgress,Start,remove,flags | ||
| ``` | ||
|
|
||
| [0]: https://docs.microsoft.com/en-us/xamarin/android/platform/binding-java-library/customizing-bindings/java-bindings-metadata#enumfieldsxml-and-enummethodsxml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
11 changes: 11 additions & 0 deletions
11
src/Java.Interop.Tools.Generator/Enumification/ConstantAction.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| namespace Java.Interop.Tools.Generator.Enumification | ||
| { | ||
| public enum ConstantAction | ||
| { | ||
| None, | ||
| Ignore, | ||
| Enumify, | ||
| Add, | ||
| Remove | ||
| } | ||
| } |
Oops, something went wrong.