The bobbin Reference Manual

Table of Contents

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

The bobbin Reference Manual

This is the bobbin Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 12:59:53 2019 GMT+0.


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

1 Introduction

Bobbin

       .─────────────.
   _.─'      ( )      `──.
 ,'    ( )         ( )    `.
;          -------          :
:  ( )    |.......|    ( )  ;
 ╲         -------         ╱
  `.   ( )         ( )   ,'
 ,' `──.     ( )     _.─' `.
;       `───────────'       :
:  ( )    |       |    ( )  ;
 ╲         \_____/         ╱
  `.   ( )         ( )   ,'
    `──.     ( )     _.─'
        `───────────'

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 need very high-performance word wrapping Bobbin is not for you.

Documentation

Bobbin's API only has a single function:

(bobbin:wrap string-or-strings width)

The simplest way to use Bobbin is to pass it a string:

(bobbin:wrap "hello, world!" 10)
"hello,
world!"

Every line in the string returned by wrap will contain at most width characters (not including the newline itself).

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 hyphenation:

(bobbin:wrap "This is a test of Bobbin's line-breaking." 10)
"This is a
test of
Bobbin's
line-break
ing."

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:

(bobbin:wrap "    foo bar baz" 10)
"    foo
bar baz"

(bobbin:wrap "    thisisjusttoolong" 10)
"thisisjust
toolong"

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:

(bobbin:wrap "there  are  two  spaces  between  these  words" 12)
"there  are
two  spaces
between
these  words"

Existing line breaks in the text are preserved. Bobbin will only ever add line breaks, never remove them:

(bobbin:wrap (format nil "foo~%bar baz frob") 7)
"foo
bar baz
frob"

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 returned as a (flat) list of lines, each of which will be no more than width characters long:

(bobbin:wrap '("here is a line." "" "and here is another line") 8)
("here is"
 "a line."
 ""
 "and here"
 "is"
 "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


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 bobbin

Author

Steve Losh <steve@stevelosh.com>

Home Page

https://sjl.bitbucket.io/bobbin/

License

MIT

Description

Simple (word) wrapping utilities for strings.

Version

1.0.0

Dependency

split-sequence

Source

bobbin.asd (file)

Components

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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 bobbin/src

Dependency

package.lisp (file)

Parent

bobbin (system)

Location

src/

Component

main.lisp (file)


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

4 Files

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


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

4.1 Lisp


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

4.1.1 bobbin.asd

Location

bobbin.asd

Systems

bobbin (system)


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

4.1.2 bobbin/package.lisp

Parent

bobbin (system)

Location

package.lisp

Packages

bobbin


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

4.1.3 bobbin/src/main.lisp

Parent

src (module)

Location

src/main.lisp

Exported Definitions

wrap (function)

Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 bobbin

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

wrap (function)

Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Functions

Function: wrap STRING-OR-STRINGS WIDTH

Wrap ‘string-or-strings‘ to ‘width‘.

‘string-or-strings‘ can be a string or a list of strings. A list of strings is treated as multiple lines. In either case the string(s) may also contain newlines. All of these linebreaks will be included in the output — wrapping will only add linebreaks, never remove them.

The result with be of the same type as the argument: either a single string (containing newlines) or a list of strings (not containing newlines).

Examples:

(print (wrap (format nil "foo bar baz") 3))
foo
bar
baz

(print (wrap (format nil "foo bar baz") 7))
foo bar
baz

(print (wrap (format nil "foo~%bar baz") 7))
foo
bar baz

(print (wrap ’("foo" "bar baz") 7))
("foo" "bar baz")

(print (wrap ’("foo" "bar baz") 3))
("foo" "bar" "baz")

Package

bobbin

Source

main.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Functions

Function: wrap-line LINE WIDTH

Wrap the single-line string ‘line‘ to ‘width‘, returning a multi-line string.

Package

bobbin

Source

main.lisp (file)

Function: wrap-lines STRINGS WIDTH

Wrap a list of ‘strings‘ to ‘width‘, returning a list of strings.

Package

bobbin

Source

main.lisp (file)

Function: wrap-string STRING WIDTH

Wrap a multi-line string, returning a multi-line string.

Package

bobbin

Source

main.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   B   F   L   M  
Index Entry  Section

B
bobbin.asd: The bobbin<dot>asd file
bobbin/package.lisp: The bobbin/package<dot>lisp file
bobbin/src: The bobbin/src module
bobbin/src/main.lisp: The bobbin/src/main<dot>lisp file

F
File, Lisp, bobbin.asd: The bobbin<dot>asd file
File, Lisp, bobbin/package.lisp: The bobbin/package<dot>lisp file
File, Lisp, bobbin/src/main.lisp: The bobbin/src/main<dot>lisp file

L
Lisp File, bobbin.asd: The bobbin<dot>asd file
Lisp File, bobbin/package.lisp: The bobbin/package<dot>lisp file
Lisp File, bobbin/src/main.lisp: The bobbin/src/main<dot>lisp file

M
Module, bobbin/src: The bobbin/src module

Jump to:   B   F   L   M  

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

A.2 Functions

Jump to:   F   W  
Index Entry  Section

F
Function, wrap: Exported functions
Function, wrap-line: Internal functions
Function, wrap-lines: Internal functions
Function, wrap-string: Internal functions

W
wrap: Exported functions
wrap-line: Internal functions
wrap-lines: Internal functions
wrap-string: Internal functions

Jump to:   F   W  

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

A.3 Variables


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

A.4 Data types

Jump to:   B   P   S  
Index Entry  Section

B
bobbin: The bobbin system
bobbin: The bobbin package

P
Package, bobbin: The bobbin package

S
System, bobbin: The bobbin system

Jump to:   B   P   S