(doc-group io «Files and input/output functionality.»)(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 #o755)) «Create the directory (directories) if they do not already exist. Each directory is created with the default mode bits `#o755`, unless it already exists.» :doc-group io)(defdoc (file path (mode #o644) (:read NIL) (:write NIL) (:create NIL) (:truncate NIL) (:append NIL)) «Open a file for input and/or output. An `io` object is returned. Without any modes specified the file must already exist and is opened in read-only mode. Files are created with the default mode bits `#o644`.» :doc-group io)(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)
(doc-group io
«Files and input/output functionality.»)
(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 #o755))
«Create the directory (directories) if they do not already exist.
Each directory is created with the default mode bits `#o755`,
unless it already exists.»
:doc-group io)
(defdoc (file path (mode #o644)
(:read NIL)
(:write NIL)
(:create NIL)
(:truncate NIL)
(:append NIL))
«Open a file for input and/or output.
An `io` object is returned. Without any modes specified the file
must already exist and is opened in read-only mode.
Files are created with the default mode bits `#o644`.»
:doc-group io)
(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)