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

   1 USING: help.markup help.syntax io io.ports kernel math
   2 io.files.unique.private math.parser io.files ;
   3 IN: io.files.unique
   4
   5 ARTICLE: "unique" "Making and using unique files"
   6 "Files:"
   7 { $subsection make-unique-file }
   8 { $subsection with-unique-file }
   9 "Directories:"
  10 { $subsection make-unique-directory }
  11 { $subsection with-unique-directory } ;
  12
  13 ABOUT: "unique"
  14
  15 HELP: make-unique-file ( prefix suffix -- path )
  16 { $values { "prefix" "a string" } { "suffix" "a string" }
  17 { "path" "a pathname string" } }
  18 { $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." }
  19 { $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." }
  20 { $see-also with-unique-file } ;
  21
  22 HELP: make-unique-directory ( -- path )
  23 { $values { "path" "a pathname string" } }
  24 { $description "Creates a directory that is guaranteed not to exist in a platform-specific temporary directory and returns the full pathname." }
  25 { $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." }
  26 { $see-also with-unique-directory } ;
  27
  28 HELP: with-unique-file ( prefix suffix quot -- )
  29 { $values { "prefix" "a string" } { "suffix" "a string" }
  30 { "quot" "a quotation" } }
  31 { $description "Creates a file with " { $link make-unique-file } " and calls the quotation with the path name on the stack." }
  32 { $notes "The unique file will be deleted after calling this word." } ;
  33
  34 HELP: with-unique-directory ( quot -- )
  35 { $values { "quot" "a quotation" } }
  36 { $description "Creates a directory with " { $link make-unique-directory } " and calls the quotation with the pathname on the stack." }
  37 { $notes "The directory will be deleted after calling this word." } ;