add paragraphs and unparagraphs

README.md

@@ -493,6 +493,22 @@ A terminal newline character does *not* result in an extra empty string
 
 Join the list of strings with a newline character.
 
+#### paragraphs, unparagraphs
+
+Split the string by \n\n: paragraphs are sections of text separated by a blank line
+(two #\Newline characters in a row).
+
+Return a list of strings.
+
+Each paragraph has whitespace strimmed around it. As such, the
+operation `(unparagraphs (paragraphs s))` doesn't always re-create
+`s`, it creates a new string with less blank lines.
+
+Equivalent to `ppcre:split "\\n\\n" s`, plus trimming whitespace on the results.
+
+The `unparagraphs` functions joins the list of strings by a blank line.
+
+
 #### split `(separator s &key omit-nulls limit start end regex)`
 
 Split into subtrings. If

str.lisp

@@ -120,7 +120,9 @@
   #:*whitespaces*
   #:version
   #:+version+
-  #:?))
+  #:?
+  #:unparagraphs
+  #:paragraphs))
 
 (in-package :str)
 
@@ -139,6 +141,8 @@
                             #+lispworks #\no-break-space #-lispworks #\No-break_space)
   "On some implementations, linefeed and newline represent the same character (code).")
 
+(defvar *newline* #\Newline "Newline character")
+
 (defvar +version+ (asdf:component-version (asdf:find-system "str")))
 
 (defun version ()
@@ -330,6 +334,16 @@ It uses `subseq' with differences:
   "Join the list of strings with a newline character."
   (join (make-string 1 :initial-element #\Newline) strings))
 
+(defun paragraphs (string)
+  "Split the string by paragraphs. Paragraphs are separated by two new lines.
+  Return a list of strings. Each paragraph has whitespace strimmed around it."
+  (mapcar #'str:trim (ppcre:split "\\n\\n" string)))
+
+(defun unparagraphs (strings)
+  "Join the list of strings by two newlines (have them separated by a blank line)."
+  (let ((separator (concatenate 'string (list *newline* *newline*))))
+    (join separator strings)))
+
 (defun repeat (count s)
   "Make a string of S repeated COUNT times."
   (let ((result nil))

test/test-str.lisp

@@ -24,6 +24,14 @@
            #:case-functions
            #:miscellaneous))
 
+;;; Test for cl-str.
+;;;
+;;; To run the test at point when compiling it with C-c C-c, set this:
+
+#+(or)
+(setf fiveam:*run-test-when-defined* t)
+
+
 (in-package :test-str)
 
 (def-suite str
@@ -289,6 +297,23 @@
 2
 " (unlines '("1" "2" "")))))
 
+(test paragraphs
+  (let ((s "abc
+
+
+def
+")
+        ;; only one newline and no trailing newline
+        (simple-string "abc
+
+def"))
+    (is (string= "abc" (first (paragraphs s))) "default case")
+    (is (string= "def" (second (paragraphs s))) "trim other paragraphs")
+    (is (not (string= s (unparagraphs (paragraphs s)))))
+    ;; simple-string:
+    (is (string= simple-string (unparagraphs (paragraphs simple-string)))))
+  )
+
 (test prefix
   (is (string= "foo" (prefix '("foobar" "footeam"))) "default case")
   (is (string= "" (prefix '("foobar" "barfoo"))) "no common prefix")