(:replace) - Operators

replace selection with literal text or captured values

(:replace val? sub? reconcile?)

Where:

1. val: what to replace (omit to replace whatever is matched at this position) *
2. sub: replacement text (omit to delete the matched value) *
3. reconcile: eat syntactic tokens adjacent to the selection (e.g., a comma) when dropping *

Expanding into:

(:#replace node \1 \2 \3)

Guides

• Replacement

Behavior

• When sub is omitted, the matched value is dropped (deleted) from the output.
• Supports regex capture groups ($1, $2, etc.) from pattern-based selectors.
• Supports named captures via (:capture name ...) which can be referenced as $name in the substitution string.
• Captures are scoped per match - each match site maintains isolated capture values.

Examples

Replace all instances of a deprecated API call with its modern equivalent.

(:replace (call oldAPI) "newAPI()")

Selects in lines { 1 }:

x(oldAPI())
y(process())

---

Drop the second argument from specific function calls during refactoring.

(call processData (:replace (arg 2)))

Selects in lines { 1 }:

processData(input, legacy)
otherCall(a, b)

---

Rename string literals using regex capture groups.

(:replace (str /old_(.+)/) "new_$1")

Selects in lines { 1, 2 }:

const key = "old_users"
const other = "old_settings"

---

Reorder function arguments by capturing and rearranging them.

(call log
  (arg 1
    (:and
      (:capture first)
      (:replace _ "$rest, $first")))
  (arg 2.. (:capture rest (:into))))

Selects in lines { 1 }:

log("a", "b", "c")

---

Add a parameter to function calls using captures from other arguments.

(call fetch
  (:and
    (arg 1 (:capture url (str)))
    (arg 2 (:replace _ "$url_config"))))

Selects in lines { 1 }:

fetch("/api", options)

---

Arguments

val

1. inherit

sub

1. String

Does NOT support: Composition — Free-form Selection — Refinement — Replacement

reconcile

1. "auto"
   
2. "right"
   
3. "left"
   

Does NOT support: Composition — Free-form Selection — Refinement — Replacement