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" "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 ABOUT: "io.files"
  21
  22 HELP: <file-reader>
  23 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an input stream" } }
  24 { $description "Outputs an input stream for reading from the specified pathname using the given encoding." }
  25 { $notes "Most code should use " { $link with-file-reader } " instead, to ensure the stream is properly disposed of after." }
  26 { $errors "Throws an error if the file is unreadable." } ;
  27
  28 HELP: <file-writer>
  29 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
  30 { $description "Outputs an output stream for writing to the specified pathname using the given encoding. The file's length is truncated to zero." }
  31 { $notes "Most code should use " { $link with-file-writer } " instead, to ensure the stream is properly disposed of after." }
  32 { $errors "Throws an error if the file cannot be opened for writing." } ;
  33
  34 HELP: <file-appender>
  35 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
  36 { $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." }
  37 { $notes "Most code should use " { $link with-file-appender } " instead, to ensure the stream is properly disposed of after." }
  38 { $errors "Throws an error if the file cannot be opened for writing." } ;
  39
  40 HELP: with-file-reader
  41 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
  42 { $description "Opens a file for reading and calls the quotation using " { $link with-input-stream } "." }
  43 { $errors "Throws an error if the file is unreadable." } ;
  44
  45 HELP: with-file-writer
  46 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
  47 { $description "Opens a file for writing using the given encoding and calls the quotation using " { $link with-output-stream } "." }
  48 { $errors "Throws an error if the file cannot be opened for writing." } ;
  49
  50 HELP: with-file-appender
  51 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "quot" "a quotation" } }
  52 { $description "Opens a file for appending using the given encoding and calls the quotation using " { $link with-output-stream } "." }
  53 { $errors "Throws an error if the file cannot be opened for writing." } ;
  54
  55 HELP: set-file-lines
  56 { $values { "seq" "an array of strings" } { "path" "a pathname string" } { "encoding" "an encoding descriptor" } }
  57 { $description "Sets the contents of a file to the strings with the given encoding." }
  58 { $errors "Throws an error if the file cannot be opened for writing." } ;
  59
  60 HELP: file-lines
  61 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "seq" "an array of strings" } }
  62 { $description "Opens the file at the given path using the given encoding, and returns a list of the lines in that file." }
  63 { $errors "Throws an error if the file cannot be opened for reading." } ;
  64
  65 HELP: set-file-contents
  66 { $values { "seq" sequence } { "path" "a pathname string" } { "encoding" "an encoding descriptor" } }
  67 { $description "Sets the contents of a file to a sequence with the given encoding." }
  68 { $errors "Throws an error if the file cannot be opened for writing." } ;
  69
  70 HELP: file-contents
  71 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "seq" sequence } }
  72 { $description "Opens the file at the given path using the given encoding, and the contents of that file as a sequence." }
  73 { $errors "Throws an error if the file cannot be opened for reading." } ;
  74
  75 { set-file-lines file-lines set-file-contents file-contents } related-words
  76
  77 HELP: exists?
  78 { $values { "path" "a pathname string" } { "?" "a boolean" } }
  79 { $description "Tests if the file named by " { $snippet "path" } " exists." } ;