Replace getJoke() and getJokes with joke() and jokes() [Breaking]

.gitignore

@@ -64,7 +64,6 @@ dist/
 ehthumbs.db
 fabric.properties
 gen/
-gradle.properties
 hs_err_pid*
 kobaltBuild
 kobaltw*-test

.idea/kotlinc.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="KotlinJpsPluginSettings">
-    <option name="version" value="1.8.20" />
+    <option name="version" value="1.8.22" />
   </component>
 </project>

.idea/misc.xml

@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="ExternalStorageConfigurationManager" enabled="true" />
   <component name="PDMPlugin">

README.md

@@ -17,9 +17,9 @@ A simple library to retrieve jokes from [Sv443's JokeAPI](https://v2.jokeapi.dev
 ```kotlin
 import net.thauvin.erik.jokeapi.getJoke
 
-val joke = getJoke()
+val joke = joke()
-val safe = getJoke(safe = true)
+val safe = joke(safe = true)
-val pun = getJoke(categories = setOf(Category.PUN))
+val pun = joke(categories = setOf(Category.PUN))
 ```
 The parameters match the [joke endpoint](https://v2.jokeapi.dev/#joke-endpoint).
 
@@ -41,7 +41,7 @@ data class Joke(
 To retrieve multiple jokes:
 
 ```kotlin
-val frenchJokes = getJokes(amount = 2, type = Type.TWOPART, lang = Language.FR)
+val frenchJokes = jokes(amount = 2, type = Type.TWOPART, lang = Language.FR)
 frenchJokes.forEach {
     println(it.joke.joinToString("\n"))
     println("-".repeat(46))
@@ -85,7 +85,7 @@ var config = new JokeConfig.Builder()
         .type(Type.SINGLE)
         .safe(true)
         .build();
-var joke = JokeApi.getJoke(config);
+var joke = JokeApi.joke(config);
 joke.getJoke().forEach(System.out::println);
 ```
 ## Gradle, Maven, etc.

build.gradle.kts

@@ -5,14 +5,14 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
     id("com.github.ben-manes.versions") version "0.47.0"
-    id("io.gitlab.arturbosch.detekt") version "1.23.0"
+    id("io.gitlab.arturbosch.detekt") version "1.23.1"
     id("java")
     id("maven-publish")
-    id("org.jetbrains.dokka") version "1.8.20"
+    id("org.jetbrains.dokka") version "1.9.0"
-    id("org.jetbrains.kotlinx.kover") version "0.7.2"
+    id("org.jetbrains.kotlinx.kover") version "0.7.3"
-    id("org.sonarqube") version "4.2.1.3168"
+    id("org.sonarqube") version "4.3.1.3277"
     id("signing")
-    kotlin("jvm") version "1.8.22"
+    kotlin("jvm") version "1.9.10"
 }
 
 description = "Wrapper for Sv443's JokeAPI"
@@ -36,7 +36,7 @@ dependencies {
     implementation("org.json:json:20230618")
 
     testImplementation(kotlin("test"))
-    testImplementation("org.junit.jupiter:junit-jupiter:5.9.2")
+    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
     testImplementation("com.willowtreeapps.assertk:assertk-jvm:0.26.1")
 }
 
@@ -63,7 +63,7 @@ sonarqube {
         property("sonar.organization", "ethauvin-github")
         property("sonar.host.url", "https://sonarcloud.io")
         property("sonar.sourceEncoding", "UTF-8")
-        property("sonar.coverage.jacoco.xmlReportPaths", "${project.buildDir}/reports/kover/report.xml")
+        property("sonar.coverage.jacoco.xmlReportPaths", "${project.layout.buildDirectory}/reports/kover/report.xml")
     }
 }
 

gradle.properties

@@ -0,0 +1 @@
+kotlin.code.style=official

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,7 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.1.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-bin.zip
 networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradlew

@@ -83,7 +83,8 @@ done
 # This is normally unused
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum
@@ -130,11 +131,14 @@ location of your Java installation."
     fi
 else
     JAVACMD=java
-    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
 
 Please set the JAVA_HOME variable in your environment to match the
 location of your Java installation."
     fi
+fi
 
 # Increase the maximum file descriptors if we can.
 if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then

src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt

@@ -103,7 +103,7 @@ object JokeApi {
     @JvmStatic
     @Throws(HttpErrorException::class)
     fun getRawJokes(config: JokeConfig): String {
-        return getRawJokes(
+        return rawJokes(
             categories = config.categories,
             lang = config.language,
             blacklistFlags = config.flags,
@@ -125,8 +125,8 @@ object JokeApi {
     @JvmStatic
     @JvmOverloads
     @Throws(HttpErrorException::class, JokeException::class)
-    fun getJoke(config: JokeConfig = JokeConfig.Builder().build()): Joke {
+    fun joke(config: JokeConfig = JokeConfig.Builder().build()): Joke {
-        return getJoke(
+        return joke(
             categories = config.categories,
             lang = config.language,
             blacklistFlags = config.flags,
@@ -146,8 +146,8 @@ object JokeApi {
      */
     @JvmStatic
     @Throws(HttpErrorException::class, JokeException::class)
-    fun getJokes(config: JokeConfig): Array<Joke> {
+    fun jokes(config: JokeConfig): Array<Joke> {
-        return getJokes(
+        return jokes(
             categories = config.categories,
             lang = config.language,
             blacklistFlags = config.flags,
@@ -170,7 +170,7 @@ object JokeApi {
  *
  * @param splitNewLine Split newline within [Type.SINGLE] joke.
  */
-fun getJoke(
+fun joke(
     categories: Set<Category> = setOf(Category.ANY),
     lang: Language = Language.EN,
     blacklistFlags: Set<Flag> = emptySet(),
@@ -182,7 +182,7 @@ fun getJoke(
     splitNewLine: Boolean = false
 ): Joke {
     val json = JSONObject(
-        getRawJokes(
+        rawJokes(
             categories = categories,
             lang = lang,
             blacklistFlags = blacklistFlags,
@@ -208,7 +208,7 @@ fun getJoke(
  * @param amount The required amount of jokes to return.
  * @param splitNewLine Split newline within [Type.SINGLE] joke.
  */
-fun getJokes(
+fun jokes(
     amount: Int,
     categories: Set<Category> = setOf(Category.ANY),
     lang: Language = Language.EN,
@@ -221,7 +221,7 @@ fun getJokes(
     splitNewLine: Boolean = false
 ): Array<Joke> {
     val json = JSONObject(
-        getRawJokes(
+        rawJokes(
             categories = categories,
             lang = lang,
             blacklistFlags = blacklistFlags,
@@ -250,7 +250,7 @@ fun getJokes(
  *
  * Sse the [JokeAPI Documentation](https://jokeapi.dev/#joke-endpoint) for more details.
  */
-fun getRawJokes(
+fun rawJokes(
     categories: Set<Category> = setOf(Category.ANY),
     lang: Language = Language.EN,
     blacklistFlags: Set<Flag> = emptySet(),

src/test/kotlin/net/thauvin/erik/jokeapi/ExceptionsTest.kt

@@ -58,10 +58,10 @@ internal class ExceptionsTest {
     @Test
     fun `Validate Joke Exception`() {
         val e = assertThrows<JokeException> {
-            getJoke(categories = setOf(Category.CHRISTMAS), contains = "foo")
+            joke(categories = setOf(Category.CHRISTMAS), contains = "foo")
         }
         logger.fine(e.debug())
-        assertThat(e, "getJoke(${Category.CHRISTMAS},foo)").all {
+        assertThat(e, "joke(${Category.CHRISTMAS},foo)").all {
             prop(JokeException::code).isEqualTo(106)
             prop(JokeException::internalError).isFalse()
             prop(JokeException::message).isEqualTo("No matching joke found")

src/test/kotlin/net/thauvin/erik/jokeapi/GetJokeTest.kt

@@ -64,9 +64,9 @@ import org.junit.jupiter.api.extension.ExtendWith
 internal class GetJokeTest {
     @Test
     fun `Get Joke`() {
-        val joke = getJoke()
+        val joke = joke()
         logger.fine(joke.toString())
-        assertThat(joke, "getJoke()").all {
+        assertThat(joke, "joke()").all {
             prop(Joke::joke).isNotEmpty()
             prop(Joke::type).isIn(Type.SINGLE, Type.TWOPART)
             prop(Joke::id).isGreaterThanOrEqualTo(0)
@@ -76,23 +76,23 @@ internal class GetJokeTest {
 
     @Test
     fun `Get Joke without Blacklist Flags`() {
-        val joke = getJoke(blacklistFlags = setOf(Flag.ALL))
+        val joke = joke(blacklistFlags = setOf(Flag.ALL))
         assertThat(joke::flags).isEmpty()
     }
 
     @Test
     fun `Get Joke without any Blacklist Flags`() {
         val allFlags = Flag.values().filter { it != Flag.ALL }.toSet()
-        val joke = getJoke(blacklistFlags = allFlags)
+        val joke = joke(blacklistFlags = allFlags)
         assertThat(joke::flags).isEmpty()
     }
 
     @Test
     fun `Get Joke with ID`() {
         val id = 172
-        val joke = getJoke(idRange = IdRange(id))
+        val joke = joke(idRange = IdRange(id))
         logger.fine(joke.toString())
-        assertThat(joke, "getJoke($id)").all {
+        assertThat(joke, "joke($id)").all {
             prop(Joke::flags).all {
                 contains(Flag.EXPLICIT)
                 contains(Flag.NSFW)
@@ -105,7 +105,7 @@ internal class GetJokeTest {
     @Test
     fun `Get Joke with ID Range`() {
         val idRange = IdRange(1, 100)
-        val joke = getJoke(idRange = idRange)
+        val joke = joke(idRange = idRange)
         logger.fine(joke.toString())
         assertThat(joke::id).isBetween(idRange.start, idRange.end)
     }
@@ -113,24 +113,24 @@ internal class GetJokeTest {
     @Test
     fun `Get Joke with invalid ID Range`() {
         val idRange = IdRange(100, 1)
-        val e = assertThrows<IllegalArgumentException> { getJoke(idRange = idRange, lang = Language.DE) }
+        val e = assertThrows<IllegalArgumentException> { joke(idRange = idRange, lang = Language.DE) }
         assertThat(e::message).isNotNull().contains("100, 1")
     }
 
     @Test
     fun `Get Joke with max ID Range`() {
         val idRange = IdRange(1, 30000)
-        val e = assertThrows<JokeException> { getJoke(idRange = idRange) }
+        val e = assertThrows<JokeException> { joke(idRange = idRange) }
-        assertThat(e, "getJoke{${idRange})").all {
+        assertThat(e, "joke{${idRange})").all {
             prop(JokeException::additionalInfo).contains("ID range")
         }
     }
 
     @Test
     fun `Get Joke with two Categories`() {
-        val joke = getJoke(categories = setOf(Category.PROGRAMMING, Category.MISC))
+        val joke = joke(categories = setOf(Category.PROGRAMMING, Category.MISC))
         logger.fine(joke.toString())
-        assertThat(joke.category, "getJoke(${Category.PROGRAMMING},${Category.MISC})").isIn(
+        assertThat(joke.category, "joke(${Category.PROGRAMMING},${Category.MISC})").isIn(
             Category.PROGRAMMING,
             Category.MISC
         )
@@ -139,28 +139,28 @@ internal class GetJokeTest {
     @Test
     fun `Get Joke with each Categories`() {
         Category.values().filter { it != Category.ANY }.forEach {
-            val joke = getJoke(categories = setOf(it))
+            val joke = joke(categories = setOf(it))
             logger.fine(joke.toString())
-            assertThat(joke::category, "getJoke($it)").prop(Category::value).isEqualTo(it.value)
+            assertThat(joke::category, "joke($it)").prop(Category::value).isEqualTo(it.value)
         }
     }
 
     @Test
     fun `Get Joke with each Languages`() {
         Language.values().forEach {
-            val joke = getJoke(lang = it)
+            val joke = joke(lang = it)
             logger.fine(joke.toString())
-            assertThat(joke::lang, "getJoke($it)").prop(Language::value).isEqualTo(it.value)
+            assertThat(joke::lang, "joke($it)").prop(Language::value).isEqualTo(it.value)
         }
     }
 
     @Test
     fun `Get Joke with Split Newline`() {
-        val joke = getJoke(
+        val joke = joke(
             categories = setOf(Category.DARK), type = Type.SINGLE, idRange = IdRange(178), splitNewLine = true
         )
         logger.fine(joke.toString())
-        assertThat(joke::joke, "getJoke(splitNewLine=true)").all {
+        assertThat(joke::joke, "joke(splitNewLine=true)").all {
             size().isEqualTo(2)
             each {
                 containsNone("\n")
@@ -170,25 +170,25 @@ internal class GetJokeTest {
 
     @Test
     fun `Get Safe Joke`() {
-        val joke = getJoke(safe = true)
+        val joke = joke(safe = true)
         logger.fine(joke.toString())
-        assertThat(joke, "getJoke(safe)").all {
+        assertThat(joke, "joke(safe)").all {
             prop(Joke::safe).isTrue()
         }
     }
 
     @Test
     fun `Get Single Joke`() {
-        val joke = getJoke(type = Type.SINGLE)
+        val joke = joke(type = Type.SINGLE)
         logger.fine(joke.toString())
         assertThat(joke::type).assertThat(Type.SINGLE)
     }
 
     @Test
     fun `Get Two-Parts Joke`() {
-        val joke = getJoke(type = Type.TWOPART)
+        val joke = joke(type = Type.TWOPART)
         logger.fine(joke.toString())
-        assertThat(joke, "getJoke(${Type.TWOPART})").all {
+        assertThat(joke, "joke(${Type.TWOPART})").all {
             prop(Joke::type).isEqualTo(Type.TWOPART)
             prop(Joke::joke).size().isGreaterThan(1)
         }
@@ -199,9 +199,9 @@ internal class GetJokeTest {
         val id = 265
         val search = "his wife"
         val joke =
-            getJoke(contains = search, categories = setOf(Category.PROGRAMMING), idRange = IdRange(id), safe = true)
+            joke(contains = search, categories = setOf(Category.PROGRAMMING), idRange = IdRange(id), safe = true)
         logger.fine(joke.toString())
-        assertThat(joke, "getJoke($search)").all {
+        assertThat(joke, "joke($search)").all {
             prop(Joke::id).isEqualTo(id)
             prop(Joke::joke).any {
                 it.contains(search)

src/test/kotlin/net/thauvin/erik/jokeapi/GetJokesTest.kt

@@ -53,7 +53,7 @@ internal class GetJokesTest {
     @Test
     fun `Get Multiple Jokes`() {
         val amount = 2
-        val jokes = getJokes(amount = amount, safe = true, lang = Language.FR)
+        val jokes = jokes(amount = amount, safe = true, lang = Language.FR)
         assertThat(jokes, "jokes").all {
             size().isEqualTo(amount)
             each {
@@ -66,13 +66,13 @@ internal class GetJokesTest {
 
     @Test
     fun `Get Jokes with Invalid Amount`() {
-        val e = assertThrows<IllegalArgumentException> { getJokes(amount = -1) }
+        val e = assertThrows<IllegalArgumentException> { jokes(amount = -1) }
         assertThat(e::message).isNotNull().contains("-1")
     }
 
     @Test
     fun `Get One Joke as Multiple`() {
-        val jokes = getJokes(amount = 1, safe = true)
+        val jokes = jokes(amount = 1, safe = true)
         assertThat(jokes, "jokes").all {
             size().isEqualTo(1)
             index(0).all {

src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt

@@ -46,8 +46,8 @@ import kotlin.test.assertContains
 internal class GetRawJokesTest {
     @Test
     fun `Get Raw Joke with TXT`() {
-        val response = getRawJokes(format = Format.TXT)
+        val response = rawJokes(format = Format.TXT)
-        assertThat(response, "getRawJoke(txt)").all {
+        assertThat(response, "rawJoke(txt)").all {
             isNotEmpty()
             doesNotContain("Error")
         }
@@ -55,25 +55,25 @@ internal class GetRawJokesTest {
 
     @Test
     fun `Get Raw Joke with XML`() {
-        val response = getRawJokes(format = Format.XML)
+        val response = rawJokes(format = Format.XML)
-        assertThat(response, "getRawJoke(xml)").startsWith("<?xml version='1.0'?>\n<data>\n    <error>false</error>")
+        assertThat(response, "rawJoke(xml)").startsWith("<?xml version='1.0'?>\n<data>\n    <error>false</error>")
     }
 
     @Test
     fun `Get Raw Joke with YAML`() {
-        val response = getRawJokes(format = Format.YAML)
+        val response = rawJokes(format = Format.YAML)
-        assertThat(response, "getRawJoke(yaml)").startsWith("error: false")
+        assertThat(response, "rawJoke(yaml)").startsWith("error: false")
     }
 
     @Test
     fun `Get Raw Jokes`() {
-        val response = getRawJokes(amount = 2)
+        val response = rawJokes(amount = 2)
-        assertContains(response, "\"amount\": 2", false, "getRawJoke(2)")
+        assertContains(response, "\"amount\": 2", false, "rawJoke(2)")
     }
 
     @Test
     fun `Get Raw Invalid Jokes`() {
-        val response = getRawJokes(contains = "foo", safe = true, amount = 2, idRange = IdRange(160, 161))
+        val response = rawJokes(contains = "foo", safe = true, amount = 2, idRange = IdRange(160, 161))
         assertContains(response, "\"error\": true", false, "getRawJokes(foo)")
     }
 }

src/test/kotlin/net/thauvin/erik/jokeapi/JokeConfigTest.kt

@@ -41,8 +41,8 @@ import assertk.assertions.isGreaterThanOrEqualTo
 import assertk.assertions.isTrue
 import assertk.assertions.prop
 import assertk.assertions.size
-import net.thauvin.erik.jokeapi.JokeApi.getJoke
+import net.thauvin.erik.jokeapi.JokeApi.joke
-import net.thauvin.erik.jokeapi.JokeApi.getJokes
+import net.thauvin.erik.jokeapi.JokeApi.jokes
 import net.thauvin.erik.jokeapi.JokeApi.getRawJokes
 import net.thauvin.erik.jokeapi.JokeApi.logger
 import net.thauvin.erik.jokeapi.models.Category
@@ -60,7 +60,7 @@ import kotlin.test.assertContains
 internal class JokeConfigTest {
     @Test
     fun `Get Joke with Default Builder`() {
-        val joke = getJoke()
+        val joke = joke()
         assertThat(joke, "joke").all {
             prop(Joke::id).isGreaterThanOrEqualTo(0)
             prop(Joke::lang).isEqualTo(Language.EN)
@@ -78,7 +78,7 @@ internal class JokeConfigTest {
             idRange(IdRange(id - 2, id + 2))
             safe(true)
         }.build()
-        val joke = getJoke(config)
+        val joke = joke(config)
         logger.fine(joke.toString())
         assertThat(joke, "config").all {
             prop(Joke::type).isEqualTo(Type.TWOPART)
@@ -98,7 +98,7 @@ internal class JokeConfigTest {
             idRange(IdRange(id))
             splitNewLine(true)
         }.build()
-        val joke = getJoke(config)
+        val joke = joke(config)
         logger.fine(joke.toString())
         assertThat(joke, "config").all {
             prop(Joke::id).isEqualTo(id)
@@ -127,7 +127,7 @@ internal class JokeConfigTest {
             safe(true)
             lang(Language.FR)
         }.build()
-        val jokes = getJokes(config)
+        val jokes = jokes(config)
         assertThat(jokes, "jokes").all {
             size().isEqualTo(amount)
             each {