emacs-control

# 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. ```bash 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`: ```bash # 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: ```bash # 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): ```bash # 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: ```elisp ;; 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.**