Cursor API

[nojaf]

Introduction

Once a file is formatted, it can potentially be altered drastically depending on the input. This can disruptive when you are editing code. In order to cope with this, we would introduce a marker API which editors can use. The principle would be that an input position would be captured and could be mapped to an output position afterwards.

Imagine the following:

let a = "ee{caret}ee"

after formatting:

let a =
    "ee{caret}ee"

To link the input {caret} to the result {caret}, we would allow the formatting API to accept the Position of this input and return it (when available) in the result of the formatting invocation.

API

The cursor type should be a Position type. To easily create this, we could add a CodeFormatter.MakePosition(line, column) static member.

We should consider working with Request/Response types instead of our current tupled API.

Technical

The cursor is either inside a text node or outside the tree. We should be able to handle both situations. When the cursor is inside a text node we will be able to return a reliable response. If the cursor is floating somewhere, we will have the same limitations as our trivia-resolving strategy. (A best effort approach)

If the cursor is inside a node, we should try and determine the exact location or pick the start position of the result node.

When multiple defines are in play, we should try and figure out what code fragment was used and use that position of the corresponding combination.

This API should be exposed both in CodeFormatter and in Fantomas.Client.

Closing thoughts

• Our API should be convenient to consume from both F# and C#
• Should we use marker or cursor terminology?
• Should this API also be available for FormatASTAsync?

//cc @DedSec256

[DedSec256]

Thank you for collecting all the details and thoughts in this issue.

It seems more obvious to me to use the term "cursor".

[nojaf]

Available in v6.