From 9e5092a246289979f6bb88b6cd7d44068da67309 Mon Sep 17 00:00:00 2001
From: Gold Holk <gholk@disroot.org>
Date: Fri, 2 Sep 2022 14:15:33 +0800
Subject: [PATCH] Docs for new find options and implement the jump-to option

There is a `-:` option in the docs of `find`, but it is not implemented.
This commit implement it.
The new docs of `--search-from-view` and `--reverse` are added, too.
---
 src/content/finding.ts | 16 +++++++++++++---
 src/excmds.ts          | 38 ++++++++++++++++++++++++++------------
 2 files changed, 39 insertions(+), 15 deletions(-)

diff --git a/src/content/finding.ts b/src/content/finding.ts
index 487726e6..7b306591 100644
--- a/src/content/finding.ts
+++ b/src/content/finding.ts
@@ -94,7 +94,7 @@ let selected = 0
 
 let HIGHLIGHT_TIMER
 
-export async function jumpToMatch(searchQuery, reverse) {
+export async function jumpToMatch(searchQuery, option) {
     const timeout = config.get("findhighlighttimeout")
     if (timeout > 0) {
         clearTimeout(HIGHLIGHT_TIMER)
@@ -151,15 +151,25 @@ export async function jumpToMatch(searchQuery, reverse) {
         throw new Error("Pattern not found: " + searchQuery)
     }
     lastHighlights.sort(
-        reverse ? (a, b) => b.top - a.top : (a, b) => a.top - b.top,
+        option.reverse ? (a, b) => b.top - a.top : (a, b) => a.top - b.top,
     )
 
+    if ("jumpTo" in option) {
+        selected = (option.jumpTo + lastHighlights.length) % lastHighlights.length
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+        ;(lastHighlights[selected] as any).focus()
+        return
+    }
+
     // Just reuse the code to find the first match in the view
     selected = 0
     if (lastHighlights[selected].isVisible()) {
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         ;(lastHighlights[selected] as any).focus()
-    } else jumpToNextMatch(1, true)
+    } else {
+        const searchFromView = true
+        await jumpToNextMatch(1, searchFromView)
+    }
 }
 
 function drawHighlights(highlights) {
diff --git a/src/excmds.ts b/src/excmds.ts
index d005d59d..4df12090 100644
--- a/src/excmds.ts
+++ b/src/excmds.ts
@@ -1428,14 +1428,16 @@ export function scrollpage(n = 1, count = 1) {
  *  Rudimentary find mode, left unbound by default as we don't currently support `incsearch`. Suggested binds:
  *
  *      bind / fillcmdline find
- *      bind ? fillcmdline find -?
- *      bind n findnext 1
- *      bind N findnext -1
+ *      bind ? fillcmdline find --reverse
+ *      bind n findnext --search-from-view
+ *      bind N findnext --search-from-view --reverse
+ *      bind gn findnext
+ *      bind gN findnext --reverse
  *      bind ,<Space> nohlsearch
  *
  *  Argument: A string you want to search for.
  *
- *  This function accepts two flags: `-?` to search from the bottom rather than the top and `-: n` to jump directly to the nth match.
+ *  This function accepts two flags: `-?` or `--reverse` to search from the bottom rather than the top and `-: n` or `--jump-to n` to jump directly to the nth match.
  *
  *  The behavior of this function is affected by the following setting:
  *
@@ -1445,17 +1447,30 @@ export function scrollpage(n = 1, count = 1) {
  */
 //#content
 export function find(...args: string[]) {
-    const flagpos = args.indexOf("-?")
-    const reverse = flagpos >= 0
-    if (reverse) args.splice(flagpos, 1)
+    const argOpt = arg.lib(
+        {
+            "--jump-to": Number,
+            "-:": "--jump-to",
 
-    const searchQuery = args.join(" ")
-    return finding.jumpToMatch(searchQuery, reverse)
+            "--reverse": Boolean,
+            "-?": "--reverse",
+        },
+        { argv: args, permissive: true },
+    )
+    const option = {}
+    option["reverse"] = Boolean(argOpt["--reverse"])
+    if ("--jump-to" in argOpt) option["jumpTo"] = argOpt["--jump-to"]
+    const searchQuery = argOpt._.join(" ")
+    return finding.jumpToMatch(searchQuery, option)
 }
 
-/** Jump to the next searched pattern.
+/** Jump to the next nth searched pattern.
  *
- * @param number - number of words to advance down the page (use 1 for next word, -1 for previous)
+ * Available flags:
+ * - `-f` or `--search-from-view` to search from the current view instead of the previous match
+ * - `-?` or `--reverse` to reverse the sign of the number
+ *
+ * @param number - number of words to advance down the page (use 1 for next word, -1 for previous), default to 1
  *
  */
 //#content
@@ -1464,7 +1479,6 @@ export function findnext(...args: string[]) {
     const option = arg.lib(
         {
             "--search-from-view": Boolean,
-            "--searchFromView": "--search-from-view",
             "-f": "--search-from-view",
 
             "--reverse": Boolean,