core/io/files/files-docs.factor

   1 USING: help.markup help.syntax io strings arrays io.backend
   2 io.files.private quotations ;
   3 IN: io.files
   4
   5 ARTICLE: "file-streams" "Reading and writing files"
   6 "File streams:"
   7 { $subsection <file-reader> }
   8 { $subsection <file-writer> }
   9 { $subsection <file-appender> }
  10 "Reading and writing the entire contents of a file; this is only recommended for smaller files:"
  11 { $subsection file-contents }
  12 { $subsection set-file-contents }
  13 { $subsection file-lines }
  14 { $subsection set-file-lines }
  15 "Utility combinators:"
  16 { $subsection with-file-reader }
  17 { $subsection with-file-writer }
  18 { $subsection with-file-appender } ;
  19
  20 ARTICLE: "pathnames" "Pathname manipulation"
  21 "Pathname manipulation:"
  22 { $subsection parent-directory }
  23 { $subsection file-name }
  24 { $subsection last-path-separator }
  25 { $subsection append-path }
  26 "Pathnames relative to Factor's temporary files directory:"
  27 { $subsection temp-directory }
  28 { $subsection temp-file }
  29 "Pathname presentations:"
  30 { $subsection pathname }
  31 { $subsection <pathname> } ;
  32
  33 ARTICLE: "symbolic-links" "Symbolic links"
  34 "Reading and creating links:"
  35 { $subsection read-link }
  36 { $subsection make-link }
  37 "Copying links:"
  38 { $subsection copy-link }
  39 "Not all operating systems support symbolic links."
  40 { $see-also link-info } ;
  41
  42 ARTICLE: "current-directory" "Current working directory"
  43 "File system I/O operations use the value of a variable to resolve relative pathnames:"
  44 { $subsection current-directory }
  45 "This variable can be changed with a pair of words:"
  46 { $subsection set-current-directory }
  47 { $subsection with-directory }
  48 "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:"
  49 { $subsection (normalize-path) }
  50 "The second is to change the working directory of the current process:"
  51 { $subsection cd }
  52 { $subsection cwd } ;
  53
  54 ARTICLE: "directories" "Directories"
  55 "Home directory:"
  56 { $subsection home }
  57 "Directory listing:"
  58 { $subsection directory-entries }
  59 { $subsection directory-files }
  60 { $subsection with-directory-files }
  61 "Creating directories:"
  62 { $subsection make-directory }
  63 { $subsection make-directories }
  64 { $subsection "current-directory" } ;
  65
  66 ARTICLE: "file-types" "File Types"
  67 "Platform-independent types:"
  68 { $subsection +regular-file+ }
  69 { $subsection +directory+ }
  70 "Platform-specific types:"
  71 { $subsection +character-device+ }
  72 { $subsection +block-device+ }
  73 { $subsection +fifo+ }
  74 { $subsection +symbolic-link+ }
  75 { $subsection +socket+ }
  76 { $subsection +unknown+ } ;
  77
  78 ARTICLE: "fs-meta" "File metadata"
  79 "Querying file-system metadata:"
  80 { $subsection file-info }
  81 { $subsection link-info }
  82 { $subsection exists? }
  83 { $subsection directory? }
  84
  85 "File types:"
  86 { $subsection "file-types" } ;
  87
  88 ARTICLE: "delete-move-copy" "Deleting, moving, copying files"
  89 "Operations for deleting and copying files come in two forms:"
  90 { $list
  91     { "Words named " { $snippet { $emphasis "operation" } "-file" } " which work on regular files only." }
  92     { "Words named " { $snippet { $emphasis "operation" } "-tree" } " works on directory trees recursively, and also accepts regular files." }
  93 }
  94 "The operations for moving and copying files come in three flavors:"
  95 { $list
  96     { "A word named " { $snippet { $emphasis "operation" } } " which takes a source and destination path." }
  97     { "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." }
  98     { "A word named " { $snippet { $emphasis "operation" } "s-into" } " which takes a sequence of source paths and destination directory." }
  99 }
 100 "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."
 101 $nl
 102 "Deleting files:"
 103 { $subsection delete-file }
 104 { $subsection delete-directory }
 105 { $subsection delete-tree }
 106 "Moving files:"
 107 { $subsection move-file }
 108 { $subsection move-file-into }
 109 { $subsection move-files-into }
 110 "Copying files:"
 111 { $subsection copy-file }
 112 { $subsection copy-file-into }
 113 { $subsection copy-files-into }
 114 "Copying directory trees recursively:"
 115 { $subsection copy-tree }
 116 { $subsection copy-tree-into }
 117 { $subsection copy-trees-into }
 118 "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." ;
 119
 120 ARTICLE: "io.files" "Basic file operations"
 121 "The " { $vocab-link "io.files" } " vocabulary provides basic support for working with files."
 122 { $subsection "pathnames" }
 123 { $subsection "file-streams" }
 124 { $subsection "fs-meta" }
 125 { $subsection "directories" }
 126 { $subsection "delete-move-copy" }
 127 { $subsection "symbolic-links" } ;
 128
 129 ABOUT: "io.files"
 130
 131 HELP: path-separator?
 132 { $values { "ch" "a code point" } { "?" "a boolean" } }
 133 { $description "Tests if the code point is a platform-specific path separator." }
 134 { $examples
 135     "On Unix:"
 136     { $example "USING: io.files prettyprint ;" "CHAR: / path-separator? ." "t" }
 137 } ;
 138
 139 HELP: parent-directory
 140 { $values { "path" "a pathname string" } { "parent" "a pathname string" } }
 141 { $description "Strips the last component off a pathname." }
 142 { $examples { $example "USING: io io.files ;" "\"/etc/passwd\" parent-directory print" "/etc/" } } ;
 143
 144 HELP: file-name
 145 { $values { "path" "a pathname string" } { "string" string } }
 146 { $description "Outputs the last component of a pathname string." }
 147 { $examples
 148     { $example "USING: io.files prettyprint ;" "\"/usr/bin/gcc\" file-name ." "\"gcc\"" }
 149     { $example "USING: io.files prettyprint ;" "\"/usr/libexec/awk/\" file-name ." "\"awk\"" }
 150 } ;
 151
 152 ! need a $class-description file-info
 153
 154 HELP: file-info
 155 { $values { "path" "a pathname string" } { "info" file-info } }
 156 { $description "Queries the file system for metadata. If " { $snippet "path" } " refers to a symbolic link, it is followed. See the article " { $link "file-types" } " for a list of metadata symbols." }
 157 { $errors "Throws an error if the file does not exist." } ;
 158
 159 HELP: link-info
 160 { $values { "path" "a pathname string" } { "info" "a file-info tuple" } }
 161 { $description "Queries the file system for metadata. If path refers to a symbolic link, information about the symbolic link itself is returned. If the file does not exist, an exception is thrown." } ;
 162
 163 { file-info link-info } related-words
 164
 165 HELP: +regular-file+
 166 { $description "A regular file. This type exists on all platforms. See " { $link "file-streams" } " for words operating on files." } ;
 167
 168 HELP: +directory+
 169 { $description "A directory. This type exists on all platforms. See " { $link "directories" } " for words operating on directories." } ;
 170
 171 HELP: +symbolic-link+
 172 { $description "A symbolic link file.  This type is currently implemented on Unix platforms only. See " { $link "symbolic-links" } " for words operating on symbolic links." } ;
 173
 174 HELP: +character-device+
 175 { $description "A Unix character device file. This type exists on Unix platforms only." } ;
 176
 177 HELP: +block-device+
 178 { $description "A Unix block device file. This type exists on Unix platforms only." } ;
 179
 180 HELP: +fifo+
 181 { $description "A Unix fifo file. This type exists on Unix platforms only." } ;
 182
 183 HELP: +socket+
 184 { $description "A Unix socket file. This type exists on Unix platforms only." } ;
 185
 186 HELP: +unknown+
 187 { $description "A unknown file type." } ;
 188
 189 HELP: <file-reader>
 190 {
 191   $values
 192   { "path" "a pathname string" }
 193   { "encoding" "an encoding descriptor" }
 194   { "stream" "an input stream" }
 195 }
 196 { $description "Outputs an input stream for reading from the specified pathname using the given encoding." }
 197 { $errors "Throws an error if the file is unreadable." } ;
 198
 199 HELP: <file-writer>
 200 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
 201 { $description "Outputs an output stream for writing to the specified pathname using the given encoding. The file's length is truncated to zero." }
 202 { $errors "Throws an error if the file cannot be opened for writing." } ;
 203
 204 HELP: <file-appender>
 205 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
 206 { $description "Outputs an output stream for writing to the specified pathname using the given encoding. The stream begins writing at the end of the file." }
 207 { $errors "Throws an error if the file cannot be opened for writing." } ;
 208
 209 HELP: with-file-reader
 210 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
 211 { $description "Opens a file for reading and calls the quotation using " { $link with-input-stream } "." }
 212 { $errors "Throws an error if the file is unreadable." } ;
 213
 214 HELP: with-file-writer
 215 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
 216 { $description "Opens a file for writing using the given encoding and calls the quotation using " { $link with-output-stream } "." }
 217 { $errors "Throws an error if the file cannot be opened for writing." } ;
 218
 219 HELP: with-file-appender
 220 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
 221 { $description "Opens a file for appending using the given encoding and calls the quotation using " { $link with-output-stream } "." }
 222 { $errors "Throws an error if the file cannot be opened for writing." } ;
 223
 224 HELP: set-file-lines
 225 { $values { "seq" "an array of strings" } { "path" "a pathname string" } { "encoding" "an encoding descriptor" } }
 226 { $description "Sets the contents of a file to the strings with the given encoding." }
 227 { $errors "Throws an error if the file cannot be opened for writing." } ;
 228
 229 HELP: file-lines
 230 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "seq" "an array of strings" } }
 231 { $description "Opens the file at the given path using the given encoding, and returns a list of the lines in that file." }
 232 { $errors "Throws an error if the file cannot be opened for reading." } ;
 233
 234 HELP: set-file-contents
 235 { $values { "str" "a string" } { "path" "a pathname string" } { "encoding" "an encoding descriptor" } }
 236 { $description "Sets the contents of a file to a string with the given encoding." }
 237 { $errors "Throws an error if the file cannot be opened for writing." } ;
 238
 239 HELP: file-contents
 240 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "str" "a string" } }
 241 { $description "Opens the file at the given path using the given encoding, and the contents of that file as a string." }
 242 { $errors "Throws an error if the file cannot be opened for reading." } ;
 243
 244 { set-file-lines file-lines set-file-contents file-contents } related-words
 245
 246 HELP: cwd
 247 { $values { "path" "a pathname string" } }
 248 { $description "Outputs the current working directory of the Factor process." }
 249 { $errors "Windows CE has no concept of ``current directory'', so this word throws an error there." }
 250 { $notes "User code should use " { $link with-directory } " or " { $link set-current-directory } " instead." } ;
 251
 252 HELP: cd
 253 { $values { "path" "a pathname string" } }
 254 { $description "Changes the current working directory of the Factor process." }
 255 { $errors "Windows CE has no concept of ``current directory'', so this word throws an error there." }
 256 { $notes "User code should use " { $link with-directory } " or " { $link set-current-directory } " instead." } ;
 257
 258 { cd cwd current-directory set-current-directory with-directory } related-words
 259
 260 HELP: current-directory
 261 { $description "A variable holding the current directory as an absolute path. Words that use the filesystem do so in relation to this variable."
 262 $nl
 263 "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." } ;
 264
 265 HELP: set-current-directory
 266 { $values { "path" "a pathname string" } }
 267 { $description "Changes the " { $link current-directory } " variable."
 268 $nl
 269 "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." } ;
 270
 271 HELP: with-directory
 272 { $values { "path" "a pathname string" } { "quot" quotation } }
 273 { $description "Calls the quotation in a new dynamic scope with the " { $link current-directory } " variable rebound."
 274 $nl
 275 "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." } ;
 276
 277 HELP: append-path
 278 { $values { "str1" "a string" } { "str2" "a string" } { "str" "a string" } }
 279 { $description "Appends " { $snippet "str1" } " and " { $snippet "str2" } " to form a pathname." } ;
 280
 281 HELP: prepend-path
 282 { $values { "str1" "a string" } { "str2" "a string" } { "str" "a string" } }
 283 { $description "Appends " { $snippet "str2" } " and " { $snippet "str1" } " to form a pathname." } ;
 284
 285 { append-path prepend-path } related-words
 286
 287 HELP: absolute-path?
 288 { $values { "path" "a pathname string" } { "?" "a boolean" } }
 289 { $description "Tests if a pathname is absolute. Examples of absolute pathnames are " { $snippet "/foo/bar" } " on Unix and " { $snippet "c:\\foo\\bar" } " on Windows." } ;
 290
 291 HELP: windows-absolute-path?
 292 { $values { "path" "a pathname string" } { "?" "a boolean" } }
 293 { $description "Tests if a pathname is absolute on Windows. Examples of absolute pathnames on Windows are " { $snippet "c:\\foo\\bar" } " and " { $snippet "\\\\?\\c:\\foo\\bar" } " for absolute Unicode pathnames." } ;
 294
 295 HELP: root-directory?
 296 { $values { "path" "a pathname string" } { "?" "a boolean" } }
 297 { $description "Tests if a pathname is a root directory. Examples of root directory pathnames are " { $snippet "/" } " on Unix and " { $snippet "c:\\" } " on Windows." } ;
 298
 299 { absolute-path? windows-absolute-path? root-directory? } related-words
 300
 301 HELP: exists?
 302 { $values { "path" "a pathname string" } { "?" "a boolean" } }
 303 { $description "Tests if the file named by " { $snippet "path" } " exists." } ;
 304
 305 HELP: directory?
 306 { $values { "file-info" file-info } { "?" "a boolean" } }
 307 { $description "Tests if " { $snippet "file-info" } " is a directory." } ;
 308
 309 HELP: (directory-entries)
 310 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $snippet "{ name dir? }" } " pairs" } }
 311 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." }
 312 { $notes "This is a low-level word, and user code should call one of the related words instead." } ;
 313
 314 HELP: directory-entries
 315 { $values { "path" "a pathname string" } { "seq" "a sequence of " { $link directory-entry } " objects" } }
 316 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." } ;
 317
 318 HELP: directory-files
 319 { $values { "path" "a pathname string" } { "seq" "a sequence of filenames" } }
 320 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." } ;
 321
 322 HELP: with-directory-files
 323 { $values { "path" "a pathname string" } { "quot" quotation } }
 324 { $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." } ;
 325
 326 HELP: file-systems
 327 { $values { "array" array } }
 328 { $description "Returns an array of " { $link file-system-info } " objects returned by iterating the mount points and calling " { $link file-system-info } " on each." } ;
 329
 330 HELP: file-system-info
 331 { $values
 332 { "path" "a pathname string" }
 333 { "file-system-info" file-system-info } }
 334 { $description "Returns a platform-specific object describing the file-system that contains the path. The cross-platform slot is " { $slot "free-space" } "." } ;
 335
 336 HELP: resource-path
 337 { $values { "path" "a pathname string" } { "newpath" "a pathname string" } }
 338 { $description "Resolve a path relative to the Factor source code location." } ;
 339
 340 HELP: pathname
 341 { $class-description "Class of path name objects. Path name objects can be created by calling " { $link <pathname> } "." } ;
 342
 343 HELP: normalize-path
 344 { $values { "str" "a pathname string" } { "newstr" "a new pathname string" } }
 345 { $description "Called by words such as " { $link <file-reader> } " and " { $link <file-writer> } " to prepare a pathname before passing it to underlying code." } ;
 346
 347 HELP: <pathname> ( str -- pathname )
 348 { $values { "str" "a pathname string" } { "pathname" pathname } }
 349 { $description "Creates a new " { $link pathname } "." } ;
 350
 351 HELP: make-link
 352 { $values { "target" "a path to the symbolic link's target" } { "symlink" "a path to new symbolic link" } }
 353 { $description "Creates a symbolic link." } ;
 354
 355 HELP: read-link
 356 { $values { "symlink" "a path to an existing symbolic link" } { "path" "the path pointed to by the symbolic link" } }
 357 { $description "Reads the symbolic link and returns its target path." } ;
 358
 359 HELP: copy-link
 360 { $values { "target" "a path to an existing symlink" } { "symlink" "a path to a new symbolic link" } }
 361 { $description "Copies a symbolic link without following the link." } ;
 362
 363 { make-link read-link copy-link } related-words
 364
 365 HELP: home
 366 { $values { "dir" string } }
 367 { $description "Outputs the user's home directory." } ;
 368
 369 HELP: delete-file
 370 { $values { "path" "a pathname string" } }
 371 { $description "Deletes a file." }
 372 { $errors "Throws an error if the file could not be deleted." } ;
 373
 374 HELP: make-directory
 375 { $values { "path" "a pathname string" } }
 376 { $description "Creates a directory." }
 377 { $errors "Throws an error if the directory could not be created." } ;
 378
 379 HELP: make-directories
 380 { $values { "path" "a pathname string" } }
 381 { $description "Creates a directory and any parent directories which do not yet exist." }
 382 { $errors "Throws an error if the directories could not be created." } ;
 383
 384 HELP: delete-directory
 385 { $values { "path" "a pathname string" } }
 386 { $description "Deletes a directory. The directory must be empty." }
 387 { $errors "Throws an error if the directory could not be deleted." } ;
 388
 389 HELP: touch-file
 390 { $values { "path" "a pathname string" } }
 391 { $description "Updates the modification time of a file or directory. If the file does not exist, creates a new, empty file." }
 392 { $errors "Throws an error if the file could not be touched." } ;
 393
 394 HELP: delete-tree
 395 { $values { "path" "a pathname string" } }
 396 { $description "Deletes a file or directory, recursing into subdirectories." }
 397 { $errors "Throws an error if the deletion fails." }
 398 { $warning "Misuse of this word can lead to catastrophic data loss." } ;
 399
 400 HELP: move-file
 401 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
 402 { $description "Moves or renames a file." }
 403 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
 404
 405 HELP: move-file-into
 406 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
 407 { $description "Moves a file to another directory without renaming it." }
 408 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
 409
 410 HELP: move-files-into
 411 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
 412 { $description "Moves a set of files to another directory." }
 413 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
 414
 415 HELP: copy-file
 416 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
 417 { $description "Copies a file." }
 418 { $notes "This operation attempts to preserve the original file's attributes, however not all attributes may be preserved." }
 419 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 420
 421 HELP: copy-file-into
 422 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
 423 { $description "Copies a file to another directory." }
 424 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 425
 426 HELP: copy-files-into
 427 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
 428 { $description "Copies a set of files to another directory." }
 429 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
 430
 431 HELP: copy-tree
 432 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
 433 { $description "Copies a directory tree recursively." }
 434 { $notes "This operation attempts to preserve original file attributes, however not all attributes may be preserved." }
 435 { $errors "Throws an error if the copy operation fails." } ;
 436
 437 HELP: copy-tree-into
 438 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
 439 { $description "Copies a directory tree to another directory, recursively." }
 440 { $errors "Throws an error if the copy operation fails." } ;
 441
 442 HELP: copy-trees-into
 443 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
 444 { $description "Copies a set of directory trees to another directory, recursively." }
 445 { $errors "Throws an error if the copy operation fails." } ;
 446
 447