Emacs Control Skill

Use emacsctl to interact with running Emacs.

CLI Usage

CODEBLOCK0

emacsctl needs configure for both agent and Emacs side. Check https://github.com/calsys456/emacsctl for proper setup and notice user if possible when emacsctl not found or returned connection failure

Eval

Basically, emacsctl retrieve a string of S-expressions, either from first argument or stdin, then read and eval them with progn inside Emacs, and print the return value of the last expression.

CODEBLOCK1

Be careful with interactive or blocking functions (like read-string, y-or-n-p) as they will hang.

When mistake happened, suggest user to undo or revert. only undo in yourself (e.g. emacsctl '(undo)') if nothing important or you are confident to do so.

BE CAREFUL WHEN EVAL

Insert

When -i specified, emacsctl will perform insertion with given string, file or stdin:

CODEBLOCK2

Replace

When -r specified, emacsctl can perform buffer content replacement in two style: replacing range or replacing certain text.

Replacing Range

Specify --start-position and --end-position, or --start-line and --end-line to replace a range:

CODEBLOCK3

Replacing Certain Text

Give 2 strings or files, to replace the first (old-text) to second (new-text):

CODEBLOCK4

If there's multiple occurrence of old-text, only the one nearest from current point will be replaced. For bulk replacement or regex-based replacement, write ELisp instead.

Interface

Here is some specially designed ELisp functions for agent use, start with emacsctl- and return informative Lisp plist. Call them with Eval if possible.

Point and Mark

Use (emacsctl-point-info &optional (surrounding 2)) and (emacsctl-mark-info &optional (surrounding 2)) for information and surrounding contents for point and mark.

The current point is marked out using "█" and current mark is using "▄".

Buffer

Use (emacsctl-buffer-info &optional (buffer (current-buffer))) for buffer state and metadata.

Use (emacsctl-buffer-imenu &optional (buffer (current-buffer))) for buffer overview.

Fuzzy-match normal buffers using (emacsctl-buffer-list &optional match). Use (emacsctl-hidden-buffer-list &optional match) similarly for hidden buffers.

Grep Buffer

Use (emacsctl-grep pattern &optional (buffer (current-buffer))) to grep buffer content. It will return match result and surroundings.

Use Emacs-specific regular expression. Try to construct regex with rx or regexp-* functions if there's difficult.

Read Buffer

Function:
INLINECODE29

Examples:

CODEBLOCK5

Window

Use (emacsctl-query-window) to view the window layout of current frame. Use (emacsctl-select-window <index>) to switch to a window using the index returned by query.

Kill Ring (Pasteboard)

Use (emacsctl-query-kill-ring) for a brief view of the kill-ring. Write ELisp code to search in-detail.

Environment Inquiries

To search symbol, use (emacsctl-search-symbol <pattern>); For command, use (emacsctl-search-command <pattern>); For function, use (emacsctl-search-function <pattern>); For variable, use (emacsctl-search-variable <pattern>). They will return useful informations.

Pattern will be breaked down by dashes and matched in substring. Accurate query will get better detail.

Tips

The emacs-control skill is not for replacing other tool calls. Emacs is for bodied humans but not you. Use other file-based tools for efficient work, and emacsctl only if it is really needed or user asked to.