5.7 – Средства ввода-вывода

Библиотека ввода-вывода предоставляет два различных возможных «стиля» для работы с файлами. Первый использует неявные дескрипторы файлов; т.е., существуют операции по установке «умолчательного» файла ввода или вывода, и все операции ввода-вывода работают с этими файлами. Второй «стиль» использует явные дескрипторы файлов.

При использовании неявных файловых дескрипторов, все операции предоставляются таблицей io. При использовании явных дескрипторов, операция io.open возвращает дескриптор, а после этого все операции являются методами данного дескриптора.

Таблица io также предоставляет три предопределенных (predefined) файловых дескриптора со стандартными (в C) значениями: io.stdin, io.stdout, и io.stderr.

Если не указано иное, все функции ввода-вывода возвращают nil при ошибочном завершении (а также сообщение об ошибке как второй результат и системно-независимый код ошибке в третьем результате) и какое-либо значение, отличное от nil при успешном завершении.

io.close ([file])

Эквивалентна file:close(). Без параметра file, закрывает стандартный поток вывода.

io.flush ()

Эквивалентна file:flush для стандартного потока вывода./p>

io.input ([file])

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

В случае лшибок, данная функция возбуждает ошибку вместо того, чтобы возвратить код ошибки.

io.lines ([filename])

Открывает файл с данным именем в режиме чтения и возвращает функцию-итератор (iterator function) которая при каждом последующем вызове возвращает новую строчку из файла. Т.о., конструкция

обработает все строки файла. При обнаружении функцией-итератором конца файла, она фозвращает nil (для окончания цикла) и автоматически закрывает файл.

Вызов io.lines() (без имени файла) эквивалентен io.input():lines(); т.о., он обрабатывает строки стандартного файла ввода. В этом случае, файл по окончанию итераций не закрывается автоматически.

io.open (filename [, mode])

Эта функция открывает файл в режиме, указанном в строке mode. Возвращает хендлер файла, или, в случае ошибок, nil и сообщение об ошибке.

Стрка mode может содержать следующие значения:

• "r":режим чтения (используется по умолчанию);
• "w":режим записи;
• "a": режим дозаписи в конец файла;
• "r": режим изменения, все ранее хранившиеся данные сохраняются;
• "w": режим изменения, все ранее хранившиеся данные сохраняются;
• "a": режим изменения с дозаписью в конец, все ранее хранившиеся данные защищены, запись разрешена только в конец файла.

Строка mode может также содержать 'b' в конце; этот символ нужен для некоторых систем для открытия файла в двоичном режиме. Эта строка полностью повторяет синтаксис функции C fopen.

io.output ([file])

Аналогична io.input,но работает с стандартным файлом вывода.

io.popen (prog [, mode])

Запускает программу prog в отдельном процессе и возвращает хендлер файла, который вы можете использовать для чтения данных из этой программы (если mode равен "r", значение по умолчанию) или для записи данных в эту программу ??? (если mode равен "w").

Эта функция системно зависима и доступна не на всех платформах.

io.read (···)

Аналогична io.input():read.

io.tmpfile ()

Возвращаер хендлер для временного файла. Этот файл открывается в режиме изменения и автоматически удаляется при завершении программы.

io.type (obj)

Проверяет, является ли obj валидным хендлером файла. Возвращает строку "file" если obj – открытый хендлер файла, "closed file" если obj закрытый хендлер файла, или nil если obj не является хендлером файла.

io.write (···)

Эквивалентна io.output():write.

file:close ()

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

file:flush ()

Сохраняет все данные, записанные в файл file.

file:lines ()

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

обработает все строки файла. (В отличие от io.lines , эта функция не закрывает файл по окончании цикла (т.е. достижении конца файла).)

file:read (···)

Читает данные из файла file, в соответствии с заданными форматами, которые определяют, что читать. Для каждого формата, функция возвращает строку (или число) с прочитанными символами, или nil если не может прочитать данные в указанном формате. При вызове без указания формата, использует стандартный формат, соответствующий чтению всей следующей строки (см. ниже).

Возможные форматы:

• "*n": читает число; это – единственный формат, возвращающий число вместо строки.
• "*a":читает весь файл, начиная с текущей позиции. Если позиция совпадает с концом файла, возвращает пустую строку.
• "*l": читает следующую строку (пропуская конец строки), возвращает nil в конце файла. Это – формат по умолчанию.
• число:читает строку, но не более заданного количества символов, возвращает nil по достижении конца файла. Если число равно нулю, функция ничего не читает, возвращая постую строку, или nil по достижении конца файла.

file:seek ([whence] [, offset])

Получает и ыыставляет текущую позицию в файле, отсчитываемую от начала файла, в позицию, заданную параметром offset плюс значение (исходная позиция), заданное строкой whence, следующим образом:

• "set": исходная позиция равна 0 (начало файла);
• "cur":исходная позиция – текущая;
• "end": исходная позиция – конец файла.

В случае успешного выполнения, функция seek возвращает выставленную позицию в файле, отсчитываемую от начала файла. Если функция завершается неудачно, она возвращает nil и строку – описание ошибки.

Значение по умолчанию для параметра whence равно "cur", а offset – 0. Т.о. вызов file:seek() возвращает текущую позицию в файле, не изменяя ее; вызов file:seek("set") перемещает указатель текущей позиции в начало файла (и возвращает 0); а вызов file:seek("end") перемещает указатель текущей позиции в конец файла, и возвращает его длину.

file:setvbuf (mode [, size])

Изменяет режим файла записи (output file) на буферизованный режим. Существует 3 возможных режима:

• "no": отключить буферизацию; результат записи в файл немедленно «сбрасывается» на диск.
• "full": полная буферизация; операции записи на диск выполняются только при переполнении буфера (или при вызове функции очистки буфера (см. io.flush)).
• "line": построчная буферизация; запись буферизуется до достижения конца строки или происходит ввод из особенных (специальных) файлов (таких как, например, терминал).

В двух последних случаях, size указывает размер буфера в байтах. По умолчанию используется «необходимый и достаточный размер».

file:write (···)

Записывает значение каждого из аргументов в файл file. Аргументами могут быть строки или числа. Для записи других значений, используйте функции tostring или string.format перед вызовом функции write.