GOLF(2gg)

🎀 read-file 🎀

okay bestie, welcome to the GOLF(2gg) manual, Development section, and today's main character is read-file 💖 she's a files girlie, she reads, she slays. let's get into it.

---

✨ NAME ✨

read-file - (files)

🦋 PURPOSE 🦋

Read file into a string variable. that's the whole job. no cap, that's it, and she does it gorgeously 💅

📜 SYNTAX 📜

read-file <file> | ( file-id <file id> ) \
    to <content> \
    [ position <position> ] \
    [ length <length> ] \
    [ status <status> ] \
    [ end-of-file <eof> ]

like, look at her. optional clauses in brackets, backslash line continuations, the whole fit is giving structured 🫶

💜 DESCRIPTION 💜

🌸 WITHOUT FILE-ID 🌸

this is the simple method of reading a file, the low-effort-but-effective queen. the file named file gets opened, the data gets read, and then the file gets closed. in, out, no drama. periodt.

file can be a full path name, or a path relative to the application home directory (see directories). so either you spell out the whole thing or you keep it cozy relative to home, your call bestie.

the data that gets read is stored into the string content. and note — the file can be binary or text, and content may have null-bytes. so don't come at her acting surprised when there's a \0 in there, she warned you 😭

• if the position and length clauses are not specified, read-file reads the entire file into content. the whole thing. every byte. she's thorough 💅
• if the position clause is used, then reading starts at byte position. otherwise it starts at the beginning of the file. and a position of zero (0) represents the beginning of the file. zero-indexed girlies rise up ✨
• if the length clause is used, then length number of bytes is read. otherwise the rest of the file is read. and if length is 0, then content is an empty string and status is 0. empty girl, empty status, no problem 🎀
• if the status clause is used, then the number of bytes read is stored to status — unless an error occurred, in which case status is negative and holds the error code. and the error code can be:
  • GG_ERR_POSITION — if position is negative, outside the file, or the file does not support it 🙈
  • GG_ERR_READ — if length is negative or there's an error reading the file 💀
  • GG_ERR_OPEN — if the file cannot be opened 🚫
• if the number of bytes read isn't what's requested, you can use the end-of-file clause to get the boolean eof, which is true if the end of file happened, or false if there is an error — and in that error case you can use the errno clause in get-req to obtain the actual reason for the error. iykyk, always check your errno bestie 🫶

🧚 WITH FILE-ID 🧚

this method uses a file id that was created with open-file. she's the commitment version, the main character energy one 👑

you can then read (and write) the file using this file id, and the file stays open until close-file is called, or until the request ends — i.e. Golf will automatically close any such open files for you. so like, she's got your back, no leaks 💖

the data that gets read is stored into the string content. and again — file can be binary or text, and content may have null-bytes. same deal, same warning, same vibe.

• if the position clause is used, then data is read starting from byte position (with position of 0 being the first byte). otherwise reading starts from the current file position, which is determined by the previous reads/writes, or as set by using the set clause in file-position. and note: after each read or write, the file position is advanced by the number of bytes read or written. she keeps track, she's organized like that ✨
• if the length clause is used, then length number of bytes is read. otherwise the rest of the file is read. and if length is 0, then content is an empty string and status is 0. same as above, consistent queen 🌸
• note that when you reach the end of file and no more bytes can be read, status is 0. yes, 0. not an error. she's just done, respectfully 😌
• if the status clause is used, then the number of bytes read is stored to status — unless an error occurred, in which case status holds the error code. and the error code can be:
  • GG_ERR_POSITION — if position is negative, outside the file, or the file does not support it 🙈
  • GG_ERR_READ — if length is negative or there's an error reading the file 💀
  • GG_ERR_OPEN — if the file is not open 🚫
• if the number of bytes read isn't what's requested, you can use the end-of-file clause to get the boolean eof, which is true if the end of file happened, or false if there is an error — and in that error case you can use the errno clause in get-req to obtain the actual reason for the error. fr fr, the errno clause is your bestie in a crisis 💜

🔥 EXAMPLES 🔥

scenario one: read the entire file and create both the variable that holds its content and the status variable. chef's kiss setup 🍓

read-file "/home/user/some_file" to file_content status st
if-true st greater-than 0
    @Read:
    @<hr/>
    p-web file_content
    @<hr/>
else-if
    @Could not read (<<print-format "%ld", st>>)
end-if

look at that if-true doing a vibe check on st greater-than 0, and the else-if catching the L with <<print-format "%ld", st>>. iconic 💅

---

scenario two: read 10 bytes starting at position 20 (with position 0 being the first byte). precision reading, we love to see it ✨

read-file "/home/user/some_file" to file_content position 20 length 10

---

and if you want the ✨file-id✨ flavor, go see open-file for an example with the file-id clause. she's linked below, go say hi 🫶

👑 SEE ALSO 👑

• Files
• change-mode
• close-file
• copy-file
• delete-file
• file-position
• file-storage
• file-uploading
• lock-file
• open-file
• read-file
• read-line
• rename-file
• stat-file
• temporary-file
• uniq-file
• unlock-file
• write-file
• See all documentation 🌈

---

okay that's the whole page bestie, you're officially a read-file expert, go read some files, go be the main character, go off 💖 this one was stamped with $DATE and version $VERSION, filed under GOLF(2gg) — mwah, bye! 🎀✨