// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
 
using Microsoft.CodeAnalysis.Text;
 
namespace Microsoft.CodeAnalysis.EmbeddedLanguages.VirtualChars;
 
/// <summary>
/// Helper service that takes the raw text of a string token and produces the individual
/// characters that raw string token represents (i.e. with escapes collapsed).  The difference
/// between this and the result from token.ValueText is that for each collapsed character
/// returned the original span of text in the original token can be found.  i.e. if you had the
/// following in C#:
///
/// "G\u006fo"
///
/// Then you'd get back:
///
/// 'G' -> [0, 1) 'o' -> [1, 7) 'o' -> [7, 1)
///
/// This allows for embedded language processing that can refer back to the users' original code
/// instead of the escaped value we're processing.
/// </summary>
internal interface IVirtualCharService
{
    /// <summary>
    /// <para>
    /// Takes in a string token and return the <see cref="VirtualChar"/>s corresponding to each
    /// char of the tokens <see cref="SyntaxToken.ValueText"/>.  In other words, for each char
    /// in ValueText there will be a VirtualChar in the resultant array.  Each VirtualChar will
    /// specify what char the language considers them to represent, as well as the span of text
    /// in the original <see cref="SourceText"/> that the language created that char from. 
    /// </para>
    /// <para>
    /// For most chars this will be a single character span.  i.e. 'c' -> 'c'.  However, for
    /// escapes this may be a multi character span.  i.e. 'c' -> '\u0063'
    /// </para>
    /// <para>
    /// If the token is not a string literal token, or the string literal has any diagnostics on
    /// it, then <see langword="default"/> will be returned.   Additionally, because a
    /// VirtualChar can only represent a single char, while some escape sequences represent
    /// multiple chars, <see langword="default"/> will also be returned in those cases. All
    /// these cases could be relaxed in the future.  But they greatly simplify the
    /// implementation.
    /// </para>
    /// <para>
    /// If this function succeeds, certain invariants will hold.  First, each character in the
    /// sequence of characters in <paramref name="token"/>.ValueText will become a single
    /// VirtualChar in the result array with a matching <see cref="VirtualChar.Rune"/> property.
    /// Similarly, each VirtualChar's <see cref="VirtualChar.Span"/> will abut each other, and
    /// the union of all of them will cover the span of the token's <see
    /// cref="SyntaxToken.Text"/>
    /// *not* including the start and quotes.
    /// </para>
    /// <para>
    /// In essence the VirtualChar array acts as the information explaining how the <see
    /// cref="SyntaxToken.Text"/> of the token between the quotes maps to each character in the
    /// token's <see cref="SyntaxToken.ValueText"/>.
    /// </para>
    /// </summary>
    VirtualCharSequence TryConvertToVirtualChars(SyntaxToken token);
 
    /// <summary>
    /// Produces the appropriate escape version of <paramref name="ch"/> to be placed in a
    /// normal string literal.  For example if <paramref name="ch"/> is the <c>tab</c>
    /// character, then this would produce <c>t</c> as <c>\t</c> is what would go into a string
    /// literal.
    /// </summary>
    bool TryGetEscapeCharacter(VirtualChar ch, out char escapeChar);
}