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

   1 USING: help.markup help.syntax io io.ports kernel math
   2 io.pathnames io.directories math.parser io.files strings
   3 quotations io.files.unique.private ;
   4 IN: io.files.unique
   5
   6 HELP: default-temporary-directory
   7 { $values
   8      { "path" "a pathname string" }
   9 }
  10 { $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." } ;
  11
  12 HELP: touch-unique-file
  13 { $values
  14      { "path" "a pathname string" }
  15 }
  16 { $description "Creates a unique file in a platform-specific way. The file is guaranteed not to exist and is openable by your user." } ;
  17
  18 HELP: unique-length
  19 { $description "A symbol storing the number of random characters inserted between the prefix and suffix of a random file name." } ;
  20
  21 HELP: unique-retries
  22 { $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 } "." } ;
  23
  24 { unique-length unique-retries } related-words
  25
  26 HELP: make-unique-file ( prefix suffix -- path )
  27 { $values { "prefix" "a string" } { "suffix" "a string" }
  28 { "path" "a pathname string" } }
  29 { $description "Creates a file that is guaranteed not to exist in the directory stored in " { $link current-temporary-directory } ". The file name is composed of a prefix, a number of random digits and letters, and the suffix. Returns the full pathname." }
  30 { $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." } ;
  31
  32 { unique-file make-unique-file cleanup-unique-file } related-words
  33
  34 HELP: cleanup-unique-file ( prefix suffix quot: ( path -- ) -- )
  35 { $values { "prefix" "a string" } { "suffix" "a string" }
  36 { "quot" "a quotation" } }
  37 { $description "Creates a file with " { $link make-unique-file } " and calls the quotation with the path name on the stack." }
  38 { $notes "The unique file will be deleted after calling this word." } ;
  39
  40 HELP: unique-directory ( -- path )
  41 { $values { "path" "a pathname string" } }
  42 { $description "Creates a directory in the value in " { $link current-temporary-directory } " that is guaranteed not to exist in and returns the full pathname." }
  43 { $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." } ;
  44
  45 HELP: cleanup-unique-directory ( quot -- )
  46 { $values { "quot" "a quotation" } }
  47 { $description "Creates a directory with " { $link unique-directory } " and calls the quotation with the pathname on the stack using the " { $link with-temporary-directory } " combinator. The quotation can access the " { $link current-temporary-directory } " symbol for the name of the temporary directory. Subsequent unique files will be created in this unique directory until the combinator returns." }
  48 { $notes "The directory will be deleted after calling this word, even if an error is thrown in the quotation. This combinator is like " { $link with-unique-directory } " but does not delete the directory." } ;
  49
  50 HELP: with-unique-directory
  51 { $values
  52      { "quot" quotation }
  53      { "path" "a pathname string" }
  54 }
  55 { $description "Creates a directory with " { $link unique-directory } " and calls the quotation with the pathname on the stack using the " { $link with-temporary-directory } " combinator. The quotation can access the " { $link current-temporary-directory } " symbol for the name of the temporary directory. Subsequent unique files will be created in this unique directory until the combinator returns." } ;
  56
  57 HELP: current-temporary-directory
  58 { $values
  59      { "value" "a path" }
  60 }
  61 { $description "The temporary directory used for creating unique files and directories." } ;
  62
  63 HELP: unique-file
  64 { $values
  65      { "path" "a pathname string" }
  66      { "path'" "a pathname string" }
  67 }
  68 { $description "Creates a temporary file in the directory stored in " { $link current-temporary-directory } " and outputs the path name." } ;
  69
  70 HELP: with-temporary-directory
  71 { $values
  72      { "path" "a pathname string" } { "quot" quotation }
  73 }
  74 { $description "Sets " { $link current-temporary-directory } " to " { $snippet "path" } " and calls the quotation, restoring the previous temporary path after execution completes." } ;
  75
  76 ARTICLE: "io.files.unique" "Unique files"
  77 "The " { $vocab-link "io.files.unique" } " vocabulary implements cross-platform unique file creation in temporary directories in a high-level and secure way." $nl
  78 "Changing the temporary path:"
  79 { $subsection current-temporary-directory }
  80 "Creating unique files:"
  81 { $subsection unique-file }
  82 { $subsection cleanup-unique-file }
  83 { $subsection make-unique-file }
  84 "Creating unique directories:"
  85 { $subsection unique-directory }
  86 { $subsection with-unique-directory }
  87 { $subsection cleanup-unique-directory }
  88 "Default temporary directory:"
  89 { $subsection default-temporary-directory } ;
  90
  91 ABOUT: "io.files.unique"