From 0bfcc9fc97bc1db9a40d447d67f42d5e12156bda Mon Sep 17 00:00:00 2001
From: Pietro Cerutti <gahr@gahr.ch>
Date: Fri, 11 Sep 2026 00:12:54 +0200
Subject: [PATCH] Fix a couple of imprecisions in the file/ docs (#1848)

* Fix a couple of imprecisions in the file/ docs

The `+` flag to `(file/open)` was incorrectly documented as being for
appending. Instead, this allows to read to files opened with `:w` or
`:a`, and to write to files opened with `:r`. This is the same as the
`+` flag in `fopen(3)`.

The `(file/seek)` function was documented as having both `whence` and
`n` as optional arguments. It also didn't say what the default for `n`
was. Anyway, this doesn't make sense, as a default of `:cur` and `0`
would effectively make `(file/seek f)` a no-op. I also amended a test so
both `(file/seek f :set 0)` and `(file/seek f :set)` are covered and
checked to move to the beginning of the file.

* Remove useless check for argc >= 2

We already determined it is between 2 and 3 with `janet_arity(argc, 2, 3)`.

* Dump args in assertion

* Unroll loop in test

* Differentiate failure messages
---
 src/core/io.c       | 32 +++++++++++++++-----------------
 test/suite-io.janet |  5 ++++-
 2 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/core/io.c b/src/core/io.c
index 61488cb8..3bbda25b 100644
--- a/src/core/io.c
+++ b/src/core/io.c
@@ -150,7 +150,7 @@ JANET_CORE_FN(cfun_io_fopen,
               "* a - append to the file\n\n"
               "Following one of the initial flags, 0 or more of the following flags can be appended:\n\n"
               "* b - open the file in binary mode (rather than text mode)\n\n"
-              "* + - append to the file instead of overwriting it\n\n"
+              "* + - open the file for both reading and writing\n\n"
               "* n - error if the file cannot be opened instead of returning nil\n\n"
               "See fopen (<stdio.h>, C99) for further details.") {
     janet_arity(argc, 1, 3);
@@ -342,12 +342,12 @@ JANET_CORE_FN(cfun_io_fclose,
 
 /* Seek a file */
 JANET_CORE_FN(cfun_io_fseek,
-              "(file/seek f &opt whence n)",
+              "(file/seek f whence &opt n)",
               "Jump to a relative location in the file `f`. `whence` must be one of:\n\n"
               "* :cur - jump relative to the current file location\n\n"
               "* :set - jump relative to the beginning of the file\n\n"
               "* :end - jump relative to the end of the file\n\n"
-              "By default, `whence` is :cur. Optionally a value `n` may be passed "
+              "By default, `n` is 0. Optionally a value `n` may be passed "
               "for the relative number of bytes to seek in the file. `n` may be a real "
               "number to handle large files of more than 4GB. Returns the file handle.") {
     janet_arity(argc, 2, 3);
@@ -356,20 +356,18 @@ JANET_CORE_FN(cfun_io_fseek,
         janet_panic("file is closed");
     int64_t offset = 0;
     int whence = SEEK_CUR;
-    if (argc >= 2) {
-        const uint8_t *whence_sym = janet_getkeyword(argv, 1);
-        if (!janet_cstrcmp(whence_sym, "cur")) {
-            whence = SEEK_CUR;
-        } else if (!janet_cstrcmp(whence_sym, "set")) {
-            whence = SEEK_SET;
-        } else if (!janet_cstrcmp(whence_sym, "end")) {
-            whence = SEEK_END;
-        } else {
-            janet_panicf("expected one of :cur, :set, :end, got %v", argv[1]);
-        }
-        if (argc == 3) {
-            offset = (int64_t) janet_getinteger64(argv, 2);
-        }
+    const uint8_t *whence_sym = janet_getkeyword(argv, 1);
+    if (!janet_cstrcmp(whence_sym, "cur")) {
+        whence = SEEK_CUR;
+    } else if (!janet_cstrcmp(whence_sym, "set")) {
+        whence = SEEK_SET;
+    } else if (!janet_cstrcmp(whence_sym, "end")) {
+        whence = SEEK_END;
+    } else {
+        janet_panicf("expected one of :cur, :set, :end, got %v", argv[1]);
+    }
+    if (argc == 3) {
+        offset = (int64_t) janet_getinteger64(argv, 2);
     }
     if (fseek(iof->file, offset, whence)) janet_panic("error seeking file");
     return argv[0];
diff --git a/test/suite-io.janet b/test/suite-io.janet
index 23672f62..6062b518 100644
--- a/test/suite-io.janet
+++ b/test/suite-io.janet
@@ -55,7 +55,10 @@
   (file/flush f)
   (file/seek f :set 0)
   (assert (= 0 (file/tell f)) "start of file again")
-  (assert (= (string (file/read f :all)) "foo\n") "temp files work"))
+  (assert (= (string (file/read f :all)) "foo\n") "temp files work")  
+  (file/seek f :set)
+  (assert (= 0 (file/tell f)) "start of file again 2")
+  (assert (= (string (file/read f :all)) "foo\n") "temp files work 2"))
 
 # issue #1055 - 2c927ea76
 (let [b @""]