Reload Your Personal Configuration

By the end of this chapter, you will have loaded a personal Ruby helper, changed its behavior without restarting, recovered from a syntax error and saved the exact text ABBC. Use the terminal prerequisites. Configuration executes trusted Ruby with your process's permissions.

Create an Isolated Personal Source

Run these commands from the repository root. This exercise selects a temporary configuration root for the editor process:

personal_demo=$(mktemp -d)
mkdir -p "$personal_demo/config/rur/parts"
printf '' > "$personal_demo/note.txt"

Save this entrypoint as $personal_demo/config/rur/init.rb:

Rur.configuration.load_relative('parts/personal.rb')

Save this helper as $personal_demo/config/rur/parts/personal.rb:

module Personal
  VERSION = 'A'

  def self.insert(context)
    point = context.selection.fetch('point')
    context.replace(context.observe_range(point, point).merge('replacement' => VERSION))
  end
end

configuration = Rur.configuration
configuration.command('personal-insert', Personal.method(:insert), {
  'kind' => 'compound', 'requires' => 'view', 'effects' => ['text', 'selection']
})
configuration.editing_policy({'fill_column' => 80})
configuration.scoped_editing_policy('context', 'modal', {'indentation_width' => 6})

Start the editor:

env -u RUBYOPT -u RUBYLIB -u GEM_HOME -u GEM_PATH XDG_CONFIG_HOME="$personal_demo/config" cargo run --locked -p rur-editor --bin rur-terminal-proof -- --profile nonmodal "$personal_demo/note.txt"

Without --config, Rur selects $XDG_CONFIG_HOME/rur/init.rb. When XDG_CONFIG_HOME is unset or empty it uses $HOME/.config/rur/init.rb. A missing personal file starts factory behavior without creating a file. An explicit --config PATH selects that file instead. The editor never rewrites your source.

Inspect and Replace the Helper

Alt-x opens command entry in both profiles. Type personal-insert and press Enter: the file contains A. Press Ctrl-X h, type context, then Enter to inspect the active and selected Personal configuration and Fill column: 80; user/global. Close inspection with Ctrl-G.

Edit the helper in another editor, changing VERSION = 'A' to VERSION = 'B'. Invoke reload-configuration, then personal-insert. The text becomes AB. Reload rereads each supported helper into a fresh source module; the old module continues serving already admitted work until its owners retire. Ordinary global Ruby require keeps its usual cache semantics.

Recover from a Failed Reload

Temporarily replace the helper with two empty lines followed by def broken(. Invoke reload-configuration. The status reports active configuration unchanged; syntax. Press Ctrl-X h, type context, then Enter to read the helper's complete path, line 3 and cause. The selected source remains Personal and the prior confirmed behavior stays usable. Close inspection, then invoke personal-insert: the text becomes ABB.

Restore the complete helper, this time with VERSION = 'C'. Reload and invoke personal-insert: the text becomes ABBC. Invoke undo and check ABB; invoke redo and check ABBC. Save with Ctrl-X Ctrl-S and wait for saved durably. Exit with Ctrl-X Ctrl-C. The terminal returns to its original modes and flags. In the shell, verify the exact bytes, with no trailing newline:

printf ABBC | cmp - "$personal_demo/note.txt"

Repeat with a new empty note and --profile modal; restore helper version A before starting. Named commands work from Normal without entering Insert. The context page also reports indentation width 6 from the modal profile rule. An invalid personal source at startup uses factory behavior with factory startup; syntax; correct that source and reload to activate it. An invalid explicit --config source rejects startup before entering interactive modes.

Choose Scopes and Pane Policy

Global editing values inherit field by field. Profile/context and file-suffix rules apply in declaration order, then an exact live buffer override wins. Buffer owners use the complete displayed normalized filename; keymap owners also accept a native live buffer identity. Open the buffer before reloading a declaration for it. Closing and reopening the same filename creates a different allocation. Component maps belong to supported native roles; project/language owners are unavailable. See the scope reference for exact forms and precedence.

For independent pane placement, copy pane-policy/reuse-first.rb beside your entrypoint in a pane-policy directory and append:

Rur.configuration.load_relative('pane-policy/reuse-first.rb')

Reload and inspect Placement provider: configuration callable in the context Help page. Open a second file, return to the note, invoke keep-only-pane, then split-pane-right. Invoke display-buffer-other-pane and confirm the second file's complete name: the helper reuses the eligible pane. Change its REUSE_FIRST constant to false and reload to prefer a fresh split. Remove the entrypoint's policy-loading line and reload to restore Placement provider: native fallback. Removing only the helper file rejects replacement and retains the previous policy.

The configuration how-to covers explicit command customization. The source and builder reference defines source limits, observers and annotation ownership; the ownership explanation describes publication and retirement. Trusted Ruby globals and external side effects remain outside editor-owned rollback.

Previous: Customization | Part | User Guide | Next: Run and Inspect Finite Process Work