reference.md

Function reference (work in progress)

Special mode

vilpy commands operate when special mode is active.

If you know vi, think of special mode as vilpy's normal mode.

Special-mode is activated when:

• the point is before an open paren: (, [ or {
• the point is after a close paren: ), ] or }
• the region is active

In the examples below, consider that the point is represented by |.

As the point is just before the parenthesis, keys will invoke vilpy commands. If you press A, for example, it will call vilpy-insert-at-end-of-sexp.

|(foo)

After A:

(foo|)

However, if the point is not at a position that activates special-mode, pressing A will self-insert the letter A, as usual.

(|foo)

After A:

(A|foo)

Getting in special mode

command	binding
vilpy-special	backtab

Note that backtab is shift and tab.

If not in special mode

Move the point to the nearest leftmost paren.

Starting with:

(foo |bar)

after backtab:

|(foo bar)

If already in special mode

Cycle through parens.

Starting with:

|(foo bar)

after backtab:

(foo bar)|

after backtab:

|(foo bar)

Getting out of special mode

command	binding
forward-char	a
vilpy-insert-at-end-of-sexp	A
vilpy-open-line-below	o
vilpy-open-line-above	O
backward-char	C-b
forward-char	C-f

forward-char (a)

Starting with

|(foo)

after a:

(|foo)

vilpy-insert-at-end-of-sexp (A)

Starting with

|(foo bar)

after A:

(foo bar|)

vilpy-open-line-below (o)

Starting with

|(foo)

after o:

(foo)
|

vilpy-open-line-above (O)

Starting with

|(foo)

after O:

|
(foo)

Navigation

command	binding
vilpy-step-out	h
vilpy-step-in	l
vilpy-down	j
vilpy-up	k
vilpy-knight-down	S
vilpy-knight-up	W
vilpy-beginning-of-defun	I
vilpy-back	b
vilpy-right	L
vilpy-go-to-first-defun	gg
vilpy-go-to-last-defun	G

vilpy-step-out (h)

Starting with

(foo (bar |(baz))

after h:

(foo |(bar (baz))

after h:

|(foo (bar (baz))

vilpy-step-in (l)

Starting with

|(foo (bar (baz))

after l:

(foo |(bar (baz))

after l:

(foo (bar |(baz))

vilpy-down (j)

Starting with:

|(foo)
(bar)

after j:

(foo)
|(bar)

vilpy-up (k)

Starting with:

(foo)
|(bar)

after k:

|(foo)
(bar)

vilpy-knight-down (S)

Navigate to the next line disregarding syntax.

Starting with:

|(foo (bar)
      (xum))

after S:

(foo (bar)
     |(xum))

vilpy-knight-up (W)

Navigate to the previous line disregarding syntax.

Starting with:

(foo (bar)
     |(xum))

after W:

|(foo (bar)
      (xum))

vilpy-beginning-of-defun (I)

Starting with this top level form:

(defun abc ()
  (interactive)
  |(foo))

after Ias

|(defun abc ()
  (interactive)
  (foo))

vilpy-back (b)

Moves the point to the previous position in vilpy-back history. The following functions write to this history: function name

command	binding
vilpy-step-out	h
vilpy-step-in	l
vilpy-down	j
vilpy-up	k
vilpy-right	L
vilpy-mark-list	v
vilpy-ace-paren	q

vilpy-right (L)

Moves forward out of arg (default 1) levels of parentheses.

Works as replacement for the standard up-list.

Takes a numeric prefix arg and moves up forward list arg times or until error.

Unlike up-list, no error will be reported if it's not possible to move up arg times. It that case, move as many times as possible.

Return point if could move arg times, otherwise return nil.

Unlike up-list, parens in strings and comments are ignored.

vilpy-go-to-first-defun (gg)

Starting with

(a)
(b |(c))

after gg:

|(a)
(b (c))

vilpy-go-to-last-defun (G)

Starting with

(a |(b))
(c)

after G:

(a (b))
|(c)

Code actions

command	binding
vilpy-eval	e
vilpy-eval-defun	D
vilpy-eval-buffer	B
vilpy-tab	=
vilpy-describe	K

vilpy-eval (e)

Eval current region or sexp.

Emacs Lisp and Clojure (cider and inf-clojure) are supported.

The evaluation function is defined in vilpy--handlers-alist.

vilpy-eval-defun (D)

Eval top level form.

Emacs Lisp and Clojure (cider and inf-clojure) are supported.

The evaluation function is defined in vilpy--handlers-alist.

vilpy-eval-buffer (B)

Eval buffer.

Emacs Lisp and Clojure (cider and inf-clojure) are supported.

The evaluation function is defined in vilpy--handlers-alist.

vilpy-tab (=)

If before left paren or after right paren, indent the current sexp.

Emacs Lisp and Clojure (cider and inf-clojure) are supported.

The indentation function is defined in vilpy--handlers-alist.

vilpy-describe (K)

Describe the symbol at point.

Emacs Lisp and Clojure (cider and inf-clojure) are supported.

The function for describing the symbol is defined in vilpy--handlers-alist.

Transformation

command	binding
vilpy-raise	r
vilpy-raise-some	R
vilpy-move-up	p
vilpy-move-down	n
vilpy-slurp	>
vilpy-barf	<
vilpy-move-and-slurp-actions	/
vilpy-splice	x
vilpy-join	+
vilpy-convolute	C
vilpy-oneline	J
vilpy-alt-multiline	M
vilpy-teleport	t

vilpy-raise (r)

Starting with

(foo |(bar))

after r:

(bar)

vilpy-raise-some (R)

Starting with:

(foo
  |(bar)
  (xum))

after R:

(bar)
(xum)

vilpy-move-up (p)

Starting with:

(foo)
|(bar)

after p:

|(bar)
(foo)

vilpy-move-down(n)

Starting with:

|(foo)
(bar)

after n:

(bar)
|(foo)

vilpy-splice(x)

Starting with:

(foo |(bar))

after x:

(foo bar)

vilpy-join(+)

Starting with:

(foo)
|(bar)

after +:

|(foo
bar)

vilpy-convolute(C)

Starting with:

(foo
 (bar
  |(xum)))

after C:

(bar
 (foo
  (xum)))

after C:

(foo
 (bar
  |(xum)))

vilpy-oneline(J)

Starting with:

|(foo
 (bar
  (xum)))

after J:

(foo (bar (xum)))

vilpy-split (M-j)

vilpy-join (M-J)

Barfage & Slurpage

command	binding
vilpy-slurp	>
vilpy-barf	<
vilpy-move-left	sh
vilpy-move-right	sl
vilpy-down-slurp	sj
vilpy-up-slurp	sk

vilpy-slurp(>)

Starting with:

(foo)| (bar) (xum)

after >:

(foo (bar))| (xum)

after >:

(foo (bar) (xum))

vilpy-barf (<)

Starting with:

(foo) (bar) |(xum)

after <:

(foo) |((bar) xum)

after <:

|((foo) (bar) xum)

vilpy-move-left (sh)

Move current expression to the left, outside the current list.

(require 'ob-python)
(let ((color "Blue"))
  |(message "What... is your favorite color?")
  (message "%s. No yel..." color))

after /h:

(require 'ob-python)
|(message "What... is your favorite color?")
(let ((color "Blue"))
  (message "%s. No yel..." color))

vilpy-move-right (sl)

Move current expression to the right, outside the current list.

(require 'ob-python)
(message "What... is your favorite color?")
(let ((color "Blue"))
  (message color)
  |(message "Go on. Off you go."))

after /l:

(require 'ob-python)
(message "What... is your favorite color?")
(let ((color "Blue"))
  (message color))
|(message "Go on. Off you go.")

vilpy-down-slurp (sj)

Move current expression to become the first element of the first list below.

(list 'my-sword
      'my-bow)
|(my-axe)

after /j:

'(|(first!)
  foo bar)

Acing

command	binding
vilpy-ace-symbol	f
vilpy-ace-subword	-
vilpy-ace-symbol-beginning-of-defun	F
vilpy-ace-paren	q
vilpy-ace-char	Q

vilpy-ace-symbol (f)

Marks symbol in the current form. This can be followed up with eval, raise, deletion etc. For unmarking the symbol afterwards, as usual, press C-g.

Starting with:

(foo bar baz)

After f, each symbol will be annotated with a character:

(afoo bbar cbaz)

In this example, say you press c. Then, the cursor will jump to baz and it will be marked.

vilpy-ace-subword (-)

Marks subword.

Starting with:

(foo-bar-baz)

After -:

(afoo-bbaz-cbaz)

In this example, use a, b or c for jumping and marking a subword.

vilpy-ace-symbol-beginning-of-defun (F)

Same as vilpy-ace-symbol, but the range of acing is the current defun rather than the current form.

vilpy-ace-paren (q)

Marks form.

Starting with:

(a (b) (c) d)

After q:

a((bb) (cc) d)

In this example, use a, b or c for jumping and marking a form.

vilpy-ace-char (Q)

Asks for a char and jumps to it in the current form.

Deleting & killing

command	binding
vilpy-delete	C-d
vilpy-kill	C-k
vilpy-kill-word	M-DEL
vilpy-delete-backward	DEL

vilpy-delete (C-d)

Deletes region, form or string, depending on the position of the point. Accepts numerical argument.

For the complete list of behaviours, please refer to the lispy documentation.

Example 1: In region

Starting with (~ denotes a marked region):

(~foo~)

After C-d:

()

Example 2: Before form

Starting with

|(foo) (bar)

after C-d:

|(bar)

vilpy-kill (C-k)

Similar to kill-line, but keeps parens balanced.

Example 1: Before form

Starting with:

(foo |(bar) (baz))

after C-k:

(foo )

Example 2: In string

Starting with:

"foo |bar"

after C-k:

"foo "

vilpy-kill-word (M-DEL)

Kill words. Accepts numerical argument.

Starting with:

|(foo bar)

After M-DEL:

(| bar)

After M-DEL:

(|)

vilpy-delete-backward (DEL)

Bound to DEL.

Replaces backward-delete-char, keeping parens balanced.

The result depends on the following conditions, each tried one by one until one that holds true is found:

Active region

Delete region.

At first char of the string

Move to the end of the string. This allows to delete the whole string with the next DEL.

(message "|more gold is required")

after DEL:

(message "more gold is required"|)

In string near \\( or \\)

Remove \\( and \\).

Starting with:

(looking-at "\\([a-z]+\\)|")

After DEL:

(looking-at "[a-z]+")

Starting with:

(looking-at "\\(|[a-z]+\\)")

after DEL:

(looking-at "|[a-z]+")

In string or comment

Call backward-delete-char.

After right paren

Delete arg sexps.

Starting with:

(foo (bar) (baz)|)

after 2 DEL:

(foo)

After left paren

Delete containing sexp.

(foo (|bar) (baz))

After DEL:

(foo| (bar))

After a string

Delete string.

(message "more gold is required"|)

After DEL:

(message |)

Otherwise

Call backward-delete-char.

Copying & yanking

command	binding
vilpy-copy	y
vilpy-clone	w
vilpy-paste	P

vilpy-copy(y)

Copy the current sexp or region to kill ring.

vilpy-clone (w)

Copy current sexp or region and paste it below. With a numerical argument, copy that many times.

Starting with:

|(foo)

after w:

|(foo)
(foo)

vilpy-paste (P)

When region is active, replace it with current kill. Otherwise, forward to yank.

Marking

command	binding
vilpy-mark-list	m
vilpy-mark-symbol	M-m
vilpy-mark	C-M-,

vilpy-mark-list (m)

Mark the current sexp. When the mark is already active, deactivate it instead.

vilpy-mark-symbol (M-m)

Marks the symbol at point, comment or symbol in the next or previous list.

Point is under symbol

Mark the symbol.

In comment

Mark the comment.

In special mode, before paren

Marks the next symbol.

In special mode, after paren

Marks the previous symbol.

Region is active

Call forward-sexp.

Otherwise

Forward to lispy-mark.

vilpy-mark (C-M-,)

Mark the smallest comment, string or sexp that includes point.

Misc

command	binding
vilpy-comment	;
vilpy-space	SPC
vilpy-narrow	gn
vilpy-widen	gw
vilpy-undo	u
vilpy-scroll-line-to-top	zt
vilpy-scroll-line-to-center	zz
vilpy-scroll-line-to-bottom	zb
vilpy-repeat	.

Magic

command	binding
vilpy-teleport	t

vilpy-teleport(t)