GOLF(2gg)

👑 GOLF(2gg) — the manual page, but make it a vibe ✨

okay bestie, welcome to GOLF(2gg), the Development girlies' corner of the manual 💅 we're talking about a page whose NAME is literally:

💖 NAME 💖

write-file — (files) 🦋

---

🌸 PURPOSE 🌸

Write to a file. That's it. That's the whole job. Iconic, honestly.

---

✨ SYNTAX ✨

write-file <file> | ( file-id <file id> ) \
    from <content> \
    [ length <length> ] \
    [ ( position <position> ) | ( append [ <append> ] ) ] \
    [ status <status> ]

no cap, that's the shape of it. now let's get into it 🫶

---

💜 DESCRIPTION 💜

🎀 WITHOUT FILE-ID 🎀

This is the simple-girl method of writing a file, and honestly? obsessed. A file named <file> gets opened, data gets written, and the file gets closed. clean, simple, no loose ends. 💅

<file> can be a full path name, OR a path relative to the application home directory (peep directories for that one 🌈).

write-file writes <content> to <file>. here's the tea though:

• if the "append" clause is used without the boolean variable <append>, or if <append> evaluates to true → the <content> is appended to the file 🍓
• otherwise the file is overwritten with <content> 💀
• UNLESS the "position" clause is used — in that case the file is not overwritten, and <content> is written at byte <position> (with 0 being the first byte). and yes bestie, <position> can be beyond the end of file, in which case null-bytes get written between the current end of file and <position>. the void gets filled in fr fr.

The file is created if it does not exist (even if "append" is used) — unless the "position" clause is used, in which case the file must exist. so like, position mode is not for making new friends 🙈

If "length" is not used, then a whole string <content> is written to the file, and the number of bytes written is the length of that string. If "length" is specified, then exactly <length> bytes are written. exactly. no more, no less. periodt. ⭐

If the "status" clause is used, then the number of bytes written is stored to <status>, unless an error occurred, in which case <status> has the error code. and the error code can be:

• GG_ERR_POSITION — if <position> is negative or the file does not support it 😭
• GG_ERR_WRITE — if there is an error writing the file 💀
• GG_ERR_OPEN — if the file cannot be open 🔥

---

🦋 WITH FILE-ID 🦋

This method uses a <file id> that was created with open-file. you can then write (and read!) the file using this <file id>, and the file stays open until close-file is called or the request ends. main character energy, keeping the file alive 👑

If the "position" clause is used, then data is written starting from byte <position>. otherwise, writing starts from the current file position, which was determined by the previous reads/writes, or as set by using the "set" clause in file-position. after each read or write, the file position is advanced by the number of bytes read or written. and yes, position can be set passed the last byte of the file, in which case writing will fill the space between the current end of file and the current position with null-bytes 🌈 (again with the null-bytes, the void stays hungry)

If "length" is not used, then a whole string is written to a file, and the number of bytes written is the length of that string. If "length" is specified, then exactly <length> bytes are written. same energy as before 💖

If the "append" clause is used without the boolean variable <append>, or if <append> evaluates to true, then the file pointer is set at the end of file and data written. 🍓

If the "status" clause is used, then the number of bytes written is stored to <status>, unless an error occurred, in which case <status> has the error code. the error code can be:

• GG_ERR_POSITION — if <position> is negative or the file does not support it 😭
• GG_ERR_WRITE — if there is an error writing the file 💀
• GG_ERR_OPEN — if the file is not open 🔥

---

🔥 EXAMPLES 🔥

To overwrite file "/path/to/file" with "Hello World":

write-file "/path/to/file" from "Hello World"

To append "Hello World" to file:

set-string path="/path/to/file"
set-string cont="Hello World"
write-file path from cont append

To write only 5 bytes (i.e. "Hello") and get status (if successful, number "st" would be "5"):

set-string cont="Hello World"
write-file "file" from cont length 5 status st

To write a string "Hello" at byte position 3 in the existing "file":

set-string cont="Hello"
write-file "file" from cont position 3 status st

See open-file for an example with the "file-id" clause. 🫶

---

🌈 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 — and "See all documentation" ✨

---

okay that's the whole page bestie, you ate 💅 this was $VERSION, dated $DATE, and it's giving GOLF(2gg) energy — go write some files, mwah 🎀