Interpolation Expression Sequences (IES) are expressions that interspersestring literal data and values. An interpolation expression is written like astring, but can contain values that are passed directly to a function that isable to accept them. It is transformed into aSequence of expressions thatcan be overloaded or handled by template functions.
InterpolationExpressionSequence:InterpolatedDoubleQuotedLiteralInterpolatedWysiwygLiteralInterpolatedTokenLiteral
An Interpolation Expression sequence can be either wysiwyg quoted, doublequoted, or a token literal. Only double quoted literals can have escapes inthem.
Unlike string literals, IES literals cannot have a suffix defining thewidth of the character type for the string expressions.
InterpolatedDoubleQuotedLiteral:i"InterpolatedDoubleQuotedCharactersopt"InterpolatedDoubleQuotedCharacters:InterpolatedDoubleQuotedCharacterInterpolatedDoubleQuotedCharacterInterpolatedDoubleQuotedCharactersInterpolatedDoubleQuotedCharacter:DoubleQuotedCharacterInterpolationEscapeSequenceInterpolationExpressionInterpolationEscapeSequence:EscapeSequence\$InterpolationExpression:$(AssignExpression)
LikeDoubleQuotedString, double-quoted IES literals canhave escape characters in them. Added to the normal escapes is the ability toescape a literal $
A $ followed by any character other than a left parenthesis is treated as aliteral $ in the expression, there is no need to escape it.
The expression inside anInterpolationExpression is a full Dexpression, and escapes are not needed inside that part of the expression.
InterpolatedWysiwygLiteral:i`InterpolatedWysiwygCharactersopt`InterpolatedWysiwygCharacters:InterpolatedWysiwygCharacterInterpolatedWysiwygCharacterInterpolatedWysiwygCharactersInterpolatedWysiwygCharacter:WysiwygCharacterInterpolationExpression
Wysiwyg ("what you see is what you get") IES literals are defined likeWysiwygString strings, but only support backquote syntax. Noescapes are recognized inside these literals.
InterpolatedTokenLiteral:iq{InterpolatedTokenStringTokensopt}InterpolatedTokenStringTokens:InterpolatedTokenStringTokenInterpolatedTokenStringTokenInterpolatedTokenStringTokensInterpolatedTokenStringToken:InterpolatedTokenNoBraces{InterpolatedTokenStringTokensopt}InterpolatedTokenNoBraces:TokenNoBracesInterpolationExpression
LikeTokenString, IES Token literals must contain onlyvalid D tokens, with the exception ofInterpolationExpression. Noescapes are recognized.
When the lexer encounters an Interpolation Expression Sequence, the tokenis translated into a sequence of expressions, which replaces the single token.The sequence always starts with the expressioncore.interpolation.InterpolationHeader() and always ends withcore.interpolation.InterpolationFooter()
Each partstr of the token which is literal string data is translatedinto the expressioncore.interpolation.InterpolatedLiteral!(str)
Each part$(expr) of the token which is anInterpolationExpression is translated into the sequencecore.interpolation.InterpolatedExpression!(expr), expr.
// simple version of std.typecons.Tuplestruct Tuple(T...) { T value; }Tuple!T tuple(T...)(T value) {return Tuple!T(value); }import core.interpolation;string name ="John Doe";auto items = tuple(i"Hello, $(name), how are you?");assert(items == tuple( InterpolationHeader(),// denotes the start of an IES InterpolatedLiteral!("Hello, ")(),// literal string data InterpolatedExpression!("name")(),// expression literal data name,// expression passed directly InterpolatedLiteral!(", how are you?")(),// literal string data InterpolationFooter()));// denotes the end of an IES
Types defined incore.interpolation need not be imported to use IES.These are automatically imported when an IES is used. The types are defined soas to make it easy to introspect the IES for processing at compile-time.
TheInterpolationHeader andInterpolationFooter type are emptystructs that allow easy overloading of functions to handle IES. They also canbe used to understand which parts of a expression list were passed via IES.
These types have atoString definition that returns an empty string,to allow for processing by functions which intend to convert IES to text, suchasstd.stdio.writeln orstd.conv.text.
TheInterpolatedLiteral type is an empty struct that providescompile-time access to the string literal portion of an IES. This type alsoprovides atoString member function which returns the part of thesequence that this value replaced.
TheInterpolatedExpression type is an empty struct that providescompile-time access to the literal that was used to form the followingexpression. It provides atoString member function which returns the emptystring. It also has anenum expression member, which is equal to thetemplate parameter used to construct the type.
string name ="John Doe";auto ies =i"Hello, $(name)";staticassert(is(typeof(ies[0]) == InterpolationHeader));staticassert(ies[1].toString() =="Hello, ");staticassert(ies[2].expression =="name");assert(ies[3] == name);staticassert(is(typeof(ies[4]) == InterpolationFooter));
The recommended mechanism to accept IES is to provide a variadic templatefunction to match the various parameters inside the sequence, surrounded byexplicitInterpolationHeader andInterpolationFooter parameters.
void processIES(Sequence...)(InterpolationHeader, Sequence data, InterpolationFooter){// process `data` here}
An IES can also contain types as interpolation expressions. This can beused by passing to a variadic template parameter.
template processIESAtCompileTime(InterpolationHeader header, Sequence...){staticassert(Sequence[$-1] == InterpolationFooter());}alias result = processIES!i"Here is a type: $(int)";
In many cases, it is desirable to convert an IES to astring. ThePhobos functionstd.conv.text can convert the IES to astring for usein any context where a string is needed, for instance to assign to a stringvariable, or call a function that accepts a string.
import std.conv : text;string name ="John Doe";string badgreeting =i"Hello, $(name)";// Errorstring greeting =i"Hello, $(name)".text;// OKassert(greeting =="Hello, John Doe");
It is highly recommended for library authors who wish to accept IES toprovide an overload that accepts them, rather than rely onstd.conv, asthis incurs unnecessary allocations. This is especially important where certaintypes of injection attacks are possible from malicious user-provided data.
