Xah Lee, 2008-03, …, 2010-08, 2011-03-12
This page gives a list of the most useful elisp functions for text processing tasks in elisp programing. This is not a comprehensive list, but shows the most frequently used functions.
You should be familiar with basic emacs lisp, such as how to code a loop, define local variables, etc. (See Emacs Lisp Basics.) You should also have basic concept of how programing is done in the emacs lisp environment. (See: Overview to Text-Editing Programing In Emacs.)
; current cursor position ; The first char in buffer is 1 (point) ; returns the position of the beginning/end of region (region-beginning) (region-end) ; returns the position for the end of buffer ; (taking account of narrow-to-region) (point-max) (point-min)
; move cursor to position 392 (goto-char 392) ; move cursor by n chars (forward-char n) (backward-char n) ; move cursor to the first char that's not a newline or tab ; Returns the distance traveled (skip-chars-forward "\n\t") (skip-chars-backward "\n\t") ; move cursor to the location of myStr ; returns the new position (search-forward myStr) (search-backward myStr) ; move cursor to the location matched by a regex ; returns the new position (re-search-forward myRegex) (re-search-backward myRegex)
The following functions all have the Current Buffer as target.
; insert string at current cursor position (insert "hi i ♥ u.") ; insert content of another buffer (insert-buffer-substring buffer &optional start end) ; insert part of a buffer (insert-buffer-substring-no-properties buffer &optional start end) ; insert a file's content (encoding, line ending, may be changed) (insert-file-contents myPath) ; insert a file's content literally (insert-file-contents-literally filename &optional visit beg end replace)
; delete 9 chars starting at current cursor pos (delete-char 9) ; deleting text (delete-region myStartPos myEndPos) ; delete whole buffer content (erase-buffer)
Changing letter case.
(upcase obj) (upcase-word n) ; upcase the next n words (upcase-region beg end) (upcase-initials obj) (upcase-initials-region beg end) ; upcase only the first letter (capitalize obj) (capitalize-word n) ; next n words; n can be negative (capitalize-region beg end) (downcase) (downcase-word n) (downcase-region beg end)
Find and replace string in a given region.
; replace the string in a given region (replace-string from-string to-string &optional start end) ; note: there is no replace-string-regex. ; for regex, use search-forward-regexp and replace-match
A typical idiom is to use search-forward or re-search-forward, then use replace-match. Use “while” if you want to do more than one replacement. Example:
; idiom for string replacement. (goto-char (point-min)) (while (search-forward "myStr" nil t) (replace-match "myReplaceStr")) ; idiom for string replacement using regex (goto-char (point-min)) (while (search-forward-regexp "myRegexPattern" nil t) (replace-match "myRepStr"))
; the second captured string (match-string 2) ; get the position of the 2nd captured string (match-beginning 2) (match-end 2)
Another idiom is to capture a region as string, then do replacement on this string, then delete the region, insert the new string.
This is easier when you want to do replacement only inside a region, because the search-forward etc functions do not respect narrow-to-region, and its optional bound argument does not work well because the ending position changes after each replacement. Example:
; idiom for find ＆ replace in a region between pos1 and pos2 (let (myStr (pos1 …) (pos2 …)) (setq myStr (buffer-substring pos1 pos2)) (setq myStr (replace-regexp-in-string "myRegex1" "myRep1" myStr)) (setq myStr (replace-regexp-in-string "myRegex2" "myRep2" myStr)) ;; more replacements here … (delete-region pos1 pos2) (goto-char pos1) (insert myStr) )
Functions that grab text in a buffer into a string.
; get the string from buffer (setq myStr (buffer-substring myStartPos myEndPos)) (setq myStr (buffer-substring-no-properties myStartPos myEndPos)) ; grab a thing at point. The “thing” is a semantic unit. It can be a ; word, symbol, line, sentence, filename, url and others. ; grab the current word (setq myStr (thing-at-point 'word)) ; grab the current word with hyphens or underscore (setq myStr (thing-at-point 'symbol)) ; grab the current line (setq myStr (thing-at-point 'line)) ; grab the start and end positions of a word (setq myBoundaries (bounds-of-thing-at-point 'word))
(info "(elisp) Buffer Contents")
Functions that takes a string argument.
; length (length "abc") ; returns 3 ; Extract a substring (substring myStr startIndex endIndex) ; join strings (concat "some" "thing") ; check if a string matches a pattern (string-match myRegex myStr) ; get captured match (match-string 1 myStr) ; change a given string using regex. Returns changed string. (replace-regexp-in-string myRegex myReplacement myStr) ; split a string into parts, returns a list (split-string "ry_007_cardioid" "_") (string-to-number "3") ; change datatype (number-to-string 3) ; convert to string (format "0%4x" (random 65535)) ; like number-to-string but with fine control
Emacs has only very few functions that takes a string as argument. Any non-trivial string processing is done with a buffer. Use “with-temp-buffer”, then insert your string, process it, then use buffer-string to get the whole buffer content.
(info "(elisp) Strings and Characters")
Functions that acts on the buffer data type. Most buffer function assumes the current buffer if no argument is given. Some requires a argument, such as “kill-buffer”. The argument can usually be a buffer's name, or a buffer object.
; return the name of current buffer (buffer-name) ; return the full path of the file (buffer-file-name) ; switch to a given buffer (set-buffer myBuffer) ; close a given buffer (kill-buffer myBuffer) ; use a temp buffer to manipulate string (with-temp-buffer (insert mystr) ;; manipulate the string here (buffer-string) ; get result )
; open a file (returns a buffer) (find-file myPath) ; save current buffer (write to the associated file) (save-buffer) ; same as “Save As”. Close current buffer and open the new saved (write-file myPath) ; append a text block to file (append-to-file myStartPos myEndPos myPath) ; close a buffer (kill-buffer myBuffName)
(rename-file fileName newName) (copy-file oldName newName) (delete-file fileName) (copy-directory dirPath newDirPath) ; delete a whole dir. (new in emacs 23) (delete-directory dirPath t)
; get dir path (file-name-directory myFullPath) ; get filename part (file-name-nondirectory myFullPath) ; get filename's suffix (file-name-extension myFileName) ; get filename sans suffix (file-name-sans-extension myFileName) ; get relative path (file-relative-name myFilePath dirPath) ; get full path (expand-file-name myFilePath)