From 2e1835d9df5ca93981471fc848001dab0cb9d5a6 Mon Sep 17 00:00:00 2001
From: Noah Lavine <noah.b.lavine@gmail.com>
Date: Tue, 10 Jul 2012 21:02:15 -0400
Subject: [PATCH 4/4] Document (ice-9 string-fun)

 * doc/ref/string-fun.texi: add documentation.
 * doc/ref/Makefile.am: update Makefile.

Based on documentation contributed by Thien-Thi Nguyen.
---
 doc/ref/Makefile.am     |    1 +
 doc/ref/string-fun.texi |  139 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+), 0 deletions(-)
 create mode 100644 doc/ref/string-fun.texi

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index f86a831..5524ab6 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -71,6 +71,7 @@ guile_TEXINFOS = preface.texi			\
 		 poe.texi			\
 		 popen.texi			\
 		 runq.texi			\
+		 string-fun.texi		\
 		 session.texi			\
 		 stack-catch.texi		\
 		 threads.texi			\
diff --git a/doc/ref/string-fun.texi b/doc/ref/string-fun.texi
new file mode 100644
index 0000000..9a70738
--- /dev/null
+++ b/doc/ref/string-fun.texi
@@ -0,0 +1,139 @@
+@c string-fun.texi
+
+@c Copyright (C) 2012 Free Software Foundation, Inc.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is included in the section entitled ``GNU Free
+@c Documentation License.''
+
+@node String Utilities
+@section String Utilities
+@cindex string utilities
+@cindex strings
+
+Guile provides a convenient set of procedures that take advantage of the
+shared substring capability.  These are available by evaluating:
+
+@lisp
+(use-modules (ice-9 string-fun))
+@end lisp
+
+@c @twerpcommentary (verbatim (ice-9 string-fun))
+
+This module provides the following procedures:
+
+@verbatim
+ (split-after-char char str ret)
+ (split-before-char char str ret)
+ (split-discarding-char char str ret)
+ (split-after-char-last char str ret)
+ (split-before-char-last char str ret)
+ (split-discarding-char-last char str ret)
+ (split-before-predicate pred str ret)
+ (split-after-predicate pred str ret)
+ (split-discarding-predicate pred str ret)
+ (separate-fields-discarding-char ch str ret)
+ (separate-fields-after-char ch str ret)
+ (separate-fields-before-char ch str ret)
+ ((string-prefix-predicate pred?) prefix str)
+ (string-prefix=? prefix str)
+ (sans-surrounding-whitespace s)
+ (sans-trailing-whitespace s)
+ (sans-leading-whitespace s)
+ (sans-final-newline str)
+ (has-trailing-newline? str)
+@end verbatim
+
+@subsection Dividing Strings Into Fields
+
+The names of these functions are very regular.
+Here is a grammar of a call to one of these:
+
+@verbatim
+  <string-function-invocation>
+  := (<action>-<seperator-disposition>-<seperator-determination>
+               <seperator-param> <str> <ret>)
+
+<str>    = the string
+
+<ret>    = The continuation.  String functions generally return
+           multiple values by passing them to this procedure.
+
+<action> =    split
+            | separate-fields
+
+ "split" means to divide a string into two parts.
+ <ret> will be called with two arguments.
+
+ "separate-fields" means to divide a string into as many parts as
+ possible.  <ret> will be called with however many fields are found.
+
+<seperator-disposition> =      before
+                             | after
+                             | discarding
+
+ "before" means to leave the seperator attached to
+ the beginning of the field to its right.
+
+ "after" means to leave the seperator attached to
+ the end of the field to its left.
+
+ "discarding" means to discard seperators.
+
+ Other dispositions might be handy.  For example, "isolate"
+ could mean to treat the separator as a field unto itself.
+
+<seperator-determination> =    char
+                             | predicate
+
+ "char" means to use a particular character as field seperator.
+ "predicate" means to check each character using a particular predicate.
+
+ Other determinations might be handy.  For example, "character-set-member".
+
+<seperator-param> = A parameter that completes the meaning of the
+                    determinations.  For example, if the determination
+                    is "char", then this parameter says which character.
+                    If it is "predicate", the parameter is the predicate.
+
+For example:
+
+ (separate-fields-discarding-char #\, "foo, bar, baz, , bat" list)
+ => ("foo" " bar" " baz" " " " bat")
+
+ (split-after-char #\- 'an-example-of-split list)
+ => ("an-" "example-of-split")
+@end verbatim
+
+As an alternative to using a determination "predicate", or to trying to
+do anything complicated with these functions, consider using regular
+expressions.
+
+
+@subsection String Prefix Predicates
+
+Very simple:
+
+@lisp
+(define-public ((string-prefix-predicate pred?) prefix str)
+ (and (<= (string-length prefix) (string-length str))
+       (pred? prefix (make-shared-substring str 0 (string-length prefix)))))
+
+(define-public string-prefix=? (string-prefix-predicate string=?))
+@end lisp
+
+@subsection Strippers
+
+@verbatim
+<stripper> = sans-<removable-part>
+
+<removable-part> =     surrounding-whitespace
+                     | trailing-whitespace
+                     | leading-whitespace
+                     | final-newline
+@end verbatim
+
+@c string-fun.texi ends here
-- 
1.7.6

