Better docs for sequences.deep

diff --git a/basis/sequences/deep/deep-docs.factor b/basis/sequences/deep/deep-docs.factor
index 3dc560f46d9201b7300a5b3c24636bae6dcf54bd..f067e6ecdda39183a5b06b0af8a54a8306a6981a 100644 (file)
--- a/basis/sequences/deep/deep-docs.factor
+++ b/basis/sequences/deep/deep-docs.factor
@@ -1,30 +1,49 @@
-USING: help.syntax help.markup ;
+USING: help.syntax help.markup kernel sequences ;
 IN: sequences.deep
 
 HELP: deep-each
-{ $values { "obj" "an object" } { "quot" "a quotation ( elt -- ) " } }
-{ $description "Execute a quotation on each nested element of an object and its children, in preorder." } ;
+{ $values { "obj" object } { "quot" { $quotation "( elt -- )" } } }
+{ $description "Execute a quotation on each nested element of an object and its children, in preorder." }
+{ $see-also each } ;
 
 HELP: deep-map
-{ $values { "obj" "an object" } { "quot" "a quotation ( elt -- newelt )" } { "newobj" "the mapped object" } }
-{ $description "Execute a quotation on each nested element of an object and its children, in preorder. That is, the result of the execution of the quotation on the outer is used to map the inner elements." } ;
+{ $values { "obj" object } { "quot" { $quotation "( elt -- newelt )" } } { "newobj" "the mapped object" } }
+{ $description "Execute a quotation on each nested element of an object and its children, in preorder. That is, the result of the execution of the quotation on the outer is used to map the inner elements." }
+{ $see-also map }  ;
 
 HELP: deep-filter
-{ $values { "obj" "an object" } { "quot" "a quotation ( elt -- ? )" } { "seq" "a sequence" } }
-{ $description "Creates a sequence of sub-nodes in the object which satisfy the given quotation, in preorder. This includes the object itself, if it passes the quotation." } ;
+{ $values { "obj" object } { "quot" { $quotation "( elt -- ? )" } } { "seq" "a sequence" } }
+{ $description "Creates a sequence of sub-nodes in the object which satisfy the given quotation, in preorder. This includes the object itself, if it passes the quotation." }
+{ $see-also filter }  ;
 
 HELP: deep-find
-{ $values { "obj" "an object" } { "quot" "a quotation ( elt -- ? )" } { "elt" "an element" } }
-{ $description "Gets the first sub-node of the object, in preorder, which satisfies the quotation. If nothing satisifies it, it returns " { $link f } "." } ;
+{ $values { "obj" object } { "quot" { $quotation "( elt -- ? )" } } { "elt" "an element" } }
+{ $description "Gets the first sub-node of the object, in preorder, which satisfies the quotation. If nothing satisifies it, it returns " { $link f } "." }
+{ $see-also find }  ;
 
 HELP: deep-contains?
-{ $values { "obj" "an object" } { "quot" "a quotation ( elt -- ? )" } { "?" "a boolean" } }
-{ $description "Tests whether the given object or any subnode satisfies the given quotation." } ;
+{ $values { "obj" object } { "quot" { $quotation "( elt -- ? )" } } { "?" "a boolean" } }
+{ $description "Tests whether the given object or any subnode satisfies the given quotation." }
+{ $see-also contains? } ;
 
 HELP: flatten
-{ $values { "obj" "an object" } { "seq" "a sequence" } }
+{ $values { "obj" object } { "seq" "a sequence" } }
 { $description "Creates a sequence of all of the leaf nodes (non-sequence nodes, but including strings and numbers) in the object." } ;
 
 HELP: deep-change-each
-{ $values { "obj" "an object" } { "quot" "a quotation ( elt -- newelt )" } }
-{ $description "Modifies each sub-node of an object in place, in preorder." } ;
+{ $values { "obj" object } { "quot" { $quotation "( elt -- newelt )" } } }
+{ $description "Modifies each sub-node of an object in place, in preorder." }
+{ $see-also change-each } ;
+
+ARTICLE: "sequences.deep" "Deep sequence combinators"
+"The combinators in the " { $vocab-link "sequences.deep" } " vocabulary are variants of standard sequence combinators which traverse nested subsequences."
+{ $subsection deep-each }
+{ $subsection deep-map }
+{ $subsection deep-filter }
+{ $subsection deep-find }
+{ $subsection deep-contains? }
+{ $subsection deep-change-each }
+"A utility word to collapse nested subsequences:"
+{ $subsection flatten } ;
+
+ABOUT: "sequences.deep"

diff --git a/basis/sequences/deep/deep.factor b/basis/sequences/deep/deep.factor
index 2e50fa5411a7262999c6f554c4523586cdbdcfbe..db572681a16c72f56d9721fbf3dc06aa5bf7a4c3 100644 (file)
--- a/basis/sequences/deep/deep.factor
+++ b/basis/sequences/deep/deep.factor
@@ -21,28 +21,27 @@ M: object branch? drop f ;
     [ [ deep-map ] curry map ] [ drop ] if ; inline recursive
 
 : deep-filter ( obj quot: ( elt -- ? ) -- seq )
-    over >r
-    pusher >r deep-each r>
-    r> dup branch? [ like ] [ drop ] if ; inline recursive
+    over [ pusher [ deep-each ] dip ] dip
+    dup branch? [ like ] [ drop ] if ; inline recursive
 
-: deep-find-from ( obj quot: ( elt -- ? ) -- elt ? )
+: (deep-find) ( obj quot: ( elt -- ? ) -- elt ? )
     [ call ] 2keep rot [ drop t ] [
         over branch? [
-            f -rot [ >r nip r> deep-find-from ] curry find drop >boolean
+            f -rot [ [ nip ] dip (deep-find) ] curry find drop >boolean
         ] [ 2drop f f ] if  
     ] if ; inline recursive
 
-: deep-find ( obj quot -- elt ) deep-find-from drop ; inline
+: deep-find ( obj quot -- elt ) (deep-find) drop ; inline
 
-: deep-contains? ( obj quot -- ? ) deep-find-from nip ; inline
+: deep-contains? ( obj quot -- ? ) (deep-find) nip ; inline
 
 : deep-all? ( obj quot -- ? )
     [ not ] compose deep-contains? not ; inline
 
 : deep-change-each ( obj quot: ( elt -- elt' ) -- )
-    over branch? [ [
-        [ call ] keep over >r deep-change-each r>
-    ] curry change-each ] [ 2drop ] if ; inline recursive
+    over branch? [
+        [ [ call ] keep over [ deep-change-each ] dip ] curry change-each
+    ] [ 2drop ] if ; inline recursive
 
 : flatten ( obj -- seq )
     [ branch? not ] deep-filter ;