call-with-port(3scm)

💖 call-with-port 💖

okay bestie, welcome to the Scheme Programmer's Manual, section 3scm — this little icon is all about call-with-port, and it's giving “clean up after yourself” energy. The way that it handles ports? Obsessed. 🫶

---

🌸 NAME 🌸

call-with-port — call a procedure with a port, closing it afterwards 💅

📚 LIBRARY 📚

Import situation, no cap:

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

🪄 SYNOPSIS 🪄

(call-with-port port proc)

💖 DESCRIPTION 💖

So call-with-port literally calls proc with port as an argument. That's the main character move. ✨

If proc returns, port is closed automatically and the values returned by proc are returned. Slay, automatic cleanup. 🎀

If proc does not return, port is not closed automatically, except perhaps when it is possible to prove that port will never again be used for an input or output operation. That “except perhaps” is doing a lot of heavy lifting, so don't go assuming, bestie. 😭

🔁 RETURN VALUES 🔁

Returns whatever values proc returns. Literally just passes them through. 🫶

🌟 EXAMPLES 🌟

Here's the example, exactly:

(call-with-port (open-input-file "config.scm") read)

There are also examples in the put-bytevector(3scm) and put-u8(3scm) pages. Go look, iykyk. 👀

🛠️ APPLICATION USAGE 🛠️

This procedure is a convenience that sometimes makes it easier to structure code. Not mandatory, just a cute lil helper. 💅

🧠 RATIONALE 🧠

Okay so here's the lore: because Scheme's escape procedures have unlimited extent, it is possible to escape from the current continuation but later to resume it. If implementations were permitted to close the port on any escape from the current continuation, then it would be impossible to write portable code using both call-with-current-continuation(3scm) and call-with-port(3scm). That's the whole reason, bestie. 🤯

🧩 COMPATIBILITY 🧩

This procedure is identical in R6RS and R7RS, apart from the differences in error handling. Same vibe, different error drama. 🦋

🚨 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. In particular, this is raised if procedure does not accept one argument. 💀
• 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, “fail catastrophically” is the actual phrase, so... yeah. 😭

👀 SEE ALSO 👀

• call-with-bytevector-output-port(3scm)
• call-with-string-output-port(3scm)
• call-with-input-file(3scm)
• with-input-from-file(3scm)

📜 STANDARDS 📜

R6RS, R7RS. Both. Periodt. ✨

🕰️ HISTORY 🕰️

This procedure is new in R6RS and later also became new in R7RS. Glow-up timeline, honestly. 🌈

💌 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/. 🫶

---

mwah 💋 this cutie is the call-with-port(3scm) page, dated 2022-05-01 — source/version and date, right there, no cap. 🎀