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 { $notes "User code should use the value of the " { $link current-directory } " variable instead." } ;
   9
  10 HELP: cd
  11 { $values { "path" "a pathname string" } }
  12 { $description "Changes the current working directory of the Factor process." }
  13 { $notes "User code should use " { $link with-directory } " or " { $link set-current-directory } " instead." } ;
  14
  15 { cd cwd current-directory set-current-directory with-directory } related-words
  16
  17 HELP: current-directory
  18 { $description "A variable holding the current directory as an absolute path. Words that use the filesystem do so in relation to this variable."
  19 $nl
  20   "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." } ;
  21
  22 HELP: make-parent-directories
  23 { $values { "path" "a pathname string" } }
  24 { $description "Creates all parent directories of the path which do not yet exist." }
  25 { $errors "Throws an error if the directories could not be created." } ;
  26
  27 HELP: set-current-directory
  28 { $values { "path" "a pathname string" } }
  29 { $description "Changes the " { $link current-directory } " variable."
  30 $nl
  31 "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." } ;
  32
  33 HELP: with-directory
  34 { $values { "path" "a pathname string" } { "quot" quotation } }
  35 { $description "Calls the quotation in a new dynamic scope with the " { $link current-directory } " variable rebound."
  36 $nl
  37 "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." } ;
  38
  39 HELP: (directory-entries)
  40 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $link directory-entry } " objects" } }
  41 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." }
  42 { $notes "This is a low-level word, and user code should call one of the related words instead." } ;
  43
  44 HELP: directory-entries
  45 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $link directory-entry } " objects" } }
  46 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." } ;
  47
  48 HELP: qualified-directory-entries
  49 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $link directory-entry } " objects" } }
  50 { $description "Outputs the contents of a directory named by " { $snippet "path" } ". using absolute file paths." } ;
  51
  52 HELP: directory-files
  53 { $values { "path" "a pathname string" } { "seq" "a sequence of filenames" } }
  54 { $description "Outputs the contents of a directory named by " { $snippet "path" } " as a sequence of filenames." } ;
  55
  56 HELP: qualified-directory-files
  57 { $values { "path" "a pathname string" } { "seq" "a sequence of filenames" } }
  58 { $description "Outputs the contents of a directory named by " { $snippet "path" } " as a sequence of absolute paths." } ;
  59
  60 HELP: with-directory-files
  61 { $values { "path" "a pathname string" } { "quot" quotation } }
  62 { $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." }
  63 { $examples
  64     "Print all files in your home directory which are larger than a megabyte:"
  65     { $code
  66         "USING: io.directories io.files.info io.pathnames ;
  67 home [
  68     [
  69         dup link-info size>> 20 2^ >
  70         [ print ] [ drop ] if
  71     ] each
  72 ] with-directory-files"
  73     }
  74 } ;
  75
  76 HELP: with-directory-entries
  77 { $values { "path" "a pathname string" } { "quot" quotation } }
  78 { $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." } ;
  79
  80 HELP: delete-file
  81 { $values { "path" "a pathname string" } }
  82 { $description "Deletes a file." }
  83 { $errors "Throws an error if the file could not be deleted." } ;
  84
  85 HELP: make-directory
  86 { $values { "path" "a pathname string" } }
  87 { $description "Creates a directory." }
  88 { $errors "Throws an error if the directory could not be created." } ;
  89
  90 HELP: make-directories
  91 { $values { "path" "a pathname string" } }
  92 { $description "Creates a directory and any parent directories which do not yet exist." }
  93 { $errors "Throws an error if the directories could not be created." } ;
  94
  95 HELP: delete-directory
  96 { $values { "path" "a pathname string" } }
  97 { $description "Deletes a directory. The directory must be empty." }
  98 { $errors "Throws an error if the directory could not be deleted." } ;
  99
 100 HELP: touch-file
 101 { $values { "path" "a pathname string" } }
 102 { $description "Updates the modification time of a file or directory. If the file does not exist, creates a new, empty file." }
 103 { $errors "Throws an error if the file could not be touched." } ;
 104
 105 HELP: move-file
 106 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
 107 { $description "Moves or renames a file." }
 108 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
 109
 110 HELP: move-file-into
 111 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
 112 { $description "Moves a file to another directory without renaming it." }
 113 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
 114
 115 HELP: move-files-into
 116 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
 117 { $description "Moves a set of files to another directory." }
 118 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
 119
 120 HELP: copy-file
 121 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
 122 { $description "Copies a file." }
 123 { $notes "This operation attempts to preserve the original file's attributes, however not all attributes may be preserved." }
 124 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 125
 126 HELP: copy-file-into
 127 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
 128 { $description "Copies a file to another directory." }
 129 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 130
 131 HELP: copy-files-into
 132 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
 133 { $description "Copies a set of files to another directory." }
 134 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 135
 136 ARTICLE: "current-directory" "Current working directory"
 137 "File system I/O operations use the value of a variable to resolve relative pathnames:"
 138 { $subsections current-directory }
 139 "This variable can be changed with a pair of words:"
 140 { $subsections
 141     set-current-directory
 142     with-directory
 143 }
 144 "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:"
 145 { $subsections absolute-path }
 146 "The second is to change the working directory of the current process:"
 147 { $subsections
 148     cd
 149     cwd
 150 } ;
 151
 152 ARTICLE: "io.directories.listing" "Directory listing"
 153 "Directory listing:"
 154 { $subsections
 155     directory-entries
 156     directory-files
 157     with-directory-entries
 158     with-directory-files
 159     qualified-directory-entries
 160     qualified-directory-files
 161     with-qualified-directory-files
 162     with-qualified-directory-entries
 163 } ;
 164
 165 ARTICLE: "io.directories.create" "Creating directories"
 166 { $subsections
 167     make-directory
 168     make-directories
 169 } ;
 170
 171 ARTICLE: "delete-move-copy" "Deleting, moving, and copying files"
 172 "The operations for moving and copying files come in three flavors:"
 173 { $list
 174     { "A word named " { $snippet { $emphasis "operation" } } " which takes a source and destination path." }
 175     { "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." }
 176     { "A word named " { $snippet { $emphasis "operation" } "s-into" } " which takes a sequence of source paths and destination directory." }
 177 }
 178 "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."
 179 $nl
 180 "Deleting files:"
 181 { $subsections
 182     delete-file
 183     delete-directory
 184 }
 185 "Moving files:"
 186 { $subsections
 187     move-file
 188     move-file-into
 189     move-files-into
 190 }
 191 "Copying files:"
 192 { $subsections
 193     copy-file
 194     copy-file-into
 195     copy-files-into
 196 }
 197 "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." ;
 198
 199 ARTICLE: "io.directories" "Directory manipulation"
 200 "The " { $vocab-link "io.directories" } " vocabulary defines words for inspecting and manipulating directories."
 201 { $subsections
 202     home
 203     "current-directory"
 204     "io.directories.listing"
 205     "io.directories.create"
 206     "delete-move-copy"
 207     "io.directories.hierarchy"
 208 } ;
 209
 210 ABOUT: "io.directories"