Merge from upstream

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: Build, Test and Release
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  release:
+    types: [ released ]
+
+env:
+  DOTNET_NOLOGO: true
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 100
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v5.1.0
+      with:
+        dotnet-version: 10.0.x
+
+    - name: Install dependencies
+      working-directory: ./src
+      run: dotnet restore
+
+    - name: Build
+      working-directory: ./src
+      run: | 
+        dotnet build --configuration Release --no-restore
+        dotnet pack -c Release Jeffijoe.MessageFormat/Jeffijoe.MessageFormat.csproj
+
+    - name: Test
+      working-directory: ./src
+      run: dotnet test --no-restore --verbosity normal
+
+    - name: Publish to NuGet
+      if: github.event_name == 'release' # Only publish on Release creation.
+      working-directory: ./src
+      run: |
+        dotnet nuget push Jeffijoe.MessageFormat/**/*.nupkg --api-key ${{ secrets.NUGET_JEFFIJOE_KEY }} --source https://api.nuget.org/v3/index.json

.gitignore

@@ -27,3 +27,6 @@ obj
 bin
 imagecache
 /src/.vs
+src/.idea/.idea.MessageFormat/.idea/workspace.xml
+.DS_Store
+BenchmarkDotNet.Artifacts/

README.md

@@ -2,18 +2,18 @@
 
 #### - better UI strings.
 
- [![Build status](https://ci.appveyor.com/api/projects/status/9g7dplst1vyibc3e?svg=true)](https://ci.appveyor.com/project/jeffijoe/messageformat-net) [![Join the chat at https://gitter.im/jeffijoe/messageformat.net](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jeffijoe/messageformat.net?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Build & Test](https://github.com/jeffijoe/messageformat.net/actions/workflows/ci.yml/badge.svg)](https://github.com/jeffijoe/messageformat.net/actions/workflows/ci.yml)
 
 This is an implementation of the ICU Message Format in .NET. For official information about the format, go to:
-http://userguide.icu-project.org/formatparse/messages
+https://unicode-org.github.io/icu/userguide/format_parse/messages/
 
 ## Quickstart
 
 ````csharp
 var mf = new MessageFormatter();
 
 var str = @"You have {notifications, plural,
-              zero {no notifications}
+                =0 {no notifications}
                one {one notification}
                =42 {a universal amount of notifications}
              other {# notifications}
@@ -60,20 +60,19 @@ Install-Package MessageFormat
 ## Features
 
 * **It's fast.** Everything is hand-written; no parser-generators, *not even regular expressions*.
-* **It's portable.** The library is a PCL, and has just a single dependency ([Portable.ConcurrentDictionary](https://www.nuget.org/packages/Portable.ConcurrentDictionary/) for thread safety) - other than that the only reference is the standard `.NET` in PCL's.
-* **It's compatible with other implementations.** I've been peeking a bit at the [MessageFormat.js][0] library to make sure
-  the results would be the same.
+* **It's portable.** The library is targeting **.NET Standard 2.0**.
 * **It's (relatively) small**. For a .NET library, ~25kb is not a lot.
 * **It's very white-space tolerant.** You can structure your blocks so they are more readable - look at the example above.
 * **Nesting is supported.** You can nest your blocks as you please, there's no special structure required to do this, just ensure your braces match.
 * **Adding your own formatters.** I don't know why you would need to, but if you want, you can add your own formatters, and
   take advantage of the code in my base classes to help you parse patterns. Look at the source, this is how I implemented the built-in formatters.
-* **Exceptions make atleast a little sense.** When exceptions are thrown due to a bad pattern, the exception should include useful information.
+* **Exceptions make at least a little sense.** When exceptions are thrown due to a bad pattern, the exception should include useful information.
 * **There are unit tests.** Run them yourself if you want, they're using XUnit.
 * **Built-in cache.** If you are formatting messages in a tight loop, with different data for each iteration,
   and if you are reusing the same instance of `MessageFormatter`, the formatter will cache the tokens of each pattern (nested, too),
   so it won't have to spend CPU time to parse out literals every time. I benchmarked it, and on my monster machine,
   it didn't make much of a difference (10000 iterations).
+* **Built-in pluralization formatters**. Generated from the [CLDR pluralization rule data][plural-cldr].
 
 ## Performance
 
@@ -84,21 +83,73 @@ and about 3 seconds (3236ms) without it. **These results are with a debug build,
 
 ## Supported formats
 
-Basically, it should be able to do anything that [MessageFormat.js][0] can do.
+MessageFormat.NET supports the most commonly used formats:
 
 * Select Format: `{gender, select, male{He likes} female{She likes} other{They like}} cheeseburgers`
-* Plural Format: `There {msgCount, plural, zero {are no unread messages} one {is 1 unread message} other{are # unread messages}}.` (where `#` is the actual number, with the offset (if any) subtracted).
+* Plural Format: `There {msgCount, plural, =0 {are no unread messages} one {is 1 unread message} other{are # unread messages}}.` (where `#` is the actual number, with the offset (if any) subtracted).
+* Ordinal Format: `You are the {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} person in line.`
 * Simple variable replacement: `Your name is {name}`
+* Numbers: `Your age is {age, number}`
+* Dates: `You were born {birthday, date}` 
+* Time: `The time is {now, time}` 
+
+You can also specify a _predefined style_, for example `{birthday, date, short}`. The supported predefined styles are:
+
+* For the `number` format: `integer`, `currency`, `percent`
+* For the `date` format: `short`, `full`
+* For the `time` format: `short`, `medium`
+
+These are currently mapped to the built-in .NET format specifiers. This package does not ship with
+any locale data beyond the pluralizers that are generated based on [CLDR data][plural-cldr], so if you wish
+to provide your own localized formatting, read the section below.
+
+## Customize formatting
+
+If you wish to control exactly how `number`, `date` and `time` are formatted, you can either:
+* Derive `CustomValueFormatter` and override the format methods
+* Instantiate a `CustomValueFormatters` and assign a lambda to the desired properties
+Then pass it in as the `customValueFormatter` parameter to `new MessageFormatter`.
+
+**Example**: A custom formatter that allows the use of .NET's formatting tokens. This is for illustration purposes only and 
+is not recommended for use in real apps.
+
+```csharp
+// This is using the lambda-based approach.
+var custom = new CustomValueFormatters
+{
+    // The formatter must set the `formatted` out parameter and return `true`
+    // If the formatter returns `false`, the built-in formatting is used.
+    Number = (CultureInfo _, object? value, string? style, out string? formatted) =>
+    {
+        formatted = string.Format($"{{0:{style}}}", value);
+        return true;
+    }
+};
+
+// Create a MessageFormatter with the custom value formatter.
+var formatter = new MessageFormatter(customValueFormatter: custom);
+
+// Format a message, passing the culture to FormatMessage.
+var message = formatter.FormatMessage("{value, number, $0.0}", new { value = 23 },
+    CultureInfo.GetCultureInfo("en-US"));
+// "$23.0"
+```
 
 ## Adding your own pluralizer functions
 
+> Since MessageFormat 5.0, pluralizers based on the [official CLDR data][plural-cldr] ship
+> with the package, so this is no longer needed except when overriding specific custom locales.
+
 Same thing as with [MessageFormat.js][0], you can add your own pluralizer function.
-The `Pluralizers` property is a `IDictionary<string, Pluralizer>`, so you can remove the built-in
-ones if you want.
+The `CardinalPluralizers` property is a `IDictionary<string, Pluralizer>` that starts empty, along
+with `OrdinalPluralizers` for ordinal numbers.
+
+Adding to these Dictionaries will take precedence over the CLDR data for exact matches on
+the input locales.
 
 ````csharp
 var mf = new MessageFormatter();
-mf.Pluralizers.Add("<locale>", n => {
+mf.CardinalPluralizers.Add("<locale>", n => {
   // ´n´ is the number being pluralized.
   if(n == 0)
     return "zero";
@@ -108,16 +159,14 @@ mf.Pluralizers.Add("<locale>", n => {
 });
 ````
 
-There's no restrictions on what strings you may return, nor what strings
+There are no restrictions on what strings you may return, nor what strings
 you may use in your pluralization block.
 
 ````csharp
-var mf = new MessageFormatter(true, "en"); // true = use cache
-mf.Pluralizers["en"] = n =>
+var mf = new MessageFormatter(); // uses cache by default
+mf.CardinalPluralizers["en"] = n =>
 {
     // ´n´ is the number being pluralized.
-    if (n == 0)
-        return "zero";
     if (n == 1)
         return "one";
     if (n > 1000)
@@ -127,7 +176,7 @@ mf.Pluralizers["en"] = n =>
 
 mf.FormatMessage("You have {number, plural, thatsalot {a shitload of notifications} other {# notifications}}", new Dictionary<string, object>{
   {"number", 1001}
-});
+}, CultureInfo.GetCultureInfo("en"));
 ````
 
 ## Escaping literals
@@ -149,12 +198,6 @@ be (somewhat) compatible with his.
 If you have issues with the library, and the exception makes no sense, please open an issue
 and include your message, as well as the data you used.
 
-# Todo
-
-* Built-in locales (currently only `en` is added per default).
-
-Don't expect this in the near future - you're welcome to submit a PR. :)
-
 # Author
 
 I'm Jeff Hansen, a software developer who likes to fiddle with string parsing when it is not too difficult.
@@ -164,3 +207,4 @@ You can find me on Twitter: [@jeffijoe][1].
 
   [0]: https://github.com/SlexAxton/messageformat.js
   [1]: https://twitter.com/jeffijoe
+  [plural-cldr]: https://cldr.unicode.org/index/downloads

src/Jeffijoe.MessageFormat.Benchmarks/Jeffijoe.MessageFormat.Benchmarks.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <SignAssembly>True</SignAssembly>
+    <AssemblyOriginatorKeyFile>MessageFormat.snk</AssemblyOriginatorKeyFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Jeffijoe.MessageFormat\Jeffijoe.MessageFormat.csproj" />
+  </ItemGroup>
+
+</Project>

src/Jeffijoe.MessageFormat.Benchmarks/MessageFormatterBenchmarks.cs

@@ -0,0 +1,104 @@
+using System.Collections.Generic;
+using BenchmarkDotNet.Attributes;
+using Jeffijoe.MessageFormat;
+
+namespace Jeffijoe.MessageFormat.Benchmarks;
+
+[MemoryDiagnoser]
+public class MessageFormatterBenchmarks
+{
+    private MessageFormatter _formatter = null!;
+
+    private readonly Dictionary<string, object?> _simpleArgs = new() { ["name"] = "World" };
+
+    private readonly Dictionary<string, object?> _pluralSimpleArgs = new() { ["count"] = 5 };
+
+    private readonly Dictionary<string, object?> _selectSimpleArgs = new() { ["gender"] = "male" };
+
+    private readonly Dictionary<string, object?> _pluralOffsetArgs = new() { ["count"] = 3 };
+
+    private readonly Dictionary<string, object?> _nested2Args = new() { ["gender"] = "female", ["count"] = 1 };
+
+    private readonly Dictionary<string, object?> _nested3Args = new()
+    {
+        ["gender"] = "male",
+        ["count"] = 2,
+        ["total"] = 10
+    };
+
+    [GlobalSetup]
+    public void Setup()
+    {
+        _formatter = new MessageFormatter();
+    }
+
+    [Benchmark]
+    public string SimpleSubstitution()
+    {
+        return _formatter.FormatMessage("{name}", _simpleArgs);
+    }
+
+    [Benchmark]
+    public string PluralSimple()
+    {
+        return _formatter.FormatMessage(
+            "{count, plural, one {1 thing} other {# things}}",
+            _pluralSimpleArgs);
+    }
+
+    [Benchmark]
+    public string SelectSimple()
+    {
+        return _formatter.FormatMessage(
+            "{gender, select, male {He} female {She} other {They}}",
+            _selectSimpleArgs);
+    }
+
+    [Benchmark]
+    public string PluralWithOffset()
+    {
+        return _formatter.FormatMessage(
+            "{count, plural, offset:1 =0 {Nobody} one {You and one other} other {You and # others}}",
+            _pluralOffsetArgs);
+    }
+
+    [Benchmark]
+    public string Nested2Levels()
+    {
+        return _formatter.FormatMessage(
+            "{gender, select, male {{count, plural, one {He has 1 item} other {He has # items}}} female {{count, plural, one {She has 1 item} other {She has # items}}} other {{count, plural, one {They have 1 item} other {They have # items}}}}",
+            _nested2Args);
+    }
+
+    [Benchmark]
+    public string Nested3Levels()
+    {
+        return _formatter.FormatMessage(
+            "{gender, select, male {{count, plural, one {He has 1 of {total} items} other {He has # of {total} items}}} female {{count, plural, one {She has 1 of {total} items} other {She has # of {total} items}}} other {{count, plural, one {They have 1 of {total} items} other {They have # of {total} items}}}}",
+            _nested3Args);
+    }
+
+    [Params(1, 2, 4, 8)]
+    public int ThreadCount { get; set; }
+
+    [Benchmark]
+    public void MultiThreadFormatMessage()
+    {
+        var args = new Dictionary<string, object?> { ["count"] = 5 };
+        var pattern = "{count, plural, one {1 thing} other {# things}}";
+
+        var tasks = new Task[ThreadCount];
+        for (var t = 0; t < ThreadCount; t++)
+        {
+            tasks[t] = Task.Run(() =>
+            {
+                for (var i = 0; i < 1000; i++)
+                {
+                    _formatter.FormatMessage(pattern, args);
+                }
+            });
+        }
+
+        Task.WaitAll(tasks);
+    }
+}