Xah Lee, 2008-03-10
This page gives a outline of the most useful elisp function related to text processing and sys admin.
The purpose of this page is as a simple reference for elisp programing for beginners. This is not a comprehensive list. It only list the most useful functions, that are related to text processing, and some sys admin ones (such as renaming files, deleting files, calling shell utilities, etc.).
; 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)
; 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 3) ; upcase the next 3 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 myStartPos myEndPos) (downcase) (downcase-word arg) (downcase-region beg end)
; replace the string in a given region (replace-string from-string to-string &optional delimited 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:
(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. Normally, you just manipulate the text in the buffer, but often, you need grab the text as a string and assign this string as a value to a variable, so that you can use this string elsewhere. Once you have a string, you can process the string using fuctions that takes a string argument.
; 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. (setq myStr (thing-at-point 'word)) ; grab the current word (setq myStr (thing-at-point 'symbol)) ; grab the current word with hyphens or underscore (setq line (thing-at-point 'line)) ; grab the current line ; grab the start and end positions of a thing (setq myBoundaries (bounds-of-thing-at-point thing))
Functions that act on a string argument.
; length (length "abc") ; returns 3 ; Extract a substring (substring myStr startIndex endIndex) ; 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" "_") ; check if a string matches a pattern (string-match myRegex myStr)
Functions that acts on the buffer datatype.
; return the name of current buffer (buffer-name) ; return the full path of current file (buffer-file-name) ; switch to the buffer named myBufferName (set-buffer myBufferName)
; open a file (in 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)
; 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)
For a simple introduction to elisp, see: Emacs Lisp Basics. For a simple introduction to programing elisp in the emacs environment, see Overview to Text-Editing Programing In Emacs.
Page created: 2008-03. © 2008 by Xah Lee.