/core/io/files/files-docs.factor

 1USING: help.markup help.syntax io strings arrays io.backend
 2io.files.private quotations sequences ;
 3IN: io.files
 4
 5ARTICLE: "io.files.examples" "Examples of reading and writing files"
 6"Sort the lines in a file and write them back to the same file:"
 7{ $code
 8    "USING: io io.encodings.utf8 io.files sequences sorting ;"
 9    "\"lines.txt\" utf8 [ file-lines natural-sort ] 2keep set-file-lines"
10}
11"Read 1024 bytes from a file:"
12{ $code
13    "USING: io io.encodings.binary io.files ;"
14    "\"data.bin\" binary [ 1024 read ] with-file-reader"
15} ;
16
17ARTICLE: "io.files" "Reading and writing files"
18{ $subsections "io.files.examples" }
19"File streams:"
20{ $subsections
21    <file-reader>
22    <file-writer>
23    <file-appender>
24}
25"Reading and writing the entire contents of a file; this is only recommended for smaller files:"
26{ $subsections
27    file-contents
28    set-file-contents
29    file-lines
30    set-file-lines
31}
32"Utility combinators:"
33{ $subsections
34    with-file-reader
35    with-file-writer
36    with-file-appender
37} ;
38
39ABOUT: "io.files"
40
41HELP: <file-reader>
42{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an input stream" } }
43{ $description "Outputs an input stream for reading from the specified pathname using the given encoding." }
44{ $notes "Most code should use " { $link with-file-reader } " instead, to ensure the stream is properly disposed of after." }
45{ $errors "Throws an error if the file is unreadable." } ;
46
47HELP: <file-writer>
48{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
49{ $description "Outputs an output stream for writing to the specified pathname using the given encoding. The file's length is truncated to zero." }
50{ $notes "Most code should use " { $link with-file-writer } " instead, to ensure the stream is properly disposed of after." }
51{ $errors "Throws an error if the file cannot be opened for writing." } ;
52
53HELP: <file-appender>
54{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
55{ $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." }
56{ $notes "Most code should use " { $link with-file-appender } " instead, to ensure the stream is properly disposed of after." }
57{ $errors "Throws an error if the file cannot be opened for writing." } ;
58
59HELP: with-file-reader
60{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
61{ $description "Opens a file for reading and calls the quotation using " { $link with-input-stream } "." }
62{ $errors "Throws an error if the file is unreadable." } ;
63
64HELP: with-file-writer
65{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
66{ $description "Opens a file for writing using the given encoding and calls the quotation using " { $link with-output-stream } "." }
67{ $errors "Throws an error if the file cannot be opened for writing." } ;
68
69HELP: with-file-appender
70{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
71{ $description "Opens a file for appending using the given encoding and calls the quotation using " { $link with-output-stream } "." }
72{ $errors "Throws an error if the file cannot be opened for writing." } ;
73
74HELP: set-file-lines
75{ $values { "seq" "an array of strings" } { "path" "a pathname string" } { "encoding" "an encoding descriptor" } }
76{ $description "Sets the contents of a file to the strings with the given encoding." }
77{ $errors "Throws an error if the file cannot be opened for writing." } ;
78
79HELP: file-lines
80{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "seq" "an array of strings" } }
81{ $description "Opens the file at the given path using the given encoding, and returns a list of the lines in that file." }
82{ $errors "Throws an error if the file cannot be opened for reading." } ;
83
84HELP: set-file-contents
85{ $values { "seq" sequence } { "path" "a pathname string" } { "encoding" "an encoding descriptor" } }
86{ $description "Sets the contents of a file to a sequence with the given encoding." }
87{ $errors "Throws an error if the file cannot be opened for writing." } ;
88
89HELP: file-contents
90{ $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "seq" sequence } }
91{ $description "Opens the file at the given path using the given encoding, and the contents of that file as a sequence." }
92{ $errors "Throws an error if the file cannot be opened for reading." } ;
93
94{ set-file-lines file-lines set-file-contents file-contents } related-words
95
96HELP: exists?
97{ $values { "path" "a pathname string" } { "?" "a boolean" } }
98{ $description "Tests if the file named by " { $snippet "path" } " exists." } ;