Стандартные библиотеки Lua предоставляют полезные функции, реализованные непосредственно через C-ишный API.
Некоторые из этих функций придают языку основные услуги (например, type и getmetatable); другие обеспечивают доступ к "внешним" службам (например, I/O);
и третьи, что могут быть реализованы и в самой Lua, но очень полезны или имеют критические запросы производительности, что стоит реализовать их на C (например, table.sort).
Все библиотеки реализованы через официальный C-ишный API и представлены как отдельные C модули.
В настоящее время, Lua имеет следующие стандартные библиотеки:
- основные функции (базовая библиотека) (§6.1);
- библиотека сопрограмм (§6.2);
- библиотека пакетов (модули) (§6.3);
- обработка строк (§6.4);
- основная поддержка UTF-8 (§6.5);
- обработка таблиц (§6.6);
- математические функции (§6.7) (sin, log, и т.д.);
- средства ввода/вывода (§6.8);
- возможности операционной системы (§6.9);
- библиотека отладки (§6.10).
За исключением базовой библиотеки и библиотеки пакетов, каждая библиотека предоставляет все свои функции как поля глобальной таблицы или как методы своих объектов.
Для получения доступа к этим библиотекам, хост-программа на C должна вызвать функцию luaL_openlibs, которая и откроет все стандартные библиотеки.
Кроме того, хост-программа может открывать их отдельно используя функцию luaL_requiref для вызова
Эти функции объявлены в заголовочном файле lualib.h.
Базовая библиотека предоставляет для Lua основные функции. Если эту библиотеку не включать в приложение, то следует внимательно проверить нужны ли некоторые из её возможностей для обеспечения выполнения.
Вызывает функцию error, если значение своего аргумента v ложно (то есть, nil или false); в противном случае возвращает все свои аргументы.
В случае ошибки, message является объектом ошибки; если этот аргумент отсутствует, то по умолчанию используется "assertion failed!" - "сбой проверочного утверждения!".
Данная функция представляет собой общий интерфейс для сборщика мусора. Она выполняет различные функции, в соответствии со своим первым аргументом opt:
- "collect": выполняет полный цикл сборки мусора. Это опция по умолчанию.
- "stop": останавливает автоматическое выполнение сборщика мусора. Сборщик будет работать только когда явно вызывается, пока вызов не перезапустит его.
- "restart": перезапускает автоматическое выполнение сборщика мусора.
- "count": возвращает полный объем памяти, используемый Lua, в килобайтах. Значение имеет дробную часть, так что умножение его на 1024 даст точное число байт, используемых Lua (за исключением переполнений).
- "step": выполняет шаг по сборке мусора.
"Размером" шага управляет аргумент arg. С нулевым значением сборщик будет выполнять один основной (неделимый) шаг.
Для ненулевых значений сборщик будет выполнять свою работу так, как если бы такое количество памяти (в килобайтах) было выделено от Lua. Возвращает true, если шаг заканчивает цикл сборки мусора.
- "setpause": устанавливает аргумент arg как новое значение для паузы в работе сборщика мусора (смотрите §2.5). Возвращает предыдущее значение для pause.
- "setstepmul": устанавливает аргумент arg как новое значение для множителя шага сборщика мусора (смотрите §2.5).
Возвращает предыдущее значение шага.
- "isrunning": возвращает логическое значение, которое сообщает, запущен ли сборщик мусора (то есть, он не остановлен).
Открывает названный файл и выполняет его содержимое как Lua порцию (chunk).
При вызове без аргументов dofile выполняет содержимое стандартного ввода (stdin). Возвращает все значения возвращаемые блоком.
В случае ошибок, dofile передает ошибку в функцию, которая вызвала dofile (то есть, dofile не работает в защищенном режиме).
Завершает последнюю вызванную защищенную функцию и возвращает message как объект ошибки. Функция error никогда не возвращается.
Обычно, если сообщение является строкой, error добавляет некоторую информацию о положении ошибки к началу сообщения.
Аргумент level (уровень) указывает как получить позицию ошибки.
При level 1 (по умолчанию), позиция ошибки там, где была вызвана функция error.
А level 2 указывает, что ошибка была там, где была вызвана функция, которая вызвала error; и так далее.
Передача level 0 исключает добавление информации о позиции ошибки в сообщение.
Глобальная переменная (не функция), в которой хранится глобальное окружение (смотрите §2.2).
Собственно сам Lua не использует эту переменную; изменение его значения не влияет на какое-либо окружение, ни наоборот.
Если object не имеет метатаблицы, возвращается nil.
В противном случае, если метатаблица объекта имеет поле "__metatable", возвращается связанное с ним значение.
Если же в метатаблице объекта нет поля "__metatable", возвращается метатаблица заданного объекта.
Возвращает три значения (функцию-итератор, таблицу t, и 0), так что конструкция
for i,v in ipairs(t) do body end
будет перебирать пары ключ-значение (1,t[1]), (2,t[2]), ..., до первого отсутствующего (nil) значения.
Загружает порцию (chunk).
Если chunk является строкой, порция является этой строкой. Если chunk это функция, load вызовет её неоднократно для получения частей порции (chunk pieces).
Каждый вызов chunk должен возвращать строку, которая соединяется (конкатенирует) с предыдущими результатами. Возврат пустой строки, nil, или отсутствие значения означает конец порции.
Если нет синтаксических ошибок, возвращается скомпилированная порция как функция; в противном случае, возвращается nil плюс сообщение об ошибке.
Если результирующая функция имеет внешние локальные переменные (upvalue), первой upvalue устанавливается значение env, если этот параметр задан, или значение глобального окружения.
Другие внешние локальные переменные инициализируются с nil.
(Когда загружается основная порция (chunk), результирующая функция будет уже иметь ровно один upvalue, переменную _ENV (смотрите §2.2).
Тем не менее, когда загружается бинарная порция, созданная функцией (смотрите string.dump), результирующая функция может иметь произвольное количество внешних локальных переменных.)
Все внешние локальные переменные являются свободными (fresh), то есть, они не являются общими с какой-либо другой функцией.
chunkname используется в качестве имени порции для сообщений об ошибках и отладочной информации (смотрите §4.9).
При отсутствии этого аргумента по умолчанию принимается chunk, если chunk является строкой, или "=(load)", в противном случае.
Строковый аргумент mode управляет, может ли порция быть текстовой или бинарной (то есть, предварительно скомпилированной порцией).
Это может быть строка "b" (только бинарная порция), "t" (только текстовые порции), или "bt" (обе, и бинарная и текстовая). По умолчанию установлен как "bt".
Lua не проверяет состав бинарных порций. Злонамеренно созданные бинарные порции могут привести к сбою интерпретатора.
Аналогична функции load, но получает порцию (chunk) из файла filename или из стандартного ввода, если имя файла не задано.
Функция позволяет программе перемещаться по всем полям таблицы. Первым её аргументом является таблица, а вторым - индекс в этой таблице.
Аргумент next возвращает следующий индекс таблицы и связанное с ним значение.
При вызове с nil в качестве второго аргумента, next возвратит начальный индекс и соответственное ему значение.
При вызове с последним индексом или с nil в пустой таблице next возвратит nil.
Если второй аргумент отсутствует, то это интерпретируется как nil.
В частности, можно использовать next(t) для проверки, пуста ли таблица.
Порядок, в котором перечислены индексы, не задается, даже для числовых индексов. (Для прохождения таблицы в числовом порядке, используйте числовой for.)
Поведение функции next неопределенно, если, во время перемещения добавить любое значение в несуществующее поле таблицы. Хотя можно изменять существующие поля. В частности, можно очистить существующие поля.
Если у t есть метаметод __pairs, функция вызывает его с t в качестве аргумента и возвращает первые три результата из вызова.
В противном случае, возвращает три значения: функцию next, таблицу t, и nil, так что конструкция
for k,v in pairs(t) do body end
будет перебирать все пары ключ-значение таблицы t.
Для предостережений от изменения таблицы в процессе её обхода, смотрите описание функции next.
Вызывает функцию f с заданными аргументами в защищенном режиме.
Это означает, что любая ошибка внутри f не распространяется; вместо этого, pcall перехватывает ошибку и возвращает код состояния.
Её первым результатом является код состояния (логическое значение), которое будет истинным, если вызов выполнен успешно, без ошибок.
В этом случае, pcall также возвращает все результаты из вызова после этого первого результата.
В случае любой ошибки, pcall возвращает false плюс сообщение об ошибке.
Принимает любое число аргументов и выводит их значения в stdout, используя функцию tostring для конвертирования каждого аргумента в строку.
print предназначен не для формирования вывода, а только как быстрый способ показать значение, например для отладки.
Для полного управления выводом, используйте string.format и io.write.
Проверка равенства аргументов v1 и v2, без вызова какого-либо метаметода. Возвращается логическое значение.
Получает реальное значение table[index], без вызова какого-либо метаметода. table должен быть таблицей; index может быть любым значением.
Возвращает длину объекта v, который должен быть таблицей или строкой, без вызова какого-либо метаметода. Возвращается целое число.
Устанавливает реальное значение table[index] как value, без вызова какого-либо метаметода.
table должен быть таблицей, index - любым числом, отличным от nil и NaN, а value - любое Lua значение. Данная функция возвращает table.
Если index является числом, возвращаются все аргументы после числа в аргументе index; отрицательное число определяет индексацию с конца (-1 представляет последний аргумент).
В противном случае, index должен быть строкой "#", и функция select возвратит полное число дополнительных аргументов, полученных ею.
Устанавливает метатаблицу для заданной таблицы. (Для других типов Lua нельзя изменять метатаблицу, только из C.)
Если metatable является значение nil, из заданной таблицы удаляется метатаблица. Если исходная метатаблица имеет поле "__metatable", выдается ошибка.
Данная функция возвращает table.
При вызове с отсутствующим аргументом base, tonumber пытается конвертировать свой аргумент в число.
Если аргумент уже является числом или строкой, которую можно конвертировать в число, то tonumber возвращает это число; в противном случае она возвращает значение nil.
Преобразование строк может привести к целым числам или к числам с плавающей запятой, в соответствии с лексическими соглашениями Lua (смотрите §3.1).
(Строка может иметь начальные и конечные пробелы, а также знак.)
Если функция вызвана с аргументом base, тогда e должен быть строкой, которая трактуется как целое числительное с таким основанием системы счисления.
base может быть любое целое число между 2 и 36, включительно.
В системах счисления с основанием больше 10, буква 'A' (как в верхнем, так и в нижнем регистре) представляет 10, 'B' представляет 11, и так далее, включая 'Z', представляющую 35.
Если строка e не является правильным числительным в заданной системе счисления, функция возвращает значение nil.
Принимает значение любого типа и конвертирует его как строку в формате, удобном для чтения.
(Для полного контроля преобразования чисел, используйте string.format.)
Если метатаблица v имеет поле "__tostring", то функция tostring вызывает соответствующее значение с v в качестве аргумента, и использует результат вызова как свой результат.
Возвращает тип своего единственного аргумента в виде строки.
Возможными результатами этой функции являются:
"nil" (строка, а не значение nil),
"number",
"string",
"boolean",
"table",
"function",
"thread", и
"userdata".
Глобальная переменная (не функция), которая хранит строку с текущей версией интерпретатора. На данный момент значение этой переменной "Lua 5.3".
Эта функция похожа на pcall, за исключением того, что она устанавливает новый обработчик сообщений msgh.
Данная библиотека включает в себя операции для управления сопрограммами, которые размещаются в таблице coroutine.
Общее описание сопрограмм смотрите в §2.6.
Создает новую сопрограмму с телом f, причем f должна быть функцией. Возвращает эту новую сопрограмму, объект типа "thread".
Возвращает значение true, если работающая сопрограмма может быть приостановлена.
Работающая сопрограмма будет приостанавливаемой, если она не является основным потоком и не находится внутри неприостанавливаемой C-ишной функции.
Запускает или продолжает выполнение сопрограммы co. При первом возобновлении сопрограммы, она начинает выполнение своего тела. Значения val1, ... передаются в качестве аргументов в тело функции.
Если сопрограмма была приостановлена, resume перезапустит её; значения val1, ... передаются как результаты от приостановки.
Если сопрограмма работает без каких-либо ошибок, resume возвращает true плюс любые значения, переданные в yield (при приостановке сопрограммы), или любые значения, возвращенные телом функции (при завершении сопрограммы).
Если имеется какая-либо ошибка, resume возвращает false плюс сообщение об ошибке.
Возвращает работающую сопрограмму плюс логическое значение, true - если работающая сопрограмма является основной.
Возвращает состояние (статус) сопрограммы co, в виде строки:
"running" (работает), если сопрограмма работает (то есть, она вызвала status);
"suspended" (приостановлена), если сопрограмма приостановлена вызовом yield, или если она еще не была запущена;
"normal" (обычная) если сопрограмма активна, но не работает (то есть, она возобновила другую сопрограмму); и
"dead" (мертвая) если сопрограмма закончила выполнение тела своей функции, или если была остановлена из-за ошибки.
Создает новую сопрограмму с телом f. f должна быть функцией. Возвращает функцию, которая возобновляет выполнение сопрограммы каждый раз при её вызове.
Любые аргументы переданные функции ведут себя как дополнительные аргументы для resume.
Возвращает теже значения, что и resume, за исключением первого логического значения. В случае ошибки, передает её функции, что вызвала сопрограмму.
Приостанавливает выполнение вызываемой сопрограммы. Любые аргументы для yield передаются в resume как дополнительные результаты.
Пакетная библиотека предоставляет основные возможности по загрузке модулей в Lua. Она экспортирует одну функцию непосредственно в глобальное окружение: require.
Все остальное экспортируется в таблицу package.
Загружает заданный модуль. Функция начинает с просмотра таблицы package.loaded для определения, не является ли модуль modname уже загруженным.
Если это так, то require возвращает значение, сохраненное в package.loaded[modname].
В противном случае, она попытается найти для модуля загрузчик loader.
Для розыска загрузчика require руководствуется package.searchers sequence.
Изменяя этот порядок следования, можно изменять как require разыскивает модуль.
Следующее объяснение основано на package.searchers с настройками, заданными по умолчанию.
Вначале require запрашивает package.preload[modname].
Если он имеет значение, то это значение (которым должна быть функция) является загрузчик. В противном случае, require ищет Lua загрузчик используя путь, сохраненный в package.path.
Если это не приносит удачи, он ищет C загрузчик используя путь, сохраненный в package.cpath.
Если и здесь поиск также безуспешен, он пробует загрузчик все-в-одном (all-in-one) (смотрите package.searchers).
После того, как загрузчик найден, require вызывает его с двумя аргументами: modname и дополнительное значение, зависящее от того, как был получен загрузчик.
(Если загрузчик прибыл из файла, этим дополнительным значением будет имя файла.)
Если загрузчик возвращает любое значение, не равное nil, require присваивает возвращенное значение package.loaded[modname].
Если загрузчик не возвращает значение, не равное nil и не присваивает никакого значения package.loaded[modname], то require присваивает этой записи значение true.
В любом случае, require возвращает конечное значение package.loaded[modname].
Если имеется какая-нибудь ошибка в загрузке или в работе модуля, или если require не находит никакого загрузчика модуля, то он выдает ошибку.
Строка, описывающая некоторые параметры конфигурации во время компиляции пакетов. Это строковое значение является рядом строк:
- Первая строка - значение разделителя каталогов. По умолчанию им является '\' для Windows и '/' для всех остальных систем.
- Вторая строка - символ, разделяющий шаблоны в пути. По умолчанию это ';'.
- Третья строка - значение, которое маркирует точки замен в шаблоне. По умолчанию это '?'.
- Четвертой строкой является строковое значение, которое в пути Windows заменяется каталогом выполнения. По умолчанию это '!'.
- Пятой строкой является знак игнорирования всего текста после него, при построении имени функции luaopen_. По умолчанию это '-'.
Путь, используемый require, для поиска C-ишного загрузчика.
Lua инициализирует C путь package.cpath тем же способом, как и инициализируется Lua путь package.path,
используя переменную окружения LUA_CPATH_5_3 или переменную окружения LUA_CPATH или путь по умолчанию, заданный в luaconf.h.
Таблица, используемая require, для контроля какие из модулей уже загружены.
Когда требуется модуль modname и значение package.loaded[modname] не является ложным, require просто возвращает значение, хранящееся там.
Данная переменная является только ссылкой на реальную таблицу; присваивания (назначения) в эту переменную не изменяют таблицу, используемую require.
Функция динамически связывает хост-программу с C-ишной библиотекой libname.
Если funcname является "*", то она связывается только с библиотекой, делая символы, экспортируемые библиотекой, доступными для других динамически связанных библиотек.
В противном случае, она разыскивает функцию funcname внутри библиотеки и возвращает её как C функцию.
Так что, funcname должна придерживаться прототипа lua_CFunction (смотрите lua_CFunction).
Это низко-уровневая функция. Она полностью обходит пакет и систему модуля.
В отличие от require, она не выполняет никакого поиска пути и не добавляет расширение автоматически.
libname должен быть полным именем файла из C библиотеки, включающим в себя, при необходимости, путь и расширение.
funcname должен быть точным именем, экспортируемым C библиотекой (которое может зависеть от используемых в C компилятора и компоновщика).
Данная функция не поддерживается Standard C.
Как таковая, она доступна только на некоторых платформах (Windows, Linux, Mac OS X, Solaris, BSD, плюс другие Unix системы, которые поддерживают ).
Путь, используемый require для поиска загрузчика Lua.
При запуске, Lua инициализирует эту переменную значением переменной окружения LUA_PATH_5_3 или переменной окружения LUA_PATH,
либо значением пути по умолчанию, определенным в luaconf.h, если эти переменные окружения не определены.
Любые символы ";;", встреченные в значении переменной окружения, заменяются на путь по умолчанию.
Таблица для хранения загрузчиков для конкретных модулей (смотрите require).
Данная переменная является только ссылкой на реальную таблицу; присваивания (назначения) в эту переменную не изменяет таблицу, используемую require.
Таблица, используемая require, для управления загрузкой модулей.
Каждая запись в этой таблице является функцией поисковиком.
При поиске модуля, require вызывает каждый из этих поисковиков в восходящем порядке, с именем модуля (аргумент заданный require) в качестве его единственного параметра.
Функция может возвратить другую функцию (загрузчик модуля) плюс дополнительное значение, что будет передано этому загрузчику,
или строку, поясняющую, почему она не нашла этот модуль (или значение nil, если ей больше нечего сказать).
Lua инициализирует эту таблицу с четырьмя поисковыми функциями.
Первый поисковик просто разыскивает загрузчик в таблице package.preload.
Второй поисковик ищет загрузчик как Lua библиотеку, используя путь, хранящийся в переменной package.path.
Поиск выполняется как описано в функции package.searchpath.
Третий поисковик разыскивает загрузчик как C библиотеку, используя путь, заданный переменной package.cpath.
Опять же, поиск осуществляется как описано в функции package.searchpath.
Например, если C путь - это строка
"./?.so;./?.dll;/usr/local/?/init.so"
поисковик для модуля foo попытается открыть файлы ./foo.so, ./foo.dll, и /usr/local/foo/init.so, по порядку.
Как только находится C библиотека, этот поисковик вначале использует возможность динамического подключения для связи приложения с этой библиотекой.
Затем он пытается найти C функцию, для использования в качестве загрузчика, внутри библиотеки.
Именем этой C функции является строка "luaopen_" соединенная (конкатенированная) с копией имени модуля, в котором каждая точка заменена символом подчеркивания.
Более того, если в имени модуля имеется дефис, его суффикс (в том числе и сам дефис) после первого дефиса удаляется.
Например, если имя модуля a.b.c-v2.1, именем функции будет luaopen_a_b_c.
Четвертый поисковик попробует вызвать универсальный загрузчик все-в-одном.
Он ищет C путь для библиотеки по основному имени заданного модуля. Например, если требуется a.b.c, он будет искать C библиотеку по a.
Если библиотека найдена, он будет разыскивать в ней открывающую функцию для субмодуля; в нашем примере это будет luaopen_a_b_c.
Таким образом, пакет может упаковать несколько C субмодулей в одну отдельную библиотеку, сохраняя с каждым субмодулем его исходную функцию открытия.
Все поисковики, за исключением первого из них (preload), в виде возвращаемого значения функции package.searchpath,
возвращают в качестве дополнительного значения имя файла, где был найден модуль. Первый поисковик не возвращает дополнительного значения.
Разыскивает заданное name (имя) в указанном path (пути).
Путь является строкой, содержащей последовательный ряд шаблонов, разделенный точкой с запятой.
Для каждого шаблона функция заменяет каждый вопросительный знак (если таковые имеются) в шаблоне копией name, в котором все имеющиеся случаи sep
(по умолчанию это точка) были заменены на rep (по умолчанию это разделитель системных каталогов), и затем пробует открыть файл с получившимся именем.
Например, если путь - вот такая строка
"./?.lua;./?.lc;/usr/local/?/init.lua"
при поиске имени foo.a функция будет пытаться открыть файлы ./foo/a.lua, ./foo/a.lc, и /usr/local/foo/a/init.lua, именно в этом порядке.
Функция возвращает итоговое название первого файла, что она смогла открыть в режиме чтения (после закрытия файла), или значение nil плюс сообщение об ошибке, если не было успешного выполнения.
(В этом сообщении об ошибке перечисляются все имена файлов, которые она пыталась открыть.)
Данная библиотека предоставляет общие функции для работы со строками, такие как поиск и извлечение подстрок, а также поиск соответствия шаблону.
При индексировании строки в Lua, первый символ находится на позиции 1 (а не 0, как в C).
Индексы могут быть отрицательными, что трактуется как индексирование в обратном направлении, от конца к началу строки. Следовательно, последний символ будет в позиции -1, и так далее.
Все свои функции строковая библиотека предоставляет в таблице string. Также она устанавливает метатаблицу для строк, где поле __index указывает на таблицу string.
Таким образом, можно использовать строковые функции в объектно-ориентированном стиле. Например, string.byte(s,i) можно записать как s:byte(i).
Строковая библиотека принимает однобайтовую кодировку символов.
Возвращает внутренние числовые коды символов s[i], s[i+1], ..., s[j].
Значением по умолчанию для i является 1; значением по умолчанию для j является i.
Эти индексы корректируются следуя тем же правилам, что и у функции string.sub. Числовые коды не обязательно переносимы между платформами (операционными системами).
Принимает ноль или более целых чисел. Возвращает строку, длиной равной числу аргументов, в которой каждый символ имеет внутренний числовой код, равный соответствующему его аргументу.
То есть, функция переводит числовой код в соответствующий ему символ. Числовые коды не обязательно переносимы между платформами (операционными системами).
Возвращает строку, содержащую бинарное представление (бинарная порция chunk) заданной функции, так что позднее, функция load по этой строке возвратит копию функции (но с новыми внешними локальными переменными - upvalue).
Если аргумент strip имеет значение true, для экономии места бинарное представление может не включать всю отладочную информацию о функции.
Функции с внешними локальными переменными сохраняют только количество своих внешних локальных переменных.
При (пере)загрузке, эти внешниех локальные переменные принимают новые копии, содержащие nil.
(Можно использовать библиотеку отладки для
и перезагрузки внешних локальных переменных функции в некотором смысле, достаточном чтобы закрыть потребности.)
Разыскивает первое совпадение с шаблоном pattern (смотрите §6.4.1) в строке s.
Если совпадение найдено, то find возвращает индексы строки s, где место этого совпадения началось и закончилось; в противном случае, она возвращает значение nil.
Третий, необязательный аргумент init определяет место, откуда нужно начинать поиск; его значение по умолчанию равно 1 и может быть отрицательным.
Значение true в качестве четвертого, дополнительного аргумента plain отключает возможности поиска совпадения с шаблоном,
так что функция делает простую операцию "поиска подстроки", как если бы в pattern не было символов, считающихся магическими.
Обратите внимание, что если задан аргумент plain, то аргумент init также должен быть задан.
Если шаблон имеет захваты, то в случае успешного совпадения захваченные значения также возвращаются, после двух индексов.
Возвращает отформатированную версию строки из своего, переменного количества аргументов, придерживаясь описания, заданного в своем первом аргументе (который должен быть строкой).
Строка формата следует тем же правилам, что и функция ISO C sprintf.
Единственные отличия в том, что не поддерживаются опции/модификаторы *, h, L, l, n и p и что имеется дополнительная опция q.
Опция q форматирует строку между двойными кавычками, при необходимости
используя ,
для гарантии, что она может быть благополучно считана обратно, интерпретатором Lua.
Например, вызов
string.format('%q', 'a string with "quotes" and \n new line')
может выдать строку:
"a string with \"quotes\" and \
new line"
Опции A, a, E, e, f, G, и g все предполагают число в качестве аргумента.
Опции c, d, i, o, u, X, и x ожидают число. Опция q предполагает строку.
Опция s в качестве аргумента предполагает строку без вложенных нолей; если её аргумент не является строкой, она конвертирует её следуя тем же правилам, что и tostring.
Когда Lua компилируется не-C99 компилятором, опции A и a (шестнадцатиричные числа с плавающей запятой) не поддерживают никаких модификаторов (флаги, ширина, длина).
Возвращает функцию-итератор, которая при каждом своем вызове, возвращает следующие захваты из шаблона pattern (смотрите §6.4.1) найденные в строке s.
Если в шаблоне pattern нет захватов, то при каждом вызове выдается все найденное совпадение.
В качестве примера, цикл, указанный ниже, будет перебирать все слова из строки s, печатая их по одному в строке:
s = "hello world from Lua"
for w in string.gmatch(s, "%a+") do
print(w)
end
Следующий пример собирает в таблицу все пары key=value из заданной строки:
t = {}
s = "from=world, to=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
t[k] = v
end
Для данной функции символ карет '^' в начале шаблона не работает в качестве привязки, так как будет препятствовать итерации (перебору).
Возвращает копию строки s, в которой все (или первые n, если этот аргумент задан) случаи совпадения шаблона pattern
(смотрите §6.4.1) заменены на строку замены, указанную repl и которая может быть строкой, таблицей или функцией.
gsub также возвращает, в качестве своего второго значения, полное число случившихся совпадений.
Название функции gsub происходит он Global SUBstitution - глобальная замена.
Если repl является строкой, то её значение используется для замены.
Символ % работает в качестве экранирующего символа: любая последовательность в repl в виде %d, где d - это число между 1 и 9, обозначает значение d-нной захваченной подстроки.
Последовательность %0 обозначает все совпадение целиком. Последовательность %% обозначает одиночный символ %.
Если repl является таблицей, то эта таблица запрашивается для каждого совпадения, используя в качестве ключа первый захват.
Если repl является функцией, то эта функция вызывается каждый раз при нахождении совпадения, со всеми захваченными подстроками, передаваемыми в качестве аргументов, по порядку расположения.
В любом случае, если в шаблоне нет захватов, то он ведет себя так, как будто весь шаблон целиком был внутри захвата.
Если значение, возвращаемое запросом таблицы или вызовом функции, является строкой или числом, то оно используется в качестве замещающей строки;
в противном случае, если это значение false или nil, то замена не производится (то есть, исходное совпадение в строке сохраняется).
Вот некоторые примеры:
x = string.gsub("hello world", "(%w+)", "%1 %1")
--> x="hello hello world world"
x = string.gsub("hello world", "%w+", "%0 %0", 1)
--> x="hello hello world"
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
--> x="world hello Lua from"
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
--> x="home = /home/roberto, user = roberto"
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
return load(s)()
end)
--> x="4+5 = 9"
local t = {name="lua", version="5.3"}
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
--> x="lua-5.3.tar.gz"
Принимает строку и возвращает её длину. Пустая строка "" имеет длину 0.
Вложенные нули считаются, так что длина строки "a\000bc\000" равна 5.
Принимает строку и возвращает копию этой строки, в которой все буквы в верхнем регистре заменены на буквы в нижнем регистре. Все остальные символы оставлены без изменения.
Определение того, что является буквой в верхнем регистре зависит от текущей локали.
Функция разыскивает первое совпадение с шаблоном pattern (смотрите §6.4.1) в строке s.
Если таковое находится, то string.match возвращает захваты из шаблона; в противном случае возвращается значение nil.
Если в шаблоне pattern нет захватов, то возвращается все найденное совпадение.
Третий, необязательный числовой аргумент init указывает, с какого места начинать поиск; его значение по умолчанию равно 1 и может быть отрицательным.
Возвращает бинарную строку, содержащую значения v1, v2, и т.д. упакованную
(то есть, в двоичный вид)
в соответствии со строкой форматирования fmt (смотрите §6.4.2).
Возвращает размер строки, полученной в результате действия функции string.pack в заданном формате.
Строка формата не может иметь опций с изменяемой длиной 's' или 'z' (смотрите §6.4.2).
Возвращает строку, полученную в результате конкатенации n копий строки s разделенных строкой sep.
Значением по умолчанию для аргумента sep является пустая строка (то есть, без разделителя). Возвращает пустую строку, если n не положительное число.
Возвращает строку, в которой символы строки s расположены в обратном порядке.
Возвращает подстроку s, которая начинается от i и продолжается до j; i и j могут быть отрицательными.
Если j отсутствует, то он считается равным -1 (что то же самое, что и длина строки).
В частности, вызов string.sub(s,1,j) возвратит начало строки s длиной j, а string.sub(s, -i) возвратит окончание строки s длиной i.
Если, после преобразования отрицательных индексов, i становится меньше 1, он корректируется до 1.
Если j больше длины строки, он корректируется до этой длины.
Если, после этих исправлений, i стал больше j, функция возвратит пустую строку.
Возвращает значения, упакованные в строке s (смотрите string.pack) в соответствии со строкой формата fmt (смотрите §6.4.2).
Дополнительный (необязательный) аргумент pos обозначает место, откуда нужно начинать считывание строки s (по умолчанию значение равно 1).
После считанных значений данная функция также возвращает индекс первого несчитанного байта в строке s.
Принимает строку и возвращает копию этой строки, в которой все буквы в нижнем регистре заменены на буквы в верхнем регистре. Все другие символы остаются без изменений.
Определение того, что является буквой в нижнем регистре зависит от текущей локали.
Шаблоны в Lua описываются обычными строками (т.е. значениями типа строка), которые трактуются как шаблоны функциями сопоставления шаблонов
В этом разделе описан синтаксис и обозначение (то есть, чему они соответствуют) таких строк.
Символьный класс:
Символьный класс используется для представления наборов символов.
В описании символьного класса допустимы следующие комбинации:
- x: представляет собственно сам символ x (причем x не может быть одним из магических символов ^ $ ( ) % . [ ] * + - ?).
- .: (точка) представляет все символы.
- %a: представляет все буквы.
- %c: представляет все управляющие символы.
- %d: представляет все цифры.
- %g: представляет все печатаемых символы, кроме пробела.
- %l: представляет все строчные буквы (нижний регистр).
- %p: представляет все знаки препинания.
- %s: представляет все символы пробела.
- %u: представляет все заглавные буквы (верхний регистр).
- %w: представляет все буквенно-цифровые символы.
- %x: представляет все шестнадцатиричные цифры.
- %x: представляет символ x (причем x является любым не буквенно-цифровым символом). Это стандартный способ избежать магических символов (это действие, т.е. постановка знака процента перед символом, также называется экранированием символов).
Любому не буквенно-цифровому символу (включая все знаки препинания, даже не магические), когда он используется в шаблоне для представления самого себя, может предшествовать символ '%'.
- [set]: представляет класс, который объединяет все символы в набор. Диапазон символов может быть указан разделением конечных символов диапазона в возрастающем порядке, с помощью '-'.
Все классы %x описанные выше, также могут использоваться в качестве компонентов набора. Все другие символы в наборе представляют сами себя.
Например, набор [%w_] (или [_%w]) представляет все буквенно-цифровые символы плюс символ подчеркивания,
[0-7] представляет все восьмиричные цифры, а [0-7%l%-] представляет восьмиричные цифры плюс строчные буквы плюс символ '-'.
Взаимодействие между диапазонами и классами не определяется. Поэтому шаблоны, подобные [%a-z] или [a-%%] не имеют никакого значения.
- [^set]: представляет дополнение к set (т.е. любые символы, кроме входящих в набор), где set трактуется как показано выше.
Для всех классов, представляющих одиночные буквы (%a, %c, etc.), соответствующая буква в верхнем регистре представляет дополнение класса, т.е. все символы не входящие в класс.
Например, %S представляет все символы, отличные от пробела.
Определения букв, пробела и других символьных групп зависят от текущей локали. В частности, класс [a-z] может быть не равнозначен %l.
Элементы шаблона:
Элементом шаблона (pattern item) может быть
- одиночный символьный класс, соответствующий любому одиночному символу в классе;
- одиночный символьный класс, сопровождаемый символом '*', соответствующий нулю или большему числу повторений символов в классе.
Эти элементы повторения всегда будут соответствовать наиболее длинной возможной последовательности;
- одиночный символьный класс, сопровождаемый символом '+', соответствующий одному или большему числу повторений символов в классе.
Эти элементы повторения всегда будут соотвествовать наиболее длинной возможной последовательности;
- одиночный символьный класс, сопровождаемый символом '-', также соответствующий нулю или большему числу повторений символов в классе.
В отличие от '*', эти элементы повторения всегда будут соответствовать наиболее короткой возможной последовательности;
- одиночный символьный класс, сопровождаемый символом '?', соответствующий нулевому или единственному совпадению символа в классе. По возможности он всегда соответствует единственному совпадению;
- %n, при n между 1 и 9; такой элемент соответствует части строки равной n-ной захваченной строке (смотрите ниже);
- %bxy, где x и y - это два разных символа;
такой элемент соответствует строкам, начинающимся с x и заканчивающимся с y, и где x и y являются сбалансированными.
Это означает, что если подсчитывать их в строке слева направо, полагая что x - это +1, а y -1, то последний y станет первым y, на котором счетчик станет равным 0.
Например, элемент %b() соответствует выражениям со сбалансированными круглыми скобками.
- %f[set], пограничный (frontier) шаблон;
такой элемент соответствует пустой строке в любой позиции, когда последующий символ входит в состав set, а предыдущий символ не относится к set.
Набор set трактуется как описано выше. Начало и конец предмета разговора обрабатываются как если они были символом '\0'.
Шаблон:
Шаблон - это последовательность элементов шаблона. Символ карет '^' в начале шаблона, привязывает соответствие к началу обрабатываемой строки.
Символ '$' в конце шаблона, привязывает соответствие к концу обрабатываемой строки. В других позициях, символы '^' и '$' ничего особенного не обозначают и представляют сами себя.
Захваты:
Шаблон может содержать вложенные шаблоны, заключаемые в круглые скобки; они описывают захваты (capture).
При успешном обнаружении соответствия, части обрабатываемой строки, которые соответствуют захвату, сохраняются (захватываются) для дальнейшего использования.
Захваты нумеруются по их левым скобкам. Например, в шаблоне "(a*(.)%w(%s*))", часть строки, соответствующая "a*(.)%w(%s*)", сохраняется как первый захват (и поэтому имеет номер 1);
символ, соответствующий ".", является захватом номер 2, а часть, соответствующая "%s*", имеет номер 3.
Как особый случай, пустой захват () захватывает текущую позицию строки (число). Например, если применить шаблон "()aa()" к строке "flaaap", то получим два захвата: 3 и 5.
Первым аргументом для функций string.pack, string.packsize и string.unpack является строка формата,
которая описывает схему структуры, создаваемой или считываемой.
Строка формата - это последовательность опций преобразования. Варианты преобразования следующие:
- <: устанавливает прямой порядок байтов (little endian)
- >: устанавливает обратный порядок байтов (big endian)
- =: устанавливает естественный порядок байтов (native endian)
- ![n]: устанавливает максимальное выравнивание в n (по умолчанию является естественным выравниванием)
- b: байт со знаком (char)
- B: байт без знака (char)
- h: знаковое число в "коротком" формате short (естественный размер)
- H: беззнаковое число в "коротком" формате short (естественный размер)
- l: знаковое число в "длинном" формате long (естественный размер)
- L: беззнаковое число в "длинном" формате long (естественный размер)
- j: lua_Integer - целое Lua число
- J: lua_Unsigned - беззнаковое Lua число
- T: size_t (естественный размер)
- i[n]: знаковое целое число int в n байт (по умолчанию является естественным размером)
- I[n]: беззнаковое целое число int в n байт (по умолчанию является естественным размером)
- f: float - число с плавающей запятой (естественный размер)
- d: double - число двойной точности (естественный размер)
- n: lua_Number - число Lua
- cn: строка фиксированного размера в n байт
- z: строка, завершающаяся нулем
- s[n]: строка, которой предшествует её длина, кодированная как беззнаковое целое число в n байт (по умолчанию это size_t)
- x: один байт поля выравнивания (padding)
- Xop: пустой элемент, что выравнивает в соответствии с опцией op (которая в противном случае игнорируется)
- '
': (пустое место) игнорируется
("[n]" означает дополнительную встроенную цифру.)
За исключением полей (padding), пробелов (space) и конфигураций (configuration) (опции "xX <=>!"), каждая опция соответствует аргументу (в string.pack) или результату (в string.unpack).
Для опций "!n", "sn", "in", и "In", n может быть любым целым числом между 1 и 16.
Все встроенные опции проверяют переполнение; string.pack проверяет, уместится ли заданное значение в заданный размер;
string.unpack проверяет, соответствует ли считываемое значение целому числу Lua.
Любая строка формата начинается, как если бы у нее был префикс "!1=", то есть, с максимального выравнивания равного 1 (нет выравнивания) и естественного порядка байтов.
Выравнивание работает следующим образом:
Для каждой опции формат получает дополнительное поле до начала данных со смещением, которое кратно минимуму между размером опции и максимальным выравниванием; этот минимум должен быть степенью двойки.
Опции "c" и "z" не выравниваются; опция "s" придерживается выравнивания своего начального целого числа.
Все поля заполняются нулями функцией string.pack (и игнорируются функцией string.unpack).
Эта библиотека предоставляет базовую поддержку для кодирования UTF-8. Она размещает все свои функции в таблице utf8.
Данная библиотека не предоставляет какой-либо поддержки Unicode кроме обработки кодирования.
Любая операция, требующая обозначения символа, вроде классификации символов, находится вне сферы применения данной библиотеки.
Если не указано иное, все функции, ожидающие местоположение байта в качестве параметра, предполагают, что заданная позиция является либо началом последовательности байтов, либо оно же плюс длина представленной строки.
Как и в строковой библиотеке, отрицательные индексы отсчитываются от конца строки.
Функция получает ноль или более целых чисел, преобразовывает каждый из них в соответствующую UTF-8 последовательность байтов и возвращает строку с присоединением (конкатенацией) всех этих последовательностей.
Шаблон (строка, а не функция) "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" (смотрите §6.4.1),
который в точности соответствует однобайтовой UTF-8 последовательности (одному символу UTF-8), предполагая что испытуемый объект является допустимой UTF-8 строкой.
Функция возвращает значения, так что конструкция
for p, c in utf8.codes(s) do body end
будет перебирать все символы в строке s, с p, что является позицией (в байтах) и
c - каждого символа.
Функция выдает ошибку, если встретит любую недопустимую последовательность байтов.
Возвращает кодовые точки (коды символов) (в виде целых чисел) от всех символов в строке s, которая начинается между байтовой позицией i и j (включая и ту и другую).
Значением по умолчанию для i является 1, а для j - i.
Функция выдает ошибку, если встретит любую недопустимую последовательность байтов.
Функция возвращает число символов UTF-8 в строке s, которая начинается между позициями i и j (включая и ту и другую).
Значением по умолчанию для i является 1, и -1 для j.
Если она находит любую недопустимую последовательность байтов, то возвращает значение false плюс положение первого неправильного байта.
Функция возвращает позицию (в байтах), где начинается закодированный n-ный символ из строки s (считая от позиции i). Отрицательный n получает символы перед позицией i.
Значением по умолчанию для i является 1, при положительном n, и #s + 1 в противном случае, так что utf8.offset(s, -n) получит смещение n-ного символа от конца строки.
Если указанный символ нет ни в представленной части, ни сразу после её окончания, функция возвращает nil.
В качестве особого случая, при n равном 0 функция возвращает начало кодировки символа, который содержит i-ковый байт строки s.
Данная функция предполагает, что s является допустимой UTF-8 строкой.
Данная библиотека предоставляет типовые функции для обработки таблиц.
Она размещает все свои функции в таблице table.
Помните, что каждый раз, когда операции требуется длина таблицы, таблица должна быть правильной последовательностью или иметь метаметод __len (смотрите §3.4.7).
Все функции игнорируют нечисловые ключи в таблицах, заданные в качестве аргументов.
Функции задается список, где все элементы являются строками или числами, а она возвращает строку list[i]..sep..list[i+1] ... sep..list[j].
Значением по умолчанию для sep является пустая строка, i по умолчанию равен 1, а для j по умолчанию является #list, т.е. длина списка.
Если i больше j, возвращается пустая строка.
Вставляет элемент value в позицию pos списка list, сдвигая вверх элементы list[pos], list[pos+1], ..., list[#list].
Значением по умолчанию для pos является #list+1, так что вызов table.insert(t,x) вставит x в конец списка t.
Перемещает элементы из таблицы a1 в таблицу a2. Данная функция по выполнямому действию эквивалентна следующему множественному присваиванию: a2[t],... = a1[f],...,a1[e].
Значением по умолчанию для a2 является a1. Диапазон назначения может перекрывать исходный диапазон. Число элементов для перемещения должно соответствовать целому числу Lua.
Возвращает новую таблицу со всеми параметрами, хранящимися в ключах 1, 2, и т.д., и полем "n" с полным числом параметров.
Обратите внимание, что получившаяся таблица может не быть последовательностью.
Функция удаляет из списка list элемент в позиции pos и возвращает значение удаленного элемента.
Когда pos является целым числом между 1 и #list, она сдвигает вниз элементы list[pos+1], list[pos+2], ..., list[#list] и удаляет элемент list[#list];
Индекс pos также может быть 0, когда #list является 0, или #list + 1; в этих случаях, функция удаляет элемент list[pos].
Значением по умолчанию для pos является #list (т.е. длина списка), так что вызов table.remove(l) удалит последний элемент списка l.
Сортирует список элементов в заданном порядке, по месту (т.е. внутри таблицы), от list[1] до list[#list].
Если задан аргумент comp, то он должен быть функцией, которая принимает два списка элементов и возвращает, в конечном счете, значение true, когда первый элемент должен предшествовать второму
(так что выражение not comp(list[i+1],list[i]) после сортировки будет истинным).
Если аргумент comp не задан, то вместо него используется стандартный Lua оператор < "меньше чем".
Алгоритм сортировки нестабилен; то есть, элементы, которые в заданном порядке были признаны равными, при сортировке могут изменить свое местоположение относительно друг друга.
Возвращает элементы из заданного списка. Эта функция эквивалентна
return list[i], list[i+1], ..., list[j]
По умолчанию, i равно 1, а j равно #list (длине списка).
Данная библиотека представляет основные математические функции.
Она размещает все свои функции и константы в таблице math.
Функции с пометкой "integer/float" (целое число/число с плавающей запятой) выдают целочисленные результаты для целочисленных аргументов, а для аргументов в числах с плавающей запятой (или смешанных) - результаты в числах с плавающей запятой.
Функции округления (math.ceil, math.floor, и math.modf) возвращают целое число, если результат умещается в диапазон целых чисел, или, в противном случае, число с плавающей запятой.
Возвращает x.
Возвращает арккосинус x (в радианах).
Возвращает арксинус x (в радианах).
Возвращает арктангенс y/x (в радианах), а использование знаков у обоих аргументов позволяет отыскать результата.
(Также функция корректно обрабатывает случай когда x равен нулю.)
По умолчанию значением для x является 1, так что вызов math.atan(y) возвращает арктангенс y.
Возвращает наименьшее целочисленное значение большее чем или равное x (округление вверх).
Возвращает косинус x (предполагается, что в радианах).
Конвертирует угол x из радианов в градусы.
Возвращает значение ex (где e - основание натуральных логарифмов).
Возвращает наибольшее целочисленное значение меньшее чем или равное x (округление вниз).
Возвращает остаток от деления x на y с округлением частного в сторону нуля.
Значение с плавающей запятой HUGE_VAL, значение большее чем любое другое числовое значение.
Возвращает логарифм x с заданным основанием. Значением по умолчанию для base является e (так что функция возвращает натуральный логарифм x).
Возвращает аргумент с максимальным значением, в соответствии с Lua оператором < "меньше чем".
Возвращает целое число с максимальным значением для целого числа.
Возвращает аргумент с минимальным значением, в соответствии с Lua оператором < "меньше чем".
Возвращает целое число с минимальным значением для целого числа.
Возвращает целочисленную часть x и дробную часть x. Второй результат - всегда число с плавающей запятой.
Значение числа π.
Конвертирует угол x из градусов в радианы.
При вызове без аргументов, возвращает псевдослучайное число с плавающей запятой с равномерным распределением в диапазоне [0,1].
При вызове с двумя целочисленными аргументами m и n, math.random возвратит псевдослучайное целое число с равномерным распределением в диапазоне [m, n].
(Значение m-n не может быть отрицательным и должно соответствовать целому Lua числу.) Вызов math.random(n) равнозначен math.random(1,n).
Данная функция является интерфейсом к функции простейшего генератора псевдослучайных чисел предоставляемого C. По его статистическим свойствам не дается никаких гарантий.
Устанавливает x в качестве "зерна" (seed) для генератора псевдослучайных чисел: равные "зерна" выдают равные последовательности чисел.
Возвращает синус x (предполагается, что в радианах).
Возвращает квадратный корень из x. (Для вычисления этого значения также можно использовать выражение x^0.5.)
Возвращает тангенс x (предполагается, что в радианах).
Если значение x можно конвертировать в целое число, то возвращает это число. В противном случае возвращает значение nil.
Возвращает "integer" - если x является целым числом, "float" - если это число с плавающей запятой, или nil - если x не является числом.
Возвращает логическое значение true если целочисленное значение m ниже целочисленного значения n, когда они сравниваются как беззнаковые целые числа.
Библиотека ввода/вывода (I/O - input/output) предоставляет два разных стиля для работы с файлами.
Первый из них использует неявные (скрытые) дескрипторы файлов; то есть, существуют операции по установке входного и выходного файлов по умолчанию, и все операции ввода/вывода производятся над этими файлами по умолчанию.
Второй стиль использует явные дескрипторы файлов.
При использовании неявных дескрипторов файлов, все операции предоставлены таблицей io.
При использовании явных дескрипторов файлов, функция io.open возвращает дескриптор файла и затем все операции предоставляются как методы дескриптора файла.
Таблица io также предоставляет три, предварительно определенных дескриптора файла из С, со стандартными их обозначениями: io.stdin, io.stdout, и io.stderr.
Эти файлы библиотека ввода/вывода никогда не закрывает.
Если не указано иное, при неудачном выполнении все функции ввода/вывода возвращают nil (плюс сообщение об ошибке в качестве второго результата и системно-зависимый код ошибки как третий результат),
и некоторое значение, отличное от nil, в случае успеха.
На не-POSIX системах, вычисление сообщения об ошибке и кода ошибки в случае ошибок может иметь проблемы с многопоточностью, так как они базируются на глобальной C переменной errno.
Эквивалентна file:close(). В отсутствии аргумента file, закрывает выходной файл по умолчанию.
Эквивалентна io.output():flush().
При вызове с именем файла, функция открывает названный файл (в текстовом режиме) и устанавливает его дескриптор (handle) как входной файл по умолчанию.
При вызове с дескриптором файла, она просто устанавливает данный файл в качестве входного файла по умолчанию. При вызове без параметров, она возвращает текущий входной файл по умолчанию.
В случае ошибок данная функция выдает ошибку, вместо возвращения кода ошибки.
Открывает файл с заданным именем в режиме чтения и возвращает функцию итератора, которая работает с открытым файлом как file:lines(...).
Когда функция итератор определяет окончание файла, она не возвращает значений (для завершения цикла), а автоматически закрывает файл.
Вызов io.lines() (с отсутствующим именем файла) эквивалентен io.input():lines("*l"); то есть, она итерирует строки входного файла по умолчанию. В этом случае она не закрывает файл по окончанию цикла.
В случае ошибок, данная функция выдает ошибку вместо возврата кода ошибки.
Данная функция открывает файл в режиме, указанном в строке mode. Она возвращает дескриптор нового файла, или, в случае ошибок, значение nil плюс сообщение об ошибке.
Строка mode может быть любой из следующих:
- "r": режим чтения (по умолчанию);
- "w": режим записи;
- "a": режим добавления;
- "r+": режим обновления, все предыдущие данные сохраняются;
- "w+": режим обновления, все предыдущие данные удаляются;
- "a+": режим обновления с добавлением, предыдущие данные сохраняются, запись допускается только в конец файла.
Строка mode также может иметь в конце символ 'b', который необходим в некоторых системах для открытия файла в бинарном режиме.
Функция аналогична io.input, но работает с выходным файлом по умолчанию.
Данная функция системно зависима и доступна не на всех платформах.
Запускает программу prog в отдельном процессе и возвращает дескриптор файла, который можно использовать для считывания данных из этой программы
(если mode установлен как "r", по умолчанию) или для записи данных к этой программе (если mode установлен как "w").
Эквивалентна io.input():read(...).
Возвращает дескриптор временного файла. Этот файл открывается в режиме обновления и автоматически удаляется по завершению работы программы.
Функция проверяет, является ли obj действующим дескриптором файла.
Возвращает строку "file" если obj является дескриптором открытого файла, "closed file",
если obj - дескриптор закрытого файла, или nil, если obj не является дескриптором файла.
Эквивалентна io.output():write(...).
Закрывает файл file. Обратите внимание, что файлы закрываются автоматически, когда их дескрипторы прибирает сборщик мусора, но ожидание, когда это произойдет, может занять непредсказуемое количество времени.
При закрытии файла с дескриптором, созданным с помощью io.popen, функция file:close возвращает те же самые значения, что и os.execute.
Сохраняет любые записанные данные в file.
Возвращает функцию-итератор, которая при каждом своем вызове считывает файл в соответствии с заданными форматами. Если формат не задан, используется "l" как формат по умолчанию.
В качестве примера, конструкция
for c in file:lines(1) do body end
будет перебирать все символы файла, начиная с текущей позиции.
В отличие от io.lines, данная функция не закрывает файл при завершении цикла.
В случае ошибок эта функция выдает ошибку, взамен возвращения кода ошибки.
Считывает файл file, в соответствии с заданными форматами, которые определяют, что считывать.
Для каждого формата функция возвращает строку или число сосчитанных символов, или nil если она не смогла прочитать данные в указанном формате. (В этом последнем случае, функция не считывает последующие форматы.)
При вызове без форматов, она использует формат по умолчанию, который считывает следующую строку (смотрите ниже).
Доступные форматы
- "n": считывает число и возвращает его как число с плавающей запятой или целое число, следуя лексическим соглашениям Lua. (Число может иметь перед собой пробелы и знак.)
Этот формат всегда считывает самую длинную входную последовательность, которая является для числа допустимым префиксом; если этот префикс не формирует
допустимое число (например, пустая строка, "0x", или "3.4e-"), он отбрасывается и функция возвращает nil.
- "a": считывает весь файл, начиная с текущей позиции. По окончании файла, возвращает пустую строку.
- "l": считывает следующую строку, пропуская символ конца строки; возвращает nil по окончании файла. Это формат по умолчанию.
- "L": считывает следующую строку, сохраняя символ конца строки (если он присутствует); возвращает nil по окончании файла.
- number: считывает строку вплоть до указанного числа байт (number - число), возвращая nil по завершении файла.
Если number является нулем, то ничего не считывается и возвращается пустая строка, или nil по завершении файла.
Форматы "l" и "L" должны использоваться только для текстовых файлов.
Устанавливает и получает позицию в файле, отмеряемую от начала файла, к позиции, задаваемой аргументом offset (смещение) плюс базовое значение, указываемое строковым аргументом whence (откуда) следующим образом:
- "set": базовое значение равно 0 (начало файла);
- "cur": базовым значением является текущая позиция;
- "end": базовым значением является конец файла;
В случае успешного выполнения, seek возвращает конечную позицию в файле, отмеренную в байтах от начала файла.
Если выполнение seek окончилось неудачно, она возвращает nil, плюс строку с описанием ошибки.
Значением по умолчанию для аргумента whence является "cur", а для offset оно равно 0.
Таким образом, вызов file:seek() возвратит текущую позицию в файле, без её изменения; вызов file:seek("set") установит позицию на начало файла (и возвратит 0);
а вызов file:seek("end") установит позицию на конец файла и возвратит его размер.
Устанавливает режим буферизации выходного файла. Существуют три доступных режима:
- "no": нет буферизации; результат любой выходной операции появляется немедленно.
- "full": полная буферизация; выходная операция выполняется только когда буфер полон, или когда буферы файла явно сбрасываются (смотрите io.flush).
- "line": строчная буферизация; выход буферизуется до тех пор, пока на выходе не появится символ "новая строка" или имеется любой ввод из некоторых специальных файлов (таких как терминальное устройство).
В двух последних случаях, size определяет размер буфера, в байтах. Значением по умолчанию является соответствующий размер.
Записывает значение каждого из своих аргументов в file. Аргументы должны быть строками или числами.
При успешном выполнении функция возвращает file. В противном случае она возвращает nil плюс строку с описанием ошибки.
Данная библиотека реализуется через таблицу os.
Возвращает примерное количество секунд времени процессора (CPU), использованного программой.
Возвращает строку или таблицу, содержащую дату и время, отформатированные в соответствии с форматом, заданным в строке format.
Если предоставляется аргумент time, то время форматируется в соответствии с ним (смотрите функцию os.time для описания этого значения).
В противном случае, аргумент date отформатирует время как текущее.
Если строковый аргумент format начинается с '!', то дата форматируется в Coordinated Universal Time - UTC (всемирное координированное время).
После этого необязательного символа, если аргумент format является строкой "*t", то date возвратит таблицу со следующими полями:
year (четыре цифры), month (1–12), day (1–31), hour (0–23), min (0–59), sec (0–61),
wday (неделя (weekday), воскресенье (Sunday) является 1), yday (день года), и isdst (флаг перехода на летнее время, логическое значение, равное true, если задействован перевод времени).
Это последнее поле может отсутствовать, если сведения недоступны.
Если format не является "*t", то date возвратит дату в виде строки, отформатированной в соответствии с теми же правилами как у функции ISO C strftime.
При вызове без аргументов, date возвращает подходящее представление даты и времени, которое зависит от операционной системы и текущей локали (то есть, вызов os.date() эквивалентен вызову os.date("%c")).
На не-POSIX системах, данная функция может быть не многопоточной, из-за её зависимости от C-ишных функций gmtime и localtime.
Возвращает разницу между временами t1 и t2, в секундах (где времена являются значениями, возвращенными функцией os.time).
В POSIX, Windows, и некоторых других системах, это значение в точности равно t2-t1.
Данная функция эквивалентна функции system на ISO C.
Она передает команду command для выполнения оболочкой операционной системы.
Её первым результатом является логическое значение true, если команда завершилась успешно, или значение nil, в противном случае.
После этого первого результата, функция возвращает строку плюс число, следующим образом:
- "exit": команда завершена нормально; последующее число является выходным статусом команды.
- "signal": команда была завершена по сигналу; последующее число является сигналом, что завершил команду.
При вызове без аргумента command, os.execute возвращает логическое значение, которым будет true, если оболочка доступна.
Вызывает функцию exit ISO C для завершения хост-программы. Если аргумент code является true, возвращаемым состоянием является EXIT_SUCCESS;
если code - false, возвращаемое состояние - EXIT_FAILURE; если code является числом, возвращаемое состояние является этим числом. Значением по умолчанию для code является true.
Если второй, необязательный аргумент close является true, то перед выходом Lua состояние закрывается.
Возвращает значение переменной среды процесса varname, или nil, если переменная не определена.
Удаляет файл (или пустую директорию, на POSIX системах) с заданным именем. Если эта функция завершилась неудачей, она возвращает значение nil, плюс строку, описывающую ошибку, и код ошибки.
Переименовывает файл или директорию с именем oldname на newname. Если эта функция завершилась неудачей, она возвращает значение nil, плюс строку, описывающую ошибку, и код ошибки.
Устанавливает текущую локаль программы.
locale - это системно-зависимый строковый аргумент определяющий локаль;
category - дополнительный (необязательный) строковый аргумент, описывающий которую из категорий нужно изменять: "all" - все, "collate" - сопоставление символов, "ctype" - тип символов,
"monetary" - валютная, "numeric" - числа или "time" - время; категорией по умолчанию является "all".
Функция возвращает имя текущей локали или значение nil, если запрос не может быть выполнен.
Если аргументом locale является пустая строка, текущая локаль устанавливается как определяемая реализацией местная (региональная) локаль.
Если locale является строкой "C", текущая локаль устанавливается как стандартная С локаль.
При вызове с nil в качестве первого аргумента, эта функция возвращает только имя текущей локали для заданной категории.
Эта функция может быть не многопоточной, из-за её зависимости от C-ишной функции setlocale.
Возвращает текущее время, при вызове без аргументов, или время, представляющее локальные дату и время, указанные в приведенной таблице.
Эта таблица должна иметь поля year, month, и day, и может иметь поля hour (по умолчанию равно 12),
min (по умолчанию равно 0), sec (по умолчанию равно 0), и isdst (по умолчанию равно nil). Другие поля игнорируются.
Описание этих полей смотрите в описании функции os.date.
Значениям этих полей не требуется быть внутри диапазонов их допустимых значений.
Например, если sec равен -10, это означает -10 секунд от времени указанного в других полях; если hour равен 1000, это значит +1000 от времени, указанного в других полях.
Возвращаемое значение является числом, значение которого зависит от системы.
В POSIX, Windows и некоторых других системах, это число считается числом секунд начиная с некоторого заданного
.
В других системах, обозначение не определено и число возвращаемое os.time можно использовать только как аргумент функций os.date и os.difftime.
Возвращает строку с именем файла, который может использоваться в качестве временного файла. Файл, перед его использованием, должен быть явно открыт и явно удален, когда станет не нужен.
На POSIX системах, во избежание угрозы безопасности, эта функция также создает файл с этим именем. Кто-нибудь может создать файл с неверными разрешениями во время между получением имени и созданием файла.
Остается открывать файл для его использования и удалять его (даже если он не используется).
По возможности предпочтительнее использовать функцию io.tmpfile, которая автоматически удаляет файл при завершении программы.
Эта библиотека предоставляет набор функций отладочного интерфейса (§4.9) для Lua программ. При использовании данной библиотеки следует проявлять осторожность.
Несколько функций этой библиотеки нарушают основные положения Lua кода (например, что переменные, локальные для функции, не могут быть доступны снаружи;
что метатаблицы userdata не могут быть изменены Lua кодом; что Lua программы не ломаются) и, следовательно, могут поставить под угрозу другой, защищенный код.
Кроме того, некоторые функции из этой библиотеки могут быть медленными.
Все функции этой библиотеки размещаются в таблице debug.
Все функции, работающие с нитями (thread) имеют дополнительный первый аргумент, который определяет нить для обработки. Значением по умолчанию всегда является текущая нить.
Вводит режим взаимодействия (интерактивный режим) с пользователем, запуская каждую строку, введенную пользователем.
Используя простые команды и другие возможности отладки, пользователь может проверить глобальные и локальные переменные, изменять их значения, вычислять выражения и так далее.
Строка, содержащая единственное слово cont завершает выполнение этой функции, так чтобы вызывающая программа продолжила свое выполнение.
Обратите внимание, что команды для debug.debug лексически не вложены ни в какую функцию и поэтому не имеют прямого доступа к локальным переменным.
Возвращает настройки текущей ловушки потока, в виде трех значений: текущая функция ловушки, текущая маска ловушки и текущий счетчик ловушки (как установлено функцией debug.sethook).
Возвращает таблицу со сведениями о функции. Можно непосредственно задавать функцию или задавать число в качестве значения f, которое означает функцию работающую на уровне f стека вызовов заданного потока:
уровень 0 - это текущая функция (собственно сама getinfo); уровень 1 - это функция, которая вызвала getinfo (кроме хвостовых вызовов (tail calls), которые не учитываются стеком); и так далее.
Если число f больше числа активных функций, то getinfo возвращает значение nil.
Возвращаемая таблица может содержать все поля, возвращаемые функцией lua_getinfo, со строкой what, описывающей какие поля в ней нужно заполнить.
Для параметра what значением по умолчанию является получение всей доступной информации, кроме таблицы действующих (valid) строк.
Опция 'f' (если имеется) добавляет поле по имени func с собственно самой функцией.
Опция 'L' (если присутствует) добавляет поле с именем activelines с таблицей действующих строк.
Например, выражение debug.getinfo(1,"n").name возвратит имя текущей функции, если подходящее имя может быть найдено,
а выражение debug.getinfo(print) возвратит таблицу со всеми доступными сведениями о функции print.
Данная функция возвращает имя и значение локальной переменной с индексом local функции, находящейся в стеке на уровне f.
Эта функция получает доступ не только к явным локальным переменным, но также к параметрам, временным переменным, и т.д.
Первый параметр или локальная переменная имеют индекс 1, и так далее, следуя порядку, в котором они объявлены в коде, считая только переменные, которые активны в текущей области видимости функции.
Отрицательные индексы относятся к функциям с переменным числом аргументов; -1 является первым vararg параметром.
Функция возвращает значение nil, если не существует переменной с заданным индексом и выдает ошибку при вызове с уровнем вне диапазона стека.
(Для проверки правильности уровня можно вызвать debug.getinfo.)
Имена переменных, начинающиеся с '(' (открывающей круглой скобки) представляют переменные с неизвестными именами (внутренние переменные,
такие как переменные управления в цикле, и переменные из порций (chunk), сохраненные без отладочной информации).
Параметр f также может быть функцией. В этом случае, getlocalвозвращает только имена параметров функции.
Возвращает метатаблицу заданного value или nil, если он не имеет метатаблицы.
Возвращает таблицу реестра (смотрите §4.5).
Данная функция возвращает имя и значение upvalue с индексом up функции f.
Функция возвращает значение nil, если upvalue с заданным индексом не существует.
Имена переменных, начинающиеся с '(' (открывающей круглой скобки) представляют переменные с неизвестными именами (переменные из порций (chunk), сохраненные без отладочной информации).
Возвращает Lua значение связанное с u. Если u не является userdata, возвращается значение nil.
Устанавливает заданную функцию в качестве ловушки (hook). Строка mask и число count описывают, когда ловушка будет вызвана.
Строка маски может иметь любую комбинацию из следующих символов, с данным значением:
- 'c': ловушка вызывается каждый раз когда Lua вызывает функцию;
- 'r': ловушка вызывается каждый раз когда Lua возвращает из функции;
- 'l': ловушка вызывается каждый раз когда Lua вводит новую строку в код.
Кроме того, с аргументом count отличным от нуля, ловушка также вызывается после выполнения каждого, определенного количества (указанного в count) инструкций.
При вызове без аргументов debug.sethook отключает ловушку.
При вызове ловушки, её первым параметром является строка, описывающая событие, на которое срабатывает её вызов:
"call" - вызов (или "tail call" - хвостовой вызов), "return" - возврат, "line" - строка, и "count" - счет.
Для строковых событий, ловушка также получает новый номер строки в качестве второго параметра.
Внутри ловушки можно вызывать функцию getinfo с уровнем 2, для получения более подробной информации о работающей функции (уровень 0 - это функция getinfo, а уровень 1 - функция ловушки).
Эта функция присваивает значение value локальной переменной с индексом local функции на уровне level стека.
Функция возвращает значение nil, если локальной переменной с заданным индексом не существует и выдает ошибку при вызове с уровнем level, выходящим за пределы стека.
(Для проверки правильности уровня можно вызвать функцию getinfo.)
В противном случае, она возвращает имя локальной переменной.
Посмотрите описание debug.getlocal для более подробных сведений о индексах и именах переменных.
Устанавливает метатаблицу для заданного value как заданную table (которая может быть nil). Возвращает value.
Данная функция присваивает значение value для внешней локальной переменной (upvalue) с индексом up функции f.
Функция возвращает nil если не существует upvalue с заданным индексом. В противном случае, она возвращает имя этой upvalue.
Функция устанавливает заданное значение value в качестве Lua значения, связанного с заданным udata. udata должен быть полноценными userdata.
Возвращает udata.
Если аргумент message присутствует, но не является ни строкой, ни значением nil, то эта функция возвратит message без последующей обработки. В противном случае, она возвратит строку с трассировкой (traceback) стека вызова.
В начало трассировки добавляется строка из дополнительного (необязательного) аргумента message.
Число в необязательном аргументе level сообщает уровень, с которого нужно начать отслеживание (значение по умолчанию равно 1, т.е. это функция вызвавшая traceback).
Возвращает уникальный идентификатор (в виде легких userdata) внешней локальной переменной (upvalue) под номером n из заданной функции.
Эти уникальные идентификаторы позволяют программе проверить, используют ли совместно различные замыкания функции внешние локальные переменные.
Lua замыкания, которые совместно используют upvalue (то есть те, что обращаются к одной и той же внешней локальной переменной) будут возвращать одинаковые идентификаторы для индексов этой upvalue.
Функция делает n1-ную внешнюю локальную переменную (upvalue) замыкания Lua f1 отсылаемой на n2-ную upvalue замыкания Lua f2.