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 { $notes "User code should use the value of the " { $link current-directory } " variable instead." } ;
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." } ;
15 { cd cwd current-directory set-current-directory with-directory } related-words
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."
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." } ;
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." } ;
27 HELP: set-current-directory
28 { $values { "path" "a pathname string" } }
29 { $description "Changes the " { $link current-directory } " variable."
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." } ;
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."
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." } ;
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." } ;
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" } "." } ;
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." } ;
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." } ;
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." } ;
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." }
64 "Print all files in your home directory which are larger than a megabyte:"
66 "USING: io.directories io.files.info io.pathnames ;
69 dup link-info size>> 20 2^ >
72 ] with-directory-files"
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." } ;
81 { $values { "path" "a pathname string" } }
82 { $description "Deletes a file." }
83 { $errors "Throws an error if the file could not be deleted." } ;
86 { $values { "path" "a pathname string" } }
87 { $description "Creates a directory." }
88 { $errors "Throws an error if the directory could not be created." } ;
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." } ;
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." } ;
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." } ;
106 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
107 { $description "Moves or renames a file. This operation is not guaranteed to be atomic. In particular, if you attempt to move a file across volumes, this will copy the file and then delete the original in a nontransactional manner." }
108 { $errors "Throws an error if the file does not exist or if the move operation fails." }
109 { $see-also move-file-atomically } ;
111 HELP: move-file-atomically
112 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
113 { $description "Moves or renames a file as an atomic operation." }
114 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
117 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
118 { $description "Moves a file to another directory without renaming it." }
119 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
121 HELP: move-files-into
122 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
123 { $description "Moves a set of files to another directory." }
124 { $errors "Throws an error if the file does not exist or if the move operation fails." } ;
127 { $values { "from" "a pathname string" } { "to" "a pathname string" } }
128 { $description "Copies a file." }
129 { $notes "This operation attempts to preserve the original file's attributes, however not all attributes may be preserved." }
130 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
133 { $values { "from" "a pathname string" } { "to" "a directory pathname string" } }
134 { $description "Copies a file to another directory." }
135 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
137 HELP: copy-files-into
138 { $values { "files" "a sequence of pathname strings" } { "to" "a directory pathname string" } }
139 { $description "Copies a set of files to another directory." }
140 { $errors "Throws an error if the file does not exist or if the copy operation fails." } ;
142 ARTICLE: "current-directory" "Current working directory"
143 "File system I/O operations use the value of a variable to resolve relative pathnames:"
144 { $subsections current-directory }
145 "This variable can be changed with a pair of words:"
147 set-current-directory
150 "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:"
151 { $subsections absolute-path }
152 "The second is to change the working directory of the current process:"
158 ARTICLE: "io.directories.listing" "Directory listing"
163 with-directory-entries
165 qualified-directory-entries
166 qualified-directory-files
167 with-qualified-directory-files
168 with-qualified-directory-entries
171 ARTICLE: "io.directories.create" "Creating directories"
177 ARTICLE: "delete-move-copy" "Deleting, moving, and copying files"
178 "The operations for moving and copying files come in three flavors:"
180 { "A word named " { $snippet { $emphasis "operation" } } " which takes a source and destination path." }
181 { "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." }
182 { "A word named " { $snippet { $emphasis "operation" } "s-into" } " which takes a sequence of source paths and destination directory." }
184 "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."
203 "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." ;
205 ARTICLE: "io.directories" "Directory manipulation"
206 "The " { $vocab-link "io.directories" } " vocabulary defines words for inspecting and manipulating directories."
210 "io.directories.listing"
211 "io.directories.create"
213 "io.directories.hierarchy"
216 ABOUT: "io.directories"