Merge pull request #7 from teogor/feature/plurals-enhancement

Enhance Pluralization Support: Add PluralForms and Rule Implementations
teogor · Aug 28, 2024 · c657e2e · c657e2e
2 parents 83b02c0 + 049ea09
commit c657e2e
Show file tree

Hide file tree

Showing 14 changed files with 1,247 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -92,6 +92,39 @@ To get started with Xenoglot, refer to the comprehensive documentation available
 [source.teogor.dev/xenoglot](https://source.teogor.dev/xenoglot). The documentation provides
 detailed explanations, examples, and best practices for using the library effectively.
 
+## Pluralization Support
+
+The `xenoglot-pluralization` module offers comprehensive support for pluralization, allowing you to manage
+and format strings based on quantities. This feature helps in correctly displaying text for
+different numbers of items, adapting to various pluralization rules.
+
+### Quick Start
+
+To get started with pluralization:
+
+1. **Create Plural Forms**: Define templates for different plural categories (e.g., zero, one, few,
+   many).
+2. **Retrieve Formatted Strings**: Use methods to get the appropriate string for specific
+   quantities.
+
+Here's a brief example:
+
+```kotlin
+val pluralForms = createPluralForms(
+    zeroTemplate = "No items",
+    oneTemplate = "One item",
+    twoTemplate = "Two items",
+    fewTemplate = "%d items",
+    manyTemplate = "%d items",
+    otherTemplate = "%d items",
+)
+
+println(pluralForms.getQuantityString(5))  // Output: "5 items"
+```
+
+For a more detailed guide on how to use pluralization effectively, please refer to
+the [Pluralization Module Documentation](docs/pluralization-guide.md).
+
 ## Find this repository useful? 🩷
 * Support it by joining __[stargazers](https://github.com/teogor/xenoglot/stargazers)__ for this repository. 📁
 * Get notified about my new projects by __[following me](https://github.com/teogor)__ on GitHub. 💻

diff --git a/docs/index.md b/docs/index.md
@@ -185,6 +185,39 @@ val dialectCountryCode = dialect.country.code
 * **Promote Language-Aware Development:** Xenoglot encourages language-aware development practices,
   ensuring that language data is handled accurately and appropriately.
 
+## Pluralization Support
+
+The `xenoglot-pluralization` module offers comprehensive support for pluralization, allowing you to manage
+and format strings based on quantities. This feature helps in correctly displaying text for
+different numbers of items, adapting to various pluralization rules.
+
+### Quick Start
+
+To get started with pluralization:
+
+1. **Create Plural Forms**: Define templates for different plural categories (e.g., zero, one, few,
+   many).
+2. **Retrieve Formatted Strings**: Use methods to get the appropriate string for specific
+   quantities.
+
+Here's a brief example:
+
+```kotlin
+val pluralForms = createPluralForms(
+    zeroTemplate = "No items",
+    oneTemplate = "One item",
+    twoTemplate = "Two items",
+    fewTemplate = "%d items",
+    manyTemplate = "%d items",
+    otherTemplate = "%d items",
+)
+
+println(pluralForms.getQuantityString(5))  // Output: "5 items"
+```
+
+For a more detailed guide on how to use pluralization effectively, please refer to
+the [Pluralization Module Documentation](pluralization-guide.md).
+
 ## Find this repository useful? 🩷
 
 * Support it by joining __[stargazers](https://github.com/teogor/xenoglot/stargazers)__ for this

diff --git a/docs/pluralization-guide.md b/docs/pluralization-guide.md
@@ -0,0 +1,81 @@
+# Pluralization Support in Xenoglot
+
+The `xenoglot-pluralization` module provides tools for handling plural forms of strings. This document
+offers a comprehensive overview of how to utilize these features effectively.
+
+## Creating Plural Forms
+
+Use the `createPluralForms` function to define templates for various plural categories:
+
+```kotlin
+val pluralForms = createPluralForms(
+    zeroTemplate = "No items",
+    oneTemplate = "One item",
+    twoTemplate = "Two items",
+    fewTemplate = "%d items",
+    manyTemplate = "%d items",
+    otherTemplate = "%d items",
+)
+```
+
+## Methods for Retrieving Quantity Strings
+
+### `getQuantityString(quantity: Int)`
+
+Returns the formatted string for the specified quantity. Uses the "other" template if the quantity
+does not match any rule.
+
+```kotlin
+val result = pluralForms.getQuantityString(5)  // Example: "5 items"
+```
+
+### `getQuantityStringOrNull(quantity: Int)`
+
+Returns the formatted string or `null` if the quantity is not handled.
+
+```kotlin
+val result = pluralForms.getQuantityStringOrNull(-1)  // Example: null
+```
+
+### `getQuantityStringOrElse(quantity: Int, fallback: String)`
+
+Returns the formatted string or a fallback string if the quantity is not handled.
+
+```kotlin
+val result = pluralForms.getQuantityStringOrElse(-1, "Unknown")  // Example: "Unknown"
+```
+
+### `getQuantityStringOrThrow(quantity: Int)`
+
+Returns the formatted string or throws an exception if the quantity is not handled.
+
+```kotlin
+val result = pluralForms.getQuantityStringOrThrow(1)  // Example: "One item"
+```
+
+## Example Usage
+
+Here’s how you can use these methods in practice:
+
+```kotlin
+val pluralForms = createPluralForms(
+    zeroTemplate = "No items",
+    oneTemplate = "One item",
+    twoTemplate = "Two items",
+    fewTemplate = "%d items",
+    manyTemplate = "%d items",
+    otherTemplate = "%d items",
+)
+
+println(pluralForms.getQuantityString(0))  // Output: "No items"
+println(pluralForms.getQuantityString(1))  // Output: "One item"
+println(pluralForms.getQuantityString(2))  // Output: "Two items"
+println(pluralForms.getQuantityString(5))  // Output: "5 items"
+println(pluralForms.getQuantityString(11)) // Output: "11 items"
+
+println(pluralForms.getQuantityStringOrNull(-1)) // Output: null
+println(pluralForms.getQuantityStringOrElse(-1, "Unknown")) // Output: "Unknown"
+```
+
+This module helps in managing pluralized strings effectively, ensuring accurate representation
+across different quantities.
diff --git a/settings.gradle.kts b/settings.gradle.kts
@@ -31,8 +31,9 @@ dependencyResolutionManagement {
   }
 }
 
-include("xenoglot-bom")
 include("xenoglot-atlas")
-include("xenoglot-core")
 include("xenoglot-atlas-extended")
+include("xenoglot-bom")
+include("xenoglot-core")
 include("xenoglot-locale")
+include("xenoglot-pluralization")
diff --git a/xenoglot-pluralization/.gitignore b/xenoglot-pluralization/.gitignore
@@ -0,0 +1 @@
+/build
diff --git a/xenoglot-pluralization/api/android/xenoglot-pluralization.api b/xenoglot-pluralization/api/android/xenoglot-pluralization.api
@@ -0,0 +1,72 @@
+public final class dev/teogor/xenoglot/pluralization/FewRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/ManyRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/OneRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/OtherRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/PluralForms {
+	public fun <init> (Ljava/util/List;)V
+	public final fun copy (Ljava/util/List;)Ldev/teogor/xenoglot/pluralization/PluralForms;
+	public static synthetic fun copy$default (Ldev/teogor/xenoglot/pluralization/PluralForms;Ljava/util/List;ILjava/lang/Object;)Ldev/teogor/xenoglot/pluralization/PluralForms;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getQuantityString (I)Ljava/lang/String;
+	public final fun getQuantityStringOrElse (ILjava/lang/String;)Ljava/lang/String;
+	public static synthetic fun getQuantityStringOrElse$default (Ldev/teogor/xenoglot/pluralization/PluralForms;ILjava/lang/String;ILjava/lang/Object;)Ljava/lang/String;
+	public final fun getQuantityStringOrNull (I)Ljava/lang/String;
+	public final fun getQuantityStringOrThrow (I)Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class dev/teogor/xenoglot/pluralization/PluralFormsKt {
+	public static final fun createPluralForms (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Ldev/teogor/xenoglot/pluralization/PluralForms;
+}
+
+public abstract interface class dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public abstract fun getTemplate ()Ljava/lang/String;
+	public abstract fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/PluralizationRuleKt {
+	public static final fun createPluralizationRules (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Ljava/util/List;
+}
+
+public abstract interface class dev/teogor/xenoglot/pluralization/PluralizationTemplates {
+	public abstract fun getFewTemplate ()Ljava/lang/String;
+	public abstract fun getManyTemplate ()Ljava/lang/String;
+	public abstract fun getOneTemplate ()Ljava/lang/String;
+	public abstract fun getOtherTemplate ()Ljava/lang/String;
+	public abstract fun getTwoTemplate ()Ljava/lang/String;
+	public abstract fun getZeroTemplate ()Ljava/lang/String;
+}
+
+public final class dev/teogor/xenoglot/pluralization/TwoRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/ZeroRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
diff --git a/xenoglot-pluralization/api/jvm/xenoglot-pluralization.api b/xenoglot-pluralization/api/jvm/xenoglot-pluralization.api
@@ -0,0 +1,72 @@
+public final class dev/teogor/xenoglot/pluralization/FewRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/ManyRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/OneRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/OtherRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/PluralForms {
+	public fun <init> (Ljava/util/List;)V
+	public final fun copy (Ljava/util/List;)Ldev/teogor/xenoglot/pluralization/PluralForms;
+	public static synthetic fun copy$default (Ldev/teogor/xenoglot/pluralization/PluralForms;Ljava/util/List;ILjava/lang/Object;)Ldev/teogor/xenoglot/pluralization/PluralForms;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getQuantityString (I)Ljava/lang/String;
+	public final fun getQuantityStringOrElse (ILjava/lang/String;)Ljava/lang/String;
+	public static synthetic fun getQuantityStringOrElse$default (Ldev/teogor/xenoglot/pluralization/PluralForms;ILjava/lang/String;ILjava/lang/Object;)Ljava/lang/String;
+	public final fun getQuantityStringOrNull (I)Ljava/lang/String;
+	public final fun getQuantityStringOrThrow (I)Ljava/lang/String;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class dev/teogor/xenoglot/pluralization/PluralFormsKt {
+	public static final fun createPluralForms (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Ldev/teogor/xenoglot/pluralization/PluralForms;
+}
+
+public abstract interface class dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public abstract fun getTemplate ()Ljava/lang/String;
+	public abstract fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/PluralizationRuleKt {
+	public static final fun createPluralizationRules (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Ljava/util/List;
+}
+
+public abstract interface class dev/teogor/xenoglot/pluralization/PluralizationTemplates {
+	public abstract fun getFewTemplate ()Ljava/lang/String;
+	public abstract fun getManyTemplate ()Ljava/lang/String;
+	public abstract fun getOneTemplate ()Ljava/lang/String;
+	public abstract fun getOtherTemplate ()Ljava/lang/String;
+	public abstract fun getTwoTemplate ()Ljava/lang/String;
+	public abstract fun getZeroTemplate ()Ljava/lang/String;
+}
+
+public final class dev/teogor/xenoglot/pluralization/TwoRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+
+public final class dev/teogor/xenoglot/pluralization/ZeroRule : dev/teogor/xenoglot/pluralization/PluralizationRule {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getTemplate ()Ljava/lang/String;
+	public fun matches (I)Z
+}
+