1 USING: help.markup help.syntax io.files.private io.pathnames
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." } ;
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." } ;
17 { cd cwd current-directory set-current-directory with-directory } related-words
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."
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." } ;
24 HELP: set-current-directory
25 { $values { "path" "a pathname string" } }
26 { $description "Changes the " { $link current-directory } " variable."
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." } ;
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."
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." } ;
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." } ;
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" } "." } ;
46 { $values { "path" "a pathname string" } { "seq" "a sequence of filenames" } }
47 { $description "Outputs the contents of a directory named by " { $snippet "path" } "." } ;
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." } ;
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." } ;
58 { $values { "path" "a pathname string" } }
59 { $description "Deletes a file." }
60 { $errors "Throws an error if the file could not be deleted." } ;
63 { $values { "path" "a pathname string" } }
64 { $description "Creates a directory." }
65 { $errors "Throws an error if the directory could not be created." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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:"
118 set-current-directory
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 absolute-path }
123 "The second is to change the working directory of the current process:"
129 ARTICLE: "io.directories.listing" "Directory listing"
134 with-directory-entries
138 ARTICLE: "io.directories.create" "Creating directories"
144 ARTICLE: "delete-move-copy" "Deleting, moving, and copying files"
145 "Operations for deleting and copying files come in two forms:"
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." }
150 "The operations for moving and copying files come in three flavors:"
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." }
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."
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." ;
177 ARTICLE: "io.directories" "Directory manipulation"
178 "The " { $vocab-link "io.directories" } " vocabulary defines words for inspecting and manipulating directory trees."
182 "io.directories.listing"
183 "io.directories.create"
185 "io.directories.hierarchy"
188 ABOUT: "io.directories"