Move document encoding code from hashicorp/terraform-ls to hashicorp/hcl-lang

[rcjsuen]

This library operates off of byte offsets instead of lines and columns which is the basis of many LSP requests. This effectively means that anyone adopting this library will have to calculate byte offsets before calling functions such as HoverAtPos.

From what I can tell, hashicorp/terraform-ls has internal/document/position.go and internal/lsp/position.go that performs these conversions from LSP types. Are there any plans to move those functions over here to hashicorp/hcl-lang to make people's lives easier?

[dbanck]

Hi @rcjsuen,

Thanks for the suggestion, but it's not currently planned for the scope of this library.

The hcl-lang API is designed to work with HCL files (hcl.File) and positions (hcl.Pos).
While it's true that many text document positions usually come from language server requests, there are also cases where a consumer does some HCL parsing in the background and can work directly with HCL-based positions. In this case, they would need to artificially create a lsp.Position to use this library.

We try to avoid adding anything too LSP-specific to this library. For positions, we leave the conversion to the consumer to give them more flexibility when working with this library.

What I've been thinking about for a while is to extract parts of terraform-ls into a separate helper library for LSP building blocks. Like the generic JSON-RPC handling, document and file system handlers, position and range conversion, etc. But I don't see this happening anytime soon.

[rcjsuen]

Thank you for looking at this request, @dbanck.

The hcl-lang API is designed to work with HCL files (hcl.File) and positions (hcl.Pos). While it's true that many text document positions usually come from language server requests, there are also cases where a consumer does some HCL parsing in the background and can work directly with HCL-based positions.

Could you provide some example code for this? I'm just thinking of cases like textDocument/hover and textDocument/completion and in these cases all I have to work with are line and column numbers. How should I be parsing HCL and "working directly with HCL-based positions"? Is there some best practices thing I should be following for using this library?