4.53. kink/io/FILE

Mod to operate files in the filesystem.

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

`open_to_read` opens the file specified by `Path` then returns an input.

Preconditions:

• `Path` must be a str

• $config, if provided, must be a fun which takes a conf val

The conf val has the following methods:

• Config.on_success($success_cont): uses $success_cont as the success cont. If the method is not called, VAL.identity is used as the default success cont.

• Config.on_error($error_cont): uses $error_cont as the error cont. If the method is not called, the default error cont raises an exception when it is called.

• .buffer(...[Buf_size]): specifies that the result input does bufering. `Buf_size` must be a positive int num. If `buffer` is not called, the result input does not do buffering. If `buffer` is called with no argument, a default buffer size is used.

Result:

• If an IO error does not occur when opening the file, `open_to_read` tail-calls the success cont with the result input.

• If an IO error occurs when openeing the file, `open_to_read` tail-calls the error cont with the error message.

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{(:Msg) 'error: {}'.format(Msg) }
}
stdout.print_line(Result.repr)
# => "error: file not found: /no/such/file (No such file or directory)"

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

4.53.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.

Preconditions:

• `Path` must be a str

• `Charset` must be a charset.

• $config, if specified, must be a fun which takes a conf val

The conf val has the following methods:

• Config.on_success($success_cont) : uses $success_cont as the success cont. If the method is not called, VAL.identity is used as the default success cont.

• Config.on_error($error_cont) : uses $error_cont as the error cont. If the method is not called, `open_to_scan` raises an exception when it cannot open the file.

• Config.buffer(...[Buf_size]): specifies that the result scanner does bufering. `Buf_size` must be a positive int num. If `buffer` is not called, the result input does not do buffering. If `buffer` is called with no argument, a default buffer size is used.

Result:

• If `open_to_scan` can open the file, it tail-calls the success cont with the scanner.

• If an IO error occurs, `open_to_scan` tail-calls the success cont with the message.

See kink/io/SCANNER for scanner type.

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

`open_to_write` opens the file specified by `Path`, then returns an output.

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

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

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

Preconditions:

• `Path` must be a str

• $config, if provided, must be a fun which takes a conf val

The conf val has the following methods:

• Config.append: opens the file by APPEND mode. If the method is not called, the filed is opend by OVERWRITE mode.

• Config.on_success($success_cont): uses $success_cont as the success cont. If the method is not called, VAL.identity is used as the default success cont.

• Config.on_error($error_cont): uses $error_cont as the error cont. If the method is not called, the default error cont raises an exception when it is called.

• Config.buffer(...[Buf_size]): indicates that the result output does buffering. `Buf_size` must be a positive int num. If `buffer` is not called, the result output does not do buffering. If `buffer` is called with no argument, a default buffer size is used.

Result:

• If an IO error does not occur when opening the file, `open_to_write` tail-calls the success cont with the output.

• If an IO error occurs when opening the file, `open_to_write` tail-calls the error cont with the message.

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 kink/io/OUTPUT for ”output” type.

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

`open_to_print` opens the file and returns the printer.

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

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

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

Preconditions:

• `Path` must be a str

• `Charset` must be a charset

• `Newline` must be a str

• $config, if specified, must be a fun which takes a conf val

The conf val has the following methods.

• Config.append : opens the file by APPEND mode. If the method is not called, OVERWRITE mode is used.

• Config.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception when an IO error occurs.

• Config.on_success($success_cont) : uses $success_cont as the success cont. If not called, VAL.identity is used as the default success cont.

• Config.buffer(...[Buf_size]) : specifies that the printer does buffering. `Buf_size` must be a positive int num. If `buffer` is not called, the result printer does not do buffering. If `buffer` is called with no argument, a default buffer size is used.

• Config.flush_on_print : specifies that the printer flushes the buffer after each invocation of `print` and `print_line`.

Result:

• If `open_to_print` succeeds to open the file, it tail-calls the success cont with the printer.

• If `open_to_print` fails to open the file, it tail-calls the error cont with the error message.

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

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

Preconditions:

• `Path` must be a str

• $config must be a fun which takes a conf val as the only argument

The conf val provides the following methods:

• C.on_success($success_cont) : uses $success_cont as the success cont. If not called, {} is used as the default success cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception on an IO error.

Result of the fun:

• If `mkdir` succeeds to make a directory, `mkdir` tail-calls the success cont with no args.

• If an IO error occurs during invocation, `mkdir` tail-calls the error cont with an error message.

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

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

Preconditions:

• `Path` must be a str

• $config, if given, must be a fun which takes a conf val.

The conf val provides the following methods:

• C.on_success($success_cont) : uses $success_cont as the success cont. If not called, {} is used as the default success cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception on an IO error.

Result of the fun:

• If `rm` succeeds to remove an entry, it tail-calls the success cont with no args.

• If an IO error occurs, `rm` tail-calls the error cont with an error message.

4.53.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 agains `Dir_path`.

Preconditions:

• `Dir_path` must be a str

• $config, if given, must be a fun which takes a conf val.

The conf val provides the following methods:

• C.on_success($success_cont) : uses $success_cont as the success cont. If not called, VAL.identity is used as the default success cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception on an IO error.

Result of the fun:

• If `ls` succeeds to fetch paths, it tail-calls the success cont with a vec of the paths.

• If an IO error occurs, `ls` tail-calls the error cont with an error message.

Example:

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

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

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

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

Preconditions:

• `Path` must be a str

• $config, if given, must be a fun which takes a conf val.

The conf val provides the following methods:

• C.on_success($success_cont) : uses $success_cont as the success cont. If not called, VAL.identity identity used as the default success cont.

• C.on_error($error_cont) : uses $error_cont as the error cont. If not called, the default error cont raises an exception on an IO error.

Result:

• If `realpath` succeeds to read the real path, it tail-calls the success cont with the real path.

• If `realpath` hits an IO error, it tail-calls the error cont with an error message.

Example:

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

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

4.53.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

4.53.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

4.53.13. FILE.resolve(Base_path Top_path)

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

4.53.14. FILE.pwd

`pwd` returns the path of the current directory.

4.53.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 "\".

4.53.16. FILE.file?(Path)

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

4.53.17. FILE.dir?(Path)

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