File Methods

Every method on the built-in file type, with its signature, what it returns, and the cases where it does something other than the obvious thing.

exists()

exists() -> boolean

Returns true if a file exists or false otherwise.

For example:

%> file('sample.txt').exists()
true

Returns boolean

close()

close() -> void

Closes the stream to an opened file. You’ll rarely ever need to call this method yourself in most use cases.

For example:

%> var f = file('sample.txt')
%> f.close()

Returns void

open()

open() -> void

Opens the stream to a file for the operation originally specified on the file object during creation. You may need to call this method after a call to read() if the length isn’t specified or write() if you wish to read or write again as the file will already be closed.

For example:

%> f.open()

Returns void

read()

read(length: ?int) -> string|bytes

Reads the content of an opened file up to the specified length and returns it as string or bytes if the file was opened in the binary mode. If the length is not specified, the file will be read to the end.

In text mode the bytes read must be valid UTF-8; anything else raises rather than being silently replaced. Open the file in a binary mode ('rb') to read arbitrary bytes instead. Note that io.stdin is already binary.

This method requires that the file be opened in the read mode (default mode) or a mode that supports reading. If you aren’t reading the full length of the file, you’ll need to call the close() method to free the file for further reading, otherwise, the close() method will be automatically called for you.

An example has been given above.

Parameters

• length (?int)

Returns string|bytes

gets()

gets(length: ?int) -> string|bytes

Same as read(), but doesn’t open or close the file automatically.

Parameters

• length (?int)

Returns string|bytes

write()

write(data: string|bytes) -> string|bytes

Writes a string or bytes to an opened file at the current insertion point. When the file is opened with the a mode enabled, write will always start from the end of the file. If the seek() method has been previously called, write will begin from the seeked position, otherwise it will start at the beginning of the file.

An example has been given above.

Parameters

• data (string|bytes)

Returns string|bytes

puts()

puts(data: string|bytes) -> string|bytes

Same as write(), but doesn’t open or close the file automatically.

Parameters

• data (string|bytes)

Returns string|bytes

number()

number() -> int

Returns the integer file descriptor number that is used by the underlying implementation to request I/O operations from the operating system. This can be very useful for low-level interfaces that uses or act as file descriptors.

For example:

%> file('sample.txt').number()
6

A standard stream reports the descriptor it is named by, 0, 1 or 2, rather than the private duplicate the runtime holds open for it, so number() is what tells io.stdout apart from io.stderr.

Returns int

Note: -1 on a platform with no file descriptors, and on any handle that is not currently open.

is_tty()

is_tty() -> boolean

Returns true if the file is connected to a TTY like device or false otherwise.

For example:

%> file('sample.txt').is_tty()
false
%> import io
%> io.stdout.is_tty()   # io.stdin is a file...
true

Returns boolean

is_open()

is_open() -> boolean

Returns true if the file is open for reading or writing and false otherwise.

@note: std files are always open.

For example:

%> file('sample.txt').is_open()
true

Returns boolean

is_closed()

is_closed() -> boolean

Returns true if the file is closed for reading or writing and false otherwise.

For example:

%> file('sample.txt').is_closed()
false

Returns boolean

flush()

flush() -> void

Flushes the buffer held by a file. This could be useful for writable files as file writes are buffered.

For example:

%> w.flush()

Returns void

stats()

stats() -> dict

Returns the statistics or details of a file.

For example:

%> file('sample.txt').stats()
{is_readable: true, is_writable: true, is_executable: false,
is_symbolic: false, size: 72, mode: 33188, dev: 16777230,
ino: 4865113, nlink: 1, uid: 501, gid: 20, mtime: 1631395239,
atime: 1631395271, ctime: 1631395239, blocks: 8, blksize: 4096}

Every key above is present on every platform, so reading size or mtime needs no check of which one you are on.

Returns dict

Note: Windows keeps a different set of facts about a file, and the ones it has no answer for read as 0: dev, ino, uid and gid, with nlink always 1. mode is assembled from the file’s type and its read-only attribute, so it carries the right file-type bits and either 0o444 or 0o666, widened by 0o111 for a directory or a name PATHEXT says the shell would run. ctime is the file’s creation time there, Windows having no equivalent of a Unix inode-change time.

symlink()

symlink() -> boolean

Creates a symbolic link for the original file at the specified path.

For example:

%> file('sample.txt').symlink('sample2.txt')
true

Returns boolean

Note: Windows decides at creation time whether a link stands for a file or a directory, so the original is inspected first; one pointing at something that does not exist yet is made as a file link. Creating any symbolic link there is privileged, and fails unless the machine is in developer mode or the process is elevated.

delete()

delete() -> boolean

Deletes a file.

For example:

%> file('test-2.zu').delete()
true

Returns boolean

Note: If the file is opened by one or more processes or threads outside of the current process or thread, the file will not be deleted until the last process frees it.

Note: This method throws Error on failure.

rename()

rename(new_name: string) -> boolean

Renames a file to to new_name. The new name can be a full path in another location in which case the file will be moved.

For example:

%> file('sample copy.txt').rename('sample-2.txt')
true

Parameters

• new_name (string)

Returns boolean

Note: The new name cannot be empty

Note: This method throws Error on failure.

path()

path() -> string

Returns the path to the file.

For example:

%> file('sample.txt').path()
'sample.txt'

Returns string

abs_path()

abs_path() -> string

Returns the absolute path to the file.

For example:

%> file('sample.txt').abs_path()
'C:\Users\username\zuri-docs\sample.txt'

Returns string

copy()

copy(path: string) -> boolean

Copies a file from the path specified in the original file to the given path.

For example:

%> file('./sample.txt').copy('samp.txt')
true

Parameters

• new_name (string)

Returns boolean

truncate()

truncate(length: ?number) -> boolean

Truncates the entire file if length is not given or truncates the file such that only length number of bytes is left in it.

For example:

%> file('./samp.txt').truncate()
true

Parameters

• length (?number)

Returns boolean

chmod()

chmod(mode: int) -> boolean

Changes the permission on the file to the one specified in the number given.

@note: The number is required to be an octal number. e.g. 0c755

For example:

%> file('sample.txt').chmod(0c755)
true

Parameters

• mode (int)

Returns boolean

Note: Windows stores one read-only attribute where Unix stores nine permission bits, so the owner-write bit decides it and the rest are dropped: 0o755 and 0o700 are the same instruction there. A mode with no owner-write bit marks the file read-only.

set_times()

set_times(atime: number, mtime: number) -> boolean

Sets the last access time and last modified time of the file.

@note: Time is expected in UTC seconds
@note: set argument -1 to leave the current value.

For example:

%> file('sample.txt').set_times(time(), time())
true
%> file('sample.txt').stats()
{is_readable: true, is_writable: true, is_executable: true,
is_symbolic: false, size: 72, mode: 33261, dev: 16777230,
ino: 4865113, nlink: 1, uid: 501, gid: 20, mtime: 1631477099,
atime: 1631477100, ctime: 1631477099, blocks: 8, blksize: 4096}

Parameters

• atime (number)
• mtime (number)

Returns boolean

seek()

seek(offset: number, seek_type: int) -> boolean

Sets the position of a file reader or writer in a file. The position must be within the range of the file size. seek_type must be on of SEEK_SET, SEEK_CUR or SEEK_END from the io package.

For example:

%> f.seek(5, io.SEEK_SET)
true

Parameters

• offset (number)
• seek_type (int)

Returns boolean

tell()

tell() -> number

Returns the current position of the reader/writer in a file.

For example:

%> import io
%> var f = file('sample.txt')
%> f.seek(5, io.SEEK_SET)
true
%> f.tell()
5

Returns number

mode()

mode() -> string

Returns the mode in which the current file was opened.

For example:

%> file('sample.txt').mode()
'r'

Returns string

name()

name() -> string

Returns the name of the current file.

For example:

%> file('./sample.txt').name()
'sample.txt'

Returns string

to_string()

to_string() -> string

Returns the file handle as a string, naming its path and the mode it was opened in.

%> file('sample.txt', 'w').to_string()
'<file at sample.txt in mode w>'

Returns string