emacs-control（emacs 控制）

Emacs Control Skill

Use emacsctl to interact with running Emacs.

CLI Usage

emacsctl [options]... [arguments]...

Options:
  -i, --insert                Perform insertion
  -r, --replace               Perform replacement
  -b, --buffer BUFFER         Buffer for insertion or replacement. Current buffer by default
  -s, --save                  Save the buffer after insertion or replacement
  -p, --position INSERT_POSITION
  -l, --line INSERT_LINE
  -c, --column INSERT_COLUMN
      --start-position REPLACE_START_POSITION
      --end-position REPLACE_END_POSITION
      --start-line REPLACE_START_LINE
      --end-line REPLACE_END_LINE
  -h, --help

*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.

emacsctl '(emacs-version)'
# with pipe
echo '(emacs-version)' | emacsctl 
# => "GNU Emacs XX.X.XX"

# Use HEREDOC for multi-line input or input with quote
# Note that HEREDOC has trailing newline
emacsctl <<EOF
(defun multi-line-function ()
  (message "Hello my user")
  'return-to-me)
(multi-line-function)
EOF
# => return-to-me

*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:

# Insert "Hello" at line 50, column 15 of buffer emacsctl.el
emacsctl -i -b "emacsctl.el" -l 50 -c 15 -p 100 "Hello"

# Insert your-code at point 100 of current buffer
emacsctl -i -p 100 <<EOF
<your-code>
EOF

# Insert the content of ~/gpl-3.0.txt at the current point of current buffer, and save the buffer
emacsctl -i -s ~/gpl-3.0.txt

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:

# Replace first 5 characters of buffer emacsctl.el with "XXXXX"
emacsctl -r -b "emacsctl.el" --start-position 1 --end-position 5 "XXXXX"

# Replace line 50-100 of the current buffer with your-code, and save the buffer
emacsctl -r --start-line 50 --end-line 100 -s <<EOF
<your-code>
EOF

Replacing Certain Text

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

# Replace nearest "(require 'function)" form of buffer emacsctl.el to the content of ~/function.el
emacsctl -r -b "emacsctl.el" "(require 'function)" ~/function.el

# Replace `to-be-refined` function to `refined` function in current buffer
emacsctl -r <(cat <<OLD_TEXT
(defun to-be-refined ()
  (message "replace me"))
OLD_TEXT
) <<NEW_TEXT
(defun refined ()
  (message "new message"))
NEW_TEXT

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: (emacsctl-read-buffer &key (buffer (current-buffer)) line (start-line line) (end-line line) position (start-position (or position (point-min))) (end-position (or position (point-max))) (surrounding 2) full-p)

Examples:

;; Read a region
(emacsctl-read-buffer :start-position <point-number> :end-position <point-number>)
;; Read lines
(emacsctl-read-buffer :start-line <line-number> :end-line <line-number>)
;; Get region around line
(emacsctl-read-buffer :line <line-number> :surrounding 20)
;; Retrieve FULL content of the buffer (USE WITH CAUTION)
(emacsctl-read-buffer :buffer <buffer> :full-p t)

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.