v6.0

Three years in the making, v6.0 is the largest release of persianutils to date! Two brand-new modules, a strongly typed and calendar-aware date API, Scala.js support, and a proper documentation site.

Highlights

New module: TextSanitiser

TextSanitiser normalises messy Persian text into clean, canonical form:

• Standardises Arabic character variants (ك → ک, ي/ى → ی, heh variants)
• Converts Western and Eastern Arabic digits to Persian digits (123, ١٢٣ → ۱۲۳)
• Normalises punctuation to Persian equivalents (، ؛ ؟)
• Cleans spacing: collapses repeated spaces, removes non-breaking and zero-width characters, and ensures half-spaces (ZWNJ) take priority over full spaces
• Strips kashida/tatweel elongation
• Optionally removes tashkeel (diacritics)

Every step is configurable via SanitiserConfig.

TextSanitiser.sanitise("  كتاب علي 123 و ١٤٠٣, تست?  ")
// کتاب علی ۱۲۳ و ۱۴۰۳، تست؟

New module: DateToWord

Long-standing issue #4, finally closed. Dates become spoken Persian:

PersianDate(1361, 3, 3).toWords     // سوم خرداد یک هزار و سیصد و شصت و یک
GregorianDate(1992, 12, 3).toWords  // سوم دسامبر یک هزار و نه‌صد و نود و دو

NumToWord: cardinal and ordinal

NumToWord now distinguishes cardinal and ordinal numbering:

NumToWord.cardinal(235) // دویست و سی و پنج
NumToWord.ordinal(235)  // دویست و سی و پنجم

DateConverter: typed, calendar-aware dates

• New PersianDate and GregorianDate case classes (sharing the sealed ConvertibleDate trait) replace the calendar-agnostic SimpleDate, so the compiler now knows which calendar a value belongs to.
• First-class java.time.LocalDate bridging: every date converts to and from LocalDate, and DateConverter.gregorianToPersian accepts a LocalDate directly.
• Date-string parsing (YYYY/MM/DD) is shared by all date types; malformed input raises InvalidDateException.
• SimpleDate is retained for source compatibility, but PersianDate/GregorianDate are recommended going forward.

Scala.js support

The library is now cross-built for the JVM and Scala.js (sjs1), so the same API works in browser and Node.js projects.

Documentation site

Documentation moved out of the README to a MkDocs Material site at https://persianutils.bahmanm.com with per-module guides, a compatibility matrix, and published Scaladoc for both Scala 3 and Scala 2.13.

Breaking changes

• Scala 2.12 is no longer supported; the library is cross-built for 2.13 and 3 only.
• JDK 11 is no longer supported; CI covers 17, 21, and 25.

Deprecated (removal scheduled for 7.0.0)

• NumToWord.apply — use NumToWord.cardinal or NumToWord.ordinal
• java.util.Date interop (SimpleDate.apply(java.util.Date) and asDate) — use java.time.LocalDate and asLocalDate

Installation

SBT (JVM):

libraryDependencies += "com.bahmanm" %% "persianutils" % "6.0"

SBT (Scala.js):

libraryDependencies += "com.bahmanm" %%% "persianutils" % "6.0"

Maven (Scala 3; use persianutils_2.13 for Scala 2.13):

<dependency>
  <groupId>com.bahmanm</groupId>
  <artifactId>persianutils_3</artifactId>
  <version>6.0</version>
</dependency>

What's Changed

• [#4] DateToWords by @bahmanm in #99
• [#3] Implement text sanitiser by @bahmanm in #106
• [#95] Implement ordinal NumToWords by @bahmanm in #96
• [#80] Make SimpleDate calendar-aware by @bahmanm in #81
• [#85] Use java.util.LocalDate by @bahmanm in #90
• [#84] Add Scala.js integration by @bahmanm in #94
• [#82] Drop 2.12 support by @bahmanm in #86
• [#83] Switch from specs2 to munit by @bahmanm in #88
• [#71] Add JDK 21 by @bahmanm in #74
• [#91] Drop JDK 11 and add JDK 25 by @bahmanm in #92
• [#97] Smoke-test suites by @bahmanm in #98
• [#68] Switch to GitHub Actions and dependabot by @bahmanm in #70
• [#87] Set up GitHub Pages by @bahmanm in #100
• [#104] Switch to MkDocs by @bahmanm in #105
• [#111] Fix stale documentation by @bahmanm in #112
• [#109] Fix the broken links in documentation by @bahmanm in #110
• [#122] Ensure half-spaces have higher priority that full-spaces by @bahmanm in #123
• [#126] add scalafmt by @bahmanm in #127
• [#128] Create a GitHub release by @bahmanm in #129
• [#130] Update the documents (v6.0) by @bahmanm in #131

Plus the usual batch of dependency and tooling updates (sbt 1.13, Scala 2.13.18 / 3.3.8, Scala.js 1.22, scalafmt 3.11.5).

Full Changelog: v5.0...v6.0