From 6e59cbf1d7f007ceb3a4ffa397b3be6d77071d08 Mon Sep 17 00:00:00 2001
From: Jay McCarthy <jay@racket-lang.org>
Date: Sun, 24 Jul 2011 16:45:04 -0400
Subject: [PATCH] Adding documentation and tests for xml/path

---
 collects/tests/xml/test-path.rkt | 33 ++++++++++++++++++++++++++++----
 collects/xml/path.rkt            | 10 +++++-----
 collects/xml/xml.scrbl           | 32 ++++++++++++++++++++++++++++++-
 3 files changed, 65 insertions(+), 10 deletions(-)

diff --git a/collects/tests/xml/test-path.rkt b/collects/tests/xml/test-path.rkt
index 3c00624369..8bfbef4e9b 100644
--- a/collects/tests/xml/test-path.rkt
+++ b/collects/tests/xml/test-path.rkt
@@ -2,7 +2,32 @@
 (require xml/path
          tests/eli-tester)
 
-(test
- (se-path*/list '(p) '(html (body (p "Hey") (p "Bar")))) => (list "Hey" "Bar")
- (se-path* '(p) '(html (body (p "Hey")))) => "Hey"
- (se-path* '(p #:bar) '(html (body (p ([bar "Zog"]) "Hey")))) => "Zog")
\ No newline at end of file
+(define some-page
+  '(html (body (p ([class "awesome"]) "Hey") (p "Bar"))))
+(test (se-path*/list '(p) some-page) 
+      => '("Hey" "Bar")
+      (se-path* '(p) some-page)
+      => "Hey"
+      (se-path* '(p #:class) some-page)
+      => "awesome"
+      (se-path*/list '(body) some-page)
+      => '((p ((class "awesome")) "Hey") (p "Bar"))
+      
+      (se-path*/list '() '(p ((class "awesome")) "Hey"))
+      => '((p ((class "awesome")) "Hey")
+           "Hey")
+      
+      (se-path*/list '() some-page)
+      => '((html (body (p ((class "awesome")) "Hey") (p "Bar"))) 
+           (body (p ((class "awesome")) "Hey") (p "Bar"))
+           (p ((class "awesome")) "Hey")
+           "Hey"
+           (p "Bar")
+           "Bar")
+      
+      (se-path*/list '(p) '(html (body (p "Hey") (p "Bar")))) 
+      => (list "Hey" "Bar")
+      (se-path* '(p) '(html (body (p "Hey"))))
+      => "Hey"
+      (se-path* '(p #:bar) '(html (body (p ([bar "Zog"]) "Hey"))))
+      => "Zog")
\ No newline at end of file
diff --git a/collects/xml/path.rkt b/collects/xml/path.rkt
index 678d3c7dc5..641c60ed20 100644
--- a/collects/xml/path.rkt
+++ b/collects/xml/path.rkt
@@ -33,7 +33,7 @@
     [(list-rest (? symbol?) _)
      (match x
        [(list-rest (list (list (? symbol?) (? string?)) ...) rs)
-        (se-path/tag-body p rs)]
+        (append-map (curry se-path/xexpr p) rs)]
        [(? list?)
         (append-map (curry se-path/xexpr p) x)]
        [_
@@ -51,10 +51,10 @@
 (define (se-path*/list p x)
   (append (se-path/xexpr p x)
           (match x
-            [(list-rest (list (cons (? symbol?) (? string?)) ...) rs)
-             (se-path*/list p rs)]
-            [(? list?)
-             (append-map (curry se-path*/list p) x)]
+            [(list (? symbol? tag) (list (list (? symbol?) (? string?)) ...) rs ...)
+             (append-map (curry se-path*/list p) rs)]
+            [(list (? symbol? tag) rs ...)
+             (append-map (curry se-path*/list p) rs)]
             [_
              empty])))
 (define (se-path* p x)
diff --git a/collects/xml/xml.scrbl b/collects/xml/xml.scrbl
index 99faa00e5b..b4747cbe81 100644
--- a/collects/xml/xml.scrbl
+++ b/collects/xml/xml.scrbl
@@ -475,6 +475,36 @@ looks like the following, if re-formatted by:
 
 @section{Simple X-expression Path Queries}
 
+@(require (for-label xml/path))
 @defmodule[xml/path]
 
-XXX
+This library provides a simple path query library for X-expressions.
+
+@defthing[se-path? contract?]{
+ A sequence of symbols followed by an optional keyword.
+
+ The prefix of symbols specifies a path of tags from the leaves with an implicit any sequence to the root. The final, optional keyword specifies an attribute. 
+}
+
+@defproc[(se-path*/list [p se-path?] [xe xexpr?])
+         (listof any/c)]{
+ Returns a list of all values specified by the path @racket[p] in the X-expression @racket[xe].         
+}
+
+@defproc[(se-path* [p se-path?] [xe xexpr?])
+         any/c]{
+ Returns the first answer from @racket[(se-path*/list p xe)].
+}
+
+@(define path-eval (make-base-eval))
+@interaction-eval[#:eval path-eval (require xml/path)]
+@examples[
+#:eval path-eval
+       (define some-page 
+         '(html (body (p ([class "awesome"]) "Hey") (p "Bar"))))
+       (se-path*/list '(p) some-page)
+       (se-path* '(p) some-page)
+       (se-path* '(p #:class) some-page)                 
+       (se-path*/list '(body) some-page)
+       (se-path*/list '() some-page)
+]
\ No newline at end of file