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