[generator] Add support for <ns-replace> metadata. (#939)

Fixes: #727

Today, when `generator` creates a .NET `namespace` from a
Java `package`, it applies a simple PascalCase transformation to make
the namespace match established .NET naming standards.  For example.
`package android.database` becomes `namespace Android.Database`.

However there are a few scenarios that this is not a good fit for:

 1. Word phrases where upper-casing only the first letter is not
    desirable, e.g. `package androidx` to `namespace AndroidX`.

 2. When Java package names are longer than the desired C# namespaces;
    `com.` is a common Java package prefix, but isn't common in C#:
    `package com.google.android.material.animation` should become
    `namespace Google.Android.Material.Animation`.

Both of these scenarios can require many repeated `metadata` lines
[to fix][0]:

	<attr path="/api/package[@name='androidx.core.accessibilityservice']" name="managedName">AndroidX.Core.AccessibilityService</attr>
	<attr path="/api/package[@name='androidx.core.app']" name="managedName">AndroidX.Core.App</attr>
	…

Improve support for this scenario by adding a support for a new
`<ns-replace/>` element to `Metadata.xml` transform files.
(We may also add support for an `@(AndroidNamespaceReplacement)` item
group as suggested in #727 in the future.)

	<metadata>
	  <ns-replace source='Androidx'     replacement='Xamarin.AndroidX' />
	  <ns-replace source='.Androidx.'   replacement='Xamarin.AndroidX' />
	  <ns-replace source='Com'          replacement='' />
	  <ns-replace source='Com.Google.'  replacement='Google' />
	  <ns-replace source='.Compose'     replacement='ComposeUI' />
	</metadata>

The `//ns-replace/@source` attribute is a Java [PackageName][1] to
replace.  Note: the Java PackageName grammar is:

> *PackageName*:
>   - *Identifier*
>   - *PackageName* `.` *Identifier*

The `//ns-replace` values *do not* override the [managedName][2]
attribute if already specified within metadata.

The `//ns-replace/@source` attribute:

  * Specifies a "match"; when it matches, instances of `@source` are
    replaced with `@replacement`.

  * Is interpreted in a *case-insensitive* manner; `Androidx` matches
    `androidx` and `AndroidX` and `ANDROIDX`.

  * Only matches on full [Identifier][3]s and [PackageName][1]s;

        <ns-replace source='Com' replacement='' />

    Matches `Com.Google.Library`, but not `Common.Google.Library` or
    `Google.Imaging.Dicom`.

  * Multiple "dotted" Identifiers may be used, and all may match
    *anywhere*, *in order*, in the Java package name.

        <ns-replace source='Com.Google' replacement='Google' />

    will match `com.google.library` and `example.com.google`, but
    won't match `Common.Google` or `Com.Googles`.

  * *May start with* a `.`, which means that `//ns-replace/@source`
    is only matched at the *end* of a Java package name:

        <ns-replace source='.Compose' replacement='ComposeUI' />

    will match `com.google.androidx.compose`,
    but not `com.google.androidx.compose.writer`.

  * *May end with* a `.`, which means that `//ns-replace/@source` is
    only matched at the *beginning* of the package name:

        <ns-replace source='Androidx.' replacement='Xamarin.AndroidX' />

    matches `androidx.core`, but not `com.square.okhttp.androidx`.

  * May both begin and end with a `.`, which means that only exact
    (case insensitive) Java package names are matched:

        <ns-replace source='.Androidx.' replacement='Xamarin.AndroidX' />

    matches `androidx`, but not `com.google.androidx.core`.

Additionally, duplicate `//ns-replace/@source` values are *ignored*.

`//ns-replace` elements are processed "in order" for a given
`Metadata.xml` file, but the ordering of `generator --fixup` files /
`@(TransformFile)`s is unspecified.

Multiple replacements may affect a single namespace:

	<ns-replace source='Androidx'   replacement='Xamarin.AndroidX' />
	<ns-replace source='View'       replacement='Views' />

changes `Androidx.View` to `Xamarin.AndroidX.Views`.

[0]: https://github.com/xamarin/AndroidX/blob/f97553ff428f9b6ea754f173567d220048245a16/source/androidx.core/core/Transforms/Metadata.Namespaces.xml#L10-L34
[1]: https://docs.oracle.com/javase/specs/jls/se8/html/jls-6.html#jls-6.5
[2]: https://docs.microsoft.com/en-us/xamarin/android/platform/binding-java-library/customizing-bindings/java-bindings-metadata#managedname
[3]: https://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-Identifier

Author: jpobst

src/Java.Interop.Localization/Resources.Designer.cs

@@ -286,6 +286,10 @@ The following terms should not be translated: &lt;package&gt;.</comment>
     <comment>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</comment>
   </data>
+  <data name="Generator_BG8A07" xml:space="preserve">
+    <value>Invalid namespace transform '{0}'</value>
+    <comment>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</comment>
+  </data>
   <data name="Generator_BG8B00" xml:space="preserve">
     <value>Unknown generic argument constraint type '{0}' for member '{1}'.</value>
     <comment>{0} - .NET type name

src/Java.Interop.Localization/Resources.resx

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.cs.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.de.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.es.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.fr.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.it.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.ja.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.ko.xlf

@@ -207,6 +207,11 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <note>{0} - XML transform. (example: '&lt;remove-node path="/api/package[@name='javax.sql']"')
 The following terms should not be translated: Metadata.xml.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8A07">
+        <source>Invalid namespace transform '{0}'</source>
+        <target state="new">Invalid namespace transform '{0}'</target>
+        <note>{0} - XML transform. (example: '&lt;ns-replace source="example" replacement="Example" /&gt;')</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8B00">
         <source>Unknown generic argument constraint type '{0}' for member '{1}'.</source>
         <target state="new">Unknown generic argument constraint type '{0}' for member '{1}'.</target>