With the addition of citation keys as first class file references it's worth thinking about what a file reference is. At its core a file reference is a bidirectional link from a node in a remark AST to a file.
In this application files are always associated with a vscode.Uri and are uniquely identified by their vscode.fsPath which is a string. We can use the term fsPath to get these ids.
We need some data structure for storing the AST associated with a file. I propose calling it a LinkedFile. This is different from a direct reference to a vscode document which will be either a vscode.TextDocument or a vscode.Uri.
All our methods should be implemented in the most DRY way. So methods which translate from a vscode.TextDocument or a vscode.Uri to relevant FileReferences should accept a vscode.Uri and output FileReference or FileReference[]. Methods which translate from a FileReference to a vscode.Uri are straightforward.
There are many methods which should be supported on FileReferences. We can implement FileReferences as a discriminated union (this does have the downside that new file references require a lot of implementation, but demands that new file references remain first class). The base type would look something like the following. The node could be subtyped in the interfaces which extend FileReference.
// allow iteration and type safety for the discriminant type
const FileReferenceKeys = ["note", "reference"] as const;
type FileReferenceType = typeof FileReferenceKeys[number];
interface FileReference {
type: FileReferenceType;
node: UNIST.Node;
}
List of methods which involve fileReferences. In the following Uri refers to a vscode.Uri
lukesmurray
commented
4 years ago
With the addition of
citation keysas first class file references it's worth thinking about what a file reference is. At its core a file reference is a bidirectional link from a node in a remark AST to a file.In this application files are always associated with a
vscode.Uriand are uniquely identified by theirvscode.fsPathwhich is a string. We can use the termfsPathto get these ids.We need some data structure for storing the AST associated with a file. I propose calling it a
LinkedFile. This is different from a direct reference to a vscode document which will be either avscode.TextDocumentor avscode.Uri.All our methods should be implemented in the most DRY way. So methods which translate from a
vscode.TextDocumentor avscode.Urito relevantFileReferences should accept avscode.Uriand outputFileReferenceorFileReference[]. Methods which translate from aFileReferenceto avscode.Uriare straightforward.There are many methods which should be supported on
FileReferences. We can implementFileReferences as a discriminated union (this does have the downside that new file references require a lot of implementation, but demands that new file references remain first class). The base type would look something like the following. Thenodecould be subtyped in the interfaces which extendFileReference.List of methods which involve
fileReferences. In the followingUrirefers to avscode.Uri(fileReference: FileReference): string(fileReference: FileReference): string(fileReference: FileReference): Promise<string>(fileReference: FileReference): string(fsPath: string): FileReference[](fsPath: string): FileReference[]fsPathfsPathis a markdown file since afileReferencehas aUNIST.Nodefromremark(fileReference: FileReference): vscode.DocumentLinkfileReference: FileReference): vscode.MarkdownStringvscode.MarkdownStringfor displaying on hover(document: vscode.TextDocument, position: vscode.Position): FileReference | undefinedImplementing this is a big rewrite but it should unify the terminology.
linkedFilefsPath