Implement and document stream-peek

[factor.git] / core / io / io-docs.factor

diff --git a/core/io/io-docs.factor b/core/io/io-docs.factor
index 11848cfa0369fbd1792dae53b661ee9a70c68701..408346d83c464a0b2372fa2f9f8683eabaa08744 100644 (file)
--- a/core/io/io-docs.factor
+++ b/core/io/io-docs.factor
@@ -262,6 +262,61 @@ HELP: contents
 { $description "Reads all elements in the " { $link input-stream } " until the stream is exhausted. The type of the sequence depends on the stream's element type." }
 $io-error ;
 
+HELP: peek
+{ $values
+    { "n" integer }
+    { "seq/f" "a sequence or f" }
+}
+{ $description "Reads the next " { $snippet "n" } " elements from the stream and seeks the stream to before the read." } ;
+
+HELP: peek1
+{ $values
+        { "elt" "an element or f" }
+}
+{ $description "Reads the next object from a stream and seeks the stream to before the read." } ;
+
+HELP: stream-peek
+{ $values
+    { "n" integer } { "stream" "an input stream" }
+    { "seq/f" "a sequence or f" }
+}
+{ $contract "Peeks " { $snippet "n" } " elements from the stream. Outputs " { $link f } " on stream exhaustion." }
+{ $notes "Most code only works on one stream at a time and should instead use " { $link peek } "; see " { $link "stdio" } "." }
+$io-error ;
+
+HELP: stream-peek1
+{ $values
+    { "stream" "an input stream" }
+    { "elt/f" "an element or f" }
+}
+{ $contract "Peeks an element from the stream. Outputs " { $link f } " on stream exhaustion." }
+{ $notes "Most code only works on one stream at a time and should instead use " { $link peek1 } "; see " { $link "stdio" } "." }
+$io-error ;
+
+HELP: tell-input
+{ $values
+        { "n" integer }
+}
+{ $description "Returns the index of the stream stored in " { $link input-stream } "." } ;
+
+HELP: tell-output
+{ $values
+        { "n" integer }
+}
+{ $description "Returns the index of the stream stored in " { $link output-stream } "." } ;
+
+HELP: with-input-rewind
+{ $values
+    { "quot" quotation }    
+}
+{ $description "Records the current seek position of the stream and calls the quotation. The position is then reset after the call." } ;
+
+HELP: with-input-seek
+{ $values
+    { "n" integer } { "seek-type" "a seek singleton" } { "quot" quotation }    
+}
+{ $description "Seeks the stream to a location, calls " { $snippet "quot" } ", and resets the input stream to where it was before the quotation was called." } ;
+
 ARTICLE: "stream-protocol" "Stream protocol"
 "The stream protocol consists of a large number of generic words, many of which are optional."
 $nl
@@ -271,6 +326,8 @@ $nl
 { $subsections "stream-types" }
 "These words are required for binary and string input streams:"
 { $subsections
+    stream-peek1
+    stream-peek
     stream-read1
     stream-read
     stream-read-until
@@ -290,6 +347,8 @@ $nl
 { $subsections
     stream-tell
     stream-seek
+    tell-input
+    tell-output
 }
 { $see-also "io.timeouts" } ;
 
@@ -338,6 +397,8 @@ ARTICLE: "stdio" "Default input and output streams"
 $nl
 "Words reading from the default input stream:"
 { $subsections
+    peek1
+    peek
     read1
     read
     read-until
@@ -376,6 +437,11 @@ $nl
     seek-relative
     seek-end
 }
+"Seeking combinators:"
+{ $subsections
+    with-input-seek
+    with-input-rewind
+}
 "A pair of combinators for rebinding the " { $link output-stream } " variable:"
 { $subsections
     with-output-stream