// 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 System.Threading;
using System.Threading.Tasks;
 
namespace Microsoft.CodeAnalysis.BraceMatching;
 
internal interface IBraceMatcher
{
    /// <summary>
    /// Given a <paramref name="document"/> and a <paramref name="position"/> within that document, gets the <see
    /// cref="BraceMatchingResult"/> if the position is at the start or end character of a matching pair of braces.
    /// Importantly, the <paramref name="position"/> is the position of the actual character to examine.  For
    /// example, given: <c>Goo()$$[1, 2, 3]</c> (where <c>$$</c> is the position), this would only be considering
    /// the <c>[</c> brace, not the <c>)</c> brace that precedes it.  Similarly, for <c>Goo()[1, 2, 3$$]</c> this
    /// would be considering the <c>]</c> brace.  If <c>Goo()[1, 2, 3]$$</c> were passed, no braces should be
    /// reported, despite the position being at the end of a brace.
    /// <para>
    /// It is the job of the calling feature ("Brace Matching") to actually make multiple calls into these matchers
    /// to then determine what to do.  For example with <c>Goo(true)$$[1, 2, 3]</c> (where $$ is now the caret
    /// position of the user), the feature will make two calls in, one for <c>Goo(true$$)[1, 2, 3]</c> and one for
    /// <c>Goo(true)$$[1, 2, 3]</c>.  This will allow it to see that the caret is between two complete brace pairs,
    /// and it can highlight both.  The <see cref="IBraceMatcher"/> does not have to consider this, or try to pick
    /// which set of braces to return.
    /// </para>
    /// </summary>
    Task<BraceMatchingResult?> FindBracesAsync(Document document, int position, BraceMatchingOptions options, CancellationToken cancellationToken);
}