basis/io/directories/directories-docs.factor

   1 USING: help.markup help.syntax io.files.private io.pathnames
   2 quotations ;
   3 IN: io.directories
   4
   5 HELP: cwd
   6 { $values { "path" "a pathname string" } }
   7 { $description "Outputs the current working directory of the Factor process." }
   8 { $errors "Windows CE has no concept of “current directory”, so this word throws an error there." }
   9 { $notes "User code should use the value of the " { $link current-directory } " variable instead." } ;
  10
  11 HELP: cd
  12 { $values { "path" "a pathname string" } }
  13 { $description "Changes the current working directory of the Factor process." }
  14 { $errors "Windows CE has no concept of “current directory”, so this word throws an error there." }
  15 { $notes "User code should use " { $link with-directory } " or " { $link set-current-directory } " instead." } ;
  16
  17 { cd cwd current-directory set-current-directory with-directory } related-words
  18
  19 HELP: current-directory
  20 { $description "A variable holding the current directory as an absolute path. Words that use the filesystem do so in relation to this variable."
  21 $nl
  22 "This variable should never be set directly; instead, use " { $link set-current-directory } " or " { $link with-directory } ". This preserves the invariant that the value of this variable is an absolute path." } ;
  23
  24 HELP: set-current-directory
  25 { $values { "path" "a pathname string" } }
  26 { $description "Changes the " { $link current-directory } " variable."
  27 $nl
  28 "If " { $snippet "path" } " is relative, it is first resolved relative to the current directory. If " { $snippet "path" } " is absolute, it becomes the new current directory." } ;
  29
  30 HELP: with-directory
  31 { $values { "path" "a pathname string" } { "quot" quotation } }
  32 { $description "Calls the quotation in a new dynamic scope with the " { $link current-directory } " variable rebound."
  33 $nl
  34 "If " { $snippet "path" } " is relative, it is first resolved relative to the current directory. If " { $snippet "path" } " is absolute, it becomes the new current directory." } ;
  35
  36 HELP: (directory-entries)
  37 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $snippet "{ name dir? }" } " pairs" } }
  38 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." }
  39 { $notes "This is a low-level word, and user code should call one of the related words instead." } ;
  40
  41 HELP: directory-entries
  42 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $link directory-entry } " objects" } }
  43 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." } ;
  44
  45 HELP: directory-files
  46 { $values { "path" "a pathname string" } { "seq" "a sequence of filenames" } }
  47 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." } ;
  48
  49 HELP: with-directory-files
  50 { $values { "path" "a pathname string" } { "quot" quotation } }
  51 { $description "Calls the quotation with the directory file names on the stack and with the directory set as the " { $link current-directory } ".  Restores the current directory after the quotation is called." } ;
  52
  53 HELP: with-directory-entries
  54 { $values { "path" "a pathname string" } { "quot" quotation } }
  55 { $description "Calls the quotation with the directory entries on the stack and with the directory set as the " { $link current-directory } ".  Restores the current directory after the quotation is called." } ;
  56
  57 HELP: delete-file
  58 { $values { "path" "a pathname string" } }
  59 { $description "Deletes a file." }
  60 { $errors "Throws an error if the file could not be deleted." } ;
  61
  62 HELP: make-directory
  63 { $values { "path" "a pathname string" } }
  64 { $description "Creates a directory." }
  65 { $errors "Throws an error if the directory could not be created." } ;
  66
  67 HELP: make-directories
  68 { $values { "path" "a pathname string" } }
  69 { $description "Creates a directory and any parent directories which do not yet exist." }
  70 { $errors "Throws an error if the directories could not be created." } ;
  71
  72 HELP: delete-directory
  73 { $values { "path" "a pathname string" } }
  74 { $description "Deletes a directory. The directory must be empty." }
  75 { $errors "Throws an error if the directory could not be deleted." } ;
  76
  77 HELP: touch-file
  78 { $values { "path" "a pathname string" } }
  79 { $description "Updates the modification time of a file or directory. If the file does not exist, creates a new, empty file." }
  80 { $errors "Throws an error if the file could not be touched." } ;
  81
  82 HELP: move-file
  83 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
  84 { $description "Moves or renames a file." }
  85 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
  86
  87 HELP: move-file-into
  88 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
  89 { $description "Moves a file to another directory without renaming it." }
  90 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
  91
  92 HELP: move-files-into
  93 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
  94 { $description "Moves a set of files to another directory." }
  95 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
  96
  97 HELP: copy-file
  98 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
  99 { $description "Copies a file." }
 100 { $notes "This operation attempts to preserve the original file's attributes, however not all attributes may be preserved." }
 101 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 102
 103 HELP: copy-file-into
 104 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
 105 { $description "Copies a file to another directory." }
 106 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 107
 108 HELP: copy-files-into
 109 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
 110 { $description "Copies a set of files to another directory." }
 111 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 112
 113 ARTICLE: "current-directory" "Current working directory"
 114 "File system I/O operations use the value of a variable to resolve relative pathnames:"
 115 { $subsections current-directory }
 116 "This variable can be changed with a pair of words:"
 117 { $subsections
 118     set-current-directory
 119     with-directory
 120 }
 121 "This variable is independent of the operating system notion of “current working directory”. While all Factor I/O operations use the variable and not the operating system's value, care must be taken when making FFI calls which expect a pathname. The first option is to resolve relative paths:"
 122 { $subsections (normalize-path) }
 123 "The second is to change the working directory of the current process:"
 124 { $subsections
 125     cd
 126     cwd
 127 } ;
 128
 129 ARTICLE: "io.directories.listing" "Directory listing"
 130 "Directory listing:"
 131 { $subsections
 132     directory-entries
 133     directory-files
 134     with-directory-entries
 135     with-directory-files
 136 } ;
 137
 138 ARTICLE: "io.directories.create" "Creating directories"
 139 { $subsections
 140     make-directory
 141     make-directories
 142 } ;
 143
 144 ARTICLE: "delete-move-copy" "Deleting, moving, and copying files"
 145 "Operations for deleting and copying files come in two forms:"
 146 { $list
 147     { "Words named " { $snippet { $emphasis "operation" } "-file" } " which work on regular files only." }
 148     { "Words named " { $snippet { $emphasis "operation" } "-tree" } " works on directory trees recursively, and also accepts regular files." }
 149 }
 150 "The operations for moving and copying files come in three flavors:"
 151 { $list
 152     { "A word named " { $snippet { $emphasis "operation" } } " which takes a source and destination path." }
 153     { "A word named " { $snippet { $emphasis "operation" } "-into" } " which takes a source path and destination directory. The destination file will be stored in the destination directory and will have the same file name as the source path." }
 154     { "A word named " { $snippet { $emphasis "operation" } "s-into" } " which takes a sequence of source paths and destination directory." }
 155 }
 156 "Since both of the above lists apply to copying files, that this means that there are a total of six variations on copying a file."
 157 $nl
 158 "Deleting files:"
 159 { $subsections
 160     delete-file
 161     delete-directory
 162 }
 163 "Moving files:"
 164 { $subsections
 165     move-file
 166     move-file-into
 167     move-files-into
 168 }
 169 "Copying files:"
 170 { $subsections
 171     copy-file
 172     copy-file-into
 173     copy-files-into
 174 }
 175 "On most operating systems, files can only be moved within the same file system. To move files between file systems, use " { $link copy-file } " followed by " { $link delete-file } " on the old name." ;
 176
 177 ARTICLE: "io.directories" "Directory manipulation"
 178 "The " { $vocab-link "io.directories" } " vocabulary defines words for inspecting and manipulating directory trees."
 179 { $subsections
 180     home
 181     "current-directory"
 182     "io.directories.listing"
 183     "io.directories.create"
 184     "delete-move-copy"
 185     "io.directories.hierarchy"
 186 } ;
 187
 188 ABOUT: "io.directories"