C API: rename parser -> document

strager · strager · commit ab19ed82776f · 2021-07-22T14:47:40.000-07:00
I want to allow our VS Code extension to communicate configuration file
changes to quick-lint-js. To make this possible, we need most of the
features of qljs_vscode_parser, but not linting.

Make qljs_vscode_parser feel more general-purpose by renaming it to
qljs_vscode_document.

This commit should not change behavior.
diff --git a/plugin/vscode/extension.js b/plugin/vscode/extension.js
@@ -15,20 +15,21 @@ let {
 let processFactoryPromise = createProcessFactoryAsync();
 
 let DocumentLinterState = {
-  // A Parser hasn't been created yet.
+  // A DocumentForVSCode hasn't been created yet.
   NO_PARSER: "NO_PARSER",
 
-  // A Parser is in the process of being created.
+  // A DocumentForVSCode is in the process of being created.
   CREATING_PARSER: "CREATING_PARSER",
 
-  // A Parser has been created, but it has no text.
+  // A DocumentForVSCode has been created, but it has no text.
   PARSER_UNINITIALIZED: "PARSER_UNINITIALIZED",
 
-  // A Parser has been created, and its text is up-to-date with the
+  // A DocumentForVSCode has been created, and its text is up-to-date with the
   // vscode.Document.
   PARSER_LOADED: "PARSER_LOADED",
 
-  // The Parser's Process crashed, and we are creating a new Process and Parser.
+  // The DocumentForVSCode's Process crashed, and we are creating a new Process
+  // and DocumentForVSCode.
   //
   // Document changes should be queued.
   RECOVERING: "RECOVERING",
@@ -73,7 +74,7 @@ class DocumentLinter {
       let factory = await processFactoryPromise;
       // TODO(strager): Reuse processes across documents.
       let process = await factory.createProcessAsync();
-      let parser = await process.createParserForVSCodeAsync();
+      let parser = await process.createDocumentForVSCodeAsync();
 
       if (this._state === DocumentLinterState.DISPOSED) {
         parser.dispose();
@@ -251,7 +252,7 @@ class DocumentLinter {
         // TODO(strager): Reuse processes across documents.
         let factory = await processFactoryPromise;
         let process = await factory.createProcessAsync();
-        let parser = await process.createParserForVSCodeAsync();
+        let parser = await process.createDocumentForVSCodeAsync();
 
         // BEGIN CRITICAL SECTION (no awaiting below)
         assert.strictEqual(this._state, DocumentLinterState.RECOVERING);
diff --git a/plugin/vscode/test/other-tests.js b/plugin/vscode/test/other-tests.js
@@ -266,9 +266,9 @@ let tests = {
     let rng = new ExhaustiveRNG();
     injectFaults(
       (functionName) => {
-        // TODO(strager): Figure out why qljs_vscode_create_parser failures
+        // TODO(strager): Figure out why qljs_vscode_create_document failures
         // cause this test to fail.
-        if (functionName !== "qljs_vscode_create_parser") {
+        if (functionName !== "qljs_vscode_create_document") {
           let shouldCrash = rng.nextCoinFlip();
           coinFlips.push(shouldCrash);
           if (shouldCrash) {
diff --git a/src/c-api.cpp b/src/c-api.cpp
@@ -17,7 +17,7 @@
 namespace quick_lint_js {
 namespace {
 template <class Locator, class ErrorReporter>
-class qljs_parser_base {
+class qljs_document_base {
  public:
   const auto* lint() {
     this->error_reporter_.reset();
@@ -39,8 +39,8 @@ class qljs_parser_base {
 }
 }
 
-struct qljs_vscode_parser final
-    : public quick_lint_js::qljs_parser_base<
+struct qljs_vscode_document final
+    : public quick_lint_js::qljs_document_base<
           quick_lint_js::lsp_locator,
           quick_lint_js::c_api_error_reporter<qljs_vscode_diagnostic,
                                               quick_lint_js::lsp_locator>> {
@@ -59,14 +59,14 @@ struct qljs_vscode_parser final
   }
 };
 
-qljs_vscode_parser* qljs_vscode_create_parser(void) {
-  qljs_vscode_parser* p = new qljs_vscode_parser();
+qljs_vscode_document* qljs_vscode_create_document(void) {
+  qljs_vscode_document* p = new qljs_vscode_document();
   return p;
 }
 
-void qljs_vscode_destroy_parser(qljs_vscode_parser* p) { delete p; }
+void qljs_vscode_destroy_document(qljs_vscode_document* p) { delete p; }
 
-void qljs_vscode_replace_text(qljs_vscode_parser* p, int start_line,
+void qljs_vscode_replace_text(qljs_vscode_document* p, int start_line,
                               int start_character, int end_line,
                               int end_character,
                               const void* replacement_text_utf_8,
@@ -78,12 +78,12 @@ void qljs_vscode_replace_text(qljs_vscode_parser* p, int start_line,
           replacement_text_byte_count));
 }
 
-const qljs_vscode_diagnostic* qljs_vscode_lint(qljs_vscode_parser* p) {
+const qljs_vscode_diagnostic* qljs_vscode_lint(qljs_vscode_document* p) {
   return p->lint();
 }
 
-struct qljs_web_demo_parser final
-    : public quick_lint_js::qljs_parser_base<
+struct qljs_web_demo_document final
+    : public quick_lint_js::qljs_document_base<
           quick_lint_js::web_demo_locator,
           quick_lint_js::c_api_error_reporter<
               qljs_web_demo_diagnostic, quick_lint_js::web_demo_locator>> {
@@ -93,21 +93,21 @@ struct qljs_web_demo_parser final
   }
 };
 
-qljs_web_demo_parser* qljs_web_demo_create_parser(void) {
-  qljs_web_demo_parser* p = new qljs_web_demo_parser();
+qljs_web_demo_document* qljs_web_demo_create_document(void) {
+  qljs_web_demo_document* p = new qljs_web_demo_document();
   return p;
 }
 
-void qljs_web_demo_destroy_parser(qljs_web_demo_parser* p) { delete p; }
+void qljs_web_demo_destroy_document(qljs_web_demo_document* p) { delete p; }
 
-void qljs_web_demo_set_text(qljs_web_demo_parser* p, const void* text_utf_8,
+void qljs_web_demo_set_text(qljs_web_demo_document* p, const void* text_utf_8,
                             size_t text_byte_count) {
   p->set_text(quick_lint_js::string8_view(
       reinterpret_cast<const quick_lint_js::char8*>(text_utf_8),
       text_byte_count));
 }
 
-const qljs_web_demo_diagnostic* qljs_web_demo_lint(qljs_web_demo_parser* p) {
+const qljs_web_demo_diagnostic* qljs_web_demo_lint(qljs_web_demo_document* p) {
   return p->lint();
 }
 
diff --git a/src/quick-lint-js/c-api.h b/src/quick-lint-js/c-api.h
@@ -15,7 +15,7 @@ typedef enum qljs_severity {
   qljs_severity_warning = 2,
 } qljs_severity;
 
-typedef struct qljs_vscode_parser qljs_vscode_parser;
+typedef struct qljs_vscode_document qljs_vscode_document;
 struct qljs_vscode_diagnostic {
   const char* message;
   const char* code;
@@ -25,16 +25,16 @@ struct qljs_vscode_diagnostic {
   int end_line;
   int end_character;
 };
-qljs_vscode_parser* qljs_vscode_create_parser(void);
-void qljs_vscode_destroy_parser(qljs_vscode_parser*);
-void qljs_vscode_replace_text(qljs_vscode_parser*, int start_line,
+qljs_vscode_document* qljs_vscode_create_document(void);
+void qljs_vscode_destroy_document(qljs_vscode_document*);
+void qljs_vscode_replace_text(qljs_vscode_document*, int start_line,
                               int start_character, int end_line,
                               int end_character,
                               const void* replacement_text_utf_8,
                               size_t replacement_text_byte_count);
-const qljs_vscode_diagnostic* qljs_vscode_lint(qljs_vscode_parser*);
+const qljs_vscode_diagnostic* qljs_vscode_lint(qljs_vscode_document*);
 
-typedef struct qljs_web_demo_parser qljs_web_demo_parser;
+typedef struct qljs_web_demo_document qljs_web_demo_document;
 struct qljs_web_demo_diagnostic {
   const char* message;
   const char* code;
@@ -43,11 +43,11 @@ struct qljs_web_demo_diagnostic {
   int begin_offset;
   int end_offset;
 };
-qljs_web_demo_parser* qljs_web_demo_create_parser(void);
-void qljs_web_demo_destroy_parser(qljs_web_demo_parser*);
-void qljs_web_demo_set_text(qljs_web_demo_parser*, const void* text_utf_8,
+qljs_web_demo_document* qljs_web_demo_create_document(void);
+void qljs_web_demo_destroy_document(qljs_web_demo_document*);
+void qljs_web_demo_set_text(qljs_web_demo_document*, const void* text_utf_8,
                             size_t text_byte_count);
-const qljs_web_demo_diagnostic* qljs_web_demo_lint(qljs_web_demo_parser*);
+const qljs_web_demo_diagnostic* qljs_web_demo_lint(qljs_web_demo_document*);
 
 #if defined(__cplusplus)
 }
diff --git a/test/test-c-api.cpp b/test/test-c-api.cpp
@@ -8,21 +8,21 @@
 namespace quick_lint_js {
 namespace {
 TEST(test_c_api_vscode, empty_document_has_no_diagnostics) {
-  qljs_vscode_parser* p = qljs_vscode_create_parser();
+  qljs_vscode_document* p = qljs_vscode_create_document();
   const qljs_vscode_diagnostic* diagnostics = qljs_vscode_lint(p);
   EXPECT_EQ(diagnostics[0].message, nullptr);
-  qljs_vscode_destroy_parser(p);
+  qljs_vscode_destroy_document(p);
 }
 
 TEST(test_c_api_web_demo, empty_document_has_no_diagnostics) {
-  qljs_web_demo_parser* p = qljs_web_demo_create_parser();
+  qljs_web_demo_document* p = qljs_web_demo_create_document();
   const qljs_web_demo_diagnostic* diagnostics = qljs_web_demo_lint(p);
   EXPECT_EQ(diagnostics[0].message, nullptr);
-  qljs_web_demo_destroy_parser(p);
+  qljs_web_demo_destroy_document(p);
 }
 
 TEST(test_c_api_vscode, lint_error_after_text_insertion) {
-  qljs_vscode_parser* p = qljs_vscode_create_parser();
+  qljs_vscode_document* p = qljs_vscode_create_document();
 
   const char8* document_text = u8"let x;let x;";
   qljs_vscode_replace_text(p, /*start_line=*/0, /*start_character=*/0,
@@ -40,11 +40,11 @@ TEST(test_c_api_vscode, lint_error_after_text_insertion) {
   EXPECT_EQ(diagnostics[0].end_line, 0);
   EXPECT_EQ(diagnostics[0].end_character, strlen(u8"let x;let x"));
 
-  qljs_vscode_destroy_parser(p);
+  qljs_vscode_destroy_document(p);
 }
 
 TEST(test_c_api_web_demo, lint_error_after_text_insertion) {
-  qljs_web_demo_parser* p = qljs_web_demo_create_parser();
+  qljs_web_demo_document* p = qljs_web_demo_create_document();
 
   const char8* document_text = u8"let x;let x;";
   qljs_web_demo_set_text(p, document_text, strlen(document_text));
@@ -58,11 +58,11 @@ TEST(test_c_api_web_demo, lint_error_after_text_insertion) {
   EXPECT_EQ(diagnostics[0].begin_offset, strlen(u8"let x;let "));
   EXPECT_EQ(diagnostics[0].end_offset, strlen(u8"let x;let x"));
 
-  qljs_web_demo_destroy_parser(p);
+  qljs_web_demo_destroy_document(p);
 }
 
 TEST(test_c_api_vscode, lint_new_error_after_second_text_insertion) {
-  qljs_vscode_parser* p = qljs_vscode_create_parser();
+  qljs_vscode_document* p = qljs_vscode_create_document();
 
   const char8* document_text = u8"let x;";
   qljs_vscode_replace_text(p, /*start_line=*/0, /*start_character=*/0,
@@ -74,7 +74,7 @@ TEST(test_c_api_vscode, lint_new_error_after_second_text_insertion) {
   qljs_vscode_replace_text(p, /*start_line=*/0, /*start_character=*/0,
                            /*end_line=*/0, /*end_character=*/0, document_text,
                            strlen(document_text));
-  // Parser's text: let x;let x;
+  // Document's text: let x;let x;
   diagnostics = qljs_vscode_lint(p);
   EXPECT_NE(diagnostics[0].message, nullptr);
   EXPECT_EQ(diagnostics[1].message, nullptr);
@@ -87,11 +87,11 @@ TEST(test_c_api_vscode, lint_new_error_after_second_text_insertion) {
   EXPECT_EQ(diagnostics[0].end_line, 0);
   EXPECT_EQ(diagnostics[0].end_character, strlen(u8"let x;let x"));
 
-  qljs_vscode_destroy_parser(p);
+  qljs_vscode_destroy_document(p);
 }
 
 TEST(test_c_api_web_demo, lint_new_error_after_second_text_insertion) {
-  qljs_web_demo_parser* p = qljs_web_demo_create_parser();
+  qljs_web_demo_document* p = qljs_web_demo_create_document();
 
   const char8* document_text = u8"let x;";
   qljs_web_demo_set_text(p, document_text, strlen(document_text));
@@ -110,11 +110,11 @@ TEST(test_c_api_web_demo, lint_new_error_after_second_text_insertion) {
   EXPECT_EQ(diagnostics[0].begin_offset, strlen(u8"let x;let "));
   EXPECT_EQ(diagnostics[0].end_offset, strlen(u8"let x;let x"));
 
-  qljs_web_demo_destroy_parser(p);
+  qljs_web_demo_destroy_document(p);
 }
 
 TEST(test_c_api_vscode, diagnostic_severity) {
-  qljs_vscode_parser* p = qljs_vscode_create_parser();
+  qljs_vscode_document* p = qljs_vscode_create_document();
 
   const char8* document_text = u8"let x;let x;\nundeclaredVariable;";
   qljs_vscode_replace_text(p, /*start_line=*/0, /*start_character=*/0,
@@ -131,7 +131,7 @@ TEST(test_c_api_vscode, diagnostic_severity) {
   EXPECT_EQ(diagnostics[0].severity, qljs_severity_error);
   EXPECT_EQ(diagnostics[1].severity, qljs_severity_warning);
 
-  qljs_vscode_destroy_parser(p);
+  qljs_vscode_destroy_document(p);
 }
 }
 }
diff --git a/wasm/CMakeLists.txt b/wasm/CMakeLists.txt
@@ -12,7 +12,7 @@ if (EMSCRIPTEN)
     quick-lint-js-vscode
     PRIVATE
     quick-lint-js-lib
-    "-sEXPORTED_FUNCTIONS=[\"_qljs_vscode_create_parser\",\"_qljs_vscode_destroy_parser\",\"_qljs_vscode_replace_text\",\"_qljs_vscode_lint\",\"_qljs_web_demo_create_parser\",\"_qljs_web_demo_destroy_parser\",\"_qljs_web_demo_set_text\",\"_qljs_web_demo_lint\",\"_malloc\",\"_free\"]"
+    "-sEXPORTED_FUNCTIONS=[\"_qljs_vscode_create_document\",\"_qljs_vscode_destroy_document\",\"_qljs_vscode_replace_text\",\"_qljs_vscode_lint\",\"_qljs_web_demo_create_document\",\"_qljs_web_demo_destroy_document\",\"_qljs_web_demo_set_text\",\"_qljs_web_demo_lint\",\"_malloc\",\"_free\"]"
     -sASSERTIONS=0
     -sSTANDALONE_WASM=1
     --no-entry
diff --git a/wasm/cli.js b/wasm/cli.js
@@ -16,16 +16,16 @@ async function main() {
   let factory = await createProcessFactoryAsync();
   let qljsProcess = await factory.createProcessAsync();
 
-  let parserForVSCode = await qljsProcess.createParserForVSCodeAsync();
+  let documentForVSCode = await qljsProcess.createDocumentForVSCodeAsync();
   try {
-    parserForVSCode.replaceText(
+    documentForVSCode.replaceText(
       {
         start: { line: 0, character: 0 },
         end: { line: 0, character: 0 },
       },
       fileContent
     );
-    let diagnostics = parserForVSCode.lint();
+    let diagnostics = documentForVSCode.lint();
 
     for (let diag of diagnostics) {
       console.log(
@@ -35,13 +35,13 @@ async function main() {
       );
     }
   } finally {
-    parserForVSCode.dispose();
+    documentForVSCode.dispose();
   }
 
-  let parserForWebDemo = await qljsProcess.createParserForWebDemoAsync();
+  let documentForWebDemo = await qljsProcess.createDocumentForWebDemoAsync();
   try {
-    parserForWebDemo.setText(fileContent);
-    let diagnostics = parserForWebDemo.lint();
+    documentForWebDemo.setText(fileContent);
+    let diagnostics = documentForWebDemo.lint();
 
     for (let diag of diagnostics) {
       console.log(
@@ -51,7 +51,7 @@ async function main() {
       );
     }
   } finally {
-    parserForWebDemo.dispose();
+    documentForWebDemo.dispose();
   }
 }
 
diff --git a/wasm/quick-lint-js.js b/wasm/quick-lint-js.js
diff --git a/website/public/demo/demo.mjs b/website/public/demo/demo.mjs
diff --git a/website/src/error-documentation.mjs b/website/src/error-documentation.mjs
