hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Usage / Bobbin</title>
        <link rel="stylesheet" href="../_dmedia/tango.css"/>
        <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <div class="wrap">
            <header><h1><a href="..">Bobbin</a></h1></header>
                <div class="markdown">
<h1 id="usage"><a href="">Usage</a></h1><p>Bobbin's API only has a single function:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap string-or-strings width)
</pre></div>


<p>The simplest way to use Bobbin is to pass it a string:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap "hello, world!" 10)
"hello,
world!"
</pre></div>


<p>Every line in the string returned by <code>wrap</code> will contain at most <code>width</code>
characters (not including the newline itself).</p>
<h2 id="philosophy">Philosophy</h2>
<p>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
hyphenation:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap "This is a test of Bobbin's line-breaking." 10)
"This is a
test of
Bobbin's
line-break
ing."
</pre></div>


<p>Initial whitespace (e.g. indentation) will be preserved, unless even the first
word cannot be fit if it were included.  Bobbin does not try to indent any
broken lines, but this may be added in the future:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap "    foo bar baz" 10)
"    foo
bar baz"

(bobbin:wrap "    thisisjusttoolong" 10)
"thisisjust
toolong"
</pre></div>


<p>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, <a href="https://web.archive.org/web/20171125050610/http://www.heracliteanriver.com/?p=324">as God
intended</a>:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap "there  are  two  spaces  between  these  words" 12)
"there  are
two  spaces
between
these  words"
</pre></div>


<p>Existing line breaks in the text are preserved.  Bobbin will only ever <em>add</em>
line breaks, never remove them:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap (format nil "foo~%bar baz frob") 7)
"foo
bar baz
frob"
</pre></div>


<h2 id="lists">Lists</h2>
<p>For convenience, you can also pass <code>wrap</code> a list of strings.  Each string is
treated as a separate line and wrapped as described above.  The results are
returned as a (flat) list of lines, each of which will be no more than <code>width</code>
characters long:</p>
<div class="codehilite"><pre><span/>(bobbin:wrap (list "here is a line."
                   ""
                   "and here is another line")
             8)
("here is"
 "a line."
 ""
 "and here"
 "is"
 "another"
 "line")
</pre></div>


<p>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:</p>
<div class="codehilite"><pre><span/>(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")
</pre></div>


<h2 id="possible-future-features">Possible Future Features</h2>
<p>Bobbin aims to be simple, but may grow a bit more functionality in the future
(PRs welcome):</p>
<ul>
<li>Handle tab characters.</li>
<li>Handle non-printing characters.</li>
<li>Handle wide characters.</li>
<li><code>unwrap</code> function to make writing paragraphs easier.</li>
<li>Maybe reindent broken lines?</li>
<li>Add <code>skip-p</code> argument to allow raw lines.</li>
</ul>
                </div>
            <footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.</p>
<p><br/><a id="rochester-made" href="http://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
        </div>
    </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Fri, 17 May 2019 23:17:29 -0400
parents	5d59e7aad787
children	dd80d93f061a