okaeripoland / okaeri-placeholders

Simple blazing-fast placeholders library with yet unlimited capabilities

Okaeri Placeholders (okaeri-placeholders)

Simple blazing-fast placeholders library with yet unlimited capabilities. Part of the okaeri-platform.

Installation

Maven

Add repository to the repositories section:

<repository>
    <id>okaeri-repo</id>
    <url>https://storehouse.okaeri.eu/repository/maven-public/</url>
</repository>

Add dependency to the dependencies section:

<dependency>
  <groupId>eu.okaeri</groupId>
  <artifactId>okaeri-placeholders-[platform]</artifactId>
  <version>5.1.0</version>
</dependency>

Gradle

Add repository to the repositories section:

maven { url "https://storehouse.okaeri.eu/repository/maven-public/" }

Add dependency to the maven section:

implementation 'eu.okaeri:okaeri-placeholders-[platform]:5.1.0'

Format

# basic message
Hello World!
# with simple placeholder
Hello {who}!
# with simple placeholder and fallback value
Hello {who|unknown}!
# with subfields
Hello {who.name}!
# with subfields and fallback value
Hello {who.name|unknown}!
# with pluralization for 143 locales (okaeri-pluralize)
I would like {amount} {apple,apples#amount}.
# with boolean translation
Active: {yes,no#status}
# with number formatting
Value: {%.2f#value}
# with duration (e.g. "1d12h", supports precision, see: (h))
Remaining time: {duration(h)}
# with instant (time, datetime, date, pattern - localized - optional timezone)
Time: {ldt,medium,Europe/Paris#time}

Example

Basic example representing standard usage for simple placeholders. For more examples and advanced usage cases see tests. For subfield support (e.g. {player.name}) see TestSchema.java, for pluralization and other metadata see TestMetadataUsage.java.

// this is intended to be loaded from the configuration on the startup/cached and stored compiled
CompiledMessage message = CompiledMessage.of("Hola {who}! ¿Cómo estás {when}? Estoy {how}.");

// context can be reused (use #create() and #apply(message)) 
// or created on demand (use #of(message) and #apply())
// second version can't be reused but is faster in on-demand scenario
// especially when resulting message is using only part of the placeholders
PlaceholderContext context = PlaceholderContext.of(message)
    .with("who", "Mundo") // in real life scenario these would be your variables
    .with("when", "hoy")
    .with("how", "bien");

// process message and get output: Hola Mundo! ¿Cómo estás hoy? Estoy bien.
String test = context.apply();

Benchmarks

Note: Since JDK8 times, the built-in String#replace(CharSequence, CharSequence) has become faster or comparable to the okaeri-placeholders in some benchmarks, but even ignoring lacking features, it is and will be always unsafe to use for placeholders due to the sole nature of chaining.

Charts are representing operations per second for each of the implementations. For the current source code of test see benchmark directory.

• Okaeri Placeholders benchmark is based on cached CompiledMessage as this is intended use of the library. PlaceholderContext is created every iteration.
• JDK8 String#replace benchmarks are chaining replace calls together, as one may do while implementing this type of system with no additional code.
• CommonsLang3 StringUtils#replaceEach benchmarks are using standard single call with no additional code.
• Spec: (AdoptOpenJDK)(build 1.8.0_282-b08), OS: Ubuntu 20.04.2 LTS x86_64, CPU: AMD Ryzen 5 3600 (12) @ 3.600GHz, okaeri-placeholders: 1.0.0

Simple

This group represents average messages with fields.

Repeated

This group uses multiline string built by repeating string from the simple group to check for repeated fields/stress performance.

Long

This group represents the replacement of a few evenly distributed fields inside a long string, e.g. html e-mail template. The long tricky represents long string with one field in the last 20% of the string.

Static

This group shows differences in the performance for static strings that do not require any processing, but nor String#replace chain neither StringUtils#replaceEach can know that, causing performance loss when the character count is going up.

okaeri-placeholders's Issues

Placeholder metadata does not allow comma for string formatting

These are not working as expected and are incorrectly interpreted:

• {%,.0f#value}
• {%\,.0f#value}

This is already working for placeholder parameters.

Add Duration support

It would be great to allow custom java.time.Duration formatting that can produce:

• 02:30
• 01:02:30
• 2h3m
• 1d2h3m
• 2 hours and 3 minutes
• 1 hour and 3 minutes
• 1 day and 5 hours
• 1 day, 5 hours and 1 minute

Possible solutions:

• Allow to extract specific part of the duration just by including default decomposition rules (e.g. hours {duration.hours} {hour,hours#duration.hours}) - easy solution, but this alone does not allow dynamic range and would result in things like "0 days, 4 hours, 1 minute". Good start anyway - would integrate okay with current pluralization. A bit long to write. Can even support leading zeros using the number formatting feature. Very flexible with the formatting and the different approaches languages can have for such constructs.