Cursor placement

Place the cursor after expanding abbreviations

Toggle the "expansion cursor placement" system on:

# .zshrc

ABBR_SET_EXPANSION_CURSOR=1

and use the "expansion cursor marker" in your abbreviations (default: %; learn more at Configuration variables > ABBR_EXPANSION_CURSOR_MARKER)

% abbr git m='commit -m "%"'
Added the regular user abbreviation `m`
Added the global user abbreviation `git m`

Now, typing mSpace expands the abbreviation m and replaces the expansion's first expansion cursor marker with the cursor:

git commit -m "Cursor"

 

TIP

You can use this to disable the trailing space after expanding abbreviations with Space in the default config:

% abbr a="trailing space"
% abbr b="no trailing space%"
% a[Space]b[Space] # expands to `trailing space no trailing space`

Place the cursor, regardless of expansion

zsh-abbr can change the position of your cursor even when you aren't expanding abbreviations. This unlocks "template" abbreviations.

Toggle the "line cursor placement" system on:

# .zshrc

ABBR_SET_LINE_CURSOR=1

Now, under the default configuration, Space will jump the cursor to the next instance of %. For example, create this abbreviation

% abbr a='my command --flag=% --another-flag %'

Now typing aSpace expands the abbreviation and then replaces the line's first line cursor marker (% by default) with the cursor:

my command --flag=Cursor --another-flag %

From here, typing xyzSpace places the cursor again:

my command --flag=xyz --another-flag Cursor

Advanced usage

• The "markers" don't have to be %. Customize the with ABBR_EXPANSION_CURSOR_MARKER and/or ABBR_LINE_CURSOR_MARKER. Learn more at Configuration variables.

  TIP

  Consider changing the markers to something you'll never use in a command. For example an unusual Unicode character, or a long string like %ABBR_CURSOR_MARKER%.

• The trigger doesn't have to be Space. Learn more at Widgets and key bindings.

• The expansion cursor placement and line cursor placement systems can use distinct "markers". One (ABBR_LINE_CURSOR_MARKER) is jumped to by the abbr-expand-and-insert widget^[1] regardless of whether an abbreviation was expanded. The other (ABBR_EXPANSION_CURSOR_MARKER) is jumped to by the abbr-expand widget^[2] when an abbreviation is expanded.

  By default, both are %. Learn more at Configuration variables.

  An illustration:

  # .zshrc
  
  ABBR_SET_EXPANSION_CURSOR=1
  ABBR_SET_LINE_CURSOR=1
  ABBR_EXPANSION_CURSOR_MARKER=+
  # load zsh-abbr here

  % abbr a=b+c+d%e

  Now, typing aSpace will change the line to bCursorc+d%e. The cursor replaces the abbreviation's first expansion cursor marker because Space expanded an abbreviation.

  Typing Space a second time will change the line to bc+dCursore. The cursor doesn't replace the line's next expansion cursor marker, because no abbreviation was expanded; instead the cursor replaces the line's next line cursor marker.

---

1. In the default configuration, abbr-expand is bound to Space. ↩︎

2. abbr-expand is triggered indirectly by abbr-expand-and-insert. You can also bind it directly to a key - learn more at Widgets and key bindings ↩︎