Added break line action (#2103)

`"break air"`

## Checklist

- [x] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [x] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [x] I have not broken the cheatsheet

---------

Co-authored-by: Pokey Rule <[email protected]>

Author: AndreasArvidsson

changelog/2023-12-addedBreakLineAction.md

@@ -0,0 +1,6 @@
+---
+tags: [enhancement]
+pullRequest: 2103
+---
+
+- Added `break` action. This action will break a line in two. eg `"break air"`

changelog/2023-12-addedVisibleModifier.md

@@ -0,0 +1,6 @@
+---
+tags: [enhancement]
+pullRequest: 2094
+---
+
+- Added `visible` modifier. This modifier returns all visible ranges. In most cases this will just be a single range starting from the first visible line and ending at the last visible line. If there are visible folded regions these break the visible range into po multiple ranges.

cursorless-talon/src/spoken_forms.json

@@ -3,6 +3,7 @@
   "actions.csv": {
     "simple_action": {
       "bottom": "scrollToBottom",
+      "break": "breakLine",
       "break point": "toggleLineBreakpoint",
       "carve": "cutToClipboard",
       "center": "scrollToCenter",

docs/user/README.md

@@ -717,6 +717,16 @@ eg:
 - `join air`: Join the line with the token containing the letter 'a' with its next line.
 - `join block air`: Joines all lines in the paragraph with the token containing the letter 'a' together into a single line.
 
+### Break
+
+Break line in two.
+
+- `"break <TARGET>"`
+
+eg:
+
+- `break air`: Break the line with the token containing the letter 'a'. 'a' is now the first token on the new line.
+
 ## Paired delimiters
 
 | Default spoken form | Delimiter name        | Symbol inserted before target | Symbol inserted after target | Is wrapper? | Is selectable? |

packages/common/src/types/command/ActionDescriptor.ts

@@ -8,6 +8,7 @@ import { DestinationDescriptor } from "./DestinationDescriptor.types";
  * A simple action takes only a single target and no other arguments.
  */
 const simpleActionNames = [
+  "breakLine",
   "clearAndSetSelection",
   "copyToClipboard",
   "cutToClipboard",

packages/cursorless-engine/src/actions/Actions.ts

@@ -1,7 +1,8 @@
-import { TreeSitter } from "../typings/TreeSitter";
 import { Snippets } from "../core/Snippets";
 import { RangeUpdater } from "../core/updateSelections/RangeUpdater";
 import { ModifierStageFactory } from "../processTargets/ModifierStageFactory";
+import { TreeSitter } from "../typings/TreeSitter";
+import { BreakLine } from "./BreakLine";
 import { Bring, Move, Swap } from "./BringMoveSwap";
 import Call from "./Call";
 import Clear from "./Clear";
@@ -28,7 +29,6 @@ import {
 import InsertSnippet from "./InsertSnippet";
 import JoinLines from "./JoinLines";
 import { PasteFromClipboard } from "./PasteFromClipboard";
-import ShowParseTree from "./ShowParseTree";
 import Remove from "./Remove";
 import Replace from "./Replace";
 import Rewrap from "./Rewrap";
@@ -39,6 +39,7 @@ import {
   SetSelectionAfter,
   SetSelectionBefore,
 } from "./SetSelection";
+import ShowParseTree from "./ShowParseTree";
 import {
   CopyToClipboard,
   ExtractVariable,
@@ -113,6 +114,7 @@ export class Actions implements ActionRecord {
     this.modifierStageFactory,
   );
   joinLines = new JoinLines(this.rangeUpdater);
+  breakLine = new BreakLine(this.rangeUpdater);
   moveToTarget = new Move(this.rangeUpdater);
   outdentLine = new OutdentLine(this.rangeUpdater);
   pasteFromClipboard = new PasteFromClipboard(this.rangeUpdater, this);

packages/cursorless-engine/src/actions/BreakLine.ts

@@ -0,0 +1,72 @@
+import { FlashStyle, Position, Range, TextEditor } from "@cursorless/common";
+import { flatten, zip } from "lodash";
+import type { RangeUpdater } from "../core/updateSelections/RangeUpdater";
+import { performEditsAndUpdateRanges } from "../core/updateSelections/updateSelections";
+import { ide } from "../singletons/ide.singleton";
+import { Edit } from "../typings/Types";
+import { Target } from "../typings/target.types";
+import { flashTargets, runOnTargetsForEachEditor } from "../util/targetUtils";
+import type { ActionReturnValue } from "./actions.types";
+
+export class BreakLine {
+  constructor(private rangeUpdater: RangeUpdater) {
+    this.run = this.run.bind(this);
+  }
+
+  async run(targets: Target[]): Promise<ActionReturnValue> {
+    await flashTargets(ide(), targets, FlashStyle.pendingModification0);
+
+    const thatSelections = flatten(
+      await runOnTargetsForEachEditor(targets, async (editor, targets) => {
+        const contentRanges = targets.map(({ contentRange }) => contentRange);
+        const edits = getEdits(editor, contentRanges);
+
+        const [updatedRanges] = await performEditsAndUpdateRanges(
+          this.rangeUpdater,
+          ide().getEditableTextEditor(editor),
+          edits,
+          [contentRanges],
+        );
+
+        return zip(targets, updatedRanges).map(([target, range]) => ({
+          editor: target!.editor,
+          selection: range!.toSelection(target!.isReversed),
+        }));
+      }),
+    );
+
+    return { thatSelections };
+  }
+}
+
+function getEdits(editor: TextEditor, contentRanges: Range[]): Edit[] {
+  const { document } = editor;
+  const edits: Edit[] = [];
+
+  for (const range of contentRanges) {
+    const position = range.start;
+    const line = document.lineAt(position);
+    const indentation = line.text.slice(
+      0,
+      line.firstNonWhitespaceCharacterIndex,
+    );
+    const characterTrailingWhitespace = line.text
+      .slice(0, position.character)
+      .search(/\s+$/);
+    const replacementRange =
+      characterTrailingWhitespace > -1
+        ? new Range(
+            new Position(line.lineNumber, characterTrailingWhitespace),
+            position,
+          )
+        : position.toEmptyRange();
+
+    edits.push({
+      range: replacementRange,
+      text: "\n" + indentation,
+      isReplace: !replacementRange.isEmpty,
+    });
+  }
+
+  return edits;
+}

packages/cursorless-engine/src/generateSpokenForm/defaultSpokenForms/actions.ts

@@ -5,6 +5,7 @@ import { ActionType } from "@cursorless/common";
  * if the action has no spoken form.
  */
 export const actions = {
+  breakLine: "break",
   scrollToBottom: "bottom",
   toggleLineBreakpoint: "break point",
   cutToClipboard: "carve",

packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/actions/breakBat.yml

@@ -0,0 +1,33 @@
+languageId: plaintext
+command:
+  version: 6
+  spokenForm: break bat
+  action:
+    name: breakLine
+    target:
+      type: primitive
+      mark: {type: decoratedSymbol, symbolColor: default, character: b}
+  usePrePhraseSnapshot: true
+initialState:
+  documentContents: aaa bbb ccc
+  selections:
+    - anchor: {line: 0, character: 0}
+      active: {line: 0, character: 0}
+  marks:
+    default.b:
+      start: {line: 0, character: 4}
+      end: {line: 0, character: 7}
+finalState:
+  documentContents: |-
+    aaa
+    bbb ccc
+  selections:
+    - anchor: {line: 0, character: 0}
+      active: {line: 0, character: 0}
+  thatMark:
+    - type: UntypedTarget
+      contentRange:
+        start: {line: 1, character: 0}
+        end: {line: 1, character: 3}
+      isReversed: false
+      hasExplicitRange: true

packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/actions/breakCommentSit.yml

@@ -0,0 +1,45 @@
+languageId: typescript
+command:
+  version: 6
+  spokenForm: break comment sit
+  action:
+    name: breakLine
+    target:
+      type: primitive
+      mark: {type: decoratedSymbol, symbolColor: default, character: i}
+      modifiers:
+        - type: containingScope
+          scopeType: {type: comment}
+  usePrePhraseSnapshot: true
+initialState:
+  documentContents: |-
+    [
+      0,
+      1, // interesting
+      2
+    ]
+  selections:
+    - anchor: {line: 0, character: 0}
+      active: {line: 0, character: 0}
+  marks:
+    default.i:
+      start: {line: 2, character: 8}
+      end: {line: 2, character: 19}
+finalState:
+  documentContents: |-
+    [
+      0,
+      1,
+      // interesting
+      2
+    ]
+  selections:
+    - anchor: {line: 0, character: 0}
+      active: {line: 0, character: 0}
+  thatMark:
+    - type: UntypedTarget
+      contentRange:
+        start: {line: 3, character: 2}
+        end: {line: 3, character: 16}
+      isReversed: false
+      hasExplicitRange: true