Modules index

# File

### File objects

`class File`:
File objects are created by calling the following function on the `File` class object:

`func new(path, mode):` Opens the file at `path` for reading or writing. `mode` can take the following values:

`r` | Open for reading.
`r+` | Open for reading and writing.
`w` | Open for writing; truncates file if it already exists, or creates a new file if none currently exists.
`w+` | Open for reading and writing; truncates file if it already exists, or creates a new file if none currently exists.
`a` | Open for writing; does not truncate file if it already exists, but does create a new file if none currently exists.
`a+` | Open for reading and writing; does not truncate file if it already exists, but does create a new file if none currently exists.

File objects support the following functions:

`func close():` Closes the file. Note that although the file will be closed when the file object is garbage collected, it is often good manners (and the release of a burden on the OS) to close files once they are finished with.

`func fileno():` Returns the underlying file descriptor.

`func read(size := null):` Reads `size` bytes from the file. If `size` is `null`, the full contents of the file are returned.

`func readln():` Successively generates each line of text in the file.

`func write(s):` Writes `s` to the file.

`func writeln(s):` Writes `s` to the file plus the platform appropriate newline character(s).
File objects have the following slots:

`path`: The path of the file object. Set to `NULL` if this file has no associated path (e.g. a pipe).

### File name manipulation

These functions should be used to ensure that file name manipulation is done in a platform independent manner:

`func canon_path(path):` Returns the fully canonicalized version of `path`. The exact effects are platform dependent.

`func exists(path):` Succeeds if `path` exists.

`func is_dir(path):` Succeeds if `path` is a directory. Notice that mere failure - as opposed to an exception being generated - does not necessarily imply that `path` exists but is not a directory [this behaviour is platform dependent].

`func iter_dir_entries(dir_path):` Successively generates each leaf names in the directory `dir_path`.

`func join_names(*names):` Concatenates the entries of `names` into a path. This thus reverses the effects of `split_names` or `split_leaf`.

`func join_ext(path, ext):` Joins filename extension `ext` to the path `path`. If `ext` is empty, `path` is returned. This reverses the effect of `split_ext`.

`func split_ext(path):` Returns a list of length two `[<path's directory plus leaf name>, <path's file extension>]`. The file name extension separator is not present in either component. e.g. `split_ext("/a/b/c.d")` returns `["/a/b/c", "d"]`.

`func split_leaf(path):` Returns a list of length two `[<path's directory>, <path's leaf name>]`. The file name extension separator is not present in either component. e.g. `split_leaf("/a/b/c.d")` returns `["/a/b", "c.d"]`.

`func split_names(path):` Returns a list representing all the directories and the leaf name of `path`. The separator between the directories and leaf name is not present in the output. e.g. `split_names("/a/b/c.d")` returns `["a", "b", "c.d"]`.

`DIR_SEP`: The character(s) used to separate directory names (e.g. on Unix `/`).

`EXT_SEP`: The character(s) used to separate file names from their extensions (e.g. on Unix `.`).

### File manipulation

`func mtime(path):` Returns the mtime ('modification time') of `path` as an `Instant`.

`func rm(path):` Deletes `path`. If `path` is a directory, it recursively deletes its contents.

`func temp_file():` Returns a read / write `File` object in a temporary location. The file is not deleted upon close and must be manually deleted.

### Miscellaneous

`NULL_DEV`: The name of the null file (e.g. on Unix `/dev/null`).

cvd_to_html ©2006-2007 Laurence Tratt