paredit

name	paredit
description	Structural editing CLI for S-expressions written in Janet. Use when the user wants to parse, navigate, or transform S-expression source code, or when working with .janet files that need structural edits like slurp, barf, wrap, splice, raise, kill, split, or join.

paredit

Usage

paredit <expression> <file-or->
paredit --list <file-or->

Reads S-expression source from a file or stdin (-), applies the expression, and prints the result.

paredit "@0" file.janet          # select first form from file
echo "(a b c)" | paredit "@0" -  # read from stdin

Use --list to discover top-level forms and their selectors:

$ paredit --list file.janet
@0  @[defn]  (defn potato [size] :big)
@1  @[def]  (def garden [potato tomato carrot])

Each line shows the @N index, the @[name] selector (when the form starts with an atom), and the full form text.

Expression language

Expressions are pipe-separated steps: @0 | .2 | slurp

Selectors (pick a top-level form)

Syntax	Description
@N	Select Nth top-level form (0-indexed)
@[name]	Select form whose first atom matches name

Navigation (move within the tree)

Syntax	Description
.N	Move to Nth raw child (0-indexed, includes whitespace nodes)
..	Move up to parent

Note: .N counts all children including whitespace nodes. In (a b c), .0 is a, .1 is the space, .2 is b, .3 is the space, .4 is c.

Operations (transform the tree)

All operations return the full modified source.

Operation	Description	Before → After
slurp	Pull next sibling into focused list	(a) b → (a b)
slurp-backward	Pull previous sibling into focused list	a (b) → (a b)
barf	Push last child out of focused list	(a b) → (a) b
barf-backward	Push first child out of focused list	(a b) → a (b)
wrap(D)	Wrap focused node in delimiter D ((, [, {)	(a b c) @ b → (a [b] c)
splice	Remove delimiters, merge children into parent	(a (b c) d) @ inner → (a b c d)
raise	Replace parent with focused node	(a (b c) d) @ c → (a c d)
kill	Delete focused node, clean up whitespace	(a b c) @ b → (a c)
split	Split parent list at focus into two lists	(a b c d) @ b → (a b) (c d)
join	Merge focused list with next sibling list	(a) (b) → (a b)

Examples

# Select the defn form from a file
paredit "@[defn]" src/main.janet

# Slurp the next form into the first list
paredit "@0 | slurp" file.janet

# Wrap the second child of the first form in brackets
paredit "@0 | .2 | wrap([)" file.janet

# Splice a nested list in the first form
paredit "@0 | .4 | splice" file.janet

# Kill the middle element
paredit "@0 | .2 | kill" file.janet

# Split a list at the second element
paredit "@0 | .2 | split" file.janet

# Join two adjacent top-level lists
paredit "@0 | join" file.janet

# Chain: navigate into a child, then raise it
paredit "@0 | .4 | .0 | raise" file.janet

# Read from stdin
echo "(a) b c" | paredit "@0 | slurp" -