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 HELP: temporary-path
   6 { $values
   7      { "path" "a pathname string" }
   8 }
   9 { $description "A hook that returns the path of the temporary directory in a platform-specific way. Does not guarantee that path is writable by your user." } ;
  10
  11 HELP: touch-unique-file
  12 { $values
  13      { "path" "a pathname string" }
  14 }
  15 { $description "Creates a unique file in a platform-specific way. The file is guaranteed not to exist and is openable by your user." } ;
  16
  17 HELP: unique-length
  18 { $description "A symbol storing the number of random characters inserted between the prefix and suffix of a random file name." } ;
  19
  20 HELP: unique-retries
  21 { $description "The number of times to try creating a unique file in case of a name collision. The odds of a name collision are extremely low with a sufficient " { $link unique-length } "." } ;
  22
  23 { unique-length unique-retries } related-words
  24
  25 HELP: make-unique-file ( prefix suffix -- path )
  26 { $values { "prefix" "a string" } { "suffix" "a string" }
  27 { "path" "a pathname string" } }
  28 { $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." }
  29 { $errors "Throws an error if a new unique file cannot be created after a number of tries. The most likely error is incorrect directory permissions on the temporary directory." } ;
  30
  31 HELP: make-unique-file*
  32 { $values
  33      { "prefix" null } { "suffix" null }
  34      { "path" "a pathname string" }
  35 }
  36 { $description "Creates a file that is guaranteed not to exist in the directory in the " { $link current-directory } " variable. The file name is composed of a prefix, a number of random digits and letters, and the suffix. Returns the full pathname." } ;
  37
  38 { make-unique-file make-unique-file* with-unique-file } related-words
  39
  40 HELP: with-unique-file ( prefix suffix quot: ( path -- ) -- )
  41 { $values { "prefix" "a string" } { "suffix" "a string" }
  42 { "quot" "a quotation" } }
  43 { $description "Creates a file with " { $link make-unique-file } " and calls the quotation with the path name on the stack." }
  44 { $notes "The unique file will be deleted after calling this word." } ;
  45
  46 HELP: make-unique-directory ( -- path )
  47 { $values { "path" "a pathname string" } }
  48 { $description "Creates a directory that is guaranteed not to exist in a platform-specific temporary directory and returns the full pathname." }
  49 { $errors "Throws an error if the directory cannot be created after a number of tries. The most likely error is incorrect directory permissions on the temporary directory." } ;
  50
  51 HELP: with-unique-directory ( quot -- )
  52 { $values { "quot" "a quotation" } }
  53 { $description "Creates a directory with " { $link make-unique-directory } " and calls the quotation with the pathname on the stack using the " { $link with-directory } " combinator. The quotation can access the " { $link current-directory } " symbol for the name of the temporary directory." }
  54 { $notes "The directory will be deleted after calling this word, even if an error is thrown in the quotation." } ;
  55
  56 ARTICLE: "io.files.unique" "Temporary files"
  57 "The " { $vocab-link "io.files.unique" } " vocabulary implements cross-platform temporary file creation in a high-level and secure way." $nl
  58 "Files:"
  59 { $subsection make-unique-file }
  60 { $subsection make-unique-file* }
  61 { $subsection with-unique-file }
  62 "Directories:"
  63 { $subsection make-unique-directory }
  64 { $subsection with-unique-directory } ;
  65
  66 ABOUT: "io.files.unique"