4bf539032265

Add a little more documentation
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Sun, 10 Feb 2019 18:09:48 -0500
parents abcdae1786b6
children 8524e8a06be6
branches/tags (none)
files README.markdown

Changes

--- a/README.markdown	Wed Nov 21 23:21:10 2018 -0500
+++ b/README.markdown	Sun Feb 10 18:09:48 2019 -0500
@@ -18,8 +18,8 @@
         `───────────'
 ```
 
-Bobbin is a simple (50 LOC) word-wrapping library for strings in Common Lisp.
-It depends only on `split-sequence`.
+Bobbin is a simple word-wrapping library for strings in Common Lisp.  It depends
+only on `split-sequence`.
 
 It aims to be simple, work nicely for the majority of cases, and degrade
 gracefully for edge cases.  It is not particularly concerned with speed — if you
@@ -46,11 +46,10 @@
 Every line in the string returned by `wrap` will contain at most `width`
 characters (not including the newline itself).
 
-Philosophy
-----------
+### Philosophy
 
 Bobbin will try to break lines at whitespace.  It will only break a word in the
-middle if there's no other choice.  It does not try to hyphenate, or parse
+middle if there's no other choice.  It does not try to hyphenate or parse
 hyphenation:
 
     (bobbin:wrap "This is a test of Bobbin's line-breaking." 10)
@@ -74,8 +73,7 @@
 
 Whitespace between words will be preserved, unless a line is broken at that
 point.  This does the right thing for those of us who put two spaces after
-a period, [as God
-intended](https://web.archive.org/web/20171125050610/http://www.heracliteanriver.com/?p=324):
+a period, [as God intended](https://web.archive.org/web/20171125050610/http://www.heracliteanriver.com/?p=324):
 
     (bobbin:wrap "there  are  two  spaces  between  these  words" 12)
     "there  are
@@ -91,8 +89,7 @@
     bar baz
     frob"
 
-Lists
------
+### Lists
 
 For convenience, you can also pass `wrap` a list of strings.  Each string is
 treated as a separate line and wrapped as described above.  The results are
@@ -108,6 +105,26 @@
      "another"
      "line")
 
+The strings in the list may contain newlines themselves — they will be split and
+the result will still be one flat list of lines.  You can use this to trick
+Bobbin into returning a list even when you're just passing it one string, by
+wrapping the input in a list:
+
+    (defparameter *foo* (format nil "foo and bar~%cat and mouse"))
+
+    (bobbin:wrap *foo* 8)
+    "foo and
+    bar
+    cat and
+    mouse"
+
+    (bobbin:wrap (list *foo*) 8)
+    ("foo and"
+     "bar"
+     "cat and"
+     "mouse")
+
+
 TODO
 ----
 
@@ -116,3 +133,4 @@
 * Handle wide characters.
 * `unwrap` function to make writing paragraphs easier.
 * Maybe reindent broken lines?
+* Add `skip-p` argument to allow raw lines.