The cl-strings Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-strings Reference Manual

This is the cl-strings Reference Manual, version 0.0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:34:29 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-strings

cl-strings is a small, portable, dependency-free set of utilities that make it even easier to manipulate text in Common Lisp.
It has 100% test coverage and works at least on sbcl, ecl, ccl, abcl and clisp.

How do i use it?

This section assumes you use quicklisp. If you don't, you should! Download and learn about it here.

Once you have quicklisp loaded, simply do:

(ql:quickload :cl-strings)

And it's all up and running. To run the tests do:

(ql:quickload :cl-strings-tests)

Please report if any tests fail in your Common Lisp implementation.

Example

> (ql:quickload :cl-strings)
(:CL-STRINGS)  

> (use-package :cl-strings)
T  

> (defparameter *num* (parse-number "-3.1e3"))
*NUM* ;; -3100.0  

> (format-number *num* :precision 3 :decimal-separator "." :order-separator ",")
"-3,100.000"

API

(parse-number number-str &key (decimal-separator #\.) (order-separator nil))

parse-number returns a number from a string, without using the reader (CL has parse-integer but no equivalent for other number types). It accepts integers, floats, fractional and scientific notations. It also accepts both chars and one character strings for the separators. This method may signal parse-error.

(parse-number "-3.1e2") ;; -310.0
(parse-number "1 234,9" :decimal-separator "," :order-separator " ") ;; 1234.9

(format-number number &key (precision 0) (decimal-separator ".") (order-separator ",")

format-number returns a string from a number. It's possible to set the precision (decimals), and the separators as chars or strings of length one.

(format-number 1234.326 :precision 2 :decimal-separator "," :order-separator " ") ;; "1 234,33"

(make-template-parser start-delimiter end-delimiter &key (ignore-case nil))

make-template-parser returns a function (a closure actually) that can substitute known variables for their values. start-delimiter and end-delimiter define the template tags. ignore-case defaults to nil and can be set to change the way the returned function tests variable names. The argument list of the returned lambda is (string values) where string is the template and values is an association list. It is easier by example:

(defvar *my-parser* (make-template-parser "{{" "}}")) ;; closure
(funcall *my-parser* "Hello {{name}}!" '(("name" . "Sam"))) ;; "Hello Sam!"

(starts-with string prefix &key (ignore-case nil))

starts-with checks if string starts with prefix. The key argument ignore-case defaults to nil.

(starts-with "fOo bar" "foo" :ignore-case t) ;; t

(ends-with string suffix &key (ignore-case nil))

ends-with checks if string ends with suffix. The key argument ignore-case defaults to nil.

(ends-with "fOo bar" "bAr" :ignore-case t) ;; t

(clean-diacritics string)

clean-diacritics returns a string with the diacritical characters replaced by their closest counterparts.

(clean-diacritics "Déjà vu") ;; "Deja vu"

(shorten string len &key (truncate-string "..."))

shorten returns a string consisting of string cut off to length len, and then truncate-string (which defaults to "..." but can be nil or "") appended to it.

(shorten "and then the guy bit the dog!" 8) ;; "and then..."

(replace-all string part replacement &key (ignore-case nil))

replace-all returns a string with every instance of part replaced by replacement in string. ignore-case defaults to nil.

(replace-all "Fo3sale: baby shoes, neve3worn" "3" "r ")
;; "For sale: baby shoes, never worn"

(join lst &key (separator ""))

join receives a list of strings and concatenates them. They can be delimited by separator.

(join (list "Woot" "woot" "woot!") :separator ", ") ;; "Woot, woot, woot!"

(split string &optional separator &key (ignore-case nil))

split returns a list made up of string parts, delimited by separator. separator can be a char or any string. It defaults to a space.
Note: Two consecutive separators will be seen as if there was an empty string between them.

(split "this, is, crazy" ", ") ; ("this" "is" "crazy")

(insert string original &key (position nil))

insert returns a original with string inserted at position. If position is not provided, the insertion is performed at the end of original, meaning it is the same as setting position to the length of original

(insert "each day holds " "The infinite possibilities should stagger the mind" :position 27)
;; "The infinite possibilities each day holds should stagger the mind"

(repeat string count &key (separator ""))

repeat returns a string consisting of joining string with itself count number of times, with separator in between

(repeat "clap" 3 :separator " ") ;; "clap clap clap"

(chars string)

chars returns a list with all the characters in a given string

(chars "foo bar") ;; (#\f #\o #\o #\  #\b #\a #\r)

(chop string step)

chop returns a list of parts of string, with step elements in each. If step is less than 1, no chop is performed.

(chop "take wrong turns" 5) ;; ("take " "wrong" " turn" "s")

(toggle-case string)

toggle-case returns a string with each character being the opposite case of the original ones.

(toggle-case "oPEN uNMARKED dOORS") ;; "Open Unmarked Doors"

(clean string &key (char #\space))

clean removes char from the left and right sides of string, and replaces consecutive sequences of char by a single one.

(clean "  foo   bar ") ;; "foo bar"

(camel-case string &key (delimiter #\space))

camel-case leaves the case of the first character of string as is. The rest of the words are concatenated and the first letter of each is upcased. Word separation defaults to a space but can be customized by delimiter.

(camel-case "hello worLD") ;; "helloWorld"

(kebab-case string &key (delimiter #\space))

kebab-case downcases string and joins every word by an hyphen. Word separation defaults to space but can be customized by delimiter.

(kebab-case "hello worLD") ;; "hello-world"

(snake-case string &key (delimiter #\space))

snake-case leaves the case of the first character of string as is. The rest of the words are lowercased and joined by an underscore. Word separation defaults to space but can be customized by delimiter.

(snake-case "hello worLD") ;; "hello_world"

(title-case string &key (remove-hyphens t))

title-case upcases the first letter of every word in string, and downcases the rest. Word separation removes hyphens by default, but remove-hyphens can be set to nil to change this behaviour.

(title-case "hello-worLD") ;; "Hello World"

Contributing

If you have any suggestions, bug reports, etc, please fill in an issue describing it. If you have the time and want to contribute, that is even better! Submit some tests too, let's try and keep coverage at 100%.

Here is what I'm thinking might make sense to implement next:

License

MI


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-strings

Author

Diogo Franco

License

MIT

Description

A set of utilities for manipulating strings in CL.

Version

0.0.1

Source

cl-strings.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-strings.asd

Location

cl-strings.asd

Systems

cl-strings (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-strings/package.lisp

Parent

cl-strings (system)

Location

package.lisp

Packages

cl-strings


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-strings/cl-strings.lisp

Dependency

package.lisp (file)

Parent

cl-strings (system)

Location

cl-strings.lisp

Exported Definitions
Internal Definitions

*blank-chars* (special variable)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-strings

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

*blank-chars* (special variable)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: camel-case STRING &key DELIMITER

Returns a string which concatenates every word separated by a space (or a specified delimiter), and upcases every first letter except for the first word of the string.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: chars STRING

Returns a list with the chars in "string"

Package

cl-strings

Source

cl-strings.lisp (file)

Function: chop STRING STEP

Returns a list with parts of "string", each with length "step", except for the last one which might have a length small than "step".

Package

cl-strings

Source

cl-strings.lisp (file)

Function: clean STRING &key CHAR

Returns a trimmed string with multiple spaces replaced by one

Package

cl-strings

Source

cl-strings.lisp (file)

Function: clean-diacritics STRING

Returns a string with the diacritics replaced by their closest ASCII equivalents

Package

cl-strings

Source

cl-strings.lisp (file)

Function: ends-with STRING SUFFIX &key IGNORE-CASE

Returns true if "string"’s last characters are equal to "suffix".

Package

cl-strings

Source

cl-strings.lisp (file)

Function: format-number NUMBER &key PRECISION DECIMAL-SEPARATOR ORDER-SEPARATOR

Converts a number to a string, with "precision" number of digits.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: insert STRING ORIGINAL &key POSITION

Returns a string consisting of "original" with "string" inserted at "position".

Package

cl-strings

Source

cl-strings.lisp (file)

Function: join LST &key SEPARATOR

Joins a list of strings (or other objects) in a string, delimited by "separator"

Package

cl-strings

Source

cl-strings.lisp (file)

Function: kebab-case STRING &key DELIMITER

Returns a string with every space (or a specified char) replaced by an hyphen, and every character lower cased.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: make-template-parser START-DELIMITER END-DELIMITER &key IGNORE-CASE

Returns a closure than can substitute variables delimited by "start-delimiter" and "end-delimiter" in a string, by the provided values.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: parse-number NUMBER-STR &key DECIMAL-SEPARATOR ORDER-SEPARATOR

Parses number-str without using the reader, returning the equivalent number

Package

cl-strings

Source

cl-strings.lisp (file)

Function: repeat STRING COUNT &key SEPARATOR

Repeats a given string "count" number of times

Package

cl-strings

Source

cl-strings.lisp (file)

Function: replace-all STRING PART REPLACEMENT &key IGNORE-CASE

Returns a new string in which all the occurences of "part" in "string" are replaced with replacement.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: shorten STRING LEN &key TRUNCATE-STRING

If "string"’s length is bigger than "length", cut the last characters out. Also replaces the last characters of the shortened string for the omission string. It defaults to "...", but can be nil or the empty string.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: snake-case STRING &key DELIMITER

Returns a string with every space (or a specified delimiter) replaced by an underscore, and downcased, except for the first letter.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: split STRING &optional SEPARATOR &key IGNORE-CASE

Returns a list of substrings of string
divided by separator. Separator can be a string or a character.
Note: Two consecutive separators will be seen as if there were an empty string between them.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: starts-with STRING PREFIX &key IGNORE-CASE

Returns true if "string"’s first characters are equal to "prefix".

Package

cl-strings

Source

cl-strings.lisp (file)

Function: title-case STRING &key REMOVE-HYPHENS

Returns a string with the first letter of every word upcased, and the other ones downcased.

Package

cl-strings

Source

cl-strings.lisp (file)

Function: toggle-case STRING

Changes the case of each character in "string"

Package

cl-strings

Source

cl-strings.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *blank-chars*
Package

cl-strings

Source

cl-strings.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-strings.asd: The cl-strings<dot>asd file
cl-strings/cl-strings.lisp: The cl-strings/cl-strings<dot>lisp file
cl-strings/package.lisp: The cl-strings/package<dot>lisp file

F
File, Lisp, cl-strings.asd: The cl-strings<dot>asd file
File, Lisp, cl-strings/cl-strings.lisp: The cl-strings/cl-strings<dot>lisp file
File, Lisp, cl-strings/package.lisp: The cl-strings/package<dot>lisp file

L
Lisp File, cl-strings.asd: The cl-strings<dot>asd file
Lisp File, cl-strings/cl-strings.lisp: The cl-strings/cl-strings<dot>lisp file
Lisp File, cl-strings/package.lisp: The cl-strings/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   E   F   I   J   K   M   P   R   S   T  
Index Entry  Section

C
camel-case: Exported functions
chars: Exported functions
chop: Exported functions
clean: Exported functions
clean-diacritics: Exported functions

E
ends-with: Exported functions

F
format-number: Exported functions
Function, camel-case: Exported functions
Function, chars: Exported functions
Function, chop: Exported functions
Function, clean: Exported functions
Function, clean-diacritics: Exported functions
Function, ends-with: Exported functions
Function, format-number: Exported functions
Function, insert: Exported functions
Function, join: Exported functions
Function, kebab-case: Exported functions
Function, make-template-parser: Exported functions
Function, parse-number: Exported functions
Function, repeat: Exported functions
Function, replace-all: Exported functions
Function, shorten: Exported functions
Function, snake-case: Exported functions
Function, split: Exported functions
Function, starts-with: Exported functions
Function, title-case: Exported functions
Function, toggle-case: Exported functions

I
insert: Exported functions

J
join: Exported functions

K
kebab-case: Exported functions

M
make-template-parser: Exported functions

P
parse-number: Exported functions

R
repeat: Exported functions
replace-all: Exported functions

S
shorten: Exported functions
snake-case: Exported functions
split: Exported functions
starts-with: Exported functions

T
title-case: Exported functions
toggle-case: Exported functions

Jump to:   C   E   F   I   J   K   M   P   R   S   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*blank-chars*: Internal special variables

S
Special Variable, *blank-chars*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-strings: The cl-strings system
cl-strings: The cl-strings package

P
Package, cl-strings: The cl-strings package

S
System, cl-strings: The cl-strings system

Jump to:   C   P   S