Provide basic support for #fragment section

See redhat-developer/vscode-quarkus#563

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

qute.ls/com.redhat.qute.ls/pom.xml

@@ -39,7 +39,7 @@
 		<maven.build.timestamp.format>yyyyMMdd-HHmm</maven.build.timestamp.format>
 		<dev.build.timestamp>${maven.build.timestamp}</dev.build.timestamp>
 		<lsp4j.version>0.14.0</lsp4j.version>
-		<qute.version>2.7.0.Final</qute.version>
+		<qute.version>2.15.3.Final</qute.version>
 		<junit.version>5.6.1</junit.version>
 		<jboss.releases.repo.id>jboss-releases-repository</jboss.releases.repo.id>
 		<jboss.releases.repo.url>https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/</jboss.releases.repo.url>

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/ls/commons/snippets/Link.java

@@ -0,0 +1,38 @@
+/*******************************************************************************
+* Copyright (c) 2023 Red Hat Inc. and others.
+* All rights reserved. This program and the accompanying materials
+* which accompanies this distribution, and is available at
+* http://www.eclipse.org/legal/epl-v20.html
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*     Red Hat Inc. - initial API and implementation
+*******************************************************************************/
+package com.redhat.qute.ls.commons.snippets;
+
+/**
+ * Link used for documentation.
+ * 
+ * @author Angelo ZERR
+ *
+ */
+public class Link {
+
+	private final String url;
+	private final String label;
+
+	public Link(String url, String label) {
+		this.url = url;
+		this.label = label;
+	}
+
+	public String getUrl() {
+		return url;
+	}
+
+	public String getLabel() {
+		return label;
+	}
+
+}

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/ls/commons/snippets/Snippet.java

@@ -39,6 +39,8 @@ public class Snippet {
 
 	private ISnippetContext<?> context;
 
+	private List<Link> links;
+
 	public String getLabel() {
 		return label;
 	}
@@ -95,6 +97,14 @@ public void setSortText(String sortText) {
 		this.sortText = sortText;
 	}
 
+	public List<Link> getLinks() {
+		return links;
+	}
+
+	public void setLinks(List<Link> links) {
+		this.links = links;
+	}
+
 	public ISnippetContext<?> getContext() {
 		return context;
 	}

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/ls/commons/snippets/SnippetDeserializer.java

@@ -40,6 +40,9 @@ class SnippetDeserializer implements JsonDeserializer<Snippet> {
 	private static final String SORTTEXT_ELT = "sortText";
 	private static final String BODY_ELT = "body";
 	private static final String CONTEXT_ELT = "context";
+	private static final String LINK_ELT = "link";
+	private static final String LINK_URL_ELT = "url";
+	private static final String LINK_LABEL_ELT = "label";
 
 	private final TypeAdapter<? extends ISnippetContext<?>> contextDeserializer;
 
@@ -139,7 +142,43 @@ public Snippet deserialize(JsonElement json, Type typeOfT, JsonDeserializationCo
 			}
 		}
 
+		// link
+		List<Link> links = new ArrayList<>();
+		JsonElement linkElt = snippetObj.get(LINK_ELT);
+		if (linkElt != null) {
+			if (linkElt.isJsonArray()) {
+				JsonArray urlArray = (JsonArray) linkElt;
+				urlArray.forEach(elt -> {
+					Link link = createLink(elt);
+					if (link != null) {
+						links.add(link);
+					}
+				});
+			} else if (linkElt.isJsonObject()) {
+				Link link = createLink(linkElt);
+				if (link != null) {
+					links.add(link);
+				}
+			}
+		}
+		snippet.setLinks(links);
+
 		return snippet;
 	}
 
+	private static Link createLink(JsonElement elt) {
+		if (!elt.isJsonObject()) {
+			return null;
+		}
+		JsonObject linkObj = elt.getAsJsonObject();
+		JsonElement urlElt = linkObj.get(LINK_URL_ELT);
+		if (urlElt == null) {
+			return null;
+		}
+		String url = urlElt.getAsString();
+		JsonElement labelElt = linkObj.get(LINK_LABEL_ELT);
+		String label = labelElt != null ? labelElt.getAsString() : null;
+		return new Link(url, label);
+	}
+
 }

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/ls/commons/snippets/SnippetRegistry.java

@@ -315,9 +315,43 @@ private static MarkupContent createDocumentation(Snippet snippet, Map<String, St
 			doc.append("```");
 			doc.append(System.lineSeparator());
 		}
+		addLinks(snippet.getLinks(), doc, canSupportMarkdown);
 		return new MarkupContent(canSupportMarkdown ? MarkupKind.MARKDOWN : MarkupKind.PLAINTEXT, doc.toString());
 	}
 
+	public static void addLinks(List<Link> links, StringBuilder documentation, boolean canSupportMarkdown) {
+		if (links != null && !links.isEmpty()) {
+			documentation.append(System.lineSeparator());
+			documentation.append(System.lineSeparator());
+			documentation.append("See ");
+			if (links.size() == 1) {
+				Link link = links.get(0);
+				addLink(link.getUrl(), link.getLabel(), documentation, canSupportMarkdown);
+				documentation.append(" for more information.");
+			} else {
+				documentation.append("for more information:");
+				for (int i = 0; i < links.size(); i++) {
+					Link link = links.get(i);
+					documentation.append(System.lineSeparator());
+					documentation.append(" * ");
+					addLink(link.getUrl(), link.getLabel(), documentation, canSupportMarkdown);
+				}
+			}
+		}
+	}
+
+	public static void addLink(String url, String label, StringBuilder documentation, boolean canSupportMarkdown) {
+		if (canSupportMarkdown) {
+			documentation.append("[");
+			documentation.append(label);
+			documentation.append("](");
+			documentation.append(url);
+			documentation.append(")");
+		} else {
+			documentation.append(url);
+		}
+	}
+
 	private static String getInsertText(Snippet snippet, Map<String, String> model, boolean replace,
 			String lineDelimiter, String whitespacesIndent) {
 		StringBuilder text = new StringBuilder();

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/parser/template/ASTVisitor.java

@@ -21,6 +21,7 @@
 import com.redhat.qute.parser.template.sections.EachSection;
 import com.redhat.qute.parser.template.sections.ElseSection;
 import com.redhat.qute.parser.template.sections.ForSection;
+import com.redhat.qute.parser.template.sections.FragmentSection;
 import com.redhat.qute.parser.template.sections.IfSection;
 import com.redhat.qute.parser.template.sections.IncludeSection;
 import com.redhat.qute.parser.template.sections.InsertSection;
@@ -236,6 +237,21 @@ public boolean visit(ForSection node) {
 		return true;
 	}
 
+	/**
+	 * Visits the given type-specific AST node.
+	 * <p>
+	 * The default implementation does nothing and return true. Subclasses may
+	 * reimplement.
+	 * </p>
+	 *
+	 * @param node the node to visit
+	 * @return <code>true</code> if the children of this node should be visited, and
+	 *         <code>false</code> if the children of this node should be skipped
+	 */
+	public boolean visit(FragmentSection node) {
+		return true;
+	}
+
 	/**
 	 * Visits the given type-specific AST node.
 	 * <p>
@@ -596,6 +612,18 @@ public void endVisit(ForSection node) {
 		// default implementation: do nothing
 	}
 
+	/**
+	 * End of visit the given type-specific AST node.
+	 * <p>
+	 * The default implementation does nothing. Subclasses may reimplement.
+	 * </p>
+	 *
+	 * @param node the node to visit
+	 */
+	public void endVisit(FragmentSection node) {
+		// default implementation: do nothing
+	}
+
 	/**
 	 * End of visit the given type-specific AST node.
 	 * <p>

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/parser/template/SectionKind.java

@@ -16,6 +16,7 @@ public enum SectionKind {
 	EACH, //
 	EVAL, //
 	FOR, //
+	FRAGMENT, //
 	IF, //
 	ELSE, //
 	INCLUDE, //

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/parser/template/sections/DefaultSectionFactory.java

@@ -24,6 +24,7 @@ public class DefaultSectionFactory implements SectionFactory {
 		factoryByTag = new HashMap<>();
 		factoryByTag.put(EachSection.TAG, (tag, start, end) -> new EachSection(start, end));
 		factoryByTag.put(ForSection.TAG, (tag, start, end) -> new ForSection(start, end));
+		factoryByTag.put(FragmentSection.TAG, (tag, start, end) -> new FragmentSection(start, end));
 		factoryByTag.put(IfSection.TAG, (tag, start, end) -> new IfSection(start, end));
 		factoryByTag.put(ElseSection.TAG, (tag, start, end) -> new ElseSection(start, end));
 		factoryByTag.put(IncludeSection.TAG, (tag, start, end) -> new IncludeSection(start, end));

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/parser/template/sections/FragmentSection.java

@@ -0,0 +1,87 @@
+/*******************************************************************************
+* Copyright (c) 2023 Red Hat Inc. and others.
+* All rights reserved. This program and the accompanying materials
+* which accompanies this distribution, and is available at
+* http://www.eclipse.org/legal/epl-v20.html
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*     Red Hat Inc. - initial API and implementation
+*******************************************************************************/
+package com.redhat.qute.parser.template.sections;
+
+import java.util.List;
+
+import com.redhat.qute.parser.template.ASTVisitor;
+import com.redhat.qute.parser.template.Parameter;
+import com.redhat.qute.parser.template.ParameterInfo;
+import com.redhat.qute.parser.template.ParametersInfo;
+import com.redhat.qute.parser.template.Section;
+import com.redhat.qute.parser.template.SectionKind;
+
+/**
+ * Fragment section AST node.
+ * 
+ * <code>
+ 	{#fragment id=item_aliases} 
+	<h2>Aliases</h2>
+	<ol>
+    	{#for alias in aliases}
+    	<li>{alias}</li>
+    	{/for}
+	</ol>
+	{/fragment}
+ * </code>
+ * 
+ * @author Angelo ZERR
+ * 
+ * @see https://quarkus.io/guides/qute-reference#fragments
+ */
+public class FragmentSection extends Section {
+
+	public static final String TAG = "fragment";
+
+	private static final String ID = "id";
+
+	private static final String RENDERED = "rendered";
+
+	private static final ParametersInfo PARAMETER_INFOS = ParametersInfo.builder() //
+			.addParameter(ID) //
+			.addParameter(new ParameterInfo(RENDERED, null, true)) //
+			.build();
+
+	public FragmentSection(int start, int end) {
+		super(TAG, start, end);
+	}
+
+	@Override
+	public SectionKind getSectionKind() {
+		return SectionKind.FRAGMENT;
+	}
+
+	@Override
+	public ParametersInfo getParametersInfo() {
+		return PARAMETER_INFOS;
+	}
+
+	@Override
+	protected void initializeParameters(List<Parameter> parameters) {
+		parameters.forEach(parameter -> {
+			parameter.setCanHaveExpression(false);
+		});
+	}
+
+	@Override
+	protected void accept0(ASTVisitor visitor) {
+		boolean visitChildren = visitor.visit(this);
+		if (visitChildren) {
+			List<Parameter> parameters = getParameters();
+			for (Parameter parameter : parameters) {
+				acceptChild(visitor, parameter);
+			}
+			acceptChildren(visitor, getChildren());
+		}
+		visitor.endVisit(this);
+	}
+}

qute.ls/com.redhat.qute.ls/src/main/java/com/redhat/qute/utils/DocumentationUtils.java

@@ -12,6 +12,8 @@
 package com.redhat.qute.utils;
 
 import static com.redhat.qute.commons.JavaElementInfo.getSimpleType;
+import static com.redhat.qute.ls.commons.snippets.SnippetRegistry.addLink;
+import static com.redhat.qute.ls.commons.snippets.SnippetRegistry.addLinks;
 
 import java.net.URI;
 import java.util.List;
@@ -282,6 +284,8 @@ public static MarkupContent getDocumentation(Snippet snippet, boolean markdown)
 			documentation.append(snippet.getDescription());
 		}
 
+		addLinks(snippet.getLinks(), documentation, markdown);
+
 		return createMarkupContent(documentation, markdown);
 	}
 
@@ -340,14 +344,9 @@ private static void addUrl(String url, StringBuilder documentation, boolean mark
 		if (!StringUtils.isEmpty(url)) {
 			documentation.append(System.lineSeparator());
 			documentation.append("See ");
-			if (markdown) {
-				documentation.append("[here](");
-				documentation.append(url);
-				documentation.append(")");
-			} else {
-				documentation.append(url);
-			}
+			addLink(url, "here", documentation, markdown);
 			documentation.append(" for more informations.");
 		}
 	}
+
 }