s.el is an Emacs string manipulation library released under the GNU General Public License v3.0. It has been written by Magnar Sveen and the latest tagged release is v1.12.0. The source code is available at https://github.com/magnars/s.el. In this article, we shall explore the various string handling functions provided by the s.el library.
The s.el package is available in Milkypostman’s Emacs Lisp Package Archive (MELPA) and in the Marmalede repo. You can install the same using the following command inside GNU Emacs:
M-x package-install s
You can also copy the s.el source file to your Emacs load path to use it. If you are using Cask, then you can add the following command to your Cask file:
(depends-on “s”)
Usage
Let us explore some examples that demonstrate the functions available in the s.el library.
Whitespace functions
The s-trim function can be used to remove whitespace at the beginning or end of a string. A few examples are shown below:
(s-trim “ Hello, World”) “Hello, World” (s-trim “Hello, World “) “Hello, World” (s-trim “ Hello, World “) “Hello, World”
If you want to remove whitespace at the beginning of the string only, you can use the s-trim-left function as follows:
(s-trim-left “Emacs Lisp “) “Emacs Lisp “ (s-trim-left “ Emacs Lisp “) “Emacs Lisp “
The s-trim-right function can be used to remove whitespace at the end of a string. A couple of examples are shown below:
(s-trim-right “ Conference”) “ Conference” (s-trim-right “Conference “) “Conference”
The trailing control characters \n, \r or \r\n can be removed using the s-chomp function. Note that, if you have multiple newlines at the end of the string, only the last one entry is chopped.
(s-chomp “Excuse me\n”) “Excuse me” (s-chomp “Excuse me\r\n”) “Excuse me” (s-chomp “Excuse me\n\n”) “Excuse me “
Multiple whitespaces can be trimmed to a single whitespace using the s-collapse-whitespace function as illustrated below:
(s-collapse-whitespace “I really appreciate... “) “I really appreciate... “
You can wrap words that go beyond a size N (a number) using the s-word-wrap function. For example:
(s-word-wrap 10 “This is a very long sentence”) “This is a very long sentence”
A text can be centred using the s-center function with whitespace on either end as shown below:
(s-center 5 “God”) “ God “
If you need to add padding to the left or right, you can use the s-pad-left and s-pad-right functions respectively. A couple of examples to demonstrate the use of this function are given below:
(s-pad-left 3 “0” “42”) “042” (s-pad-right 3 “.” “45”) “45.”
Shorter string functions
Let us go through a few functions that return a shorter string from the input string. The truncate function takes a length argument, and returns the input string for the specified length. For example:
(s-truncate 6 “What do you think?”) “Wha...”
The definition of the s-truncate function from the s.el library is as follows:
(defun s-truncate (len s &optional ellipsis) “If S is longer than LEN, cut it down and add ELLIPSIS to the end. The resulting string, including ellipsis, will be LEN characters long. When not specified, ELLIPSIS defaults to ‘...’.” (declare (pure t) (side-effect-free t)) (unless ellipsis (setq ellipsis “...”)) (if (> (length s) len) (format “%s%s” (substring s 0 (- len (length ellipsis))) ellipsis) s))
You can request for the first length of the characters from the left or the right end of the string using the s-left and s-right functions, respectively. A couple of examples are given below:
(s-left 3 “Never mind”) “Nev” (s-right 4 “/etc/resolv.conf”) “conf”
The s-chop-suffix function takes a suffix argument, and removes it from the input string before returning the result. Similarly, the s-chop-prefix function accepts a prefix argument and returns the string without the prefix as shown below:
(s-chop-suffix “.js” “main.js”) “main” (s-chop-prefix “/” “/root”) “root”
Longer string functions
In this section, we shall go through functions that can create larger strings. The s-repeat functions take two arguments, a count and a character, and return a string that has count occurrences of the character. For example:
(s-repeat 6 “*”) “******”
You can concatenate multiple strings using the s-concat function as shown below:
(s-concat “pqr” “stu” “vwx” “yz”) “pqrstuvwxyz”
The s-prepend function prepends a prefix to a string, while the “s-append” function appends the suffix to the string as illustrated below:
(s-prepend “abc” “def”) “abcdef” (s-append “bar” “foo”) “foobar”
List operations
We shall now go through a few list based operations. A string that contains newlines can be split individually using the s-lines function as follows:
(s-lines “1 2 3\n4 5 6\n7 8 9”) (“1 2 3” “4 5 6” “7 8 9”)
The s-match function takes a regular expression and a string, and checks to see if the expression is present in the string. The string that is matched is returned if present, otherwise ‘nil’ is returned.
(s-match “^123” “12345”) (“123”) (s-match “^45” “12345”) nil
You can slice an input string at a character using the s-slice-at function. Few examples are shown below:
(s-slice-at “\\.” “100.45”) (“100” “.45”) (s-slice-at “\\.” “10045”) (“10045”)
You can also split a string that has a separator using the s-split function. For example:
(s-split “\\.” “192.168.1.100”) (“192” “168” “1” “100”)
The ‘s-join’ function accepts a separator and combines a list of strings provided as input. An example is shown below:
(s-join “:” ‘(“28” “24” “ff”)) “28:24:ff”
Predicate functions
The s.el library provides a number of predicate functions. Two strings can be checked if they are equal using the ‘s-equals?’ function. If there is a match, t (true) is returned, otherwise, nil is returned. A couple of examples are shown below:
(s-equals? “xyz” “XYZ”) nil (s-equals? “xyz” “xyz”) t
The source code of s-equals? from the s.el library is as follows:
(defun s-equals? (s1 s2) “Is S1 equal to S2? “This is a simple wrapper around the built-in string-equal.” (declare (pure t) (side-effect-free t)) (string-equal s1 s2))
It basically uses the built-in string-equal function to compare if two strings are equal or not. You can check if a string is empty using the s-blank? function as shown below:
(s-blank? “”) t (s-blank? nil) t (s-blank? “Beta”) nil
A non-empty string will return true t when used with the s-present? function. If the string is empty, then nil is returned.
(s-present? “”) nil (s-present? nil) nil (s-present? “Beta”) t
The s-ends-with? function checks if the input string terminates with the suffix, whereas, the s-starts-with? function ascertains if the input string begins with the prefix. A couple of examples to demonstrate the function usage are given below:
(s-ends-with? “.txt” “README.txt”) t (s-starts-with? “READ” “README.txt”) t
A needle string is given as input to the s-contains? function to check if it exists in the input string. For example:
(s-contains? “main” “src/main.js”) t
You can check if an input string has only lowercase characters using the s-lowercase? function, and the s-uppercase? function to see if it has only uppercase characters. A few examples are given below:
(s-lowercase? “/etc/resolv.conf”) t (s-lowercase? “Documents”) nil (s-uppercase? “/etc/resolv.conf”) nil (s-uppercase? “FOO”) t
The s-mixedcase? function checks to see if a string has both upper and lower case characters in it. For example:
(s-mixedcase? “Ping Pong”) t
The s-capitalized? function ascertains if the first character of the input string has a capital letter. A couple of examples are given below:
(s-capitalized? “foo bar”) nil (s-capitalized? “Foo bar”) t
You can verify that the input string has only numerals using the s-numeric? predicate function. If it contains only numbers, it returns true t. Otherwise, it returns nil. This is illustrated in the following examples:
(s-numeric? “10”) t (s-numeric? “A10”) nil
Miscellaneous functions
There are a few miscellaneous functions in the s.el library. The s-replace function takes three arguments: an old string, a new string, and an input string. It replaces the occurrence of the old string with the new string in the input string. For example:
(s-replace “main” “input” “src/main.js”) “src/input.js”
You can make all the letters in a string lowercase using the s-downcase function, and make all the letters uppercase using the s-upcase function. A couple of examples are given below:
(s-downcase “FOO”) “foo” (s-upcase “foo”) “FOO”
The s-capitalize function is used to capitalise the first letter of the input string as shown below:
(s-capitalize “pictures”) “Pictures”
You can reverse a string using the s-reverse function. For example:
(s-reverse “654321”) “123456”
Word functions
The s.el library also provides a number of functions that operate on words. The s-split-words function can break the words that are separated by hyphens, the underscore or those with camel case. For example:
(s-split-words “i-want-2-do-project.tell-me-wat-2-do”) (“i” “want” “2” “do” “project” “tell” “me” “wat” “2” “do”)
You can make an input string lower camel case using the s-lower-camel-case function, and upper camel case using the s-upper-camel-case function, respectively. A couple of examples are shown below:
(s-lower-camel-case “TheMain”) “theMain” (s-upper-camel-case “foobar”) “Foobar”
If you would like to use snake case, as in Ruby variable names, you can use the s-snake-case function. For example:
(s-snake-case “CRUD API”) “crud_api”
The source code definition of s-snake-case is given below for reference:
(defun s-snake-case (s) “Convert S to snake_case.” (declare (side-effect-free t)) (s-join “_” (mapcar ‘downcase (s-split-words s))))
It splits the words, makes them lowercase, and joins them using the “_” character.
The s-capitalized-words function can convert an input string to capitalised words as illustrated below:
(s-capitalized-words “monty python”) “Monty python”
The s-word-initials function returns the initials of each word in an input string as shown below:
(s-word-initials “Get Things Done”) “GTD”
You are encouraged to refer to the README file at https://github.com/magnars/s.el/blob/master/README.md for more examples and use cases.
