lookahead-char(3scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💅 lookahead-char(3scm) — the Scheme Programmer's Manual, but make it cute 🎀

okay bestie, so this page lives in the Scheme Programmer's Manual, and it's all about lookahead-char and peek-char — the two functions that let you sneak a glance at the next character without actually committing to it. like window shopping for characters. iconic behaviour honestly 🦋

✨ NAME ✨

lookahead-char, peek-char — peek at the next character from a port 👀

📚 LIBRARY 📚

which import you need depends on which name you're using, no cap:

;; lookahead-char
(import (rnrs))                     ;R6RS
(import (rnrs io ports))            ;R6RS

;; peek-char
(import (rnrs))                     ;R6RS
(import (rnrs io simple))           ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

🌸 SYNOPSIS 🌸

the whole vibe, in three lines:

(lookahead-char textual-input-port) ;R6RS
(peek-char)
(peek-char textual-input-port)

💖 DESCRIPTION 💖

So what it does: it reads a character from textual-input-port — but without updating the port to point past that character. so the character is still there, waiting for you, like a bestie saving your seat 💅

This procedure blocks as necessary until a character is available — or until the data that are available cannot be the prefix of any valid encoding — or until an end of file is reached. yes, it will just sit there and wait. patiently. like a good friend. 😭

If a complete character is available before the next end of file, this procedure returns that character. periodt.

If an end of file is reached before any data are read, this procedure returns the end-of-file object. (that's the sad little "nothing left ✨" object.)

If textual-input-port is omitted, it defaults to the value returned by current-input-port(3scm). so like, it just uses the standard input, ngl very convenient 🫶

🔧 IMPLEMENTATION NOTES 🔧

okay this part is a little nerdy but it matters:

  • With the standard UTF-8, UTF-16 and UTF-32 transcoders, up to four bytes of lookahead may be needed.
  • They may additionally skip over the BOM at the start of a file, in which case two to four bytes are skipped over. 🙈
  • Nonstandard transcoders may need even more lookahead. yeah. more. 💀

🎁 RETURN VALUES 🎁

Returns a single value — either a character or an end of file object. that's it. one value. main character energy, no extras.

🍓 EXAMPLES 🍓

this one demonstrates one way to parse /etc/passwd using peek-char. yes, that /etc/passwd. we're being productive today 🌈

;; This demonstrates one way to parse /etc/passwd
;; using peek-char.
(import (scheme base) (scheme file) (scheme write))

(define (get-string-until-chars p terminators)
  (let lp ((chars '()))
    (let ((c (peek-char p)))
      (cond ((or (eof-object? c)
                 (memv c terminators))
             ;; Take the characters we found up until
             ;; the terminator and return them as
             ;; a string.
             (list->string (reverse chars)))
            (else
             (lp (cons (read-char p) chars)))))))

(define (get-record p)
 (let lp ((fields '()))
   (let* ((field (get-string-until-chars p '(#\: #\newline)))
          (terminator (read-char p)))
     (cond ((and (eof-object? terminator) (null? fields))
            ;; Returns the end-of-file object
            terminator)
           ((or (eof-object? terminator)
                (eqv? terminator #\newline))
            ;; The record was terminated with or
            ;; without a newline.
            (reverse (cons field fields)))
           (else
            ;; Save the field from the record.
            (lp (cons field fields)))))))

(call-with-input-file "/etc/passwd"
  (lambda (p)
    ;; Read records from the port and write them as lists to standard
    ;; output until the end of the file.
    (let lp ()
      (let ((record (get-record p)))
        (unless (eof-object? record)
          (write record)
          (newline)
          (lp))))))

and the R7RS program above prints something like this:

;; The R7RS program above prints something like this:
;;
;; ("root" "x" "0" "0" "root" "/root" "/bin/bash")
;; ("daemon" "x" "1" "1" "daemon" "/usr/sbin" "/usr/sbin/nologin")
;; ("bin" "x" "2" "2" "bin" "/bin" "/usr/sbin/nologin")
;; ...

slay. it read the whole password file. 🔥

🌟 APPLICATION USAGE 🌟

These procedures are commonly used in a certain style of parsers — the kind that dispatch on the next character from the input. peek first, decide later. the iconique parser move 👑

🧠 RATIONALE 🧠

so why not just do the opposite thing? well, an alternative to providing lookahead would be to provide a procedure like ungetc(3), which "unreads" a character from a port. but that raises questions of how many characters it should be possible to unread. 🤔

Normally in Scheme one would not want there to be a limit for this case — but such a requirement would demand a less efficient implementation of read-char(3), which is also not in line with how Scheme is normally designed. so yeah. lookahead ate, ungetc didn't. 💅

🦋 COMPATIBILITY 🦋

Except for R7RS's variations in which types of ports and characters are supported, these procedures work the same everywhere. so like, same energy across implementations 🫶 The lookahead-char(3scm) name is unique to R6RS — that one's an R6RS exclusive, iykyk.

💀 ERRORS 💀

This procedure can raise exceptions with the following condition types. pay attention bestie, this is the part where things go sideways:

  • &assertion (R6RS) — The wrong number of arguments was passed or an argument was outside its domain.
  • &i/o-port (R6RS) — This condition is included with the conditions below and contains textual-input-port.
  • &i/o-read-error (R6RS) — There was a read error during the I/O operation.
  • &i/o-decoding (R6RS) — The input from a port cannot be translated into a character by the port's transcoder and the transcoder's error-handling-mode(7scm) is raise.
⚠️ R7RS — The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically. yes. catastrophically. 😭

🎀 SEE ALSO 🎀

⭐ STANDARDS ⭐

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — certified across basically every scheme standard, we love to see it 👑

🧚 HISTORY 🧚

The name lookahead-char(3scm) is new to R6RS's reworked I/O system. ✨ The peek-char(3scm) procedure first showed up in R4RS. so peek-char is the OG and lookahead-char is the glow-up 💖

💜 AUTHORS 💜

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/. 🫶

🙈 BUGS 🙈

okay so this is the classic one: these procedures are prone to a type of bug where you forget to consume data from the port following a peek, resulting in an infinite loop of peeking. 😭💀

peek... peek... peek... nothing is read... peek... it never ends. don't do this. please read the character after you peek, bestie. fr fr.

that's the whole page!! sign-off time: this was the lookahead-char(3scm) page from the Scheme Programmer's Manual, dated 2023-01-21 — go peek at something cute today, and remember to actually consume it afterwards 🌸🎀💖

📦 where this page comes from