From f0b7902cabd71ba48c6d03c8c0e40fdea06dabb5 Mon Sep 17 00:00:00 2001 From: "Erik C. Thauvin" Date: Sat, 25 May 2024 20:42:11 -0700 Subject: [PATCH 1/2] Bumped Kotlin to version 2.0.0 --- README.md | 2 +- examples/bld/lib/bld/bld-wrapper.properties | 2 +- examples/bld/src/.idea/workspace.xml | 8 -------- examples/gradle/build.gradle.kts | 2 +- lib/bld/bld-wrapper.properties | 4 ++-- src/bld/java/net/thauvin/erik/IsgdShortenBuild.java | 2 +- 6 files changed, 6 insertions(+), 14 deletions(-) delete mode 100644 examples/bld/src/.idea/workspace.xml diff --git a/README.md b/README.md index bfeb5b6..504f627 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ [![License (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](https://opensource.org/licenses/BSD-3-Clause) -[![Kotlin](https://img.shields.io/badge/kotlin-1.9.24-7f52ff)](https://kotlinlang.org/) +[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0-7f52ff)](https://kotlinlang.org/) [![bld](https://img.shields.io/badge/1.9.1-FA9052?label=bld&labelColor=2392FF)](https://rife2.com/bld) [![release](https://img.shields.io/github/release/ethauvin/isgd-shorten.svg)](https://github.com/ethauvin/isgd-shorten/releases/latest) [![Maven Central](https://img.shields.io/maven-central/v/net.thauvin.erik/isgd-shorten.svg?color=blue)](https://central.sonatype.com/artifact/net.thauvin.erik/isgd-shorten) diff --git a/examples/bld/lib/bld/bld-wrapper.properties b/examples/bld/lib/bld/bld-wrapper.properties index 3338e7d..1243fad 100644 --- a/examples/bld/lib/bld/bld-wrapper.properties +++ b/examples/bld/lib/bld/bld-wrapper.properties @@ -1,7 +1,7 @@ bld.downloadExtensionJavadoc=false bld.downloadExtensionSources=true bld.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.5 -bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.4 +bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.7 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES bld.downloadLocation= bld.sourceDirectories= diff --git a/examples/bld/src/.idea/workspace.xml b/examples/bld/src/.idea/workspace.xml deleted file mode 100644 index 43b4714..0000000 --- a/examples/bld/src/.idea/workspace.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - { - "keyToString": { - "settings.editor.selected.configurable": "reference.settings.ide.settings.new.ui" - } -} - \ No newline at end of file diff --git a/examples/gradle/build.gradle.kts b/examples/gradle/build.gradle.kts index 907543c..14825d6 100644 --- a/examples/gradle/build.gradle.kts +++ b/examples/gradle/build.gradle.kts @@ -3,7 +3,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile plugins { id("application") id("com.github.ben-manes.versions") version "0.51.0" - kotlin("jvm") version "1.9.24" + kotlin("jvm") version "2.0.0" } repositories { diff --git a/lib/bld/bld-wrapper.properties b/lib/bld/bld-wrapper.properties index 42b7cff..3bec20e 100644 --- a/lib/bld/bld-wrapper.properties +++ b/lib/bld/bld-wrapper.properties @@ -1,8 +1,8 @@ bld.downloadExtensionJavadoc=false bld.downloadExtensionSources=true bld.extension-jacoco=com.uwyn.rife2:bld-jacoco-report:0.9.5 -bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.4 -bld.extension-detekt=com.uwyn.rife2:bld-detekt:0.9.3 +bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.7 +bld.extension-detekt=com.uwyn.rife2:bld-detekt:0.9.4 bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES bld.downloadLocation= bld.sourceDirectories= diff --git a/src/bld/java/net/thauvin/erik/IsgdShortenBuild.java b/src/bld/java/net/thauvin/erik/IsgdShortenBuild.java index 0ed3d8a..bb5cdae 100644 --- a/src/bld/java/net/thauvin/erik/IsgdShortenBuild.java +++ b/src/bld/java/net/thauvin/erik/IsgdShortenBuild.java @@ -68,7 +68,7 @@ public class IsgdShortenBuild extends Project { repositories = List.of(MAVEN_LOCAL, MAVEN_CENTRAL); - final var kotlin = version(1, 9, 24); + final var kotlin = version(2, 0, 0); scope(compile) .include(dependency("org.jetbrains.kotlin", "kotlin-stdlib", kotlin)) .include(dependency("net.thauvin.erik.urlencoder", "urlencoder-lib-jvm", version(1, 5, 0))); From cfa49e7e3e6e175632d5e5cd957dc1323731bd02 Mon Sep 17 00:00:00 2001 From: "Erik C. Thauvin" Date: Sat, 25 May 2024 21:14:15 -0700 Subject: [PATCH 2/2] Reworked config builder. Added parameters' documentation. --- config/detekt/baseline.xml | 1 + .../bld/java/com/example/ExampleBuild.java | 2 +- examples/gradle/build.gradle.kts | 10 +- examples/gradle/settings.gradle.kts | 2 +- pom.xml | 2 +- .../kotlin/net/thauvin/erik/isgd/Config.kt | 98 +++++++++++++------ src/main/kotlin/net/thauvin/erik/isgd/Isgd.kt | 30 ++++++ 7 files changed, 109 insertions(+), 36 deletions(-) diff --git a/config/detekt/baseline.xml b/config/detekt/baseline.xml index a3e303c..0eea41c 100644 --- a/config/detekt/baseline.xml +++ b/config/detekt/baseline.xml @@ -5,6 +5,7 @@ LongParameterList:Isgd.kt$Isgd.Companion$( url: String, shorturl: String = "", callback: String = "", logstats: Boolean = false, format: Format = Format.SIMPLE, isVgd: Boolean = false ) MagicNumber:Isgd.kt$Isgd.Companion$200 MagicNumber:Isgd.kt$Isgd.Companion$399 + MaxLineLength:Isgd.kt$Isgd.Companion$* NestedBlockDepth:IsgdExample.kt$fun main(args: Array<String>) WildcardImport:IsgdTest.kt$import assertk.assertions.* diff --git a/examples/bld/src/bld/java/com/example/ExampleBuild.java b/examples/bld/src/bld/java/com/example/ExampleBuild.java index 1598991..19bb45e 100644 --- a/examples/bld/src/bld/java/com/example/ExampleBuild.java +++ b/examples/bld/src/bld/java/com/example/ExampleBuild.java @@ -24,7 +24,7 @@ public class ExampleBuild extends BaseProject { repositories = List.of(MAVEN_LOCAL, MAVEN_CENTRAL, SONATYPE_SNAPSHOTS_LEGACY); scope(compile) - .include(dependency("net.thauvin.erik:isgd-shorten:1.0.1")); + .include(dependency("net.thauvin.erik:isgd-shorten:1.0.2-SNAPSHOT")); } public static void main(String[] args) { diff --git a/examples/gradle/build.gradle.kts b/examples/gradle/build.gradle.kts index 14825d6..68ac436 100644 --- a/examples/gradle/build.gradle.kts +++ b/examples/gradle/build.gradle.kts @@ -13,7 +13,7 @@ repositories { } dependencies { - implementation("net.thauvin.erik:isgd-shorten:1.0.1") + implementation("net.thauvin.erik:isgd-shorten:1.0.2-SNAPSHOT") } java { @@ -25,11 +25,11 @@ application { mainClass.set("com.example.IsgdExampleKt") } -tasks { - withType().configureEach { - kotlinOptions.jvmTarget = java.targetCompatibility.toString() - } +kotlin { + compilerOptions.jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11) +} +tasks { register("runJava", JavaExec::class) { group = "application" mainClass.set("com.example.IsgdSample") diff --git a/examples/gradle/settings.gradle.kts b/examples/gradle/settings.gradle.kts index 4ddea20..ed4a5c2 100644 --- a/examples/gradle/settings.gradle.kts +++ b/examples/gradle/settings.gradle.kts @@ -7,4 +7,4 @@ * in the user manual at https://docs.gradle.org/6.2/userguide/multi_project_builds.html */ -rootProject.name = "isgd-examples" +rootProject.name = "isgd-shorten-examples-gradle" diff --git a/pom.xml b/pom.xml index 16d9003..a8bfca4 100644 --- a/pom.xml +++ b/pom.xml @@ -18,7 +18,7 @@ org.jetbrains.kotlin kotlin-stdlib - 1.9.24 + 2.0.0 compile diff --git a/src/main/kotlin/net/thauvin/erik/isgd/Config.kt b/src/main/kotlin/net/thauvin/erik/isgd/Config.kt index f970922..67587fc 100644 --- a/src/main/kotlin/net/thauvin/erik/isgd/Config.kt +++ b/src/main/kotlin/net/thauvin/erik/isgd/Config.kt @@ -34,41 +34,83 @@ package net.thauvin.erik.isgd /** * Provides a builder to create/lookup an is.gd shortlink. */ -class Config private constructor( - val url: String, - val shorturl: String, - val callback: String, - val logstats: Boolean, - val format: Format, - val isVgd: Boolean +class Config( + var url: String = "", + var shorturl: String = "", + var callback: String = "", + var logstats: Boolean = false, + var format: Format = Format.SIMPLE, + var isVgd: Boolean = false ) { + constructor(builder: Builder) : this() { + url = builder.url + shorturl = builder.shorturl + callback = builder.callback + logstats = builder.logstats + format = builder.format + isVgd = builder.isVgd + } + /** * Configures the parameters to create/lookup an is.gd shortlink. * - * See the [is.gd API](https://is.gd/apishorteningreference.php). + * See the [is.gd Shortening](https://is.gd/apishorteningreference.php) or + * [is.gd Lookup](https://is.gd/apilookupreference.php) APIs. */ data class Builder( - private var url: String = "", - private var shorturl: String = "", - private var callback: String = "", - private var logstats: Boolean = false, - private var format: Format = Format.SIMPLE, - private var isVgd: Boolean = false + var url: String = "", + var shorturl: String = "", + var callback: String = "", + var logstats: Boolean = false, + var format: Format = Format.SIMPLE, + var isVgd: Boolean = false ) { - fun url(url: String) = apply { this.url = url } - fun shortUrl(shortUrl: String) = apply { this.shorturl = shortUrl } - fun callback(callback: String) = apply { this.callback = callback } - fun logStats(logStats: Boolean) = apply { this.logstats = logStats } - fun format(format: Format) = apply { this.format = format } - fun isVgd(isVgd: Boolean) = apply { this.isVgd = isVgd } + /** + * The url parameter is the address that you want to shorten. + */ + fun url(url: String): Builder = apply { this.url = url } - fun build() = Config( - url, - shorturl, - callback, - logstats, - format, - isVgd - ) + /** + * You can specify the shorturl parameter if you'd like to pick a shortened URL instead of + * having is.gd randomly generate one. These must be between 5 and 30 characters long and can only contain + * alphanumeric characters and underscores. Shortened URLs are case sensitive. Bear in mind that a desired + * short URL might already be taken (this is very often the case with common words) so if you're using this + * option be prepared to respond to an error and get an alternative choice from your app's user. + */ + fun shortUrl(shortUrl: String): Builder = apply { this.shorturl = shortUrl } + + /** + * The callback parameter is used to specify a callback function to wrap the returned data in + * when using JSON format. This can be useful when working with cross domain data. Even when using JSON format + * this parameter is optional. + */ + fun callback(callback: String): Builder = apply { this.callback = callback } + + /** + * Turns on logging of detailed statistics when the shortened URL you create is accessed. This + * allows you to see how many times the link was accessed on a given day, what pages referred people to the + * link, what browser visitors were using etc. You can access these stats via the link preview page for your + * shortened URL (add a hyphen/dash to the end of the shortened URL to get to it). Creating links with + * statistics turned on has twice the "cost" towards our rate limit of other shortened links, so leave this + * parameter out of your API call if you don't require statistics on usage. See the + * [usage limits page](https://is.gd/usagelimits.php) for more information on this. + */ + fun logStats(logStats: Boolean): Builder = apply { this.logstats = logStats } + + /** + * The format parameter determines what format is.gd uses to send output back to you (e.g. to + * tell you what your new shortened URL is or if an error has occurred). + */ + fun format(format: Format): Builder = apply { this.format = format } + + /** + * Shorten using the `v.gd` domain. + */ + fun isVgd(isVgd: Boolean): Builder = apply { this.isVgd = isVgd } + + /** + * Builds a new configuration. + */ + fun build() = Config(this) } } diff --git a/src/main/kotlin/net/thauvin/erik/isgd/Isgd.kt b/src/main/kotlin/net/thauvin/erik/isgd/Isgd.kt index 92718cc..756eb3f 100644 --- a/src/main/kotlin/net/thauvin/erik/isgd/Isgd.kt +++ b/src/main/kotlin/net/thauvin/erik/isgd/Isgd.kt @@ -88,6 +88,16 @@ class Isgd private constructor() { * Lookup a shortlink. * * See the [is.gd API](https://is.gd/apilookupreference.php). + * + * @param The shorturl parameter is the shortened is.gd URL that you want to look up. You can either submit the + * full address (e.g. https://is.gd/example) or only the unique part (e.g. example). The address you submit + * should be properly formed; the API lookup function is not guaranteed to handle malformed URLs the same way as when you visit them manually. + * @param callback The callback parameter is used to specify a callback function to wrap the returned data in + * when using JSON format. This can be useful when working with cross domain data. Even when using JSON format + * this parameter is optional. + * @param format The format parameter determines what format is.gd uses to send output back to you (e.g. to + * tell you what your new shortened URL is or if an error has occurred). + * @param isVgd Lookup using the `v.gd` domain. */ @JvmStatic @JvmOverloads @@ -133,6 +143,26 @@ class Isgd private constructor() { * Shortens a link. * * See the [is.gd API](https://is.gd/apishorteningreference.php). + * + * @param url The url parameter is the address that you want to shorten. + * @param shorturl You can specify the shorturl parameter if you'd like to pick a shortened URL instead of + * having is.gd randomly generate one. These must be between 5 and 30 characters long and can only contain + * alphanumeric characters and underscores. Shortened URLs are case sensitive. Bear in mind that a desired + * short URL might already be taken (this is very often the case with common words) so if you're using this + * option be prepared to respond to an error and get an alternative choice from your app's user. + * @param callback The callback parameter is used to specify a callback function to wrap the returned data in + * when using JSON format. This can be useful when working with cross domain data. Even when using JSON format + * this parameter is optional. + * @param logstats Turns on logging of detailed statistics when the shortened URL you create is accessed. This + * allows you to see how many times the link was accessed on a given day, what pages referred people to the + * link, what browser visitors were using etc. You can access these stats via the link preview page for your + * shortened URL (add a hyphen/dash to the end of the shortened URL to get to it). Creating links with + * statistics turned on has twice the "cost" towards our rate limit of other shortened links, so leave this + * parameter out of your API call if you don't require statistics on usage. See the + * [usage limits page](https://is.gd/usagelimits.php) for more information on this. + * @param format The format parameter determines what format is.gd uses to send output back to you (e.g. to + * tell you what your new shortened URL is or if an error has occurred). + * @param isVgd Shorten using the `v.gd` domain. */ @JvmStatic @JvmOverloads