get-char(3scm)

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

💖 get-char(3scm) — a whole page about grabbing one (1) character 💖

ok so this is a page from the Scheme Programmer's Manual (yes, the actual manual manual, we're fancy now ✨) and it's all about get-char and read-char — the little icons that pull a single character out of a textual input port. one character. that's the whole vibe. 🎀

🌸 NAME 🌸

get-char, read-char — read a character from a textual input port

like, one character, bestie. one. 💅

🦋 LIBRARY 🦋

the import lines, exactly as they live, no edits no cap:

(import (rnrs))                     ;R6RS
(import (rnrs io ports))            ;R6RS
(import (rnrs io simple))           ;R6RS, read-char
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

note that read-char specifically shows up in (rnrs io simple) for the R6RS girlies 👑

✨ SYNOPSIS ✨

(get-char textual-input-port)       ;R6RS only
(read-char)
(read-char textual-input-port)

get-char is R6RS only, okay? she's exclusive. read-char is the social one, she'll take an argument or not. 🫶

💜 DESCRIPTION 💜

so here's the tea: it reads from textual-input-port, and it blocks as necessary until one of these three things goes down:

  • a character is available from textual-input-port, or
  • the data that are available cannot be the prefix of any valid encoding, or
  • an end of file is reached.

if a complete character is available before the next end of file, that character gets returned, and the input port is updated to point past that character. bye bye character, you've been consumed 💅

if an end of file is reached before any data are read, you get the end-of-file object back. that's it. that's the whole thing.

and if textual-input-port is omitted (very "no thoughts head empty" of you), it defaults to the value returned by current-input-port(3scm). cute. 🎀

🔥 RETURN VALUES 🔥

returns a single value — either a character or an end-of-file object. just one. one value. no bundles, no packages.

R6RS — there is a single, unique end-of-file object. the end-of-file object is iconic and there is only one of her, periodt. 👑

🍓 EXAMPLES 🍓

the classic little loop that uppercases everything you feed it, verbatim:

(let lp ()
  (let ((c (read-char)))
    (unless (eof-object? c)
      (write-char (char-upcase c))
      (lp))))

she reads, she uppercases, she recurses, she stops at eof. main character energy honestly 😭🔥

🌈 COMPATIBILITY 🌈

except for differences in the supported character set and in how errors are handled, this procedure works the same everywhere. so like... basically the same everywhere. small asterisks. 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. basically you did too much or too weird, babe.
  • &i/o-decoding (R6RS) — the port's transcoder is in raise mode and it encountered an invalid byte sequence. the bytes were giving nonsense 🙈
  • &i/o-read (R6RS) — there was an I/O error during the read operation. the read simply did not read.
  • &i/o-port (R6RS) — this condition specifies the port object related to an &i/o-read condition. it's the port's little plus-one at the error party.

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. real word, real warning, do not test her 💀⚠️

🧚 SEE ALSO 🧚

the whole character-port friend group, honestly. 🫶

⭐ STANDARDS ⭐

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — she's been certified by everybody, we love a well-documented queen 👑

🎀 HISTORY 🎀

the name get-char is new for the reworked I/O in R6RS. glow-up. ✨

the read-char procedure first appeared in R2RS. a true veteran.

Scheme prior to this, running on MacLISP, had the readch function. we love an ancestor.

and LISP 1.5 had the subroutines startread, advance, and endread for reading characters from punched cards. punched cards!! literal cardboard computing, and honestly? iconic. the lore goes deep, bestie. 🃏

💜 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/.

ngl the whole point is: one character in, one character out, eof object if there's nothing left. don't overthink her. 🦋

ok that's the page!! mwah 💖 written up for the Scheme Programmer's Manual, dated 2023-02-03, filed under get-char(3scm) — go read something and slay, bestie 🌸✨💅

📦 where this page comes from