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