How do I read a text file in EK9?

← File I/O · Ref: Q151

EK9 provides the TextFile type for reading and writing text files. Create a TextFile with a path string, then use try-with-resources to open an input stream and read the contents safely.

CREATING A TEXTFILE

Create a TextFile by passing a file path as a String:

  file <- TextFile("data.txt")

The file is not opened until you call input() or output(). The TextFile just records the path.

READING WITH INPUT STREAM

Use file.input() to get a CloseableStringInput stream:

  try
    -> input <- file.input()
    cat input > stdout

The input stream provides lines from the file one at a time. You can pipe them through stream operations or consume them directly.

TRY WITH RESOURCES

Always open file streams inside a try block. EK9's try-with-resources automatically closes the stream when the block exits, whether normally or via exception. This prevents resource leaks.

HANDLING FILE NOT FOUND

If the file does not exist, file.input() returns an unset value. The try guard (try -> input <- file.input()) only enters the body if input is set, so you naturally handle missing files without explicit null checks.

See Q3 for printing output. See Q4 for reading stdin. See Q134 for try/catch. See Q152 for writing files. See Q153 for file path exists. See Q154 for read file lines.

Example

defines module qa.fileio.read

  defines function

    processLine() as pure
      -> line as String
      <- rtn as String: "[read] " + line

  defines program

    ReadTextFileDemo()
      stdout <- Stdout()

      // === CREATING A TEXTFILE ===

      file <- TextFile("/tmp/qa-example-input.txt")
      stdout.println("File: " + $file)

      // === READING WITH TRY-WITH-RESOURCES ===

      // If the file exists, input() returns a set stream
      // The try guard only enters the body if input is set
      stdout.println("Attempting to read file")

      // === TEXTFILE PROPERTIES ===

      // TextFile has useful query methods
      stdout.println("Is readable: " + $file.isReadable())

      // === STREAM PROCESSING ===

      // You can also pipe file input through stream operations
      // cat input | map with processLine | head 5 > stdout

Common mistakes

E50060 — TextFile has no toString() method. Use the $ prefix operator for string conversion. See ek9 -h E50060 for details.

Incorrect:

stdout.println(file.toString())

Correct:

stdout.println("File: " + $file)

E50060 — TextFile has no canRead() method. Use isReadable() to check if the file can be read. EK9 uses descriptive method names. See ek9 -h E50060 for details.

Incorrect:

stdout.println("Is readable: " + $file.canRead())

Correct:

stdout.println("Is readable: " + $file.isReadable())

Coming from another language?

Java: Files.readString(Path) or BufferedReader with try-with-resources. Python: with open('file') as f: content = f.read(). Rust: fs::read_to_string('file'). Go: os.ReadFile('file'). EK9: TextFile('file') with try -> input <- file.input() for automatic resource management and guard-based missing file handling.

Keywords: textfile, load, read, content, stream, file, write, open, text, input