XML Files support with settings

See eclipse-lemminx/lemminx#1464

Signed-off-by: azerr <[email protected]>

Author: angelozerr

docs/Features/XMLFilePathSupport.md

@@ -0,0 +1,127 @@
+# XML File Paths Features
+
+XML file path support provides the capability to mark a DOM node (attribute or text) as file path with the `xml.filePathSupport.mappings` setting, by using XPath expression :
+
+ * `path/text()` defines the text node of the `path` element.
+ * `item/@path` defines the `path` attribute node of the `item` element.
+
+Once the DOM node is designated as a file path, you will enjoy the benefits of file completion.
+
+ * Files completion.
+
+## Define File path in Text Content with `path/text()`
+
+Given this XML file `items.xml` sample:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<items>
+	<path>path/to/file.xml</path>
+</items>
+```
+
+In this example:
+
+The text within the `path` tag element `<path>path/to/file.xml</path>` represents a file path. The [vscode-xml](https://github.com/redhat-developer/vscode-xml) extension offers file path support through the `xml.filePathSupport.mappings` settings. You can configure this setting as follows:
+
+```json
+"xml.filePathSupport.mappings": [
+   {
+      "pattern": "**/items.xml",
+      "expressions": [
+         {
+            "xpath": "items/path/text()"
+         }
+      ]
+   }
+]
+```
+
+After saving this setting, you will get file path completion support for the text node of `path` tag element:
+
+![XML File Paths in Text](../images/Features/XMLFilePathsInTextFeatures.png)
+
+## Define File path in Attribute with `item/@path`
+
+Attribute values may also be marked as file path by using the proper XPath.
+
+Given this `items.xml` XML file:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<items>
+	<item path="path/to/file.xml" ></item>
+</items>
+
+```
+
+You can declare this settings:
+
+```json
+"xml.filePathSupport.mappings": [
+   {
+      "pattern": "**/items.xml",
+      "expressions": [
+         {
+            "xpath": "item/@path"
+         }
+      ]
+   }
+]
+```
+
+After saving this setting, you will get file path completion support for the text node of `path` attribute:
+
+![XML File Paths in Attr](../images/Features/XMLFilePathsInAttrFeatures.png)
+
+## Filter the file path completion result
+
+Given this `images.xml` file:
+
+```xml
+<items>
+  <image src="" />
+</items>
+```
+
+If you need to restrict file path completion on `image/@src` files with the `.png`, `.gif` or `.jpg` extensions, you can use the `filter` property, with this settings:
+
+```json
+"xml.filePathSupport.mappings": [
+   {
+      "pattern": "**/images.xml",
+      "expressions": [
+         {
+            "xpath": "image/@src",
+            "filter": [".png", ".gif", ".jpg"]
+         }
+      ]
+   }
+]
+```
+
+## Separator to declare multiple file paths.
+
+Given this `paths.xml` file:
+
+```xml
+<items>
+  <item paths="path/to/file1.xml;path/to/file2.xml" />
+</items>
+```
+
+If you want to handle file path completion for `item/@paths` by declaring several file paths separated by `;`, you can use the `separator` property with these settings:
+
+```json
+"xml.filePathSupport.mappings": [
+   {
+      "pattern": "**/paths.xml",
+      "expressions": [
+         {
+            "xpath": "item/@paths",
+            "separator": ";"
+         }
+      ]
+   }
+]
+```

docs/images/Features/XMLFilePathsInAttrFeatures.png

@@ -728,6 +728,52 @@
           "markdownDescription": "Allows colors for the given file name patterns. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22Features/XMLColorsFeatures%22%2C%22section%22%3A%22xmlcolorsfeatures%22%7D%5D) for more information.",
           "scope": "window"
         },
+        "xml.filePathSupport.mappings": {
+          "type": "array",
+          "default": [],
+          "items": {
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "markdownDescription": "matches the files that file path declared with `expressions` applies to.\n\nMore information on the glob syntax: https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob"
+              },
+              "expressions": {
+                "type": "array",
+                "default": [],
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "xpath": {
+                      "type": "string",
+                      "description": "The file path DOM node (attribute, text) declared with XPath (ex: foo/@path, foo/text())"
+                    },
+                    "filter": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "String array which contains allowed file extensions (ex: [\".png\", \".gif\", \".jpg\"])"
+                    },
+                    "separator": {
+                      "type": "string",
+                      "description": "Separator character to use if multiple file paths are allowed (ex: \";\")"
+                    }
+                  }
+                },
+                "required": [
+                  "xpath"
+                ]
+              }
+            },
+            "required": [
+              "pattern",
+              "expressions"
+            ]
+          },
+          "markdownDescription": "Allows file path for the given file name patterns. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22Features/XMLFilePathSupport%22%2C%22section%22%3A%22xmlfilepathsfeatures%22%7D%5D) for more information.",
+          "scope": "window"
+        },
         "xml.extension.jars": {
           "type": "array",
           "default": [],

docs/images/Features/XMLFilePathsInTextFeatures.png

@@ -11,7 +11,7 @@
  */
 
 import * as fs from 'fs-extra';
-import { DocumentFilter, DocumentSelector, ExtensionContext, Uri, commands, extensions, languages } from "vscode";
+import { ExtensionContext, Uri, commands, extensions, languages } from "vscode";
 import { Executable, LanguageClient } from 'vscode-languageclient/node';
 import { XMLExtensionApi } from './api/xmlExtensionApi';
 import { getXmlExtensionApiImplementation } from './api/xmlExtensionApiImplementation';