(doc-group io
  «Files and input/output functionality.»)

(defdoc *io-default-dir-mode*
  «Default mode bits when creating new directories.

   It is set to `#o755` at startup.»
  :doc-group io
  :doc-see *io-default-file-mode*
  :doc-see path-make-dir)

(defdoc *io-default-file-mode*
  «Default mode bits when creating new files.

   It is set to `#o644` at startup.»
  :doc-group io
  :doc-see *io-default-dir-mode*
  :doc-see file)

(defdoc *print-width*
  «Current maximal visible width (in terminal cells) of strings printed or `NIL`
   if strings are to be printed in full.

   Truncation does not occur in the middle of a code point or a grapheme cluster.

   Note: if a string contains an invalid rune or a control character for which
   its width is undefined, the string is printed in full if the rune in question
   would fit otherwise.»
  :doc-example
  «(with-bindings ((*print-width* 3)) (princ "abcde"))
   ; ‼ abc...»
  :doc-example
  «(with-bindings ((*print-width* 3)) (princ "ab𲎿"))
   ; ‼ ab...»
  :doc-group io
  :doc-see princ)

(defdoc *stderr*
  «Standard error output IO stream.»
  :doc-group io
  :doc-see *stdout*
  :doc-see *stdin*)

(defdoc *io-err*
  «Current (default) error output IO stream.

   Functions may use `*io-err*` for error output, which then can be
   redirected to a different IO using `with-bindings`.»
  :doc-group io
  :doc-see *io-out*
  :doc-see *io-in*
  :doc-see with-bindings)

(defdoc *stdout*
  «Standard output IO stream.»
  :doc-group io
  :doc-see *stderr*
  :doc-see *stdin*)

(defdoc *io-out*
  «Current (default) output IO stream.

   Functions may use `*io-out*` for output, which then can be redirected
   to a different IO using either `with-output-to` or (a more general)
   `with-bindings`.»
  :doc-group io
  :doc-see *io-err*
  :doc-see *io-in*
  :doc-see with-output-to)

(defdoc *stdin*
  «Standard input IO stream.»
  :doc-group io
  :doc-see *stdout*
  :doc-see *stderr*)

(defdoc *io-in*
  «Current (default) input IO stream.

   Functions may use `*io-in*` for input, which then can be redirected
   from a different IO using either `with-input-from` or (a more general)
   `with-bindings`.»
  :doc-group io
  :doc-see *io-out*
  :doc-see *io-err*
  :doc-see with-input-from)

(defdoc (path-delete path)
  «Delete the name from the filesystem.

   Throws an IO error if the path does not exist or it failed to be
   removed.»
  :doc-group io
  :doc-see path-exists?
  :doc-see path-rename)

(defdoc (path-rename old new)
  «Rename a file or a directory.

   Throws an IO error if the path does not exist or it failed to be
   rename. On most operating systems (not Plan 9), files can be moved
   between directories.»
  :doc-group io
  :doc-see path-delete
  :doc-see path-exists?)

(defdoc (path-exists? path)
  «Return `T` if `path` exists on the filesystem, `NIL` otherwise.»
  :doc-group io
  :doc-see file
  :doc-see path-delete)

(defdoc (path-cwd (to NIL))
  «Return the full path to the current directory of the process, or
   change it to the path specified with `to` argument.»
  :doc-group io
  :doc-see path-exists?)

(defdoc (path-make-dir path (mode *io-default-dir-mode*))
  «Create the directory (directories) if they do not already exist.

   Each directory is created, unless it already exists, with the mode
   bits `*io-default-dir-mode*` if not specified.»
  :doc-group io
  :doc-see *io-default-dir-mode*)

(defdoc (file path (mode *io-default-file-mode*) . flags)
  «Open a file for input and/or output.

   Files are created, when a flag `:created` is used, with the mode
   bits `*io-default-file-mode*` if not specified.

   An `io` object is returned.  Without any flags specified the file
   must already exist and is opened in read-only mode.

   Supported flags:

       :append
       :create
       :exclusive
       :read
       :remove-when-closed ; only on Plan 9
       :truncate
       :write»
  :doc-group io
  :doc-see *io-default-file-mode*)

(defdoc (io? term)
  «Return `T` if `term` is of `io` type, `NIL` otherwise.»
  :doc-group io
  :doc-group type)

(defdoc (io->str io)
  «Return the data of the in-memory `io` buffer as a string.»
  :doc-group io)

(defdoc (io-eof? io)
  «Return `T` if `io` is currently in the "end of file" state, `NIL`
   otherwise.»
  :doc-group io)

(defdoc (eof? v)
  «Return `T` if the argument is `#<eof>`, `NIL` otherwise.

   This object is returned by IO functions to signal end of file,
   where applicable.»
  :doc-group io
  :doc-group type)

(defdoc (buffer)
  «Return an in-memory buffer of `io` type.

   In the first form an empty buffer for both reading and writing is returned.

   A read-only buffer pointing at the underlying data of `v` is returned in
   the second form. Optionally, the range of the data (measured in bytes)
   available when accessing the buffer may be limited by using `:start` and/or
   `:end` keyworded arguments.»
  :doc-example
  «(def b (buffer))
   (io-write b #vu8(#x68 #x65 #x6c #x6c #x6f))
   ; ↳ 5
   (io->str b)
   ; ↳ "hello"»
  :doc-example
  «(def b (buffer (arr 'f32 1.0 2.0 3.0 -4.0)))
   (io-pos! b 8)
   (io-read b 'p32 2)
   ; ↳ #arr(p32 #x40400000 #xC0800000)»
  :doc-group io
  :doc-see io->str)

(defdoc (buffer v (:start NIL) (:end NIL)))

(defdoc (io-filename io)
  «Return the filename of the IO object.»
  :doc-example
  «(def f (file "/dev/random"))
   (io-filename f)
   ; ↳ "/dev/random"
   (io-close f)
   (io-filename f) ; preserved even after it's closed
   ; ↳ "/dev/random"»
  :doc-example
  «(io-filename *io-out*)
   ; ↳ "*stdout*"»
  :doc-group io
  :doc-see io-filename!)

(defdoc (io-filename! io new-name)
  «Change the filename of the IO object, return the new filename.

   Changing the filename does not cause any side effects.  The filename
   is purely informative and does not necessarily reflect the actual
   path.»
  :doc-example
  «(def f (buffer))
   (io-filename b)
   ; ↳ ""
   (io-filename! b "new name") ; change the filename
   ; ↳ "new name"
   (io-filename b)
   ; ↳ "new name"»
  :doc-group io
  :doc-see io-filename)

(defdoc (io-line io)
  «Return the current line number of the IO object.

   Line number is purely informative and is only being automatically
   updated with the files opened for reading.  If the cursor position is
   changed via `io-skip` or `io-pos!`, the behavior is undefined.»
  :doc-group io
  :doc-see io-column
  :doc-see io-line!)

(defdoc (io-line! io new-line-number)
  «Change the current line number of the IO object.»
  :doc-group io
  :doc-see io-line
  :doc-see io-column!)

(defdoc (io-column io)
  «Return the current column number of the IO object.

   Column number is purely informative and is only being automatically
   updated with the files opened for reading.  If the cursor position is
   changed via `io-skip` or `io-pos!`, the behavior is undefined.»
  :doc-group io
  :doc-see io-line
  :doc-see io-column!)

(defdoc (io-column! io new-column-number)
  «Change the current column number of the IO object.»
  :doc-group io
  :doc-see io-column
  :doc-see io-line!)

(defdoc (io-pos io)
  «Return the current absolute position within the IO object in bytes.»
  :doc-example
  «(def f (buffer))
   (io-write f "hello, world!")
   (io-pos f)
   ; ↳ 13»
  :doc-group io
  :doc-see io-pos!)

(defdoc (io-pos! io new-position)
  «Change the current absolute position within the IO object in bytes,
   return the resulting position.»
  :doc-example
  «(def f (buffer))
   (io-write f "hello, world!")
   (io-pos! f 64)
   ; ↳ 13
   (io-pos! f 7)
   ; ↳ 7
   (read f)
   ; ↳ world!»
  :doc-group io
  :doc-see io-pos
  :doc-see io-skip)

(defdoc (io-close io)
  «Close the IO object.

   No further operations on the IO object are possible, those will throw
   an exception if attempted.  The only exception is `(io-filename io)`,
   which might be useful in some cases for debugging purposes.»
  :doc-example
  «(def f (file "/dev/random"))
   (io-read f 'u8)
   ; ↳ #u8(123)
   (io-close f)
   (io-read f 'u8)
   ; ‼ I/O error: closed file»
  :doc-group io
  :doc-see file)

(defdoc (io-skip io offset (:end NIL))
  «Update the current absolute position within the IO object by the
   relative offset in bytes, return the resulting absolute position.

   To specify the position relative to the end of the file, use the
   optional `:end T` argument with a negative offset.»
  :doc-example
  «(def f (buffer))
   (io-write f "hello, world!")
   (io-skip f -6 :end T)
   ; ↳ 7
   (read f)
   ; ↳ world!»
  :doc-group io
  :doc-see io-pos!)

(defdoc (io-write io v (endian +endianness+))
  «Write the value to the IO object, return the number of bytes written.

   The value may be a string, a fixed-width number or pointer, a rune,
   or an array.

   Numerical values may be written in a specific endianness order by
   setting `endian` to either `:little-endian` or `:big-endian`.  Host
   CPU endianness is used if not specified.

   When writing a rune or an array of runes, they will be converted and
   written as a UTF-8 string.»
  :doc-example
  «(io-write *stdout* "hello")
   ; ‼ hello
   ; ↳ 5»
  :doc-example
  «(io-write *stdout* (u32 #x44434241) :little-endian)
   ; ‼ ABCD
   ; ↳ 4»
  :doc-example
  «(io-write *stdout* #\λ)
   ; ‼ λ
   ; ↳ 2»
  :doc-example
  «(io-write *stdout* (arr 'rune #\λ #\= #\l #\a #\m #\b #\d #\a))
   ; ‼ λ=lambda
   ; ↳ 9»
  :doc-group io
  :doc-see io-read)

(defdoc (io-read io type (endian +endianness+)))

(defdoc (io-read io type (n NIL) (endian +endianness+))
  «Return a value of the specified type by reading it from the IO
   object.

   The `type` must specify a fixed-width number, pointer, or rune.

   Numerical values may be read in a specific endianness order by setting
   `endian` to either `:little-endian` or `:big-endian`.  Host CPU
   endianness is used if not specified.

   If the parameter `n` is provided, read `n` values of the type,
   returning an array of the values or a string when `type` is `utf8`.»
  :doc-example
  «(io-read f 'utf8 5)
   ; ↳ "hello"»
  :doc-example
  «(io-read f 'u32)
   ; ↳ 57»
  :doc-example
  «(io-read f 'u32 3)
   ; ↳ #arr(u32 0 1 2)»
  :doc-example
  «(io-read f 'rune 6)
   ; ↳ #arr(rune #\λ #\a #\m #\b #\d #\a)»
  :doc-group io
  :doc-see io-write
  :doc-see io-read-until)

(defdoc (io-peek io type (endian +endianness+)))

(defdoc (io-peek io type (n NIL) (endian +endianness+))
  «Return a value of the specified type by peeking at data of the IO
   object.

   Compared to `io-read`, this function does not consume the data -
   multiple repeated calls with the same arguments will return the
   same result.

   The `type` must specify a fixed-width number, pointer, or rune.

   Numerical values may be peeked at in a specific endianness order
   by setting `endian` to either `:little-endian` or `:big-endian`.
   Host CPU endianness is used if not specified.

   If the parameter `n` is provided, peek `n` values of the type,
   returning an array of the values or a string when `type` is `utf8`.»
  :doc-example
  «(io-peek f 'utf8 5)
   ; ↳ "hello"»
  :doc-example
  «(io-peek f 'u32)
   ; ↳ 57»
  :doc-example
  «(io-peek f 'u32 3)
   ; ↳ #arr(u32 0 1 2)»
  :doc-example
  «(io-peek f 'rune 6)
   ; ↳ #arr(rune #\λ #\a #\m #\b #\d #\a)»
  :doc-group io
  :doc-see io-read)

(defdoc (io-read-until io r)
  «Return a string by reading from the IO object until encountering the
   delimiting rune `r`.  The returned string includes the delimiter.»
  :doc-group io
  :doc-see io-read)

(defdoc (io-copy-until io-dest io-src r)
  «Copy bytes from the source IO object to the destination until
   encountering the delimiting rune `r` and return the number of bytes
   copied.  The copied bytes include the delimiter.»
  :doc-group io
  :doc-see io-copy)

(defdoc (io-copy io-dest io-src (n NIL))
  «Copy bytes from the source IO object to the destination and return
   the number of bytes copied.  If `n` is provided, copy up to that many
   bytes.»
  :doc-group io
  :doc-see io-copy-until)

(defdoc (io-buffer-mode io)
  «Return the output buffering mode of the writable IO.

   Possible values include:

   * `NIL` - no buffering, data is written immediately
   * `:line` - data is written when `#\newline` is encountered
   * `:block` - data is written when the buffer is full
   * `:memory` - the IO is an in-memory buffer itself»
  :doc-group io
  :doc-see io-buffer-mode!)

(defdoc (io-buffer-mode! io)
  «Changed the output buffering behavior of the writable IO, return the
   applied value.

   See `io-buffer-mode` for supported modes.»
  :doc-group io
  :doc-see io-buffer-mode)

(defdoc (io-discard-buffer io)
  «Discard the contents of the output buffer of the writable IO.»
  :doc-group io
  :doc-see io-flush
  :doc-see io-buffer-mode)

(defdoc (io-flush io)
  «Flush the contents of the output buffer to the underlying IO.»
  :doc-group io
  :doc-see io-discard-buffer
  :doc-see io-buffer-mode)

(defdoc (io-truncate io nbytes)
  «Truncate the underlying IO object to the specified number of bytes.»
  :doc-group io)

(defdoc (find-program name)
  «Returns the full path to an executable by its name, or `NIL` if not found.»
  :doc-example
  «(find-program "ls")
   ; ↳ "/usr/bin/ls"»
  :doc-group io
  :doc-see make-process)