core/io/files/files-docs.factor

   1 USING: help.markup help.syntax io strings arrays io.backend
   2 io.files.private quotations sequences ;
   3 IN: io.files
   4
   5 ARTICLE: "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
  17 ARTICLE: "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
  39 ABOUT: "io.files"
  40
  41 HELP: <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
  47 HELP: <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
  53 HELP: <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
  59 HELP: 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
  64 HELP: 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
  69 HELP: 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
  74 HELP: 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
  79 HELP: 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
  84 HELP: 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
  89 HELP: 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
  96 HELP: exists?
  97 { $values { "path" "a pathname string" } { "?" "a boolean" } }
  98 { $description "Tests if the file named by " { $snippet "path" } " exists." } ;