strings

Kotlin Multi-platform String Resource Accessor and Creator Library

Note: This project is in early development stages and is not ready for production use.

The goal of this library is to abstract both the creation and retrieval of strings in Kotlin Multi-platform Projects.

Using the library

Add the Dependencies

Plugin

apply plugin: "com.chrynan.strings.plugin.gradle.json"

Runtime Dependency

repositories {
    maven {
        url = "https://dl.bintray.com/chrynan/chrynan"
    }
}

dependencies {
    implementation "com.chrynan.strings:strings-accessor:$VERSION"
}

Configure the Plugin

jsonStrings {
    inputPaths = ["location/to/json/string/file.json"]
    outputPath = "src/commonMain/kotlin/com.chrynan.example"
    outputPackageName = "com.chrynan.example"
}

Create the Strings

JSON

Create a JSON file with a top-level array containing the String objects.

[{
  "type": "static",
  "name": "helloWorld",
  "value": "Hello World"
}]

Kotlin Annotations (Not yet supported)

// File MyStrings - File name and location can be anything
@file:StaticString(name = "helloWorld", value = "Hello World")

Run the Gradle Task

./gradlew generateStringsFromJsonInput

Add the generated StringAccessor

Strings.accessor = KotlinStrings() // Generated Class

Access the String Resources

// Using the generated String Resource IDs
val myStaticString by string(resourceID = StringResIDs.myStaticString)

Definitions

StaticString

Static Strings are String values that are not formatted, meaning they do not require any arguments to obtain a String value.

JSON

{
  "type": "static",
  "name": "hello_world",
  "value": "Hello World"
}

Kotlin Annotations (Not yet supported)

@file:StaticString(name = "hello_world", value = "Hello World", locale = "en")

Kotlin Accessibility

val helloWorld = string(resourceID = StringResID.hello_world)

StringArray

String Arrays are Arrays of Static String values.

JSON

{
  "type": "array",
  "name": "numbers",
  "values": ["one", "two", "three", "four", "five"]
}

Kotlin Annotations (Not yet supported)

@file:StringArray(
    name = "numbers",
    locale = "en",
    values = [
        StringArrayItem(value = "one"),
        StringArrayItem(value = "two"),
        StringArrayItem(value = "three"),
        StringArrayItem(value = "four"),
        StringArrayItem(value = "five")
    ]
)

Kotlin Accessibility

val numbers = stringArray(resourceID = StringResID.numbers)

DynamicString

Dynamic Strings are String values that can be formatted by providing additional arguments at runtime.

JSON

{
  "type": "dynamic",
  "name": "hello_name",
  "value": "Hello ${name:String}"
}

Kotlin Annotations (Not yet supported)

@file:DynamicString(name = "hello_name", value = "Hello \${name:String}", locale = "en")

Dynamic String Arguments:

Dynamic String arguments take the following format: ${name:type}. Or if in Kotlin code the $ character must be escaped: \${name:type}. Dynamic Strings with no arguments are essentially Static Strings.

Supported Argument Types:

Kotlin Type	Expanded Definition	Brief Definition
Any	${name:Any}	${name:a}
Char	${name:Char}	${name:c}
String	${name:String}	${name:s}
Int	${name:Int}	${name:i}
Long	${name:Long}	${name:l}
Float	${name:Float}	${name:f}
Double	${name:Double}	${name:d}
Custom	${name:com.chrynan.Example}	---

Custom Types: Custom types can be provided with the following syntax: ${name:packageName.typeName}.

The provided custom type name must be the fully qualified Kotlin type name.

Argument Names:

All Dynamic String arguments need to be prefaced with an argument name. These names will be used to create input argument names in the generated code.

• Dynamic Strings can use the same argument multiple times:

"Hello ${name:String}! How are you ${name}?"

• If Dynamic String reuse same argument multiple times, the type only has to be provided once, for the first usage of the name.
• Non-matching types for the same argument name will cause an error.
• Argument names cannot begin with a number
• Argument names must conform to Kotlin property name requirements.

Escaping Arguments:

To escape the $ character so that it doesn't register as an argument, use the \ character: \$.

HtmlString

Html Strings are Dynamic Strings that contain Html markup. No special parsing of the markup is performed in this library. Instead, this is a way to organize Html Strings separately so that they can be handled appropriately.

JSON

{
  "type": "html",
  "name": "hello_name",
  "value": "Hello <b>${name:String}</b>"
}

Kotlin Annotations (Not yet supported)

@file:HtmlString(name = "greeting", value = "Hello <b>\${name:String}</b>")

StringPlurals

String Plurals are Dynamic Strings that are grouped together and distinguished by a provided Quantity. Each of the StringPluralItems must have the same amount of arguments.

JSON

{
  "type": "plurals",
  "name": "items",
  "values": [
    {
      "quantity": "one",
      "value": "${number:Int} item"
    },
    {
      "quantity": "many",
      "value": "${number:Int} items"
    } 
  ]
}

Kotlin Annotations (Not yet supported)

@file:StringPlurals(
    name = "items",
    locale = "en",
    values = [
        StringPluralItem(quantity = Quantity.ONE, value = "\${number:Int} item"),
        StringPluralItem(quantity = Quantity.MANY, value = "\${number:Int} items")
    ]
)

Note: That it is up to the accessor of the StringPlurals value to provide a Quantity to retrieve the appropriate String.