Batteries user guide : Batteries.File

# Module Batteries.File

    module File: BatFile

###### Utilities

    val lines_of : string -> string BatEnum.t

`line_of name` reads the contents of file `name` as an enumeration of lines. The file is automatically closed once the last line has been reached or the enumeration is garbage-collected.

    val write_lines : string -> string BatEnum.t -> unit

`write_lines name lines` writes strings given by `lines` to file `name` with newline character appended to each line.

    val size_of : string -> int

`size_of name` returns the size of file `name` in bytes.

    val size_of_big : string -> Int64.t

`size_of_big name` returns the size of file `name` in bytes, as a 64-bit integer.

This function is provided as the size of a file larger than 1 Gb cannot be represented with an `int` on a 32-bit machine.

###### File permissions

File permissions are used when creating a file to allow controlling which users may read, write or open that file. To use a permission, create a value of type `BatFile.permission` and pass it as argument to `BatFile.open_in`, `BatFile.open_out`, `BatFile.with_file_in` or `BatFile.with_file_out`.

    type permission

The list of operations which are permitted on a file.

    val default_permission : permission

Default permissions.

    val user_read : permission

Give the current user permission to read the file. Ignored under Windows.

    val user_write : permission

Give the current user permission to write the file

    val user_exec : permission

Give the current user permission to execute the file. Ignored under Windows.

    val group_read : permission

Give the permission to read the file to the group containing the user. Ignored under Windows.

    val group_write : permission

Give the permission to write the file to the group containing the user. Ignored under Windows.

    val group_exec : permission

Give the permission to execute the file to the group containing the user. Ignored under Windows.

    val other_read : permission

Give the permission to read the file to the rest of the world. Ignored under Windows.

    val other_write : permission

Give the permission to modify the file to the rest of the world. Ignored under Windows.

    val other_exec : permission

Give the permission to execute the file to the rest of the world. Ignored under Windows.

    val perm : permission list -> permission

Join permissions

    val unix_perm : int -> permission

Create a permission from a Unix-style octal integer. See your favorite Unix documentation on `chmod` for more details.
Raises `Invalid_argument` if given number outside the `[0, 0o777]` range

    val set_permissions : string -> permission -> unit

Set the permissions on a file.

    val chmod : string -> permission -> unit

As `BatFile.set_permissions`

###### Opening a file for reading

    type open_in_flag = [ `create | `excl | `mmap | `nonblock | `text ]

    val open_in : ?mode:open_in_flag list ->
           ?perm:permission -> string -> BatInnerIO.input

`open_in file_name` opens the file named `file_name` for reading.

Note You will need to close the file manually, with `BatIO.close_in`. An alternative is to call `with_file_in` instead of `open_in`.

Naming conventions for files are platform-dependent.

    val with_file_in : ?mode:open_in_flag list ->
           ?perm:permission -> string -> (BatInnerIO.input -> 'a) -> 'a

`with_file_in file_name f` opens the file named `file_name` for reading, invokes `f` to process the contents of that file then, once `f` has returned or triggered an exception, closes the file before proceeding.

###### Opening a file for writing

    type open_out_flag = [ `append | `create | `excl | `nonblock | `text | `trunc ]

Flags governing file output; they correspond to the relevant flags to the POSIX `open()` call. The default flags are `[`create; `trunc]`.

    val open_out : ?mode:open_out_flag list ->
           ?perm:permission -> string -> unit BatInnerIO.output

`open_out file_name` opens the file named `file_name` for writing.

Note You will need to close the file manually, with `BatIO.close_out`. An alternative is to call `with_file_out` instead of `open_out`.

Naming conventions for files are platform-dependent.

    val with_file_out : ?mode:open_out_flag list ->
           ?perm:permission -> string -> (unit BatInnerIO.output -> 'a) -> 'a

`with_file_out file_name f` opens the file named `file_name` for writing, invokes `f` to write onto that file then, once `f` has returned or triggered an exception, closes the file before proceeding.

###### Opening a temporary file for writing

    type open_temporary_out_flag = [ `append | `create | `delete_on_exit | `excl | `nonblock | `text | `trunc ]

    val open_temporary_out : ?mode:open_temporary_out_flag list ->
           ?prefix:string ->
           ?suffix:string -> ?temp_dir:string -> unit -> unit BatInnerIO.output * string

`open_temporary_out ()` opens a new temporary file for writing.
Returns The name of the file and the `output` for writing in it.

Note You will need to close the file manually. An alternative is to call `with_temporary_out` instead of `open_out`.

Naming conventions for files are platform-dependent.

`prefix` : a string which should appear at the start of your temporary file name (by default `"ocaml"`)
`suffix` : a string which should appear at the end of your temporary file name (by default `"tmp"`)
`temp_dir` : indicates what temp dir to use

    val with_temporary_out : ?mode:open_temporary_out_flag list ->
           ?prefix:string ->
           ?suffix:string ->
           ?temp_dir:string -> (unit BatInnerIO.output -> string -> 'a) -> 'a

`with_temporary_out f` opens a new temporary file for writing, invokes `f` with to write onto that file then, once `f` has returned or triggered an exception, closes the file before proceeding.
Returns The name of the file and the `output` for writing in it.

Naming conventions for files are platform-dependent.

`prefix` : a string which should appear at the start of your temporary file name (by default `"ocaml"`)
`suffix` : a string which should appear at the end of your temporary file name (by default `"tmp"`)
`temp_dir` : indicates what temp dir to use