OpenComputers/Filesystem API

Этот интерфейс предоставляет основной способ взаимодействия с файловой системой компьютера. Каждый компонент располагается в своей собственной "папке". Он может быть "смонтирован" в какое-нибудь место главного дерева каталогов, что позволяет очень просто взаимодействовать с файловой системой компонентов.



## Интерфейс

`filesystem.isAutorunEnabled(): boolean`


Проверяет, доступен ли автозапуск. Если `true`

, то подключенные файловые системы будут проверяться на наличие файла названного `autorun[.lua]`

в корневой директории. Если такой файл будет обнаружен, система его запустит.



`filesystem.setAutorunEnabled(value: boolean)`


Определяет, разрешен ли автозапуск.



`filesystem.canonical(path: string): string`


Возвращает "каноническую" форму заданного пути. Т. е. не содержащую относительных путей вроде `.`

или `..`

. К примеру, пути `/tmp/../bin/ls.lua`

и `/bin/./ls.lua`

эквивалентны, и их каноническая форма — `/bin/ls.lua`

.

Обратите внимание, что эта функция обрезает путь до самой последней известной корневой папки. Например `../bin/ls.lua`

превратится в `bin/ls.lua`

. Путь остается относительным, однако без ведущего слеша.



`filesystem.concat(pathA: string, pathB: string[, ...]): string`


Соединяет (конкатенация) два или несколько путей. Обратите внимание, что все пути, кроме первого, обрабатываются как относительные, даже если начинаются со слеша. Возвращается каноническая форма полученного пути. То есть, `fs.concat("a", "..")`

вернет пустую строку.



`filesystem.path(path: string): string`


Вырезает из заданной строки путь к файлу. Т.е. все *до* последнего слеша в канонической записи пути.



`filesystem.name(path: string): string`


Вырезает из заданной строки имя файла. Т.е. все *после* последнего слеша в канонической записи этого пути.



`filesystem.proxy(filter: string): table or nil, string`


Эта функция похожа на `component.proxy`

, за исключением того, что передаваемая строка может быть также меткой компонента в файловой системе. Сначала система проверяет наличие такой метки в системе, а затем функция действует как `component.proxy`

. Возвращает прокси заданной файловой системы, либо `nil`

и сообщение об ошибке.



`filesystem.mount(fs: table or string, path: string): boolean or nil, string`


"Монтирует" файловую систему по указанному пути. Первым аргументом может быть прокси файловой системы, её адрес или метка. Второй аргумент — адрес в глобальном дереве каталогов (куда монтируется). Возвращает `true`

или `nil`

и текст ошибки.



`filesystem.mounts(): function -> table, string`


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



`filesystem.umount(fsOrPath: table or string): boolean`


"Размонтирует" файловую систему. Первый аргумент — это прокси, или адрес (сокращенный адрес) файловой системы. Во втором случае система будет "размонтирована" по всем путям. Либо путь в в глобальном дереве каталогов.



`filesystem.get(path: string): table, string or nil, string`


Возвращает прокси файловой системы по указанному пути. Возвращает прокси и путь, по которому смонтирована система, либо `nil`

и текст ошибки.



`filesystem.exists(path: string): boolean`


Проверяет, существует ли файл или папка по указанному пути.



`filesystem.size(path: string): number`


Возвращает размер файла по указанному пути. Возвращает `0`

если путь не указывает на файл.



`filesystem.isDirectory(path: string): boolean`


Проверяет, указывает ли путь на каталог. Возвращает `false`

в противном случае (путь указывает на файл, или `file.exists(path)`

возвращает `false`

).



`filesystem.lastModified(path: string): number`


Возвращает *реальное* (не игровое) время модификации файла по указанному адресу в формате Unix timestamp. Для папки это обычно время ее создания.



`filesystem.list(path: string): function -> string or nil, string`


Возвращает итератор всех элементов в указанной директории. Возвращает `nil`

и текст ошибки, если список получить не удалось.

*Примечание*: названия каталогов обычно дополняются в конце слешем, для того чтобы их можно было идентифицировать без дополнительного вызова `fs.isDirectory`

.



`filesystem.makeDirectory(path: string): boolean or nil, string`


Создает новый каталог по указанному пути. Создает все необходимые вложенные каталоги, если их не существовало до этого. Возвращает `true`

в случае успеха или `nil`

и сообщение об ошибке.



`filesystem.remove(path: string): boolean or nil, string`


Удаляет файл или каталог. Если путь указывает на каталог, рекурсивно удаляет все файлы и подкаталоги в нем. Возвращает `true`

в случае успеха, или `nil`

и сообщение об ошибке.



`filesystem.rename(oldPath: string, newPath: string): boolean or nil, string`


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

в случае успеха, или `nil`

и сообщение об ошибке.



`filesystem.copy(fromPath: string, toPath: string): boolean or nil, string`


Копирует файл в указанную папку. Целевой путь должен содержать имя файла. Не поддерживает каталоги.(не работает на OpenOs 1.7.5)



`filesystem.open(path: string[, mode: string]): table or nil, string`


Открывает файл по указанному адресу для чтения или записи. Режим открытия по умолчанию — `r`

.

Возможные режимы: `r`

, `rb`

, `w`

, `wb`

, `a`

и `ab`

.

Возвращает файловый поток (см. ниже) в случае успеха, или `nil`

и сообщение об ошибке.

*Примечание*: вы можете открыть только ограниченное количество файлов в каждой файловой системе одновременно. Файлы автоматически закрываются сборщиком мусора (garbage collector), но будет лучше если вы вызовете функцию `close`

по завершению работы с файлом.

**Важно**: очень рекомендуется использовать `io.open`

вместо этой функции, чтобы получить "обертку" с буфером (buffered wrapper) для файлового потока.



## Файловый поток

Когда вы открываете файл при помощи **Filesystem API**, вы получаете файловый поток — таблицу с четырьмя функциями. Эти функции — тонкая обертка к вызовам прокси файловой системы. Это означает, что операции чтения/записи не буферизованы, и могут работать медленно при чтении нескольких байт. Рекомендуется использовать `io.open`

вместо этого.



`file:close()`


Закрывает файловый поток и освобождает указатель на соответствующую файловую систему.



`file:read(n: number): string or nil, string`


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

. При возникновении ошибки возвращает `nil`

и её текст.



`file:seek(whence: string[, offset: number]): number or nil, string`


Перемещает указатель на заданную позицию в потоке, если это возможно. Функция доступна только для потоков открытых в режиме чтения. Первый аргумент определяет точку относительно которой происходит перемещение. Он может иметь значение `cur`

— текущее положение в потоке, `set`

— начало потока, `end`

— конец потока. Второй аргумент — смещение на новую позицию. Возвращает новое положение указателя в потоке, или `nil`

и сообщение об ошибке.

Второй аргумент по умолчанию равен `0`

, поэтому вызов `f:seek("set")`

переместит указатель на начало потока, `f:seek("cur")`

вернет текущее положение указателя.



`file:write(str: value): boolean or nil, string`


Пишет указанные данные в поток. Возвращает `true`

в случае успеха, или `nil`

и сообщение об ошибке.