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.
