From 59e0082236c8fdb95feedfb94a135fb2cba089a7 Mon Sep 17 00:00:00 2001
From: breandan <bre@ndan.co>
Date: Sat, 3 Apr 2021 20:37:22 -0400
Subject: [PATCH] document ExternalUsage endpoints in README.md #354

---
 README.md                            | 37 ++++++++++++++++++++++++++++
 build.gradle.kts                     |  1 +
 src/test/kotlin/ExternalUsageTest.kt |  9 +++----
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 882800d8..a9c28992 100755
--- a/README.md
+++ b/README.md
@@ -91,6 +91,43 @@ The build artifact will be placed in `build/distributions/`.
 
 *Miscellaneous: AceJump is built using [Gradle](https://gradle.com/) with the [Gradle Kotlin DSL](https://docs.gradle.org/5.1/userguide/kotlin_dsl.html) and the [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin).*
 
+## Extending
+
+AceJump can be used by other [IntelliJ Platform](https://plugins.jetbrains.com/docs/intellij/welcome.html) plugins. To do so, add the following snippet to your `build.gradle.kts` file:
+
+```kotlin
+intellij {
+  setPlugins("AceJump:<VERSION>")
+}
+```
+
+Callers who pass an instance of [`Editor`](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java) into `SessionManager.start(editor)` will receive a [`Session`](src/main/kotlin/org/acejump/session/Session.kt) instance in return. Sessions are disposed after use.
+
+To use AceJump externally, please see the following example:
+
+```kotlin
+import org.acejump.session.SessionManager
+import org.acejump.session.AceJumpListener
+import org.acejump.boundaries.StandardBoundaries.*
+import org.acejump.search.Pattern.*
+
+val aceJumpSession = SessionManager.start(editorInstance)
+
+aceJumpSession.addAceJumpListener(object: AceJumpListener {
+  override fun finished() {
+    // ...
+  }
+})
+
+// Sessions provide these endpoints for external consumers:
+
+/*1.*/ aceJumpSession.markResults(sortedSetOf(/*...*/)) // Pass a set of offsets
+/*2.*/ aceJumpSession.startRegexSearch("[aeiou]+", WHOLE_FILE) // Search for regex
+/*3.*/ aceJumpSession.startRegexSearch(ALL_WORDS, VISIBLE_ON_SCREEN) // Search for Pattern
+```
+
+Custom boundaries for search (i.e. current line before caret etc.) can also be defined using the [Boundaries](src/main/kotlin/org/acejump/boundaries/Boundaries.kt) interface.
+
 ## Contributing
 
 AceJump is supported by community members like you. Contributions are highly welcome!
diff --git a/build.gradle.kts b/build.gradle.kts
index 07a1c701..0ec14f51 100755
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -60,6 +60,7 @@ intellij {
   pluginName = "AceJump"
   updateSinceUntilBuild = false
   setPlugins("java")
+
 }
 
 group = "org.acejump"
diff --git a/src/test/kotlin/ExternalUsageTest.kt b/src/test/kotlin/ExternalUsageTest.kt
index 79c19bc4..bfb1b17f 100644
--- a/src/test/kotlin/ExternalUsageTest.kt
+++ b/src/test/kotlin/ExternalUsageTest.kt
@@ -1,10 +1,9 @@
 import junit.framework.TestCase
-import org.acejump.boundaries.StandardBoundaries
-import org.acejump.search.Pattern
+import org.acejump.boundaries.StandardBoundaries.*
+import org.acejump.search.Pattern.*
 import org.acejump.session.*
 import org.acejump.test.util.BaseTest
 
-
 /**
  * Test [org.acejump.ExternalUsage] endpoints.
  */
@@ -34,7 +33,7 @@ class ExternalUsageTest: BaseTest() {
     makeEditor("test external pattern usage")
 
     SessionManager.start(myFixture.editor)
-      .startRegexSearch(Pattern.ALL_WORDS, StandardBoundaries.WHOLE_FILE)
+      .startRegexSearch(ALL_WORDS, WHOLE_FILE)
 
     TestCase.assertEquals(4, session.tags.size)
   }
@@ -43,7 +42,7 @@ class ExternalUsageTest: BaseTest() {
     makeEditor("test external regex usage")
 
     SessionManager.start(myFixture.editor)
-      .startRegexSearch("[aeiou]+", StandardBoundaries.WHOLE_FILE)
+      .startRegexSearch("[aeiou]+", WHOLE_FILE)
 
     TestCase.assertEquals(8, session.tags.size)
   }