README.md

KUrlet -- Kotlin URi tempLET

This project (sounds "qur-let") includes the library to work with URI Template RFC-6570 implemented as Kotlin multiplatform project.

Dependency on KUrlet library

In order to use any version of this library, published to the MavenCentral, in other Gradle project add into dependencies section of the build.gradle.kts file:

dependencies {
    implementation("com.helpchoice.kotlin:KUrlet:<version>")
}

Alternatively, in the projects other than Kotlin MPP, should include platform-specific artifact:

-- in Java or Groovy project

dependencies {
    implementation("com.helpchoice.kotlin:KUrlet-jvm:<version>")
}

-- in Javascript project

dependencies {
    implementation("com.helpchoice.kotlin:KUrlet-js:<version>")
}

-- in Windows, Linux, MacOS, or iOS project

dependencies {
    implementation("com.helpchoice.kotlin:KUrlet-native:<version>")
}

For earlier versions, which were not published in MavenCentral use JitPack project. Keep in mind that they are not MPProject.

To do that add at the end of repositories list of your gradle.build.kts file:

repositories {
    ...
    maven(url = 'https://jitpack.io')
}

... and in dependencies

dependencies {
    implementation("com.helpchoice.kotlin:KUrlet:<version-tag>")
}

Project structure

The project is a multiplatform pure Kotlin library. It includes separate folder of the top level module for each supported platform (JVM, JS, and Native) code and tests.

Additional modules:

• convention-plugins -- publishes released artifacts to MavenCentral
• JVMsample -- a sample Java project using this library
• GroovySample -- a sample Groovy project using this library

Common code

The common code includes 2 classes:

• UriTemplate -- represents the UriTemplate object and encloses code to split template into literals and expressions
• Expression -- represents the string literal followed by expression and modifiers (as defined in the RFC6570)

Both classes are pure Kotlin and don't need platform-specific related code.

Platform-specific code

Because common classes defined in the pure Kotlin, there is no need to implement anything in the platform-specific code.

Regression Tests

The Common tests folder includes tests, based on the examples provided in the RFC-6570 and additional tests for more complicated cases.

Tests are organized in groups, represented by classes and inner classes.

How this project measures against RFC-6570?

People have different interpretation of some aspects of the RFC-6570. Here are some comments on this project implementation approach and reasoning behind them.

Some of these conversation are from long time ago, but because the RFC-6570 didn't change and still allows multiple interpretation, file issue in GitHub with your comments and recommendations.

Combinations of the modifiers

The RFC6570 states that a prefix modifier should not be applied to variables that have composite values. On another hand an explode modifier indicates that the variable is to be treated as a composite value.

Some people interpret this as both modifiers should not be applied to the single expansion. However, in Appendix A it saies: ... If it is an explode ("*"), scan the next character. If it is a prefix (":"), continue scanning.... This means that modifiers can be combined.

This project accepts both modifiers even though apply only one, appropriate to the type of the variable value.

Order of modifiers

The RFC6570 doesn't mention the order of modifiers. The Appendix A shows an explode modifier comes before a prefix. There is no reason to do not allow reverse order as well.

This project allows modifiers in either order.

Restrictions

This project built to expand the template. To minimize the load on the client, uses this library, it may not report on templates not following all limitations of the RFC-6570. If template is not valid, the result of expansion is undefined.

Improvements

To suggest improvements please create Pull Requests with your code changes in the GitHub project.