5.57. kink/io/FILE

Mod to operate files in the filesystem.

5.57.1. FILE.open_to_read(Path ...[$config = {}])

`open_to_read` opens the file specified by `Path` as an `input`.

• C.buffer(...[Buf_size]): default = int num >=0

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = a fun which raises an exception

When the file is opened, `open_to_read` tail-calls $success with an `input`. If `Buf_size` is zero, the result input does not do buffering. If `Buf_size` is not zero, the result input does buffering.

If an IO error occurs, `open_to_read` tail-calls $error with an `exception`.

Preconditions

• `Path` must be a str

• `Buf_size` must be an int num bigger than or equal to 0

• $success must be a fun which takes an `input`

• $error must be a fun which takes an `exception`

Example

:FILE.require_from('kink/io/')
:CONTROL.require_from('kink/')

CONTROL.with_finally{(:finally)
  :In = FILE.open_to_read('/dev/urandom')
  finally{ In.close }
  :Bin = In.read(10)
  stdout.print_line(Bin.repr)
}
# Output differs each time:
#   (bin 0xbe 0x62 0xe8 0x75 0xd4 0x88 0xd4 0xfc 0xc4 0x31)

:Result <- FILE.open_to_read('/no/such/file'){(:O)
  O.on_error{(:Exc) 'error: {}'.format(Exc.message) }
}
stdout.print_line(Result.repr)
# => "error: cannot open to read: \"/no/such/file\""

See also

See kink/io/INPUT for ”input” type.

5.57.2. FILE.open_to_scan(Path Charset ...[$config = {}])

`open_to_scan` opens the file specified by `Path` as a `scanner`, with `Charset` as the charset of the file. The created scanner also supports `input` type.

Config methods:

• C.buffer(...[Buf_size]): default = int num >=0

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = a fun which raises an exception

If the file is opened, `open_to_scan` tail-calls $success with the scanner+input.

If an IO error occurs, `open_to_scan` tail-calls $error with an `exception.

Preconditions

• `Path` must be a str

• `Charset` must be a charset.

• `Buf_size` must be an int num >=0

• $success must be a fun which takes a scanner+input

• $error must be a fun which takes an `exception`

See also

See kink/io/SCANNER for scanner type.

5.57.3. FILE.open_to_write(Path ...[$config = {}])

`open_to_write` opens the file specified by `Path` to write, as an `output`.

Config methods:

• C.append: set APPEND mode; default is OVERWRITE mode

• C.buffer(...[Buf_size]): default = int num >=1

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = a fun which raises an exception

If the specified file does not exist, `open_to_write` makes a new empty file.

If the specified file exists, and the mode is OVERWRITE, `open_to_write` truncates the content of the file.

If the specified file exists, and the mode is APPEND, `open_to_write` opens the file without truncating the content, and the file pointer is set at the end of the file.

If the file is successfully opened, `open_to_write` tail-calls $success with an `output`. If `Buf_size` is zero, the result `output` does not do buffering. If `Buf_size` non-zero, the result `output` does buffering.

If an IO error occurs, `open_to_write` tail-calls $error with an `exception`.

Preconditions

• `Path` must be a str

• `Buf_size` must be an int num >=0

• $success must be a fun which takes an `output`

• $error must be a fun which takes an `exception`

Example

:FILE.require_from('kink/io/')
:CONTROL.require_from('kink/')
:CHARSET.require_from('kink/charset/')

CONTROL.with_finally{(:finally)
  :Out = FILE.open_to_write('/dev/stdout')
  finally{ Out.close }
  Out.write(CHARSET.ascii.str_to_bin("hello\n"))
}
# => hello

See also

See kink/io/OUTPUT for `output` type.

5.57.4. FILE.open_to_print(Path Charset Newline ...[$config = {}])

`open_to_print` opens the file as a `printer`. The created printer also supports `output` type.

Config methods:

• C.append: sets the mode to APPEND; the default is OVERWRITE

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = a fun which raises an exception

• C.buffer(...[Buf_size]): default = an int num >=1

• C.flush_on_print: default = false

If the specified file does not exist, `open_to_print` makes a new empty file.

If the specified file exists, and the mode is OVERWRITE, `open_to_print` truncates the content of the file.

If the specified file exists, and the mode is APPEND, `open_to_print` opens the file without truncating the content, and the file pointer is set at the end of the file.

If a file is successfully open, `open_to_print` tail-calls $success with a printer+output.

If `Buf_size` is zero, the printer+output will not be bufferred. If `Buf_size` is non-zero, the printer+output will be bufferred.

If C.flush_on_print is called, and the printer+output is bufferred, the printer+output flushes the buffer after each invocation of `print` and `print_line`.

`Newline` will be used by `printe_line` method as the line separator.

`Charset` will be used to convert strs to bytes.

Preconditions

• `Path` must be a `str`

• `Charset` must be a `charset`

• `Newline` must be a `str`

• `Buf_size` must be an int num >=0

• $success must be a fun which takes a printer+output

• $error must be a fun which takes an `exception`

5.57.5. FILE.mkdir(Path ...[$config={}])

`mkdir` makes a directory on the `Path`.

Config methods:

• C.on_success($success): default = {}

• C.on_error($error): default = a fun which raises an exception

If a directory is successfully made, `mkdir` tail-calls $success with no arg.

If an IO error occurs during invocation, `mkdir` tail-calls $error with an `exception` val.

Preconditions

• `Path` must be a str

• $success must be a fun which takes no arg

• $error must be a fun which takes an `exception` val

5.57.6. FILE.rm(Path ...[$config={}])

`rm` removes an filesystem entry such as an empty directory, a file, or a symlink.

Config methods:

• C.on_success($success): default = {}

• C.on_error($error): default = a fun which raises an exception

If the filesystem entry is successfully removed, `rm` tail-calls $success with no arg.

If an IO error occurs, `rm` tail-calls $error with an `exception` val.

Preconditions

• `Path` must be a str

• $success must be a fun which takes no arg

• $error must be a fun which takes an `exception` val

5.57.7. FILE.ls(Dir_path ...[$config={}])

`ls` fetches a vec of the paths of the entries under the directory specified by `Dir_path`. The result paths are resolved against `Dir_path`.

Config methods:

• C.on_success($success): default = VAL.identity

• C.on_error($error_cont) : default = a fun which raises an exception

If paths are fetched successfully, `ls` tail-calls $success with a vec of the paths.

If an IO error occurs, `ls` tail-calls $error with an `exception` val.

Preconditions

• `Dir_path` must be a str

• $success must be a fun which takes a `vec`

• $error must be a fun which takes an `exception`

Example

:FILE.require_from('kink/io/')

stdout.print_line(FILE.ls('/home').repr) # => ["/home/kuro" "/home/taku"]

5.57.10. FILE.realpath(Path ...[$config={}])

`realpath` fetches the absolute real path of `Path`, resolving symlinks, links such as '..', duplicated path separators and so on.

Config methods:

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = a fun which raises an exception

If the real path is successfully read, `realpath` tail-calls $success with a `str` of the real path.

If an IO error occurs, `realpath` tail-calls $error with an `exception`.

Preconditions

• `Path` must be a str

• $success must be a fun which takes a `str` of the real path

• $error must be a fun which takes an `exception`

Example

:FILE.require_from('kink/io/')

stdout.print_line(FILE.realpath('/usr/local/bin/..')) # => /usr/local

5.57.11. FILE.basename(Path)

`basename` returns the last part of the path.

If `Path` does not contain the basename, the fun returns an empty str.

Precondition:

• `Path` must be a str

5.57.12. FILE.dirname(Path)

`dirname` returns the path except for the basename from `Path`.

If `Path` does not contain the basename, the fun returns the path which is semantically equivalent to `Path`.

Precondition:

• `Path` must be a str

5.57.13. FILE.resolve(Base_path Top_path)

`resolve` resolves `Top_path` against `Base_path`, and returns the result path.

5.57.14. FILE.pwd

`pwd` returns the path of the current directory.

5.57.15. FILE.separator

`separator` returns the separator of directory names and the file name in a path on the host system.

The result is either "/" or "\".

5.57.16. FILE.file?(Path)

`file?` returns whether the current process can determine `Path` is a regular file.

5.57.17. FILE.dir?(Path)

`file?` returns whether the current process can determine `Path` is a directory.

5.57.19. FILE.present?(Path)

`present?` returns whether the current process can determine that a file system entry exists on `Path`.