.RKT File Format – I/O and ports

Printing

Format directives

A ~ followed by anything else, too few arguments, or too many arguments raises exn:fail:contract.

Reading

Files

#lang racket
(call-with-output-file "numbers.txt" #:exists 'replace
  (lambda (out)
    (for ([i (in-range 3)])
      (fprintf out "line ~a\n" i))))

(call-with-input-file "numbers.txt"
  (lambda (in)
    (for/list ([line (in-lines in)]) (string-upcase line))))

(file->lines "numbers.txt")                 ; '("line 0" "line 1" "line 2")
(with-output-to-string (lambda () (display "hi")))   ; "hi"
(define-values (in out) (make-pipe))
(write 'data out)
(read in)                                    ; 'data

Other ports

• String and byte ports. (open-input-string s), (open-input-bytes b), (open-output-string) and (open-output-bytes), with get-output-string and get-output-bytes to take the result. with-output-to-string, call-with-output-string and with-input-from-string (racket/port) wrap them.
• Pipes. (make-pipe) returns an input and an output port joined together.
• Network. tcp-listen, tcp-accept, tcp-connect, udp-open-socket and the others in racket/tcp and racket/udp; the ports they return are used like any other.
• Processes. subprocess, system, process, system* and find-executable-path (racket/system) start programs and give their standard ports.
• Custom ports. make-input-port and make-output-port (racket/port) and prop:input-port / prop:output-port make ports from procedures; copy-port, input-port-append, make-limited-input-port and reencode-input-port combine and convert them.
• Events. A port is an event that is ready when input can be read or output written, so sync and sync/timeout wait on several; see Concurrency.

Characters, bytes and encodings

A port is a stream of bytes. A function that reads or writes characters converts them with UTF-8: a character read is one decoded from one to four bytes, and bytes that are not valid UTF-8 read as the replacement character U+FFFD. (bytes->string/utf-8 b), (string->bytes/utf-8 s), bytes->string/latin-1 and bytes->string/locale convert whole strings; bytes-open-converter and bytes-convert convert between named encodings (through iconv); reencode-input-port and reencode-output-port do it for ports. Line endings are the program's business: 'text mode on Windows converts them, and read-line chooses the separator. Racket writes \n as a single linefeed byte.

Paths

A path is not a string. (build-path "a" "b" "c.txt"), (string->path s), (path->string p), (path-element? v), (split-path p), (simplify-path p), (path->complete-path p), (path-replace-extension p ".bak"), (path-get-extension p), (file-name-from-path p) (racket/path), (current-directory), (find-system-path 'home-dir) and (system-type) are the main tools; path-string? accepts a string that is a valid path. (build-path/convention-type 'windows …) builds paths for another system.

Not described

Known, not yet covered

• Reference: the printer's parameters (print-graph, print-struct, print-hash-table, print-boolean-long-form and the rest) and current-print, custom write (prop:custom-write), the port layer (custom ports in detail, port buffers, line and column counting, port-count-lines!), the details of encodings and converters, byte and character locations, subprocess control and TCP/UDP functions were not described. The Reference chapters on I/O were read in part (file ports, string input, write and format directives, string ports).
• Reference: the claim that bytes that are not valid UTF-8 read as U+FFFD is from memory of the Reference; the section on encodings (ports.scrbl) was downloaded and not read.
• Reference: the functions in the tables for racket/port, racket/file and racket/system are named without the full argument lists.

See also

• Strings and regexps – regular expressions work on ports as well as strings
• Lexical structure – what read accepts
• Scheme: I/O ports – the Scheme view of ports