Stardust
Stardust is a software library containing a lot of powerful features that make the programmer’s life much easier. Stardust is my main project that I’ve been working on for many years. I’m developing the library with Kotlin as a multi-platform project with JVM and JavaScript as target platforms. The library is designed as an extension to Kotlin's standard API.
The Stardust library is open source software. It is licensed under the terms of the Apache License, Version 2.0. You can find the source code on GitLab: https://gitlab.com/jmpersch/stardust.
🎉 Stardust 5.0 has been released!
With this release, we celebrate 15 years Stardust! If you are interested in the background of the Stardust library, feel free to take a look into the development history!
Stardust consists of different modules that can be included to fit your needs. The following sections provide a brief overview of the modules by showing some selected features.
Main Module
Artifact: |
cc.persch:stardust
|
String Building
String formatting was yesterday—with Kotlin’s type-safe builders, we have new capabilities to build things directly with Kotlin code. The Stardust library provides type-safe builders to comfortably create strings especially for the localization of multilingual applications.
fun ShoppingCart.makeString() = rope {
+"Your shopping cart "
if(size > 0) {
+"contains "
if(size > 1)
+"$size"
else
+"one"
+" item"
plural(size, "s")
}
else
+"is empty"
+"."
}
println("Empty shopping cart: ${ShoppingCart(0).makeString()}")
println("Shopping cart containing 1 item: ${ShoppingCart(1).makeString()}")
println("Shopping cart containing 42 items: ${ShoppingCart(42).makeString()}")
Empty shopping cart: Your shopping cart is empty.
Shopping cart containing 1 item: Your shopping cart contains one item.
Shopping cart containing 42 items: Your shopping cart contains 42 items.
Extension Modules
CEH Computation Utility
Artifact: |
cc.persch:stardustx-cehc
|
Provides utils to implement the equals
, hashCode
, and compareTo
functions in a declarative manner.
Collections
Artifact: |
cc.persch:stardustx-collections
|
Mutable Collections
val mutableList: MutableList<Int> = mutableListOf(1, 2, 3, 4, 5)
// Get an immutable view of the mutable list
val immutableView: ImmutableList<Int> = mutableList.asImmutable()
// Altering the original list …
mutableList.add(6)
println("Mutable list: $mutableList")
// … also changes the immutable view
println("Immutable view: $immutableView")
Mutable list: [1, 2, 3, 4, 5, 6]
Immutable view: [1, 2, 3, 4, 5, 6]
Persistent Collections
// Create a persistent list that is guaranteed to be immutable
val persistentList1: PersistentList<Int> = persistentListOf(1, 2, 3, 4, 5)
// Create a mutated persistent copy of the original list
val persistentList2: PersistentList<Int> = persistentList1.mutate { add(6) }
println("Original list: $persistentList1")
println("Mutated copy: $persistentList2")
Original list: [1, 2, 3, 4, 5]
Mutated copy: [1, 2, 3, 4, 5, 6]
Date and Time
Artifact: |
cc.persch:stardustx-datetime
|
Stardust provides date and time classes with comfortable handling.
val date = Date.utcCurrent()
val dateTime = DateTime.utcNow()
val timeSpan = dateTime.minus(date.toUtcDateTime())
println("Date: $date")
println("DateTime: $dateTime")
println("TimeSpan: $timeSpan")
Date: 2023-11-18
DateTime: 2023-11-18 18:03:19.921 UTC
TimeSpan: 0.18:03:19.921
Event Handling
Artifact: |
cc.persch:stardustx-events
|
Stardust provides an easy-to-use event mechanism.
// Subscribe an event
eventSource.subscribe { _, arg -> println("Hello, ${arg.value}!") }
// Raise an event
eventSource.raise(this, EventArgument("Kotlin Notebook"))
Hello, Kotlin Notebook!
Results
Artifact: |
cc.persch:stardustx-results
|
With Conclude
and Unsure
, Stardust provides two result types.
Where Unsure
is used to indicate whether there is a result or not,
a Conclude
additionally contains information about the error.
fun Users.find(username: String): Conclude<User, String> {
return users.get(username) orFailure { "Username ${username.quote()} not found." }
// ↖ User? ↖ Conclude<User, String>
// ↖ Either Success<User> or Failure<String>
}
println("""Find "jdoe": ${users.find("jdoe")}""")
println("""Find "asmith": ${users.find("asmith")}""")
Find "jdoe": Success(value=John Doe)
Find "asmith": Failure(reason=Username "asmith" not found.)
Text
Artifact: |
cc.persch:stardustx-text
|
UUID
Artifact: |
cc.persch:stardustx-uuid
|
Experimental Module
Artifact: |
cc.persch:stardusty
|
This module contains experimental features. The API of this module is unstable and may change anytime.
Documentation
Take a look into the documentation of the Stardust library that explains features by showing meaningful sample implementations.
Use Stardust in Your Software Project
The following code sample shows how you can include Stardust in your software project using the Gradle build tool.
Select the modules you want use and add them to your build.gradle.kts
file.
repositories {
// The URL to the Maven package registry to retrieve the artifacts of the Stardust library.
// Find the GitLab repository under: <https://gitlab.com/jmpersch/registry>
maven("https://gitlab.com/api/v4/projects/41417498/packages/maven")
}
dependencies {
val stardustVersion = "5.0.0"
// Main module
implementation("cc.persch:stardust:$stardustVersion")
// Extension modules
implementation("cc.persch:stardustx-cehc:$stardustVersion")
implementation("cc.persch:stardustx-collections:$stardustVersion")
implementation("cc.persch:stardustx-datetime:$stardustVersion")
implementation("cc.persch:stardustx-events:$stardustVersion")
implementation("cc.persch:stardustx-results:$stardustVersion")
implementation("cc.persch:stardustx-text:$stardustVersion")
implementation("cc.persch:stardustx-uuid:$stardustVersion")
// Experimental module
implementation("cc.persch:stardusty:$stardustVersion")
}