lookahead-u8(3scm)

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

💅 lookahead-u8 — the Scheme Programmer's Manual, bestie edition 🎀

okay so real talk — this page lives in the Scheme Programmer's Manual, and today we're covering lookahead-u8 and peek-u8. yes they're the same vibe, no they're not the same standard, sit down, I'll explain ✨

🌸 NAME 🌸

lookahead-u8, peek-u8 — peek at the next byte from a port 👀

like, just look. don't touch. hands off the byte.

📚 LIBRARY 📚

where you gotta import it from, depending on your whole situation:

(import (rnrs))                     ;R6RS
(import (rnrs io ports))            ;R6RS
(import (scheme base))              ;R7RS

pick your fighter, honestly 💜

✨ SYNOPSIS ✨

(lookahead-u8 binary-input-port)    ;R6RS
(peek-u8)                           ;R7RS
(peek-u8 binary-input-port)         ;R7RS

note how R7RS got that zero-argument glow-up. main character energy fr 💅

🦋 DESCRIPTION 🦋

This procedure is like get-u8(3scm), but — and this is the whole entire point — it does not update binary-input-port to point past the byte. it's giving "look but don't touch" 🫶

And if an end of file is pending, that also does not get removed. it just sits there. waiting. iconic behavior honestly.

⭐ RETURN VALUES ⭐

Returns a single value — an exact integer object, or the end of file object.

R7RS 🩷 heads up: there may be several end of file objects. yes, several. don't @ me, that's just what the standard says.

🍓 EXAMPLES 🍓

This is for R7RS. Use open-file-input-port for R6RS.
(import (scheme base) (scheme file))
(define p (open-binary-input-file "/etc/os-release"))
(peek-u8 p)  =>  80  ; P
(read-u8 p)  =>  80  ; P
(read-u8 p)  =>  82  ; R
(peek-u8 p)  =>  69  ; E
(peek-u8 p)  =>  69  ; E
(read-u8 p)  =>  69  ; E
(read-u8 p)  =>  84  ; T
(read-u8 p)  =>  84  ; T
(read-u8 p)  =>  89  ; Y

not the peek-peek-read-read combo spelling out PRETTY 😭 she ate, honestly. the peeking does literally nothing to the port, which is exactly why you can do it twice in a row and get the same 69. slay.

💜 APPLICATION USAGE 💜

You reach for this when you're parsing binary data and your parser is written to use lookahead. this is super common with handwritten parsers, and it's generally used in modular parsers — the kind that call other parsers when they see a certain byte. peek first, decide later. that's the whole strategy 🧚

🌈 COMPATIBILITY 🌈

Both one-argument versions of this procedure are compatible with each other. cute, right? 🫶

However — and this is the lowkey important part — some implementations of the R7RS procedure allow it to be used on any type of port, which is not guaranteed to work in all implementations. so like... don't count on it everywhere. iykyk 💀

💀 ERRORS 💀

This procedure can raise exceptions with the following condition types:

  • &assertion (R6RS) — the wrong number of arguments was passed, or an argument was outside its domain. classic.

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. catastrophically. love that for us 😭

👑 SEE ALSO 👑

go read those next, bestie, they're literally the siblings 💖

🎀 STANDARDS 🎀

R6RS, R7RS — double certified, no cap ✨

🌸 HISTORY 🌸

This procedure first appeared in R6RS as part of the reworked I/O system. glow-up era 🦋

🫶 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/. shoutout to the schemedoc/manpages girlies 💜

🙈 BUGS 🙈

It is relatively easy to mistakenly have this procedure consume end of file objects. like, relatively easy. watch out. be careful. don't let the eof objects get eaten, they're precious 😭

okay that's the whole page!! go peek at some bytes responsibly, bestie 🍓✨

mwah 💋 — this lil rewrite is serving lookahead-u8(3scm), dated 2023-07-20, straight from the Scheme Programmer's Manual.

📦 where this page comes from