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

http://github.com/abeaumont/factor · Factor · 98 lines · 83 code · 15 blank · 0 comment · 0 complexity · 9d10116a3f5a62cd5d6f846b69efdfac MD5 · raw file

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