Find Text and Save Navigation

By the end of this chapter, you will have found text through Completion and search, inspected checked result locations, and reused explicitly saved text, numbers and a location after restarting Rur.

Configure a Search Command

Create a small file:

printf 'needle marker\nabsent marker\n' > markers.txt

Save this trusted configuration as navigation.rb beside it:

Rur.configuration.navigation_policy({
  'search_case' => 'sensitive',
  'search_whitespace' => 'exact',
  'search_multiline' => true,
  'search_dot_matches_newline' => false,
  'candidate_rows' => 16
})
Rur.configuration.command('find-marker', ->(context) {
  context.incremental_search('absent|needle', 'expression', 'sensitive', 'forward')
}, {'kind' => 'session', 'requires' => 'buffer',
    'effects' => ['interaction', 'selection', 'view']})

The command starts a case-sensitive expression search for either absent or needle. It declares the interaction, selection and view changes it requests. Configuration is ordinary trusted Ruby; use source you trust.

Start Rur from that directory:

env -u RUBYOPT -u RUBYLIB -u GEM_HOME -u GEM_PATH cargo run --locked -p rur-editor --bin rur-terminal-proof -- --profile nonmodal --config navigation.rb markers.txt

You can repeat the chapter with --profile modal. Alt-x opens command entry in both profiles. Enter Insert before ordinary typing in the modal profile; Normal keeps u for Undo and Ctrl-R for Redo.

Choose a Command or File

Press Alt-x and type find marker. Both components filter the shared command list, including command descriptions. Backspace removes one grapheme. Up/Down changes the highlighted row; Page Up/Down moves by the visible page. Choose find-marker and press Enter. Preparing rows cannot confirm an obsolete action.

The search header reports an expression match and the occurrence is highlighted. Press Ctrl-S to find the next occurrence and Ctrl-R to reverse direction. Press Ctrl-G to restore the search origin. Filtering, highlighting and cancelling do not edit your file.

Ctrl-X b uses the same selector for buffers. A new valid buffer name has an explicit Create row. Ctrl-X Ctrl-F opens file Completion: type a directory prefix, use Tab to enter a selected directory, and Enter to open a file. Typing filters the copied immediate listing. A disappeared file can still refuse when you confirm it. Hidden entries require an explicit prefix or path.

An initial typed / or ~ is the home-navigation shortcut. Paste a complete absolute path when you mean its absolute location. Path spelling and selected identity are rechecked when the file opens.

Recover an Interactive Search

Use Alt-x move-buffer-start, then Alt-x isearch-forward. Type needle; this entry command treats metacharacters literally. Add ? to produce a failed suffix. One Ctrl-G recovers the successful needle query and location. Another Ctrl-G restores the origin and closes search.

Start another search for needle and press Enter to accept its location. Start search again and press Alt-p to recall an older compatible query. Alt-n moves newer and eventually restores your unfinished input. Alt-h opens a history selector; Ctrl-G closes that child and returns to the same parent search. Literal and expression histories remain separate.

The expression entry commands are isearch-forward-regexp and isearch-backward-regexp. An invalid expression remains editable query input; it is different from a valid query with no match. See the search dialect before using properties, boundaries or capture groups.

Inspect Results and Replace Text

Move to the buffer start and invoke search-results. Enter marker and Enter. The result list names exact source locations. Up/Down selects a row; Enter visits it. Ctrl-G leaves the list, and pop-selection-location returns through the existing selection history. next-location and previous-location traverse the effective result source. A changed source can make a row stale; refresh it instead of reusing an old position. An Incomplete list needs explicit continuation.

For a reversible change, move to the start and invoke replace-string. Enter marker, Enter, label, Enter. Both lines now end with label. Undo restores both original lines: Ctrl-Z in nonmodal Editing, or u in modal Normal. The replace-regexp variant uses the bounded expression and capture-template dialect.

For individual decisions, query-replace and query-replace-regexp offer y or Space to replace, n or Delete to skip, ! to replace the remaining matches atomically, and . to replace once and stop. q, Enter or Ctrl-G keeps already confirmed edits and stops. A refused atomic batch publishes no prefix.

Result rows also support explicit editable replacement fields. e enters a field, Ctrl-S stages it and d opens its exact diff. Staged departure asks you to apply, discard or continue editing. Read the result-field controls before applying a group. Preview metadata is not an editable source field.

Keep Explicit Named State

After undoing the replacement, save markers.txt with Ctrl-X Ctrl-S. Move to the start and invoke save-location. Enter tutorial-marker-start and confirm its Create row. This records the clean file's point, optional mark and region state.

Invoke store-number, choose the new name tutorial-visits, and enter 7. Invoke increment-number, choose that name, and enter 1. The stored Integer is now 8. Overflow refuses without changing the value.

To retain the complete text, invoke move-buffer-start, set-mark, then move-buffer-end. Invoke save-named-text and create tutorial-copy. Successful publication deactivates the region while retaining mark. Names are exact and case-sensitive. Replacing a value with another kind requires the explicit answer yes; Ctrl-G preserves the old value.

Exit with Ctrl-X Ctrl-C and restart with the same command and file. Invoke list-named-values to inspect the Integer and saved Text, then close the list with Ctrl-G. Invoke visit-location and choose tutorial-marker-start. An unchanged portable file restores the saved location. Missing, changed or nonportable targets refuse before moving focus or selection.

Invoke insert-named-text and choose tutorial-copy. The original two lines appear twice. Undo restores the original file. Saved text is independent of the transfer ring and session-local text slots. These collections persist only through explicit named-state writes; they do not save search history or replay Ruby on restart. The named-state reference describes exact bytes, storage paths and portability.

Inspect What Is Active

Press Ctrl-X h to open help from the current interaction. Choose bindings, a command, a key, context or owners. describe-command, describe-bindings, describe-key and describe-keymap are also available through Alt-x. Describing a key resolves its effective command without invoking it. Ctrl-G closes help and restores its parent interaction.

Help reports the current profile, maps and availability. An absent provider is reported as unavailable. After configuration changes, reopen expired help to inspect the new generation.

Save the undone original text, exit, and run:

cat markers.txt

The output is still needle marker and absent marker, on separate lines. Use the navigation reference for every admitted limit and the differences between literal, expression and replacement input.

Previous: Search and Navigation | Part | User Guide | Next: Search Projects and Workspaces