From 23b3b2e56cb9bd165a2e7eae39bf4a807da3c57d Mon Sep 17 00:00:00 2001
From: Matthew Butterick <mb@mbtype.com>
Date: Wed, 21 Dec 2016 14:10:57 -0800
Subject: [PATCH] document br/indent

---
 beautiful-racket-lib/br/indent.rkt           |   9 +-
 beautiful-racket-lib/br/scribblings/br.scrbl | 105 ++++++++++++++++++-
 2 files changed, 108 insertions(+), 6 deletions(-)

diff --git a/beautiful-racket-lib/br/indent.rkt b/beautiful-racket-lib/br/indent.rkt
index a51a54a..f1d6de0 100644
--- a/beautiful-racket-lib/br/indent.rkt
+++ b/beautiful-racket-lib/br/indent.rkt
@@ -27,7 +27,7 @@
   (check-equal? (char t 11) #\nul))
 
 (define/contract (line text pos)
-  ((is-a?/c text%) exact-nonnegative-integer? . -> . exact-nonnegative-integer?)
+  ((is-a?/c text%) (or/c exact-nonnegative-integer? #f) . -> . exact-nonnegative-integer?)
   (send text position-line pos))
 
 (module+ test
@@ -155,10 +155,9 @@
   (check-equal? (line-indent t 3) #f))
 
 (define (count-char text c [start 0] [end (send text last-position)])
-  (for*/sum ([pos (in-range start (add1 end))])
-            (if ((char text pos) . char=? . c)
-                1
-                0)))
+  (for/sum ([pos (in-range start (add1 end))]
+            #:when ((char text pos) . char=? . c))
+           1))
 
 (module+ test
   (check-equal? (count-char t #\f) 1)
diff --git a/beautiful-racket-lib/br/scribblings/br.scrbl b/beautiful-racket-lib/br/scribblings/br.scrbl
index e948d00..b0a6079 100644
--- a/beautiful-racket-lib/br/scribblings/br.scrbl
+++ b/beautiful-racket-lib/br/scribblings/br.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/manual
-@(require (for-label racket/base racket/contract br))
+@(require (for-label racket/base racket/gui/base racket/contract br br/indent))
 
 @(require scribble/eval)
 
@@ -469,6 +469,109 @@ source-location information and properties. An alias for @racket[strip-context].
 Uses the bindings from @racket[stx-source] to replace the bindings of all parts of @racket[stx-target], while preserving source-location
 information and properties. An alias for @racket[replace-context].}
 
+@section{Indentation}
+
+@defmodule[br/indent]
+
+Helper functions for DrRacket language indenters.
+
+@defproc[(char 
+[textbox (is-a?/c text%)]
+[position (or/c exact-nonnegative-integer? #f)])
+(or/c char? #f)]{
+Get the character in @racket[textbox] that lives at @racket[position].
+
+@;{
+can't get this example to work without racket/gui/base instantiation error
+@examples[#:eval my-eval
+(define tb (new text%))
+(send tb insert "foobar")
+(char tb 4)
+]
+}
+
+}
+
+
+@defproc[(line 
+[textbox (is-a?/c text%)]
+[position (or/c exact-nonnegative-integer? #f)])
+exact-nonnegative-integer?]{
+Get the line index in @racket[textbox] that contains @racket[position].
+}
+
+@defproc[(prev-line 
+[textbox (is-a?/c text%)]
+[position (or/c exact-nonnegative-integer? #f)])
+exact-nonnegative-integer?]{
+Get the line index in @racket[textbox] of the line before the one that contains @racket[position].
+}
+
+@defproc[(next-line 
+[textbox (is-a?/c text%)]
+[position (or/c exact-nonnegative-integer? #f)])
+exact-nonnegative-integer?]{
+Get the line index in @racket[textbox] of the line after the one that contains @racket[position].
+}
+
+@defproc[(line-chars 
+[textbox (is-a?/c text%)]
+[line-idx (or/c exact-nonnegative-integer? #f)])
+(or/c (listof char?) #f)]{
+Get the chars in @racket[textbox] on line @racket[line-idx].
+}
+
+@defproc[(line-start 
+[textbox (is-a?/c text%)]
+[line-idx (or/c exact-nonnegative-integer? #f)])
+(or/c exact-nonnegative-integer? #f)]{
+Get the starting character position in @racket[textbox] of line @racket[line-idx] (or @racket[#f] if there is no such line).
+}
+
+
+
+@defproc[(line-end
+[textbox (is-a?/c text%)]
+[line-idx (or/c exact-nonnegative-integer? #f)])
+(or/c exact-nonnegative-integer? #f)]{
+Get the ending character position in @racket[textbox] of line @racket[line-idx] (or @racket[#f] if there is no such line).
+}
+
+@deftogether[(
+@defproc[(line-start-visible 
+[textbox (is-a?/c text%)]
+[line-idx (or/c exact-nonnegative-integer? #f)])
+(or/c exact-nonnegative-integer? #f)]
+@defproc[(line-end-visible 
+[textbox (is-a?/c text%)]
+[line-idx (or/c exact-nonnegative-integer? #f)])
+(or/c exact-nonnegative-integer? #f)]
+)]{
+Like @racket[line-start] and @racket[line-end], but skips whitespace characters.
+}
+
+@defproc[(line-indent
+[textbox (is-a?/c text%)]
+[line-idx (or/c exact-nonnegative-integer? #f)])
+(or/c exact-nonnegative-integer? #f)]{
+Get the length of the indent of line @racket[line-idx] in @racket[textbox] (or @racket[#f] the line has no indent).
+}
+
+
+@defproc[(apply-indenter
+[indenter-proc procedure?]
+[textbox-or-str (or/c (is-a?/c text%) string?)])
+string?]{
+Apply @racket[indenter-proc] to the text in @racket[textbox-or-str] and return an indented string. Useful for unit testing.
+}
+
+
+@defproc[(string-indents
+[str string?])
+(listof (or/c exact-positive-integer? #f))]{
+Lists the indents at the beginning of each line in @racket[str]. Useful for unit testing.
+}
+
 
 @section{Other helpers}