get-line(3scm)

💖 get-line, read-line — read a line from a port 💖

okay so bestie, this is get-line(3scm) from the Scheme Programmer's Manual, and it's literally the cutest little line-reading situation. she reads a line, she gives you a string, she's iconic, periodt. let's get into it 🎀

---

✨ NAME ✨

get-line, read-line — read a line from a port

📚 LIBRARY 📚

import these, depending on your whole vibe:

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

🦋 SYNOPSIS 🦋

(get-line textual-input-port)       ;R6RS
(read-line)                         ;R7RS
(read-line textual-input-port)      ;R7RS

🌸 DESCRIPTION 🌸

so what she does 💅 she reads from textual-input-port up to and including the linefeed character, or end of file — whichever comes first. characters get decoded in the same manner as get-string-n(3scm) and get-string-n!(3scm), iykyk.

if a linefeed character is read, then you get back a string containing all of the text up to (but not including) that linefeed character — and the port gets updated to point just past the linefeed character. slay, she moves on. ✨

if an end of file is encountered before any linefeed character is read, but some characters have been read and decoded as characters, then you get a string containing those characters. she's not gonna leave you empty-handed 🫶

if an end of file is encountered before any characters are read at all, then the end-of-file object is returned. that's it. that's the whole mood. 😭

R6RS — if the port's end-of-line style is not none then all line endings will be read as linefeed characters. the transcoder is doing the work, bestie 🧚

R7RS — for the purpose of this procedure, an end of line consists of either a linefeed character, a carriage return character, or a sequence of a carriage return character followed by a linefeed character. implementations may also recognize other end of line characters or sequences. giving "choose your own adventure" fr fr.

and the default value for textual-input-port is the value returned by current-input-port(3scm). so if you're lazy (affectionate) you can just call her with no args 💜

👑 RETURN VALUES 👑

these procedures return a single value, which is either a string or an end of file object. one value. that's the whole bag. 🎀

🔥 EXAMPLES 🔥

return all records in /etc/passwd — look at her go:

;; Return all records in /etc/passwd
(with-input-from-file "/etc/passwd"
  (lambda ()
    (let lp ()
      (let ((line (get-line (current-input-port))))
         (if (eof-object? line)
             '()
             (cons line (lp)))))))

recursive loop, builds a list, checks eof-object? — she ate and left no crumbs 🔥

💅 APPLICATION USAGE 💅

this procedure is used to read from linefeed-delimited files. simple as that. linefeed-delimited files are literally her whole thing, it's her main character energy ⭐

🌈 COMPATIBILITY 🌈

the R6RS and R7RS variants of this procedure are identical with some subtle differences in how linefeeds are recognized. okay so:

in R6RS, the port's transcoder is responsible for recognizing character sequences that make up linefeeds, and for translating them into a single linefeed character. this part of the transcoder is active if the eol-style is not none. so the port's doing all the heavy lifting 🧚

the R7RS variant essentially works as if ports can only have eol-style none, and moves the recognition of linefeeds into the read-line procedure. this also implies that read-char (3scm) should return each character that makes up a linefeed sequence — such as carriage return followed by linefeed. so like, read-char sees the raw pieces, no folding. 🙈

also!! R6RS has a single end-of-file object, but R7RS implementations may have several. not one, multiple. wild, I know 💀

🍓 ERRORS 🍓

this procedure can raise exceptions with the following condition types:

• &i/o-read (R6RS) — there was a read error that occurred during an I/O operation.
• &assertion (R6RS) — the wrong number of arguments was passed, or an argument was outside its domain.

R7RS — the situations described above are errors. implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically. and yes, catastrophic failure is on the menu 😭 like, pick your fighter.

⭐ SEE ALSO ⭐

get-char(3scm), read(3scm), eol-style(7scm)

go read those too, bestie, they're all connected 🫶

🎀 STANDARDS 🎀

R6RS, R7RS — certified, standard-approved, no cap ✨

🦋 HISTORY 🦋

this procedure first appeared in R6RS. the R7RS variant is described with text mostly taken from R6RS. so she's got lore 👑

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

---

okay that's the whole page!! 💖 source/version is the Scheme Programmer's Manual's get-line(3scm) page, dated 2022-05-06 — go read a line, bestie, you got this 🫶✨🌸