ResourceString.Net.Contract/Readme.md

# ResourceString.Net

## What is ResourceString.Net?

ResourceString.Net is a powerful .NET library that allows you to work with string resources in a type-safe manner.
It leverages the `resx` file in your project and utilizes a  [c# source code generator](https://learn.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview) to create a comprehensive API.
With ResourceString.Net, you can handle resource strings as "multi-language strings" (see [The ResourceString-Classes](#the-resourcestring-classes)) instead of built-in strings.
This provides the ability to switch languages during runtime without the need to rerun string factory methods.
Additionally, ResourceString.Net ensures that formatted strings have methods with the correct number of expected parameters.

## Installation and Setup Instructions

To incorporate ResourceString.Net into your .NET application, follow these simple steps:

1. Install the NuGet package by executing the following command in the NuGet package manager or the dotnet CLI:

```sh
dotnet add package ResourceString.Net
```

2. Once the package is installed, you can start using the APIs in your application.

## Getting Started

To quickly get started with ResourceString.Net, follow the steps below:

1. Run the following script to create a new project and a resource file:

```sh
dotnet new console --name MyTestConsoleApp
cd MyTestConsoleApp

dotnet add package "System.Resources.Extensions"
dotnet add package "ResourceString.Net"

echo "<?xml version='1.0' encoding='utf-8'?>
<root>
  <data name='Greetings'>
    <value>Hello {0}</value>
    <comment>0 = name</comment>
  </data>
  <data name='World' type='System.String'>
    <value>World</value>
  </data>
</root>
" > Resources.resx

echo "var message = MyTestConsoleApp.Resources.Greetings.From(
    MyTestConsoleApp.Resources.World
);

Console.WriteLine(message.Value);
" > Program.cs
```

2. Add the following `PropertyGroup` to the `MyTestConsoleApp.csproj` file to enable ResourceString.Net to handle the project's resource file:

```xml
<PropertyGroup>
  <AdditionalFileItemNames>$(AdditionalFileItemNames);EmbeddedResource</AdditionalFileItemNames>
</PropertyGroup>
```

3. Run the project using the following command:

```sh
dotnet run
# Expected output: Hello World
```

During compile time, the ResourceString.Net source code generator will automatically add the following code to the `MyTestConsoleApp.csproj` project:

```cs
using ResourceString.Net.Contract;
using System;
using System.Globalization;
using System.Resources;
using System.Threading;

namespace MyTestConsoleApp
{
  internal static class Resources
  {

      #region ResourceManager 

      private static readonly Type _Type = typeof(Resources);
    
      private static readonly Lazy<ResourceManager> _ResourceManager = new Lazy<ResourceManager>(
          () => new ResourceManager(_Type.FullName ?? string.Empty, _Type.Assembly),                   
          LazyThreadSafetyMode.PublicationOnly
      );

      public static ResourceManager ResourceManager => _ResourceManager.Value;

      #endregion // ResourceManager
  

      internal static class Greetings 
      {
          private static readonly Lazy<IResourceString> LazyFormat = new Lazy<IResourceString>(
              () => new ResourceManagerString("Greetings", ResourceManager, CultureInfo.CurrentCulture),
              LazyThreadSafetyMode.PublicationOnly
          );

          public static IResourceString Format => LazyFormat.Value;
          
          public static IResourceString From(IResourceString name) => new FormattedResourceString(
              Format, 
              name
          );
  
      } 
  
      #region World 

      private static readonly Lazy<IResourceString> LazyWorld = new Lazy<IResourceString>(
          () => new ResourceManagerString("World", ResourceManager, CultureInfo.CurrentCulture),
          LazyThreadSafetyMode.PublicationOnly
      );

      public static IResourceString World => LazyWorld.Value;

      #endregion // World 
  
  }
}

```

## The ResourceString-Classes

### IResourceString

- Interface that defines the contract for resource strings.
- Contains properties: `Value`, representing the string value, and `GetValue(CultureInfo cultureInfo)`, for retrieving the value for a specific `CultureInfo`.

### FormattedResourceString

- Implements the `IResourceString` interface.
- Represents a resource string with placeholders for parameters.
- Allows for dynamic formatting of the string by providing a format and an array of parameters.
- Formats the string by replacing the placeholders with the parameter values.

### JoinedResourceString

- Implements the `IResourceString` interface.
- Represents a resource string that joins multiple elements with a separator.
- Useful for constructing strings that involve concatenating multiple resource strings or literal strings together.
- Allows customization of the separator between the elements.

### LiteralString

- Implements the `IResourceString` interface.
- Represents a literal string resource.
- Provides the actual string value as-is without any formatting or localization.
- Can be used for static, non-localized strings.

### ResourceManagerString

- Implements the `IResourceString` interface.
- Represents a resource string retrieved from a `ResourceManager`.
- Provides access to resource strings stored in `resx` files or other resource sources.
- Handles retrieving the localized value for the specified `CultureInfo`.

Great! Based on the provided code for the console app `ResourceString.Net.App.Console`, let's enhance the Readme.md file to include instructions on how to use the console app and generate a C# class based on a given resource file.

## Console App: ResourceString.Net.App.Console

The ResourceString.Net project also provide a console app, `ResourceString.Net.App.Console`, which allows you to generate a C# class based on a given resource file. This can be useful for automating the creation of resource classes in your projects without usage of the `source generator`.

### Usage

To use the console app, follow these steps:

1. Build the console app from this source repository
2. Open a command prompt or terminal.
3. Navigate to the directory where the `ResourceString.Net.App.Console` executable is located.

#### Syntax

```
ResourceString.Net.App.Console <sourceFile> [namespaceString] [className]
```

#### Parameters

- `<sourceFile>`: Required. The path to the resource file (e.g., `Resources.resx`) that you want to generate the C# class from.
- `[namespaceString]` (optional): The namespace for the generated C# class. If not provided, the default value is `"Properties"`.
- `[className]` (optional): The name of the generated C# class. If not provided, the default value is `"Resources"`.

#### Examples

Here are some examples of how to use the console app:

- Generate a C# class named `Resources.cs` in the `"Properties"` namespace based on the `Resources.resx` file:

  ```
  ResourceString.Net.App.Console Resources.resx
  ```

- Generate a C# class named `MyResources.cs` in the `"MyNamespace"` namespace based on the `MyResources.resx` file:

  ```
  ResourceString.Net.App.Console MyResources.resx MyNamespace MyResources
  ```

### Output

The console app will generate the C# class code based on the provided resource file and output it to the console.
You can redirect the output to a file if desired.

## Third party packages

| Package                               | Version |
| ------------------------------------- | ------- |
| Fody                                  | 6.7.0   |
| ILMerge.Fody                          | 1.24.0  |
| Microsoft.CodeAnalysis.Analyzers      | 3.3.4   |
| Microsoft.CodeAnalysis.CSharp         | 4.3.0   |
| NETStandard.Library (Auto-referenced) | 2.0.3   |
| LanguageExt.Core                      | 4.4.3   |
| System.Resources.Extensions           | 7.0.0   |

## Development Notes

Here are some useful aliases for running Nix commands with experimental features:

- `nixe`: This alias runs the `nix` command with the experimental feature flag `nix-command flakes`.
- `nulock`: This alias runs the `nixe` command with the argument `run .#devTasks.updateNugetLock`, which updates the NuGet lock file.
- `fllock`: This alias runs the `nixe` command with the argument `run .#devTasks.updateFlakeLock`, which updates the Flake lock file.
- `ulock`: This alias combines the `nulock` and `fllock` aliases to update both the NuGet and Flake lock files.

To load the `alias.sh` source file from the current folder, use the following command:

```sh
source ./alias.sh
```

By executing the command above, you'll make the aliases available for use in the current terminal session.