Merge pull request #264 from scijava/scijava-ops-indexer/expose-implNote-hints

gselzer · web-flow · commit fc39f1b9ddfa · 2024-09-09T17:10:40.000-05:00
Expose Hints via Javadoc
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -1,7 +1,6 @@
 name: scijava-docs
 channels:
   - conda-forge
-  - defaults
 dependencies:
   - myst-nb
   - openjdk=11
diff --git a/docs/ops/doc/WritingYourOwnOpPackage.md b/docs/ops/doc/WritingYourOwnOpPackage.md
@@ -467,6 +467,7 @@ Assuming your project is following Maven's [standard directory layout](https://m
 ```yaml
 - op:
     names: [your.op.name1, your.op.name2, ...] # Array of Strings
+    hints: [op.hint1, op.hint2, ...] # Array of Strings
     description: 'your Op description' # String
     source: yourOpSource # String - see below
     priority: 0.0 # Number
@@ -493,6 +494,17 @@ Assuming your project is following Maven's [standard directory layout](https://m
 
 Of particular note are the following sections:
 
+#### Hints
+
+Each Op can define a set of hints (i.e. flags to the matcher) that can enable/disable particular aspects of the matcher.
+
+Some of the most useful Op hints are described below:
+
+| Hint                   | Use Case                                                                                                                                                                                                                                                              |
+|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Adaptation.FORBIDDEN` | Some algorithms like a [Fast Fourier Transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform) require their outputs be <br>of a particular size (not equivalent to the input size). If they are a `Computer`, <br>adaptation to `Function`s may cause errors. |
+| `Conversion.FORBIDDEN` | `engine.convert` Ops often require this hint to avoid infinite loops in <br>converted Op matching.                                                                                                                                                                    |
+
 #### Source
 
 For **java objects**, the `source` will start with one of the following prefix, followed by a `:/`, followed by a [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) stringification of the Op (i.e. calling `toString()` on the object). Examples are shown below:
diff --git a/scijava-ops-api/src/main/java/org/scijava/ops/api/Hints.java b/scijava-ops-api/src/main/java/org/scijava/ops/api/Hints.java
@@ -62,7 +62,7 @@ public Hints(final String... startingHints) {
 		this(Arrays.asList(startingHints));
 	}
 
-	private Hints(final Collection<String> hints) {
+	public Hints(final Collection<String> hints) {
 		this.hints = new HashSet<>(hints);
 	}
 
diff --git a/scijava-ops-engine/src/main/java/org/scijava/ops/engine/yaml/impl/AbstractYAMLOpInfo.java b/scijava-ops-engine/src/main/java/org/scijava/ops/engine/yaml/impl/AbstractYAMLOpInfo.java
@@ -35,8 +35,8 @@
 import org.scijava.priority.Priority;
 import org.scijava.struct.Struct;
 
-import java.lang.reflect.Type;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
@@ -59,7 +59,10 @@ public AbstractYAMLOpInfo(final Map<String, Object> yaml,
 		this.priority = parsePriority();
 		this.description = yaml.getOrDefault("description", "").toString();
 		this.version = (String) yaml.get("version");
-		this.hints = new Hints();
+		this.hints = new Hints((List<String>) yaml.getOrDefault( //
+				"hints", //
+				Collections.emptyList() //
+		));
 	}
 
 	/**
diff --git a/scijava-ops-engine/src/test/java/org/scijava/ops/engine/yaml/impl/YAMLOpTest.java b/scijava-ops-engine/src/test/java/org/scijava/ops/engine/yaml/impl/YAMLOpTest.java
@@ -121,4 +121,16 @@ public void testYAMLDescription() {
 		Assertions.assertEquals(expected, actual);
 	}
 
+	@Test
+	public void testYAMLHints() {
+		var infos = ops.infos("example.xor");
+		Assertions.assertEquals(1, infos.size());
+		var info = infos.iterator().next();
+		var hints = info.declaredHints();
+		Assertions.assertTrue(hints.containsAll( //
+				"Adaptation.FORBIDDEN", //
+				"Conversion.FORBIDDEN" //
+		));
+	}
+
 }
diff --git a/scijava-ops-engine/src/test/java/org/scijava/ops/engine/yaml/impl/ops/YAMLMethodOp.java b/scijava-ops-engine/src/test/java/org/scijava/ops/engine/yaml/impl/ops/YAMLMethodOp.java
@@ -57,7 +57,7 @@ public static <N extends Number> Double subtract(N aDouble, N aDouble2) {
 	/**
 	 * Another example Op, implemented by a {@link Method}
 	 *
-	 * @implNote op name=example.xor, type=Inplace1
+	 * @implNote op name=example.xor, type=Inplace1, hints="Adaptation.FORBIDDEN,Conversion.FORBIDDEN"
 	 * @param aList the first integer {@link List}
 	 * @param aList2 the second integer {@link List}
 	 */
diff --git a/scijava-ops-indexer/src/main/java/org/scijava/ops/indexer/OpImplData.java b/scijava-ops-indexer/src/main/java/org/scijava/ops/indexer/OpImplData.java
@@ -29,16 +29,15 @@
 
 package org.scijava.ops.indexer;
 
-import static org.scijava.ops.indexer.ProcessingUtils.blockSeparator;
-import static org.scijava.ops.indexer.ProcessingUtils.tagElementSeparator;
-
 import java.net.URI;
 import java.util.*;
 import java.util.stream.Collectors;
 
 import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.element.Element;
 
+import static org.scijava.ops.indexer.ProcessingUtils.*;
+
 /**
  * A data structure containing all the metadata needed to define an Op
  *
@@ -89,6 +88,11 @@ abstract class OpImplData {
 	 */
 	protected final List<String> authors = new ArrayList<>();
 
+	/**
+	 * A {@link List} of the hints declared by this Op
+	 */
+	protected final List<String> hints = new ArrayList<>();
+
 	protected final ProcessingEnvironment env;
 
 	/**
@@ -186,6 +190,10 @@ private void parseImplNote(String implTag) {
 					else if ("names".equals(kv[0]) || "name".equals(kv[0])) {
 						names.addAll(Arrays.asList(value.split("\\s*,\\s*")));
 					}
+					else if ("hints".equals(kv[0])) {
+
+						hints.addAll(Arrays.asList(value.split("\\s*,\\s*")));
+					}
 					else {
 						if (value.contains(",")) {
 							tags.put(kv[0], value.split(","));
@@ -216,6 +224,7 @@ public Map<String, Object> dumpData() {
 		map.put("description", description);
 		map.put("priority", priority);
 		map.put("authors", authors.toArray(String[]::new));
+		map.put("hints", hints.toArray(String[]::new));
         var foo = params.stream() //
 			.map(OpParameter::data) //
 			.collect(Collectors.toList());
diff --git a/scijava-ops-indexer/src/main/java/org/scijava/ops/indexer/ProcessingUtils.java b/scijava-ops-indexer/src/main/java/org/scijava/ops/indexer/ProcessingUtils.java
@@ -65,7 +65,7 @@ final class ProcessingUtils {
 	 * tags.
 	 */
 	public static final Pattern tagElementSeparator = Pattern.compile(
-		"\\s*[,\\s]+(?=(?:[^']*'[^']*')*[^']*$)");
+		"\\s*[,\\s]+(?=(?:[^'\"]*['\"][^'\"]*['\"])*[^'\"]*$)");
 
 	private ProcessingUtils() {
 		throw new AssertionError("not instantiable");

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ public Hints(final String... startingHints) {`
`62`	`62`	`this(Arrays.asList(startingHints));`
`63`	`63`	`}`
`64`	`64`
`65`		`- private Hints(final Collection<String> hints) {`
	`65`	`+ public Hints(final Collection<String> hints) {`
`66`	`66`	`this.hints = new HashSet<>(hints);`
`67`	`67`	`}`
`68`	`68`
Original file line number	Diff line number	Diff line change
`@@ -57,7 +57,7 @@ public static <N extends Number> Double subtract(N aDouble, N aDouble2) {`
`57`	`57`	`/**`
`58`	`58`	`* Another example Op, implemented by a {@link Method}`
`59`	`59`	`*`
`60`		`- * @implNote op name=example.xor, type=Inplace1`
	`60`	`+ * @implNote op name=example.xor, type=Inplace1, hints="Adaptation.FORBIDDEN,Conversion.FORBIDDEN"`
`61`	`61`	`* @param aList the first integer {@link List}`
`62`	`62`	`* @param aList2 the second integer {@link List}`
`63`	`63`	`*/`