rename io.files.temporary to io.files.unique

write documentation

extra/io/files/temporary/backend/backend.factor

@@ -1,5 +0,0 @@
-USING: io.backend ;
-IN: io.files.temporary.backend
-
-HOOK: (temporary-file) io-backend ( path prefix suffix -- stream path )
-HOOK: temporary-path io-backend ( -- path )

extra/io/files/temporary/temporary.factor

@@ -1,36 +0,0 @@
-USING: kernel math math.bitfields combinators.lib math.parser
-random sequences sequences.lib continuations namespaces
-io.files io.backend io.nonblocking io arrays
-io.files.temporary.backend system combinators vocabs.loader ;
-USE: tools.walker
-IN: io.files.temporary
-
-: random-letter ( -- ch )
-    26 random { CHAR: a CHAR: A } random + ;
-
-: random-ch ( -- ch )
-    { t f } random
-    [ 10 random CHAR: 0 + ] [ random-letter ] if ;
-
-: random-name ( n -- string )
-    [ drop random-ch ] "" map-as ;
-
-: <temporary-file> ( prefix suffix -- path duplex-stream )
-    temporary-path -rot
-    [ 10 random-name swap 3append path+ dup (temporary-file) ] 3curry
-    10 retry ;
-
-: with-temporary-file ( quot -- path )
-    >r f f <temporary-file> r> with-stream ;
-
-: temporary-directory ( -- path )
-    [ temporary-path 10 random-name path+ dup make-directory ] 10 retry ;
-
-: with-temporary-directory ( quot -- )
-    >r temporary-directory r>
-    [ with-directory ] 2keep drop delete-tree ;
-
-{
-    { [ unix? ] [ "io.unix.files.temporary" ] }
-    { [ windows? ] [ "io.windows.files.temporary" ] }
-} cond require

extra/io/files/unique/backend/backend.factor

@@ -0,0 +1,5 @@
+USING: io.backend ;
+IN: io.files.unique.backend
+
+HOOK: (make-unique-file) io-backend ( prefix suffix -- stream path )
+HOOK: temporary-path io-backend ( -- path )

extra/io/files/unique/unique-docs.factor

@@ -0,0 +1,50 @@
+USING: help.markup help.syntax io io.nonblocking kernel math
+io.files.unique.private math.parser io.files ;
+IN: io.files.unique
+
+ARTICLE: "unique" "Making and using unique files"
+"Files:"
+{ $subsection make-unique-file }
+{ $subsection with-unique-file }
+{ $subsection with-temporary-file }
+"Directories:"
+{ $subsection make-unique-directory }
+{ $subsection with-unique-directory }
+{ $subsection with-temporary-directory } ;
+
+ABOUT: "unique"
+
+HELP: make-unique-file ( prefix suffix -- path stream )
+{ $values { "prefix" "a string" } { "suffix" "a string" }
+{ "path" "a pathname string" } { "stream" "an output stream" } }
+{ $description "Creates a file that is guaranteed not to exist in a platform-specific temporary directory.  The file name is composed of a prefix, a number of random digits and letters, and the suffix.  Returns the full pathname and a " { $link <writer> } " stream." }
+{ $errors "Throws an error if a new unique file cannot be created after a number of tries.  Since each try generates a new random name, the most likely error is incorrect directory permissions on the temporary directory." }
+{ $see-also with-unique-file } ;
+
+HELP: make-unique-directory ( -- path )
+{ $values { "path" "a pathname string" } }
+{ $description "Creates a directory that is guaranteed not to exist in a platform-specific temporary directory and returns the full pathname." }
+{ $errors "Throws an error if the directory cannot be created after a number of tries.  Since each try generates a new random name, the most likely error is incorrect directory permissions on the temporary directory." }
+{ $see-also with-unique-directory } ;
+
+HELP: with-unique-file ( quot -- path )
+{ $values { "quot" "a quotation" } { "path" "a pathname string" } }
+{ $description "Creates a file with " { $link make-unique-file } " and calls " { $link with-stream } " on the newly created file.  Returns the full pathname after the stream has been closed." }
+{ $notes "The unique file will remain after calling this word." }
+{ $see-also with-temporary-file } ;
+
+HELP: with-unique-directory ( quot -- path )
+{ $values { "quot" "a quotation" } { "path" "a pathname string" } }
+{ $description "Creates a directory with " { $link make-unique-directory } " and calls " { $link with-directory } " on the newly created directory.  Returns the full pathname after the quotation has been called." }
+{ $notes "The directory will remain after calling this word." }
+{ $see-also with-temporary-directory } ;
+
+HELP: with-temporary-file ( quot -- )
+{ $values { "quot" "a quotation" } }
+{ $description "Creates a file with " { $link make-unique-file } " and calls " { $link with-stream } " on the newly created file.  The file is deleted after the quotation returns." }
+{ $see-also with-unique-file } ;
+
+HELP: with-temporary-directory ( quot -- )
+{ $values { "quot" "a quotation" } }
+{ $description "Creates a directory with " { $link make-unique-directory } " and calls " { $link with-directory } " on the newly created directory.  The directory is deleted after the quotation returns." }
+{ $see-also with-unique-directory } ;

extra/io/files/unique/unique.factor

@@ -0,0 +1,48 @@
+! Copyright (C) 2008 Doug Coleman.
+! See http://factorcode.org/license.txt for BSD license.
+USING: kernel math math.bitfields combinators.lib math.parser
+random sequences sequences.lib continuations namespaces
+io.files io.backend io.nonblocking io arrays
+io.files.unique.backend system combinators vocabs.loader ;
+IN: io.files.unique
+
+<PRIVATE
+: random-letter ( -- ch )
+    26 random { CHAR: a CHAR: A } random + ;
+
+: random-ch ( -- ch )
+    { t f } random
+    [ 10 random CHAR: 0 + ] [ random-letter ] if ;
+
+: random-name ( n -- string )
+    [ drop random-ch ] "" map-as ;
+
+: unique-length ( -- n ) 10 ; inline
+: unique-retries ( -- n ) 10 ; inline
+PRIVATE>
+
+: make-unique-file ( prefix suffix -- path stream )
+    temporary-path -rot
+    [
+        unique-length random-name swap 3append path+
+        dup (make-unique-file)
+    ] 3curry unique-retries retry ;
+
+: with-unique-file ( quot -- path )
+    >r f f make-unique-file r> with-stream ; inline
+
+: with-temporary-file ( quot -- )
+    with-unique-file delete-file ; inline
+
+: make-unique-directory ( -- path )
+    [
+        temporary-path unique-length random-name path+
+        dup make-directory
+    ] unique-retries retry ;
+
+: with-unique-directory ( quot -- path )
+    >r make-unique-directory r>
+    [ with-directory ] curry keep ; inline
+
+: with-temporary-directory ( quot -- )
+    with-unique-directory delete-tree ; inline

extra/io/unix/files/temporary/temporary.factor

@@ -1,12 +0,0 @@
-USING: kernel io.nonblocking io.unix.backend math.bitfields
-unix io.files.temporary.backend ;
-IN: io.unix.files.temporary
-
-: open-temporary-flags ( -- flags )
-    { O_RDWR O_CREAT O_EXCL } flags ;
-
-M: unix-io (temporary-file) ( path -- duplex-stream )
-    open-temporary-flags file-mode open dup io-error
-    <writer> ;
-
-M: unix-io temporary-path ( -- path ) "/tmp" ;

extra/io/unix/files/unique/unique.factor

@@ -0,0 +1,12 @@
+USING: kernel io.nonblocking io.unix.backend math.bitfields
+unix io.files.unique.backend ;
+IN: io.unix.files.unique
+
+: open-unique-flags ( -- flags )
+    { O_RDWR O_CREAT O_EXCL } flags ;
+
+M: unix-io (make-unique-file) ( path -- duplex-stream )
+    open-unique-flags file-mode open dup io-error
+    <writer> ;
+
+M: unix-io temporary-path ( -- path ) "/tmp" ;

extra/io/unix/unix.factor

@@ -1,6 +1,6 @@
 USING: io.unix.backend io.unix.files io.unix.sockets io.timeouts
-io.unix.launcher io.unix.mmap io.backend combinators namespaces
+io.unix.launcher io.unix.mmap io.backend io.files.temporary
-system vocabs.loader sequences ;
+combinators namespaces system vocabs.loader sequences ;
 
 "io.unix." os append require
 

extra/io/windows/files/unique/unique.factor

@@ -1,7 +1,7 @@
 USING: kernel system ;
-IN: io.windows.files.temporary
+IN: io.windows.files.unique
 
-M: windows-io (temporary-file) ( path -- stream )
+M: windows-io (make-unique-file) ( path -- stream )
     GENERIC_WRITE CREATE_NEW 0 open-file 0 <writer> ;
 
 M: windows-io temporary-path ( -- path )

extra/io/windows/windows.factor

@@ -2,10 +2,10 @@
 ! See http://factorcode.org/license.txt for BSD license.
 USING: alien alien.c-types arrays destructors io io.backend
 io.buffers io.files io.nonblocking io.sockets io.binary
-io.sockets.impl windows.errors strings io.streams.duplex kernel
+io.sockets.impl io.windows.files.temporary windows.errors
-math namespaces sequences windows windows.kernel32
+strings io.streams.duplex kernel math namespaces sequences
-windows.shell32 windows.types windows.winsock splitting
+windows windows.kernel32 windows.shell32 windows.types
-continuations math.bitfields ;
+windows.winsock splitting continuations math.bitfields ;
 IN: io.windows
 
 TUPLE: windows-nt-io ;