core/io/files/files-docs.factor

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