Средства ввода-вывода
Библиотека ввода-вывода предоставляет два различных варианта работы. Первый использует неявные дескрипторы файлов; т.е., существуют операции задания файла ввода и файла вывода по умолчанию и все операции ввода/вывода работают с этими файлами. Второй вариант использует явные дескрипторы файлов.
При использовании неявных файловых дескрипторов, все операции предоставляются таблицей io. При использовании явных дескрипторов, операция io.open возвращает дескриптор, а после этого все операции являются методами данного дескриптора.
Таблица io также предоставляет три предопределенных файловых дескриптора со стандартными (в C) значениями: io.stdin, io.stdout, и io.stderr.
Если не указано иное, все функции ввода-вывода возвращают nil при ошибочном завершении (а также сообщение об ошибке как второй результат и системно-независимый код ошибки как третий результат) и какое-либо значение, отличное от nil, при успешном завершении.
io.close ([file])
Эквивалентна file:close (). Без параметра file закрывает стандартный поток вывода.
io.flush ()
Эквивалентна file:flush для стандартного потока вывода.
io.input ([file])
При вызове с указанием имени файла открывает данный файл (в текстовом режиме) и направляет его поток в стандартный поток ввода. При вызове с дескриптором файла делает дескриптор файла стандартным дескриптором ввода (перенаправляет поток, соответствующий дескриптору файла, в стандартный поток ввода). При вызове функции без параметров возвращает текущий файл ввода по умолчанию.
В случае ошибок данная функция вызывает ошибку вместо того, чтобы возвратить код ошибки.
io.lines ([filename])
Открывает файл с данным именем в режиме чтения и возвращает функцию-итератор, которая при каждом последующем вызове возвращает новую строчку из файла. Т.о., конструкция
for line in io.lines(filename) do body end
обработает все строки файла. При обнаружении функцией-итератором конца файла она возвращает 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:lines ()
Возвращает функцию-итератор, которая при каждом вызове возвращает новую строку из файла. Т.о. код
for line in file:lines() do body end
обработает все строки файла. В отличие от io.lines , эта функция не закрывает файл по окончании цикла).
file:read (···)
Читает данные из файла в соответствии с заданными форматами, которые определяют, что читать. Для каждого формата, функция возвращает строку (или число) с прочитанными символами или nil, если не может прочитать данные в указанном формате. При вызове без указания формата использует стандартный формат чтения всей следующей строки (см. ниже).
Возможные форматы:
"*n": читает число; это единственный формат, возвращающий число вместо строки.
"*a": читает весь файл, начиная с текущей позиции. Если позиция совпадает с концом файла, возвращает пустую строку.
"*l": читает следующую строку (пропуская конец строки), возвращает nil в конце файла. Это формат по умолчанию.
число: читает строку, но не более заданного количества символов, возвращает nil по достижении конца файла. Если число равно нулю, функция ничего не читает и возвращает пустую строку; возвращает nil по достижении конца файла.
file:seek ([whence] [, offset])
Устанавливает и получает позицию в файле, отсчитываемую от начала файла, в позицию, заданную параметром offset плюс значение (исходная позиция), заданное строкой whence, следующим образом:
"set": исходная позиция равна 0 (начало файла);
"cur": исходная позиция – текущая;
"end": исходная позиция – конец файла.
В случае успешного выполнения возвращает итоговую позицию в файле, отсчитываемую в байтах от начала файла. Если функция завершается неудачно, она возвращает nil и строку описания ошибки.
Значение по умолчанию для параметра whence равно "cur", а offset – 0. Т.о. вызов file:seek() возвращает текущую позицию в файле, не изменяя ее; вызов file:seek("set") перемещает указатель текущей позиции в начало файла (и возвращает 0); а вызов file:seek("end") перемещает указатель текущей позиции в конец файла, и возвращает его длину.
file:setvbuf (mode [, size])
Задает режим буферизации для выходного файла. Существует 3 возможных режима:
"no": отключить буферизацию; результат записи в файл немедленно сбрасывается на диск.
"full": полная буферизация; операции записи на диск выполняются только при переполнении буфера (или когда Вы явно сбрасываете данные на диск – см. io.flush ).
"line": построчная буферизация; запись буферизуется пока новая строка выводится или происходит ввод из некоторых специальных файлов (таких, например, как терминал).
В двух последних случаях size указывает размер буфера в байтах. По умолчанию используется подобранный размер.
file:write (···)
Записывает значение каждого из аргументов в файл. Аргументами могут быть строки или числа. Для записи других значений используйте функции tostring или string.format перед вызовом функции write.