Модуль Out_channel

module Out_channel: sig .. end

Каналы вывода.

Этот модуль предоставляет функции для работы с каналами вывода. Например, его можно использовать для записи в файл или вывода данных в терминал.

См. раздел с примерами ниже.

С версии 4.14

Каналы

type t = out_channel

Тип канала вывода.

type open_flag = open_flag =

`\|`	`Open_rdonly`	`(*`	открыть для чтения.	`*)`
`\|`	`Open_wronly`	`(*`	открыть для записи.	`*)`
`\|`	`Open_append`	`(*`	открыть для добавления: всегда записывать в конец файла.	`*)`
`\|`	`Open_creat`	`(*`	создать файл, если он не существует.	`*)`
`\|`	`Open_trunc`	`(*`	очистить файл, если он уже существует.	`*)`
`\|`	`Open_excl`	`(*`	выдать ошибку, если указан Open_creat и файл уже существует.	`*)`
`\|`	`Open_binary`	`(*`	открыть в двоичном режиме (без преобразований).	`*)`
`\|`	`Open_text`	`(*`	открыть в текстовом режиме (могут выполняться преобразования).	`*)`
`\|`	`Open_nonblock`	`(*`	открыть в неблокирующем режиме.	`*)`

Режимы открытия для Out_channel.open_gen.

val stdout : t

Стандартный вывод процесса.

val stderr : t

Стандартный поток ошибок процесса.

val open_bin : string -> t

Открывает указанный файл для записи и возвращает новый канал вывода для этого файла, установленный в начало файла. Если файл уже существует, его размер обнуляется. Если файла ещё нет, он создаётся.

val open_text : string -> t

То же, что и Out_channel.open_bin, но файл открывается в текстовом режиме, поэтому при записи выполняется преобразование символов новой строки. В операционных системах, которые не различают текстовый и двоичный режимы, эта функция ведёт себя как Out_channel.open_bin.

val open_gen : open_flag list -> int -> string -> t

open_gen mode perm filename открывает указанный файл для записи, как описано выше. Дополнительный аргумент mode задаёт режим открытия. Дополнительный аргумент perm задаёт права доступа к файлу на случай, если его потребуется создать. Out_channel.open_text и Out_channel.open_bin — частные случаи этой функции.

val with_open_bin : string -> (t -> 'a) -> 'a

with_open_bin fn f открывает канал oc для файла fn и возвращает f oc. После возврата f — как с результатом, так и с исключением — гарантируется, что oc закрыт.

val with_open_text : string -> (t -> 'a) -> 'a

Как Out_channel.with_open_bin, но канал открывается в текстовом режиме (см. Out_channel.open_text).

val with_open_gen : open_flag list -> int -> string -> (t -> 'a) -> 'a

Как Out_channel.with_open_bin, но позволяет указать режим открытия и права доступа к файлу на случай, если его потребуется создать (см. Out_channel.open_gen).

val close : t -> unit

Закрывает указанный канал, записывая все данные из буфера. Функции вывода вызывают исключение Sys_error при применении к закрытому каналу вывода, за исключением Out_channel.close и Out_channel.flush, которые ничего не делают при применении к уже закрытому каналу. Обратите внимание: Out_channel.close может вызвать Sys_error, если операционная система сообщит об ошибке при сбросе буфера или закрытии канала.

val close_noerr : t -> unit

То же, что и Out_channel.close, но игнорирует все ошибки.

Вывод

val output_char : t -> char -> unit

Записывает символ в указанный канал вывода.

val output_byte : t -> int -> unit

Записывает в указанный канал вывода одно 8-битное целое число (как одиночный символ с соответствующим кодом). Перед использованием заданное целое число берётся по модулю 256.

val output_string : t -> string -> unit

Записывает строку в указанный канал вывода.

val output_bytes : t -> bytes -> unit

Записывает последовательность байтов в указанный канал вывода.

Расширенный вывод

val output : t -> bytes -> int -> int -> unit

output oc buf pos len записывает len символов из последовательности байтов buf, начиная со смещения pos, в указанный канал вывода oc.

Вызывает Invalid_argument, если pos и len не задают допустимый диапазон в buf.

val output_substring : t -> string -> int -> int -> unit

То же, что и Out_channel.output, но принимает строку вместо последовательности байтов.

val output_bigarray : t ->       ('a, Bigarray.int8_unsigned_elt, Bigarray.c_layout)       Bigarray.Array1.t -> int -> int -> unit

То же, что и Out_channel.output, но получает данные из bigarray.

С версии 5.2

Сброс буфера

val flush : t -> unit

Сбрасывает буфер, связанный с указанным каналом вывода, выполняя все ожидающие операции записи в этом канале. Интерактивным программам следует своевременно сбрасывать стандартный вывод и стандартный поток ошибок.

val flush_all : unit -> unit

Сбрасывает все открытые каналы вывода; ошибки игнорируются.

Позиционирование

val seek : t -> int64 -> unit

seek chan pos устанавливает текущую позицию записи в pos для канала chan. Функция работает только с обычными файлами. Для файлов других типов (например, терминалов, каналов и сокетов) поведение не определено.

val pos : t -> int64

Возвращает текущую позицию записи для указанного канала. Не работает с каналами, открытыми с флагом Open_append (возвращаемое значение не определено).

Для файлов, открытых в текстовом режиме в Windows, возвращаемая позиция приблизительна (из-за преобразования символов конца строки); в частности, сохранение текущей позиции с помощью Out_channel.pos с последующим возвратом к ней с помощью Out_channel.seek не сработает. Чтобы этот приём программирования работал надёжно и переносимо, файл необходимо открыть в двоичном режиме.

Атрибуты

val length : t -> int64

Возвращает размер (число символов) обычного файла, для которого открыт указанный канал. Если канал открыт для файла, не являющегося обычным, результат не имеет смысла.

val set_binary_mode : t -> bool -> unit

set_binary_mode oc true переводит канал oc в двоичный режим: при выводе преобразования не выполняются.

set_binary_mode oc false переводит канал oc в текстовый режим: в зависимости от операционной системы при выводе могут выполняться некоторые преобразования. Например, в Windows окончания строк преобразуются из \n в \r\n.

В операционных системах, которые не различают текстовый и двоичный режимы, эта функция не действует.

val is_binary_mode : t -> bool

is_binary_mode oc возвращает, находится ли канал oc в двоичном режиме (см. Out_channel.set_binary_mode).

С версии 5.2

val set_buffered : t -> bool -> unit

set_buffered oc true переводит канал oc в буферизованный режим. В этом режиме данные, выводимые в oc, помещаются в буфер, пока внутренний буфер не заполнится или не будет вызвана функция Out_channel.flush либо Out_channel.flush_all; после этого данные отправляются на устройство вывода.

set_buffered oc false переводит канал oc в небуферизованный режим. В этом режиме данные, выводимые в oc, немедленно отправляются на устройство вывода.

По умолчанию все каналы открываются в буферизованном режиме.

val is_buffered : t -> bool

is_buffered oc возвращает, буферизован ли канал oc (см. Out_channel.set_buffered).

val isatty : t -> bool

isatty oc имеет значение true, если oc указывает на терминал или окно консоли, и false в противном случае.

С версии 5.1

Примеры

Вывод в терминал:

      Out_channel.output_string Out_channel.stdout "hello, world"

Запись содержимого файла:

      let write_file file s =
        Out_channel.with_open_bin file
          (fun oc -> Out_channel.output_string oc s))