Port to Kotlin Multiplatform

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+# 6.0
+
+The library is now a Kotlin Multiplatform library. This is a breaking API change. There is also no separate artifact for Android anymore. 
+
 # 5.2
 
 - Add support placeholders for preset names (breaking change in [v5.0.0](https://github.com/ideditor/schema-builder/blob/main/CHANGELOG.md#510) of iD presets schema)

README.md

@@ -1,105 +1,101 @@
 # osmfeatures
 
-A dictionary of OSM map features, accessible by terms and by tags, for Java and Android.
+A Kotlin multiplatform dictionary of OSM map features, accessible by terms and by tags. Supported platforms are Android, JVM and iOS.
 
-Requires Java 8.
+Due to heavy use of indices, it is very fast.
 
-## Copyright and License
-
-© 2019-2022 Tobias Zwick. This library is released under the terms of the [Apache License Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt).
+It is currently used in [StreetComplete](https://github.com/streetcomplete/streetcomplete).
 
-## Installation
-
-Add [`de.westnordost:osmfeatures:5.2`](https://mvnrepository.com/artifact/de.westnordost/osmfeatures/5.2) as a Maven dependency or download the jar from there.
+## Copyright and License
 
-For Android, use [`de.westnordost:osmfeatures-android:5.2`](https://mvnrepository.com/artifact/de.westnordost/osmfeatures-android/5.2).
+© 2019-2024 Tobias Zwick. This library is released under the terms of the Apache License Version 2.0.
 
 ## Usage
 
+Add [de.westnordost:osmfeatures:6.0](https://mvnrepository.com/artifact/de.westnordost/osmfeatures/6.0) as a Maven dependency or download the jar from there.
+
 ### Get the data
 
 The data for the dictionary is not maintained in this repository.
-It actually uses the [preset data from iD](https://github.com/openstreetmap/id-tagging-schema/blob/main/dist/presets.json) and [the translations of the presets](https://github.com/openstreetmap/id-tagging-schema/tree/main/dist/translations).
-Just dump all the translations and the presets.json into the same directory.
-Do not forget to give attribution to iD since you are using their data.
-
-If you use gradle as your build tool, the easiest way to get this data is to put this task into your `build.gradle` and either execute this task manually from time to time or make the build process depend on it (by adding `preBuild.dependsOn(downloadPresets)`):
-
-```groovy
-import groovy.json.JsonSlurper
-
-task downloadPresets {
-    doLast {
-        def targetDir = "$projectDir/path/to/where/the/data/should/go"
-        def presetsUrl = new URL("https://raw.githubusercontent.com/openstreetmap/id-tagging-schema/main/dist/presets.json")
-        def contentsUrl = new URL("https://api.github.com/repos/openstreetmap/id-tagging-schema/contents/dist/translations")
-
-        new File("$targetDir/presets.json").withOutputStream { it << presetsUrl.openStream() }
-
-        def slurper = new JsonSlurper()
-        slurper.parse(contentsUrl, "UTF-8").each {
-            if(it.type == "file") {
-                def filename = it.name.substring(0, it.name.indexOf("."))
-                def javaLanguageTag = Locale.forLanguageTag(filename.replace('@','-')).toLanguageTag()
-                def translationsUrl = new URL(it.download_url)
-                new File("$targetDir/${javaLanguageTag}.json").withOutputStream { it << translationsUrl.openStream() }
-            }
-        }
-    }
-}
-```
+It actually uses the [preset data from iD](https://github.com/openstreetmap/id-tagging-schema/blob/main/dist/presets.json),  [its translations](https://github.com/openstreetmap/id-tagging-schema/tree/main/dist/translations)
+and optionally additionally the brand preset data from the [name suggestion index](https://github.com/osmlab/name-suggestion-index). 
+Each are &copy; iD contributors, licensed under the ISC license.
+
 
-In StreetComplete (app that uses this library), there is [UpdatePresetsTask.kt](https://github.com/streetcomplete/StreetComplete/blob/master/buildSrc/src/main/java/UpdatePresetsTask.kt) to do this. It's longer but it is maintained and takes care of some more edge cases. Also, take note of [UpdateNsiPresetsTask.kt](https://github.com/streetcomplete/StreetComplete/blob/master/buildSrc/src/main/java/UpdateNsiPresetsTask.kt) which fetches the [name suggestion index presets](https://github.com/osmlab/name-suggestion-index) (=brands).
+So, just dump all the translations and the presets.json into the same directory. To be always 
+up-to-date, it is advisable to have an automatic build task that fetches the current version of the 
+presets from the repository.
+
+The app for which this library was developed (StreetComplete), uses the following tasks:
+- [UpdatePresetsTask.kt](https://github.com/streetcomplete/StreetComplete/blob/master/buildSrc/src/main/java/UpdatePresetsTask.kt) to download presets and selected translations
+- [UpdateNsiPresetsTask.kt](https://github.com/streetcomplete/StreetComplete/blob/master/buildSrc/src/main/java/UpdateNsiPresetsTask.kt) to download the brand presets from the [name suggestion index](https://github.com/osmlab/name-suggestion-index)
 
 ### Initialize dictionary
 
-Point the dictionary to the directory where the data is located (see above). Use `FeatureDictionary` as a singleton.
-```java
-FeatureDictionary dictionary = FeatureDictionary.create("path/to/data"));
+Point the dictionary to the directory where the data is located (see above). Use `FeatureDictionary` as a singleton, as initialization takes a moment (loading files, building indices).
+```kotlin
+val dictionary = FeatureDictionary.create(fileSystem, "path/to/data")
 ```
 
 For Android, use
-```java
-FeatureDictionary dictionary = AndroidFeatureDictionary.create(assetManager, "path/within/assets/folder/to/data"));
+```kotlin
+val dictionary = FeatureDictionary.create(assetManager, "path/within/assets/folder/to/data")
 ```
 
-If brand features from the [name suggestion index](https://github.com/osmlab/name-suggestion-index) (see last paragraph in the previous "Get the data" section) should be included in the dictionary, you can specify the path to these presets as a further parameter. These will be loaded on-demand depending on for which countries you search for.
+If brand features from the [name suggestion index](https://github.com/osmlab/name-suggestion-index) should be included in the dictionary, you can specify the path to these presets as a third parameter. These will be loaded on-demand depending on for which countries you search for.
+
+Translations will also be loaded on demand when first querying features using a certain language.
 
 ### Find matches by tags
-```java
-List<Feature> matches = dictionary
-    .byTags(Map.of("amenity", "bench"))  // look for features that have the given tags
-    .forGeometry(GeometryType.POINT)     // limit the search to features that may be points
-    .forLocale(Locale.GERMAN)            // show results in German only, don't fall back to English or unlocalized results
-    .find();
 
-// prints "Parkbank" (or something like this) or index out of bounds exception
-// if no preset for amenity=bench exists that is localized to German
-println(matches.get(0).getName()); 
+```kotlin
+val matches = dictionary.getByTags(
+    tags = mapOf("amenity" to "bench"), // look for features that have the given tags
+    languages = listOf("de"),           // show results in German only, don't fall back to English or unlocalized results
+    geometry = GeometryType.POINT,      // limit the search to features that may be points
+)                     
+
+
+// prints "Parkbank" (or something like this)
+// or null if no preset for amenity=bench exists that is localized to German
+println(matches[0]?.getName())
 ```
 
 ### Find matches by search word
 
-```java
-List<Feature> matches = dictionary
-    .byTerm("Bank")                  // look for features matching "Bank"
-    .forGeometry(GeometryType.AREA)  // limit the search to features that may be areas
-    .forLocale(Locale.GERMAN, null)  // show results in German or fall back to unlocalized results
+```kotlin
+val matches = dictionary.getByTerm(
+    term = "Bank",                   // look for features matching "Bank"
+    languages = listOf("de", null),  // show results in German or fall back to unlocalized results
                                      // (brand features are usually not localized)
-    .inCountry("DE")                 // also include things (brands) that only exist in Germany
-    .limit(10)                       // return at most 10 entries
-    .find();
-// result list will have matches with at least amenity=bank, but not amenity=bench because it is a point-feature
+    country = "DE",                  // also include things (brands) that only exist in Germany
+    geometry = GeometryType.AREA,    // limit the search to features that may be areas
+)
+// result sequence will have matches with at least amenity=bank, but not amenity=bench because it is a point-feature
+// if the dictionary contains also brand presets, e.g. "Deutsche Bank" will certainly also be amongst the results
 ```
 
 ### Find by id
 
+```kotlin
+val match = dictionary.getById(
+    id = "amenity/bank",
+    languages = listOf("de", "en-US", null), // show results in German, otherwise fall back to American 
+                                             // English or otherwise unlocalized results
+    country = "DE",                          // also include things (brands) that only exist in Germany
+)
+```
+
+### Builders
+
+For a more convenient interface on Java, the above functions continue to be available as builders, 
+e.g.
+
 ```java
-Feature feature = dictionary
-    .byId("amenity/bank")
-    .forLocale(Locale.GERMAN,         // show results in German, otherwise fall back to English etc.
-               Locale.ENGLISH,
-               null)
-    .inCountry("DE")                 // also include things (brands) that only exist in Germany
-    .get();
+List<Feature> matches = dictionary
+    .byTags(Map.of("amenity", "bench"))
+    .forGeometry(GeometryType.POINT)
+    .inLanguage("de")
+    .find();
 ```
+

build.gradle.kts

@@ -0,0 +1,126 @@
+plugins {
+    kotlin("multiplatform") version "1.9.24"
+    id("com.android.library") version "8.2.0"
+    id("org.jetbrains.dokka") version "1.9.20"
+
+    id("maven-publish")
+    id("signing")
+}
+
+kotlin {
+    group = "de.westnordost"
+    version = "6.0"
+
+    jvm()
+    androidTarget {
+        publishLibraryVariants("release")
+        compilations.all {
+            kotlinOptions {
+                jvmTarget = "1.8"
+            }
+        }
+    }
+    iosSimulatorArm64()
+    iosX64()
+    iosArm64()
+
+    applyDefaultHierarchyTemplate()
+
+    sourceSets {
+        commonMain {
+            dependencies {
+                // multiplatform file access
+                api("org.jetbrains.kotlinx:kotlinx-io-core:0.3.4")
+                // parsing the preset.json
+                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
+                // for stripping diacritics correctly
+                implementation("com.doist.x:normalize:1.0.5")
+            }
+        }
+        commonTest {
+            dependencies {
+                implementation(kotlin("test"))
+                // we are pulling some current preset json from the iD preset repo to see if parsing
+                // does at least not crash and return something
+                implementation("io.ktor:ktor-client-core:2.3.11")
+                implementation("io.ktor:ktor-client-cio:2.3.11")
+                // ktor-client is a suspending API, so we need coroutines too
+                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
+            }
+        }
+    }
+}
+
+
+android {
+    namespace = "de.westnordost.osmfeatures"
+    compileSdk = 33
+    defaultConfig {
+        minSdk = 21
+    }
+}
+
+val javadocJar = tasks.register<Jar>("javadocJar") {
+    archiveClassifier.set("javadoc")
+    from(tasks.dokkaHtml)
+}
+
+publishing {
+    publications {
+        withType<MavenPublication> {
+            artifactId = rootProject.name + if (name != "kotlinMultiplatform") "-$name" else ""
+            artifact(javadocJar)
+
+            pom {
+                name.set("osmfeatures")
+                description.set("Java library to translate OSM tags to and from localized names.")
+                url.set("https://github.com/westnordost/osmfeatures")
+
+                licenses {
+                    license {
+                        name.set("The Apache License, Version 2.0")
+                        url.set("https://raw.githubusercontent.com/westnordost/osmfeatures/master/LICENSE")
+                    }
+                }
+                issueManagement {
+                    system.set("GitHub")
+                    url.set("https://github.com/westnordost/osmfeatures/issues")
+                }
+                scm {
+                    connection.set("https://github.com/westnordost/osmfeatures.git")
+                    url.set("https://github.com/westnordost/osmfeatures")
+                }
+                developers {
+                    developer {
+                        id.set("westnordost")
+                        name.set("Tobias Zwick")
+                        email.set("[email protected]")
+                    }
+                }
+            }
+        }
+    }
+    repositories {
+        maven {
+            name = "oss"
+            url = uri("https://oss.sonatype.org/service/local/staging/deploy/maven2/")
+            credentials {
+                val ossrhUsername: String by project
+                val ossrhPassword: String by project
+                username = ossrhUsername
+                password = ossrhPassword
+            }
+        }
+    }
+}
+
+signing {
+    sign(publishing.publications)
+}
+
+
+// FIXME - workaround for https://github.com/gradle/gradle/issues/26091
+val signingTasks = tasks.withType<Sign>()
+tasks.withType<AbstractPublishToMaven>().configureEach {
+    mustRunAfter(signingTasks)
+}

gradle.properties

@@ -1,22 +1,7 @@
-# Project-wide Gradle settings.
-
-# IDE (e.g. Android Studio) users:
-# Gradle settings configured through the IDE *will override*
-# any settings specified in this file.
-
-# For more details on how to configure your build environment visit
-# http://www.gradle.org/docs/current/userguide/build_environment.html
-
-# Specifies the JVM arguments used for the daemon process.
-# The setting is particularly useful for tweaking memory settings.
-org.gradle.jvmargs=-Xmx1536m -Dfile.encoding=UTF-8
-
-# When configured, Gradle will run in incubating parallel mode.
-# This option should only be used with decoupled projects. More details, visit
-# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
-# org.gradle.parallel=true
-
-systemProp.file.encoding=utf-8
+# Gradle
+org.gradle.jvmargs=-Xmx2048M -Dfile.encoding=UTF-8 -Dkotlin.daemon.jvm.options\="-Xmx2048M"
+org.gradle.caching=true
+org.gradle.configuration-cache=true
 
 signing.keyId=08A11DBC
 signing.password=

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
-#Thu Mar 04 22:04:30 CET 2021
-distributionBase=GRADLE_USER_HOME
-distributionPath=wrapper/dists
-zipStoreBase=GRADLE_USER_HOME
-zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-all.zip
+#Fri Dec 22 21:31:41 CET 2023
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists