From e5570ae62cd8baca03b5d836782ecb9d0e828a53 Mon Sep 17 00:00:00 2001
From: Janne Valkealahti <janne.valkealahti@gmail.com>
Date: Tue, 6 Dec 2022 09:00:24 +0000
Subject: [PATCH] Add search algo docs

- Relates #579
---
 ...ndices-techical-intro-searchalgorithm.adoc | 65 +++++++++++++++++++
 .../asciidoc/appendices-techical-intro.adoc   |  2 +
 .../using-shell-components-ui-pathsearch.adoc |  3 +
 .../shell/docs/SearchAlgorithmsSnippets.java  | 57 ++++++++++++++++
 4 files changed, 127 insertions(+)
 create mode 100644 spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc
 create mode 100644 spring-shell-docs/src/test/java/org/springframework/shell/docs/SearchAlgorithmsSnippets.java

diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc
new file mode 100644
index 00000000..5fa9492f
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc
@@ -0,0 +1,65 @@
+[#appendix-tech-intro-searchalgorithm]
+=== Search Algorithms
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+`SearchMatch` is an interface to match _text_ with a _pattern_. Match
+results are in a returned value `SearchMatchResult`. Match result
+contains info about match positions and overall score of a match.
+
+https://github.com/junegunn/fzf[fzf].
+
+==== Implementations
+
+*FuzzyMatchV2Search*
+
+Port of _fzf FuzzyMatchV2Search_ algorithm. Does a fast fuzzy search and is good
+quickly finding paths.
+
+*ExactMatchNaive*
+
+Port of _fzf ExactMatchNaive_ algorithm. Simple exact match works more accurately
+if you know what to search.
+
+==== SearchMatch
+
+Algorithms and default syntax are hidden inside package protected classes
+as we don't want to fully open these until we know API's are good to go
+for longer support. You need to construct `SearchMatch` via its
+build-in builder.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/SearchAlgorithmsSnippets.java[tag=builder]
+----
+====
+
+It's possible to configure _case sensitivity_, on what _direction_ search
+happens or if text should be _normilized_ before search happens. Normalization
+is handy when different languages have sligh variation for same type
+of characters.
+
+Search algorithm is selected based on a search syntax shown in
+below table.
+
+.Search syntax
+|===
+|Token |Match type |Description
+
+|`hell`
+|fuzzy-match
+|Items that match `hello`
+
+|`'stuff`
+|exact-match
+|Items that include `stuff`
+|===
+
+==== Examples
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/SearchAlgorithmsSnippets.java[tag=simple]
+----
+====
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc
index 62591a6f..cf835df2 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc
+++ b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc
@@ -15,3 +15,5 @@ include::appendices-techical-intro-commandcontext.adoc[]
 include::appendices-techical-intro-commandcatalog.adoc[]
 
 include::appendices-techical-intro-theming.adoc[]
+
+include::appendices-techical-intro-searchalgorithm.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc
index d383a882..aaf1b9a5 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc
@@ -13,6 +13,9 @@ include::{snippets}/UiComponentSnippets.java[tag=snippet9]
 ----
 ====
 
+NOTE: Logic for search is passed as is into algorithms documented
+in <<appendix-tech-intro-searchalgorithm>>.
+
 The following image shows typical output from a path search component:
 
 image::images/component-path-search-1.svg[text input]
diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/SearchAlgorithmsSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/SearchAlgorithmsSnippets.java
new file mode 100644
index 00000000..b6aee015
--- /dev/null
+++ b/spring-shell-docs/src/test/java/org/springframework/shell/docs/SearchAlgorithmsSnippets.java
@@ -0,0 +1,57 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * Licensed 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
+ *
+ *      https://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.springframework.shell.docs;
+
+import org.springframework.shell.support.search.SearchMatch;
+import org.springframework.shell.support.search.SearchMatchResult;
+
+class SearchAlgorithmsSnippets {
+
+	@SuppressWarnings("unused")
+	void dump1() {
+		// tag::builder[]
+		SearchMatch searchMatch = SearchMatch.builder()
+			.caseSensitive(false)
+			.normalize(false)
+			.forward(true)
+			.build();
+		// end::builder[]
+	}
+
+	void dump2() {
+		// tag::simple[]
+		SearchMatch searchMatch = SearchMatch.builder()
+			.caseSensitive(false)
+			.normalize(false)
+			.forward(true)
+			.build();
+
+		SearchMatchResult result = searchMatch.match("foo bar baz", "fbb");
+
+		result.getStart();
+		// 0 - start position inclusive
+		result.getEnd();
+		// 9 - end position exclusive
+		result.getPositions();
+		// 0,4,8 - positions, inclusive
+		result.getScore();
+		// 112 - score
+		result.getAlgorithm();
+		// FuzzyMatchV2SearchMatchAlgorithm - resolved algo
+		// end::simple[]
+	}
+
+}