[Proposal] String Interceptors

[kg]

String Interceptors

Summary

String Interceptors are a C# compiler feature that allows substituting a method call - to the interceptor - for a string literal (including interpolated strings) at compile time. This substitution occurs by having the interceptor declare the source locations of the string literals that it intercepts. This provides a limited facility to change what existing string literals evaluate to by adding new code to a compilation (e.g. in a source generator).

using System;
using System.Runtime.CompilerServices;
using static LocalizationSupport;

// For the purposes of this example, each string literal has a synthetic key which is the first 16 characters of its sha256 hash sum
int i = 1 + 2;
var a = Localized("Hello World");  // L1: evaluates to "localized text for a591a6d40bf42040"
var b = Localized($"1 + 2 = {i}"); // L2: evaluates to "localized text for da174d5fa68d0d6f"

Console.WriteLine($"a='{a}'"); // prints: a='localized text for a591a6d40bf42040'
Console.WriteLine($"b='{b}'"); // prints: b='localized text for da174d5fa68d0d6f'

// sample bare minimum library support code
public static class LocalizationSupport
{
    // source generator identifies calls to this method and intercepts string literals passed to it
    // the optional arguments are consumed by the source generator if present
    public static string Localized<T> (T text, string key = null, string note = null)
        where T : ILocalizedString
    => /* ... */;
}

public interface ILocalizedString
{
    string ToString (CultureInfo culture);
}

// generated code
namespace LocalizationSupportImplementationDetails {
    static class Interceptors
    {
        public record struct StringLiteral_void (string StringTableKey) : ILocalizedString
        {
            public string ToString (CultureInfo culture) => Interceptors.Get(culture, StringTableKey);
        }

        public record struct StringLiteral_int (string StringTableKey, int _0) : ILocalizedString
        {
            public string ToString (CultureInfo culture) => Interceptors.Format(culture, StringTableKey, _0);
        }

        private static string Get (CultureInfo culture, string key) => /* ... */;
        private static string Format (CultureInfo culture, string key, ...) => /* ... */;

        [InterceptsStringAtLocation(version: 1, data: "...(refers to the string literal at L1)")]
        public static StringLiteral_void StringLiteralInterceptorMethod_0 () => new StringLiteral_void("a591a6d40bf42040");

        [InterceptsStringAtLocation(version: 1, data: "...(refers to the interpolated string at L2)")]
        public static StringLiteral_int InterpolatedStringInterceptorMethod_1 (int i) => new StringLiteral_int("da174d5fa68d0d6f", i);
    }
}

Motivation

At present C# and the .NET BCL provide excellent tooling for high-performance string formatting, but none of that tooling is applicable when you wish to localize a formatted string. The process of taking code full of $"" literals and preparing it for localization is complex and error-prone, in part due to the need to replace named expansions like $"Good afternoon, {firstName} {lastName}" with "Good afternoon, {0} {1}", destroying useful semantic information. For non-interpolated strings the process of localizing them is still an extremely manual one.

String interceptors allow the creation of automated localization tooling in the vein of industry-standard tools like gettext with minimally intrusive changes to the compiler and language, leveraging existing investments across the ecosystem into interception, source generators, CompositeFormat, and resx files. Use of string interceptors allows building a high-performance solution that works for most string literals and integrates with existing localization pipelines.

Detailed design

InterceptsStringAtLocationAttribute

A method indicates that it is a string interceptor by adding one or more [InterceptsStringAtLocation] attribute(s). These attributes refer to the source locations of the string literals that it intercepts.

namespace System.Runtime.CompilerServices
{
    [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
    public sealed class InterceptsStringAtLocationAttribute(int version, string data) : Attribute
    {
    }
}

[InterceptsStringAtLocation] attributes included in source are emitted to the resulting assembly, just like other custom attributes.

File-local declarations of this type (file class InterceptsStringAtLocationAttribute) are valid and usages are recognized by the compiler when they are within the same file and compilation. A generator which needs to declare this attribute should use a file-local declaration to ensure it doesn't conflict with other generators that need to do the same thing.

Interceptable strings

Any string literal in the following categories (subject to future expansion) can be intercepted:

"hello" // quoted string literal
@"hello" // verbatim string literal
"""hello""" // raw string literal
$"hello {world}" // interpolated string
$@"hello {world}" // verbatim interpolated string

Attempting to intercept a string literal not included in the above set of categories produces a compile-time error.

Attempting to intercept a string literal in the definition of a compile-time constant i.e. const s = "hello" produces a compile-time error.

Attempting to intercept a string literal within an attribute's argument list i.e. [AttributeName("literal")] produces a compile-time error.

Attempting to intercept a non-string-literal expression of any type - string or otherwise - as if it were a string literal produces a compile-time error.

Location encoding

The attribute's arguments and their encoding are identical to those in the Interceptors specification.

Arity

String Interceptors cannot be declared in generic types at any level of nesting.

String Interceptors are not permitted to have optional parameters, varargs, params arrays, or default parameter values.

String Interceptors must be either be non-generic, or have a signature exactly matching the types and order of the interpolated expressions within an interpolated string.

For a non-interpolated string, this means they must accept no parameters. For an interpolated string with one interpolated expression of type int, the interceptor must accept one argument of type int, and so on.

If a string interceptor is generic it must accept a number of type parameters exactly matching the number of interpolated expressions within the string literal, and each parameter must be of the corresponding type. i.e. for an interpolated string with three interpolated expressions, the signature must exactly match that shown below:

class Interceptors {
    public static AnyType StringInterceptor<T1, T2, T3>(T1 t1, T2 t2, T3 t3)
}

Allowing string interceptors to be generic makes it possible for them to intercept interpolated strings where the interpolated expressions are of types not accessible at the string interceptor's declaration site.

The return type of the string interceptor is not required to be System.String. This enables the interceptor to capture information about an interpolated string for later use.

Conflicting interceptors

If more than one string interceptor refers to the same location, it is a compile-time error.

Invalid interception

If an [InterceptsStringAtLocation] attribute is found in the compilation which does not refer to the location of a string literal included in the list of categories specified above, it is a compile-time error.

Interceptor accessibility

Accessibility rules are identical to those in the Interceptors specification.

Editor experience

String interceptors are treated like a post-compilation step in this design.

User opt-in

To use interceptors, the user project must specify the property <StringInterceptorsNamespaces>. This is a list of namespaces which are allowed to contain string interceptors.

<StringInterceptorsNamespaces>$(StringInterceptorsNamespaces);LocalizationSupportImplementationDetails</StringInterceptorsNamespaces>

It's expected that each entry in the StringInterceptorsNamespaces list roughly corresponds to one source generator. Well-behaved components are expected to not insert string interceptors into namespaces they do not own.