From 1e30f66f3979ea09adca75dc169cfe0229343a48 Mon Sep 17 00:00:00 2001 From: Mark Amery Date: Fri, 8 Dec 2023 14:35:02 +0000 Subject: [PATCH] Remove claim, untrue since over 5 years ago, that cursorOffset is incompatible with rangeStart/rangeEnd (#15750) --- changelog_unreleased/misc/15750.md | 3 +++ docs/api.md | 2 +- docs/options.md | 2 -- src/index.d.ts | 4 +--- src/main/core-options.evaluate.js | 8 ++------ src/standalone.d.ts | 2 +- tests/dts/unit/cases/standalone.ts | 2 -- .../markdown/__snapshots__/jsfmt.spec.js.snap | 14 ++------------ tests/format/markdown/markdown/real-world-case.md | 4 +--- .../__tests__/__snapshots__/early-exit.js.snap | 6 ------ .../__tests__/__snapshots__/help-options.js.snap | 3 --- .../__tests__/__snapshots__/schema.js.snap | 9 +++------ .../__tests__/__snapshots__/support-info.js.snap | 6 +++--- website/versioned_docs/version-stable/api.md | 2 +- website/versioned_docs/version-stable/options.md | 2 -- 15 files changed, 18 insertions(+), 51 deletions(-) create mode 100644 changelog_unreleased/misc/15750.md diff --git a/changelog_unreleased/misc/15750.md b/changelog_unreleased/misc/15750.md new file mode 100644 index 000000000..ebbf8223c --- /dev/null +++ b/changelog_unreleased/misc/15750.md @@ -0,0 +1,3 @@ +#### Fix false claim in docs that cursorOffset is incompatible with rangeStart/rangeEnd (#15750 by @ExplodingCabbage) + +The cursorOffset option has in fact been compatible with rangeStart/rangeEnd for over 5 years, thanks to work by @ds300. However, Prettier's documentation (including the CLI `--help` text) continued to claim otherwise, falsely. The documentation is now fixed. diff --git a/docs/api.md b/docs/api.md index d0fbf560c..5d49e8e32 100644 --- a/docs/api.md +++ b/docs/api.md @@ -26,7 +26,7 @@ await prettier.format("foo ( );", { semi: false, parser: "babel" }); `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. -The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`. +The `cursorOffset` option should be provided, to specify where the cursor is. ```js await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" }); diff --git a/docs/options.md b/docs/options.md index c2df48f24..c79643c81 100644 --- a/docs/options.md +++ b/docs/options.md @@ -254,8 +254,6 @@ These two options can be used to format code starting and ending at a given char - Backwards to the start of the first line containing the selected statement. - Forwards to the end of the selected statement. -These options cannot be used with `cursorOffset`. - | Default | CLI Override | API Override | | ---------- | --------------------- | ------------------- | | `0` | `--range-start ` | `rangeStart: ` | diff --git a/src/index.d.ts b/src/index.d.ts index 5a7d30776..e5100597e 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -548,8 +548,6 @@ export interface CursorOptions extends Options { * Specify where the cursor is. */ cursorOffset: number; - rangeStart?: never; - rangeEnd?: never; } export interface CursorResult { @@ -572,7 +570,7 @@ export function check(source: string, options?: Options): Promise; * `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. * This is useful for editor integrations, to prevent the cursor from moving when code is formatted. * - * The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`. + * The `cursorOffset` option should be provided, to specify where the cursor is. */ export function formatWithCursor( source: string, diff --git a/src/main/core-options.evaluate.js b/src/main/core-options.evaluate.js index 36e2a6af7..5c68cc734 100644 --- a/src/main/core-options.evaluate.js +++ b/src/main/core-options.evaluate.js @@ -49,10 +49,8 @@ const options = { type: "int", default: -1, range: { start: -1, end: Number.POSITIVE_INFINITY, step: 1 }, - description: outdent` - Print (to stderr) where a cursor at the given position would move to after formatting. - This option cannot be used with --range-start and --range-end. - `, + description: + "Print (to stderr) where a cursor at the given position would move to after formatting.", cliCategory: CATEGORY_EDITOR, }, endOfLine: { @@ -160,7 +158,6 @@ const options = { description: outdent` Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. - This option cannot be used with --cursor-offset. `, cliCategory: CATEGORY_EDITOR, }, @@ -172,7 +169,6 @@ const options = { description: outdent` Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. - This option cannot be used with --cursor-offset. `, cliCategory: CATEGORY_EDITOR, }, diff --git a/src/standalone.d.ts b/src/standalone.d.ts index b77367bb7..953ccf49c 100644 --- a/src/standalone.d.ts +++ b/src/standalone.d.ts @@ -4,7 +4,7 @@ import { CursorOptions, CursorResult, Options, SupportInfo } from "./index.js"; * formatWithCursor both formats the code, and translates a cursor position from unformatted code to formatted code. * This is useful for editor integrations, to prevent the cursor from moving when code is formatted * - * The cursorOffset option should be provided, to specify where the cursor is. This option cannot be used with rangeStart and rangeEnd. + * The cursorOffset option should be provided, to specify where the cursor is. * * ```js * await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" }); diff --git a/tests/dts/unit/cases/standalone.ts b/tests/dts/unit/cases/standalone.ts index 2a23e24d0..863900241 100644 --- a/tests/dts/unit/cases/standalone.ts +++ b/tests/dts/unit/cases/standalone.ts @@ -4,13 +4,11 @@ prettierStandalone.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" }); prettierStandalone.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel", - // @ts-expect-error rangeStart: 2, }); prettierStandalone.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel", - // @ts-expect-error rangeEnd: 2, }); prettierStandalone.format(" 1", { parser: "babel" }); diff --git a/tests/format/markdown/markdown/__snapshots__/jsfmt.spec.js.snap b/tests/format/markdown/markdown/__snapshots__/jsfmt.spec.js.snap index a273f370b..86e3747c1 100644 --- a/tests/format/markdown/markdown/__snapshots__/jsfmt.spec.js.snap +++ b/tests/format/markdown/markdown/__snapshots__/jsfmt.spec.js.snap @@ -465,7 +465,7 @@ This is similar to the \`--list-different\` parameter in the CLI and is useful f \`formatWithCursor\` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. -The \`cursorOffset\` option should be provided, to specify where the cursor is. This option cannot be used with \`rangeStart\` and \`rangeEnd\`. +The \`cursorOffset\` option should be provided, to specify where the cursor is. \`\`\`js prettier.formatWithCursor(" 1", { cursorOffset: 2 }); @@ -646,8 +646,6 @@ These two options can be used to format code starting and ending at a given char * Backwards to the start of the first line containing the selected statement. * Forwards to the end of the selected statement. -These options cannot be used with \`cursorOffset\`. - Default | CLI Override | API Override --------|--------------|------------- \`0\` | \`--range-start \`| \`rangeStart: \` @@ -1454,7 +1452,6 @@ unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. The \`cursorOffset\` option should be provided, to specify where the cursor is. -This option cannot be used with \`rangeStart\` and \`rangeEnd\`. \`\`\`js prettier.formatWithCursor(' 1', { cursorOffset: 2 }); @@ -1670,8 +1667,6 @@ character offset (inclusive and exclusive, respectively). The range will extend: - Backwards to the start of the first line containing the selected statement. - Forwards to the end of the selected statement. -These options cannot be used with \`cursorOffset\`. - | Default | CLI Override | API Override | | ---------- | --------------------- | ------------------- | | \`0\` | \`--range-start \` | \`rangeStart: \` | @@ -2442,7 +2437,7 @@ This is similar to the \`--list-different\` parameter in the CLI and is useful f \`formatWithCursor\` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. -The \`cursorOffset\` option should be provided, to specify where the cursor is. This option cannot be used with \`rangeStart\` and \`rangeEnd\`. +The \`cursorOffset\` option should be provided, to specify where the cursor is. \`\`\`js prettier.formatWithCursor(" 1", { cursorOffset: 2 }); @@ -2623,8 +2618,6 @@ These two options can be used to format code starting and ending at a given char * Backwards to the start of the first line containing the selected statement. * Forwards to the end of the selected statement. -These options cannot be used with \`cursorOffset\`. - Default | CLI Override | API Override --------|--------------|------------- \`0\` | \`--range-start \`| \`rangeStart: \` @@ -3431,7 +3424,6 @@ unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. The \`cursorOffset\` option should be provided, to specify where the cursor is. -This option cannot be used with \`rangeStart\` and \`rangeEnd\`. \`\`\`js prettier.formatWithCursor(" 1", { cursorOffset: 2 }); @@ -3647,8 +3639,6 @@ character offset (inclusive and exclusive, respectively). The range will extend: - Backwards to the start of the first line containing the selected statement. - Forwards to the end of the selected statement. -These options cannot be used with \`cursorOffset\`. - | Default | CLI Override | API Override | | ---------- | --------------------- | ------------------- | | \`0\` | \`--range-start \` | \`rangeStart: \` | diff --git a/tests/format/markdown/markdown/real-world-case.md b/tests/format/markdown/markdown/real-world-case.md index ff18ed16d..1f6ff7ab7 100644 --- a/tests/format/markdown/markdown/real-world-case.md +++ b/tests/format/markdown/markdown/real-world-case.md @@ -455,7 +455,7 @@ This is similar to the `--list-different` parameter in the CLI and is useful for `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. -The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`. +The `cursorOffset` option should be provided, to specify where the cursor is. ```js prettier.formatWithCursor(" 1", { cursorOffset: 2 }); @@ -636,8 +636,6 @@ These two options can be used to format code starting and ending at a given char * Backwards to the start of the first line containing the selected statement. * Forwards to the end of the selected statement. -These options cannot be used with `cursorOffset`. - Default | CLI Override | API Override --------|--------------|------------- `0` | `--range-start `| `rangeStart: ` diff --git a/tests/integration/__tests__/__snapshots__/early-exit.js.snap b/tests/integration/__tests__/__snapshots__/early-exit.js.snap index c75519ac4..25bc0e206 100644 --- a/tests/integration/__tests__/__snapshots__/early-exit.js.snap +++ b/tests/integration/__tests__/__snapshots__/early-exit.js.snap @@ -107,15 +107,12 @@ Config options: Editor options: --cursor-offset Print (to stderr) where a cursor at the given position would move to after formatting. - This option cannot be used with --range-start and --range-end. Defaults to -1. --range-end Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. - This option cannot be used with --cursor-offset. Defaults to Infinity. --range-start Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. - This option cannot be used with --cursor-offset. Defaults to 0. Other options: @@ -274,15 +271,12 @@ Config options: Editor options: --cursor-offset Print (to stderr) where a cursor at the given position would move to after formatting. - This option cannot be used with --range-start and --range-end. Defaults to -1. --range-end Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. - This option cannot be used with --cursor-offset. Defaults to Infinity. --range-start Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. - This option cannot be used with --cursor-offset. Defaults to 0. Other options: diff --git a/tests/integration/__tests__/__snapshots__/help-options.js.snap b/tests/integration/__tests__/__snapshots__/help-options.js.snap index 960199f40..554a07d2c 100644 --- a/tests/integration/__tests__/__snapshots__/help-options.js.snap +++ b/tests/integration/__tests__/__snapshots__/help-options.js.snap @@ -136,7 +136,6 @@ exports[`show detailed usage with --help cursor-offset (stdout) 1`] = ` "--cursor-offset Print (to stderr) where a cursor at the given position would move to after formatting. - This option cannot be used with --range-start and --range-end. Default: -1" `; @@ -505,7 +504,6 @@ exports[`show detailed usage with --help range-end (stdout) 1`] = ` Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. - This option cannot be used with --cursor-offset. Default: Infinity" `; @@ -519,7 +517,6 @@ exports[`show detailed usage with --help range-start (stdout) 1`] = ` Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. - This option cannot be used with --cursor-offset. Default: 0" `; diff --git a/tests/integration/__tests__/__snapshots__/schema.js.snap b/tests/integration/__tests__/__snapshots__/schema.js.snap index 971261fa8..a9a3e05a7 100644 --- a/tests/integration/__tests__/__snapshots__/schema.js.snap +++ b/tests/integration/__tests__/__snapshots__/schema.js.snap @@ -36,8 +36,7 @@ exports[`schema 1`] = ` }, "cursorOffset": { "default": -1, - "description": "Print (to stderr) where a cursor at the given position would move to after formatting. -This option cannot be used with --range-start and --range-end.", + "description": "Print (to stderr) where a cursor at the given position would move to after formatting.", "type": "integer", }, "embeddedLanguageFormatting": { @@ -345,15 +344,13 @@ This option cannot be used with --range-start and --range-end.", "rangeEnd": { "default": Infinity, "description": "Format code ending at a given character offset (exclusive). -The range will extend forwards to the end of the selected statement. -This option cannot be used with --cursor-offset.", +The range will extend forwards to the end of the selected statement.", "type": "integer", }, "rangeStart": { "default": 0, "description": "Format code starting at a given character offset. -The range will extend backwards to the start of the first line containing the selected statement. -This option cannot be used with --cursor-offset.", +The range will extend backwards to the start of the first line containing the selected statement.", "type": "integer", }, "requirePragma": { diff --git a/tests/integration/__tests__/__snapshots__/support-info.js.snap b/tests/integration/__tests__/__snapshots__/support-info.js.snap index ee5d880c8..a74818f21 100644 --- a/tests/integration/__tests__/__snapshots__/support-info.js.snap +++ b/tests/integration/__tests__/__snapshots__/support-info.js.snap @@ -806,7 +806,7 @@ exports[`CLI --support-info (stdout) 1`] = ` { "category": "Special", "default": -1, - "description": "Print (to stderr) where a cursor at the given position would move to after formatting.\\nThis option cannot be used with --range-start and --range-end.", + "description": "Print (to stderr) where a cursor at the given position would move to after formatting.", "name": "cursorOffset", "pluginDefaults": {}, "range": { "end": null, "start": -1, "step": 1 }, @@ -1001,7 +1001,7 @@ exports[`CLI --support-info (stdout) 1`] = ` { "category": "Special", "default": null, - "description": "Format code ending at a given character offset (exclusive).\\nThe range will extend forwards to the end of the selected statement.\\nThis option cannot be used with --cursor-offset.", + "description": "Format code ending at a given character offset (exclusive).\\nThe range will extend forwards to the end of the selected statement.", "name": "rangeEnd", "pluginDefaults": {}, "range": { "end": null, "start": 0, "step": 1 }, @@ -1010,7 +1010,7 @@ exports[`CLI --support-info (stdout) 1`] = ` { "category": "Special", "default": 0, - "description": "Format code starting at a given character offset.\\nThe range will extend backwards to the start of the first line containing the selected statement.\\nThis option cannot be used with --cursor-offset.", + "description": "Format code starting at a given character offset.\\nThe range will extend backwards to the start of the first line containing the selected statement.", "name": "rangeStart", "pluginDefaults": {}, "range": { "end": null, "start": 0, "step": 1 }, diff --git a/website/versioned_docs/version-stable/api.md b/website/versioned_docs/version-stable/api.md index 139a9fa4d..25193d66a 100644 --- a/website/versioned_docs/version-stable/api.md +++ b/website/versioned_docs/version-stable/api.md @@ -27,7 +27,7 @@ await prettier.format("foo ( );", { semi: false, parser: "babel" }); `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted. -The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`. +The `cursorOffset` option should be provided, to specify where the cursor is. ```js await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" }); diff --git a/website/versioned_docs/version-stable/options.md b/website/versioned_docs/version-stable/options.md index b2ee7712b..2a4fb1577 100644 --- a/website/versioned_docs/version-stable/options.md +++ b/website/versioned_docs/version-stable/options.md @@ -255,8 +255,6 @@ These two options can be used to format code starting and ending at a given char - Backwards to the start of the first line containing the selected statement. - Forwards to the end of the selected statement. -These options cannot be used with `cursorOffset`. - | Default | CLI Override | API Override | | ---------- | --------------------- | ------------------- | | `0` | `--range-start ` | `rangeStart: ` |