This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 47b9aefdc8f9 CAMEL-25244: camel-jbang - source editor: quick doc of
the XML element or attribute at the cursor (#27241)
47b9aefdc8f9 is described below
commit 47b9aefdc8f92c2ed7c32d4d93d9c2e6bbbcf28b
Author: Claus Ibsen <[email protected]>
AuthorDate: Fri Oct 2 07:43:37 2026 +0200
CAMEL-25244: camel-jbang - source editor: quick doc of the XML element or
attribute at the cursor (#27241)
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
---
.../jbang/camel-tui-source-xml-quick-doc.png | Bin 0 -> 263348 bytes
.../ROOT/pages/camel-jbang-tui-source-editor.adoc | 6 +
.../jbang/core/commands/tui/SourceEditAssist.java | 5 +
.../dsl/jbang/core/commands/tui/SourceTab.java | 10 +-
.../jbang/core/commands/tui/XmlCompletions.java | 5 +
.../dsl/jbang/core/commands/tui/XmlQuickDoc.java | 151 +++++++++++++++++++++
.../src/main/resources/tui/help/source.md | 3 +-
.../jbang/core/commands/tui/XmlQuickDocTest.java | 82 +++++++++++
8 files changed, 259 insertions(+), 3 deletions(-)
diff --git
a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-source-xml-quick-doc.png
b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-source-xml-quick-doc.png
new file mode 100644
index 000000000000..abd43bb2bf4b
Binary files /dev/null and
b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-source-xml-quick-doc.png
differ
diff --git
a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
index a49f7d6208ca..821b9e109982 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
@@ -207,6 +207,12 @@ outside edit mode the line lists the functions it uses.
image::jbang/camel-tui-source-simple-quick-doc.png[The documentation of the
date function the cursor is on]
+In an XML route the panel also follows the cursor: on an attribute name or in
its value it shows that attribute (its
+documentation, default and values), on an element name the element and its
required attributes. The `uri` attribute
+keeps the documentation of its endpoint.
+
+image::jbang/camel-tui-source-xml-quick-doc.png[The documentation of the
loggingLevel attribute the cursor is on]
+
== Navigation
* *Jump links* -- a line that sends to another route, such as
`to("seda:shipping")`, shows `↵ shipping`. Press *Enter*
diff --git
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceEditAssist.java
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceEditAssist.java
index 460773832678..30f9bedfccf8 100644
---
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceEditAssist.java
+++
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceEditAssist.java
@@ -1011,6 +1011,11 @@ final class SourceEditAssist {
return items;
}
+ /** The quick doc of the XML element or attribute at the cursor
(CAMEL-25244). */
+ List<SourceViewer.DocEntry> provideXmlQuickDoc(List<String> lines, int
row, int col) {
+ return XmlQuickDoc.at(validationCatalog(), lines, row, col);
+ }
+
/** The quick doc of the simple function at the cursor (CAMEL-25219). */
List<SourceViewer.DocEntry> provideSimpleQuickDoc(List<String> lines, int
row, int col) {
return SimpleQuickDoc.at(validationCatalog(), lines, row, col);
diff --git
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceTab.java
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceTab.java
index 719313f05fcc..5a8b3faaefe9 100644
---
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceTab.java
+++
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/SourceTab.java
@@ -848,8 +848,14 @@ class SourceTab extends AbstractTab {
// simple expressions in every route file: YAML, Java and XML
(CAMEL-25219)
sourceViewer.setSimpleCompletion(
routeFile || isCamelSourceFile(filePath) ?
assist::provideSimpleCompletions : null);
- sourceViewer.setCursorQuickDocProvider(
- routeFile || isCamelSourceFile(filePath) ?
assist::provideSimpleQuickDoc : null);
+ boolean xmlRoute = routeFile && name.toLowerCase().endsWith(".xml");
+ sourceViewer.setCursorQuickDocProvider(!routeFile &&
!isCamelSourceFile(filePath) ? null
+ : xmlRoute ? (lines, row, col) -> {
+ // the simple function the cursor is on, else the element
or attribute (CAMEL-25244)
+ List<SourceViewer.DocEntry> simple =
assist.provideSimpleQuickDoc(lines, row, col);
+ return !simple.isEmpty() ? simple :
assist.provideXmlQuickDoc(lines, row, col);
+ }
+ : assist::provideSimpleQuickDoc);
// the elements, attributes and values of an XML route (CAMEL-25240)
// the route chain of a Java route (CAMEL-25241)
sourceViewer.setJavaCompletion(routeFile && name.endsWith(".java") ?
assist::provideJavaCompletions : null);
diff --git
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlCompletions.java
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlCompletions.java
index a17acc96787e..813f8c4d371a 100644
---
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlCompletions.java
+++
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlCompletions.java
@@ -193,6 +193,11 @@ final class XmlCompletions {
return found;
}
+ /** The catalog option an attribute of an element sets, null when the
catalog has none. */
+ static BaseOptionModel option(CamelCatalog catalog, String element, String
attribute) {
+ return options(catalog, element).stream().filter(o ->
o.getName().equals(attribute)).findFirst().orElse(null);
+ }
+
/** The options of the EIP, else of the language, of an element. */
private static List<? extends BaseOptionModel> options(CamelCatalog
catalog, String element) {
EipModel eip = catalog.eipModel(element);
diff --git
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlQuickDoc.java
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlQuickDoc.java
new file mode 100644
index 000000000000..b8e0b4b029fd
--- /dev/null
+++
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlQuickDoc.java
@@ -0,0 +1,151 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.dsl.jbang.core.commands.tui;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.camel.catalog.CamelCatalog;
+import org.apache.camel.tooling.model.BaseOptionModel;
+
+/**
+ * The quick doc of the XML element or attribute the cursor is on
(CAMEL-25244): on an attribute name or in its value
+ * the attribute (its documentation, default and values), on an element name
the element and its required attributes.
+ * From the XML schema of the catalog, completed by the catalog models, as the
XML completion; read from the text above
+ * the cursor, so it works while the file does not parse. The uri attribute is
left to the endpoint doc of the line.
+ */
+final class XmlQuickDoc {
+
+ static final String TITLE = "XML";
+
+ private XmlQuickDoc() {
+ }
+
+ /** The doc of what the cursor is on: col of row; nothing in the view (col
-1), which has the doc of the line. */
+ static List<SourceViewer.DocEntry> at(CamelCatalog catalog, List<String>
lines, int row, int col) {
+ if (catalog == null || lines == null || row < 0 || row >= lines.size()
|| col < 0) {
+ return List.of();
+ }
+ String line = lines.get(row);
+ if (col > line.length()) {
+ return List.of();
+ }
+ // the whole name the cursor is in: the context is read up to its end
+ int end = col;
+ while (end < line.length() && isNameChar(line.charAt(end))) {
+ end++;
+ }
+ XmlCompletionContext c = XmlCompletionContext.at(lines, row, end);
+ if (c == null) {
+ return List.of();
+ }
+ XmlSchemaModel model = XmlCompletions.model(catalog);
+ if (model == null) {
+ return List.of();
+ }
+ return switch (c.kind()) {
+ case ELEMENT -> c.open() && !c.prefix().isEmpty() ?
element(catalog, model, c) : List.of();
+ case ATTRIBUTE -> c.prefix().isEmpty() ? List.of() :
attribute(catalog, model, c, c.prefix());
+ case VALUE -> "uri".equals(c.attribute()) ? List.of() :
attribute(catalog, model, c, c.attribute());
+ };
+ }
+
+ private static List<SourceViewer.DocEntry> element(
+ CamelCatalog catalog, XmlSchemaModel model, XmlCompletionContext
c) {
+ String name = c.prefix();
+ List<String> path = new ArrayList<>(c.path());
+ path.add(name);
+ String type = model.typeOf(path);
+ if (type == null) {
+ return List.of();
+ }
+ String doc = null;
+ String parentType = c.path().isEmpty() ? null : model.typeOf(c.path());
+ if (parentType != null) {
+ for (XmlSchemaModel.Child child : model.children(parentType)) {
+ if (child.name().equals(name)) {
+ doc = child.doc();
+ }
+ }
+ }
+ if (doc == null) {
+ doc = model.elementDoc(name);
+ }
+ List<SourceViewer.DocEntry> entries = new ArrayList<>();
+ entries.add(new SourceViewer.DocEntry(name + (doc != null ? " — " +
doc : ""), false, TITLE));
+ List<String> required = new ArrayList<>();
+ for (XmlSchemaModel.Attribute a : XmlCompletions.attributes(catalog,
model, name, type)) {
+ if (a.required()) {
+ required.add(a.name());
+ }
+ }
+ if (!required.isEmpty()) {
+ entries.add(new SourceViewer.DocEntry("Required: " +
String.join(", ", required), false, TITLE));
+ }
+ return entries;
+ }
+
+ private static List<SourceViewer.DocEntry> attribute(
+ CamelCatalog catalog, XmlSchemaModel model, XmlCompletionContext
c, String name) {
+ if (c.element() == null) {
+ return List.of();
+ }
+ List<String> path = new ArrayList<>(c.path());
+ path.add(c.element());
+ String type = model.typeOf(path);
+ if (type == null) {
+ return List.of();
+ }
+ XmlSchemaModel.Attribute attribute = null;
+ for (XmlSchemaModel.Attribute a : XmlCompletions.attributes(catalog,
model, c.element(), type)) {
+ if (a.name().equals(name)) {
+ attribute = a;
+ }
+ }
+ if (attribute == null) {
+ return List.of();
+ }
+ List<SourceViewer.DocEntry> entries = new ArrayList<>();
+ entries.add(new SourceViewer.DocEntry(
+ c.element() + " " + name + (attribute.required() ? "
(required)" : "")
+ + (attribute.doc() != null ? " —
" + attribute.doc() : ""),
+ false, TITLE));
+ BaseOptionModel option = XmlCompletions.option(catalog, c.element(),
name);
+ if (option != null) {
+ // the values and default, unless the documentation says them
already (the panel has three lines)
+ String doc = attribute.doc() != null ? attribute.doc() : "";
+ List<String> facts = new ArrayList<>();
+ List<String> values = option.getEnums() != null &&
!option.getEnums().isEmpty()
+ ? option.getEnums() : "boolean".equals(option.getType()) ?
List.of("true", "false") : List.of();
+ if (!values.isEmpty() && !values.stream().allMatch(doc::contains))
{
+ facts.add("Values: " + String.join(", ", values));
+ }
+ if (option.getDefaultValue() != null &&
!String.valueOf(option.getDefaultValue()).isEmpty()
+ && !doc.contains("Default value")) {
+ facts.add("Default: " + option.getDefaultValue());
+ }
+ if (!facts.isEmpty()) {
+ entries.add(new SourceViewer.DocEntry(String.join(" ",
facts), false, TITLE));
+ }
+ }
+ return entries;
+ }
+
+ private static boolean isNameChar(char c) {
+ return Character.isLetterOrDigit(c) || c == '-' || c == '_' || c ==
'.' || c == ':';
+ }
+}
diff --git
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/resources/tui/help/source.md
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/resources/tui/help/source.md
index 04f6f02cc418..69f9b614c013 100644
---
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/resources/tui/help/source.md
+++
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/main/resources/tui/help/source.md
@@ -52,7 +52,8 @@ a heat map of the route: where messages go, where they fail.
- **Ctrl+Left / Ctrl+Right** — word navigation
- **Home** — smart home (content indent, then column 0)
- Quick documentation panel is shown at the bottom (shows doc for current line;
- in a simple expression, the function, header or operator the cursor is on)
+ in a simple expression, the function, header or operator the cursor is on;
+ in XML, the element or attribute the cursor is on)
- **F7** — show diff of unsaved changes
- **F9** — jump to next validation error
- **Shift+F8** — ask the AI to fix the problem on the cursor line: the file is
diff --git
a/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlQuickDocTest.java
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlQuickDocTest.java
new file mode 100644
index 000000000000..dcfa196c6203
--- /dev/null
+++
b/dsl/camel-jbang/camel-jbang-plugin-tui/src/test/java/org/apache/camel/dsl/jbang/core/commands/tui/XmlQuickDocTest.java
@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.dsl.jbang.core.commands.tui;
+
+import java.util.List;
+
+import org.apache.camel.catalog.CamelCatalog;
+import org.apache.camel.catalog.DefaultCamelCatalog;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * The quick doc of the XML element or attribute the cursor is on
(CAMEL-25244).
+ */
+class XmlQuickDocTest {
+
+ private static CamelCatalog catalog;
+
+ private static final List<String> ROUTE = List.of(
+ "<routes xmlns=\"http://camel.apache.org/schema/xml-io\";>",
+ " <route>",
+ " <from uri=\"kafka:orders\"/>",
+ " <log message=\"Got ${body}\" loggingLevel=\"WARN\"/>",
+ " <split parallelProcessing=\"true\">",
+ " <simple>${body}</simple>",
+ " </split>",
+ " </route>",
+ "</routes>");
+
+ @BeforeAll
+ static void loadCatalog() {
+ catalog = new DefaultCamelCatalog();
+ }
+
+ private static List<String> doc(int row, String on) {
+ int col = ROUTE.get(row).indexOf(on) + 2;
+ return XmlQuickDoc.at(catalog, ROUTE, row,
col).stream().map(SourceViewer.DocEntry::text).toList();
+ }
+
+ @Test
+ void anAttributeByItsNameOrValue() {
+ List<String> doc = doc(3, "loggingLevel");
+ assertThat(doc.get(0)).startsWith("log loggingLevel — Sets the logging
level");
+ // its documentation lists the levels and the default already: not
said twice
+ assertThat(doc).hasSize(1);
+ // in the value, the same attribute
+ assertThat(doc(3, "WARN").get(0)).startsWith("log loggingLevel");
+ // a boolean option
+ assertThat(doc(4, "parallelProcessing")).anyMatch(t ->
t.contains("Values: true, false"));
+ }
+
+ @Test
+ void anElementByItsName() {
+ List<String> doc = doc(3, "log ");
+ assertThat(doc.get(0)).startsWith("log — ");
+ assertThat(doc).contains("Required: message");
+ }
+
+ @Test
+ void theUriIsLeftToTheEndpointDocOfTheLine() {
+ assertThat(doc(2, "kafka")).isEmpty();
+ // nor anything in the text of an element, or in the view without a
cursor
+ assertThat(XmlQuickDoc.at(catalog, ROUTE, 6, 2)).isEmpty();
+ assertThat(XmlQuickDoc.at(catalog, ROUTE, 3, -1)).isEmpty();
+ }
+}
