From ba4aad79dc751cca9faf4826fac8c53543b653c5 Mon Sep 17 00:00:00 2001 From: Orta Therox Date: Mon, 24 Jun 2019 15:42:56 -0700 Subject: [PATCH 1/4] Adds some docs for how a formatter works --- src/services/formatting/README.md | 43 +++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 src/services/formatting/README.md diff --git a/src/services/formatting/README.md b/src/services/formatting/README.md new file mode 100644 index 00000000000..7e3bf6c46a9 --- /dev/null +++ b/src/services/formatting/README.md @@ -0,0 +1,43 @@ +# How does TypeScript formatting work? + +To format code you need to have a formatting context and a sourcefile. The formatting context contains +all user settings like tab size, newline character, etc. The sourcefile is self explanatory. + +The end result of formatting is represented by TextChange objects which hold the new string content, and +the text to replace it with. + +```ts +export interface TextChange { + span: TextSpan; // start, length + newText: string; +} +``` + +## Internals + +Most of the exposed APIs internally are `format*` and they all set up and configure `formatSpan` which could be considered the root call for formatting. Span in this case refers to the range of +the sourcefile which should be formatted. + +The formatSpan then uses a scanner (either with or without JSX support) which starts at the highest +node the covers the span of text and recurses down through the node's children. + +As it recurses, `processNode` is called on the children setting the indentation is decided and passed +through into each of that node's children. + +The meat of formatting decisions is made via `processPair`, the pair here being the current node and the previous node. `processPair` which mutates the formatting context to represent the current place in the scanner and requests a set of rules which can be applied to the items via `createRulesMap`. + +There are a lot of rules, which you can find in [rules.ts](./rules.ts) each one has a left and right reference to nodes or token ranges and note of what action should be applied by the formatter. + +### Where is this used? + +The formatter is used mainly from the language service for formatting with an editor, but [services/textChanges.ts](/src/services/textChanges.ts) also uses this formatter when emitting code for quick fixes. + +The formatter is not exported publicly, and so all usage comes through the language server. + +### Sample code + +```ts +const nonFormattedText = `[js source code]`; +const sourceFile = createSourceFile("any file name", nonFormattedText, ScriptTarget.ESNext, /*setParentNodes*/ true, ScriptKind.JS); +const changes = formatting.formatDocument(sourceFile, formatContext); +``` From 3f9395be39111f19f905b346335716955d887912 Mon Sep 17 00:00:00 2001 From: Orta Date: Mon, 24 Jun 2019 17:08:28 -0700 Subject: [PATCH 2/4] Update src/services/formatting/README.md Co-Authored-By: Andrew Branch --- src/services/formatting/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/services/formatting/README.md b/src/services/formatting/README.md index 7e3bf6c46a9..63fd5fc10ed 100644 --- a/src/services/formatting/README.md +++ b/src/services/formatting/README.md @@ -1,6 +1,6 @@ # How does TypeScript formatting work? -To format code you need to have a formatting context and a sourcefile. The formatting context contains +To format code you need to have a formatting context and a `SourceFile`. The formatting context contains all user settings like tab size, newline character, etc. The sourcefile is self explanatory. The end result of formatting is represented by TextChange objects which hold the new string content, and From 0a272e04ef8b5924f9526e64b25f3bbe180d1feb Mon Sep 17 00:00:00 2001 From: Orta Date: Mon, 24 Jun 2019 17:08:34 -0700 Subject: [PATCH 3/4] Update src/services/formatting/README.md Co-Authored-By: Andrew Branch --- src/services/formatting/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/services/formatting/README.md b/src/services/formatting/README.md index 63fd5fc10ed..bd1e451aaeb 100644 --- a/src/services/formatting/README.md +++ b/src/services/formatting/README.md @@ -1,7 +1,7 @@ # How does TypeScript formatting work? To format code you need to have a formatting context and a `SourceFile`. The formatting context contains -all user settings like tab size, newline character, etc. The sourcefile is self explanatory. +all user settings like tab size, newline character, etc. The end result of formatting is represented by TextChange objects which hold the new string content, and the text to replace it with. From 444c3059f6787915846b6db558a6df0bdfb50a72 Mon Sep 17 00:00:00 2001 From: Orta Therox Date: Tue, 25 Jun 2019 09:41:26 -0700 Subject: [PATCH 4/4] Handle feeedback --- src/services/formatting/README.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/src/services/formatting/README.md b/src/services/formatting/README.md index bd1e451aaeb..33515db34b4 100644 --- a/src/services/formatting/README.md +++ b/src/services/formatting/README.md @@ -30,14 +30,4 @@ There are a lot of rules, which you can find in [rules.ts](./rules.ts) each one ### Where is this used? -The formatter is used mainly from the language service for formatting with an editor, but [services/textChanges.ts](/src/services/textChanges.ts) also uses this formatter when emitting code for quick fixes. - -The formatter is not exported publicly, and so all usage comes through the language server. - -### Sample code - -```ts -const nonFormattedText = `[js source code]`; -const sourceFile = createSourceFile("any file name", nonFormattedText, ScriptTarget.ESNext, /*setParentNodes*/ true, ScriptKind.JS); -const changes = formatting.formatDocument(sourceFile, formatContext); -``` +The formatter is used mainly from any language service operation that inserts or modifies code. The formatter is not exported publicly, and so all usage can only come through the language server.