better docs; complete WrapWords interface
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..cf4c198
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,3 @@
+// Package text provides rudimentary functions for manipulating text in
+// paragraphs.
+package text
diff --git a/indent.go b/indent.go
index da7112d..39196f7 100644
--- a/indent.go
+++ b/indent.go
@@ -1,6 +1,7 @@
package text
-// Indent calls IndentBytes and returns the result.
+// Indent inserts prefix at the beginning of each non-empty line of s. The
+// end-of-line marker is NL.
func Indent(s, prefix string) string {
return string(IndentBytes([]byte(s), []byte(prefix)))
}
diff --git a/wrap.go b/wrap.go
index a98375f..ca88565 100755
--- a/wrap.go
+++ b/wrap.go
@@ -10,31 +10,37 @@
sp = []byte{' '}
)
-// Wrap calls WrapBytes and returns the result.
+const defaultPenalty = 1e5
+
+// Wrap wraps s into a paragraph of lines of length lim, with minimal
+// raggedness.
func Wrap(s string, lim int) string {
return string(WrapBytes([]byte(s), lim))
}
-// WrapBytes splits b on spaces, calls WrapWords, then joins the resulting
-// lines with NL. Adjacent spaces are treated as surrounding words of zero
-// length.
+// WrapBytes wraps b into a paragraph of lines of length lim, with minimal
+// raggedness.
func WrapBytes(b []byte, lim int) []byte {
words := bytes.Split(bytes.Replace(bytes.TrimSpace(b), nl, sp, -1), sp)
var lines [][]byte
- for _, line := range WrapWords(words, lim) {
+ for _, line := range WrapWords(words, 1, lim, defaultPenalty) {
lines = append(lines, bytes.Join(line, sp))
}
return bytes.Join(lines, nl)
}
+// WrapWords is the low-level line-breaking algorithm, useful if you need more
+// control over the details of the text wrapping process. For most uses, either
+// Wrap or WrapBytes will be sufficient and more convenient.
+//
// WrapWords splits a list of words into lines with minimal "raggedness",
-// treating each byte as one unit, accounting for one unit between adjacent
+// treating each byte as one unit, accounting for spc units between adjacent
// words on each line, and attempting to limit lines to lim units. Raggedness
// is the total error over all lines, where error is the square of the
// difference of the length of the line and lim. Too-long lines (which only
-// happen when a single word is longer than lim units) get an extra penalty
+// happen when a single word is longer than lim units) have pen penalty units
// added to the error.
-func WrapWords(words [][]byte, lim int) [][][]byte {
+func WrapWords(words [][]byte, spc, lim, pen int) [][][]byte {
n := len(words)
length := make([][]int, n)
@@ -42,7 +48,7 @@
length[i] = make([]int, n)
length[i][i] = len(words[i])
for j := i + 1; j < n; j++ {
- length[i][j] = length[i][j-1] + 1 + len(words[j])
+ length[i][j] = length[i][j-1] + spc + len(words[j])
}
}
@@ -60,7 +66,7 @@
d := lim - length[i][j-1]
c := d*d + cost[j]
if length[i][j-1] > lim {
- c += 1e5 // too-long lines get a worse penalty
+ c += pen // too-long lines get a worse penalty
}
if c < cost[i] {
cost[i] = c
diff --git a/wrap_test.go b/wrap_test.go
index 0adbcb4..ba92705 100644
--- a/wrap_test.go
+++ b/wrap_test.go
@@ -13,7 +13,7 @@
{[]byte("jumps"), []byte("over"), []byte("the"), []byte("lazy"), []byte("dog.")},
}
words := bytes.Split([]byte(text), sp)
- got := WrapWords(words, 24)
+ got := WrapWords(words, 1, 24, defaultPenalty)
if len(exp) != len(got) {
t.Fail()
}
