6 – Стандартные библиотеки

Стандартные библиотеки Lua предоставляют полезные функции, реализованные на C через C API. Некоторые из этих функций предоставляют языку основные услуги (например, type и getmetatable); другие предоставляют доступ к внешним службам (например, вводу-выводу); а третьи могли бы быть реализованы на самом Lua, но по разным причинам заслуживают реализации на C (например, table.sort).

Все библиотеки реализованы через официальный C API и поставляются как отдельные C модули. Если не указано иное, эти библиотечные функции не приводят число своих аргументов к ожидаемым параметрам. Например, функцию, описанную как foo(arg), не следует вызывать без аргумента.

Обозначение fail означает ложное значение, представляющее какой-либо вид отказа. (В настоящее время fail равно nil, но это может измениться в будущих версиях. Рекомендуется всегда проверять успешность этих функций с помощью (not status), а не (status == nil).)

В настоящее время Lua имеет следующие стандартные библиотеки:

• базовая библиотека (§6.2);
• библиотека сопрограмм (§6.3);
• библиотека пакетов (§6.4);
• обработка строк (§6.5);
• базовая поддержка UTF-8 (§6.6);
• обработка таблиц (§6.7);
• математические функции (§6.8) (sin, log и т.д.);
• ввод и вывод (§6.9);
• средства операционной системы (§6.10);
• средства отладки (§6.11).

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

6.1 – Загрузка библиотек в коде C

Программа-хост на C должна явно загрузить стандартные библиотеки в состояние, если она хочет, чтобы её скрипты могли их использовать. Для этого программа-хост может вызвать функцию luaL_openlibs. В качестве альтернативы хост может выбрать, какие библиотеки открывать, с помощью luaL_openselectedlibs. Обе функции объявлены в заголовочном файле lualib.h.

Автономный интерпретатор lua (см. §7) уже открывает все стандартные библиотеки.

luaL_openlibs

[-0, +0, e]

void luaL_openlibs (lua_State *L);

Открывает все стандартные библиотеки Lua в заданном состоянии.

luaL_openselectedlibs

[-0, +0, e]

void luaL_openselectedlibs (lua_State *L, int load, int preload);

Открывает (загружает) и предзагружает выбранные стандартные библиотеки в состояние L. (Предзагрузить означает добавить загрузчик библиотеки в таблицу package.preload, чтобы впоследствии библиотеку можно было запросить из программы. Учтите, что сам require предоставляется библиотекой package. Если программа не загружает эту библиотеку, она не сможет ничего запросить.)

Целое число load выбирает, какие библиотеки загружать; целое число preload выбирает, какие предзагружать из числа незагруженных. Оба являются масками, образованными побитовым ИЛИ следующих констант:

• LUA_GLIBK : базовая библиотека.
• LUA_LOADLIBK : библиотека package.
• LUA_COLIBK : библиотека корутин.
• LUA_STRLIBK : библиотека строк.
• LUA_UTF8LIBK : библиотека UTF-8.
• LUA_TABLIBK : библиотека таблиц.
• LUA_MATHLIBK : математическая библиотека.
• LUA_IOLIBK : библиотека ввода-вывода.
• LUA_OSLIBK : библиотека операционной системы.
• LUA_DBLIBK : библиотека отладки.

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

assert (v [, message])

Вызывает ошибку, если значение её аргумента v ложно (то есть nil или false); в противном случае возвращает все свои аргументы. В случае ошибки message является объектом ошибки; если он отсутствует, по умолчанию используется "assertion failed!"

collectgarbage ([opt [, arg]])

Эта функция представляет собой универсальный интерфейс к сборщику мусора. Она выполняет разные действия в зависимости от своего первого аргумента, opt:

• "collect": Выполняет полный цикл сборки мусора. Это параметр по умолчанию.
• "stop": Останавливает автоматическое выполнение сборщика мусора. Сборщик будет запускаться только при явном вызове, пока не будет вызван его перезапуск.
• "restart": Перезапускает автоматическое выполнение сборщика мусора.
• "count": Возвращает общий объём памяти, используемой Lua, в Кбайт. Значение имеет дробную часть, так что при умножении на 1024 оно даёт точное количество байтов, используемых Lua.
• "step": Выполняет шаг сборки мусора. За этим параметром может следовать дополнительный аргумент — целое число, задающее размер шага.

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

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

• "isrunning": Возвращает логическое значение, сообщающее, работает ли сборщик (то есть не остановлен).
• "incremental": Переключает режим сборщика на инкрементальный и возвращает предыдущий режим.
• "generational": Переключает режим сборщика на поколенческий и возвращает предыдущий режим.
• "param": Изменяет и/или извлекает значения параметра сборщика. За этим параметром должны следовать один или два дополнительных аргумента: имя изменяемого или извлекаемого параметра (строка) и необязательное новое значение этого параметра — целое число в диапазоне [0,100000]. Первый аргумент должен иметь одно из следующих значений:
  • "minormul": Множитель малых сборок.
  • "majorminor": Множитель major-minor.
  • "minormajor": Множитель minor-major.
  • "pause": Пауза сборщика мусора.
  • "stepmul": Множитель шага.
  • "stepsize": Размер шага.

  Вызов всегда возвращает предыдущее значение параметра. Если вызов не задаёт новое значение, значение остаётся неизменным.

  Lua хранит эти значения в сжатом формате, поэтому значение, возвращённое как предыдущее, может не быть в точности последним установленным значением.

Дополнительные сведения о сборке мусора и некоторых из этих параметров см. в §2.5.

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

dofile ([filename])

error (message [, level])

Обычно error добавляет в начало сообщения некоторую информацию о позиции ошибки, если сообщение является строкой. Аргумент level определяет способ получения позиции ошибки. При уровне 1 (по умолчанию) позиция ошибки — это место вызова функции error. Уровень 2 указывает позицию ошибки на место, откуда была вызвана функция, вызвавшая error; и так далее. Передача уровня 0 предотвращает добавление информации о позиции ошибки к сообщению.

_G

getmetatable (object)

Если object не имеет метатаблицы, возвращает nil. В противном случае, если метатаблица объекта имеет поле __metatable, возвращает связанное значение. В противном случае возвращает метатаблицу заданного объекта.

ipairs (t)

Возвращает три значения (функцию-итератор, значение t и 0), так что конструкция

     for i,v in ipairs(t) do body end

будет перебирать пары ключ–значение (1,t[1]), (2,t[2]), ..., до первого отсутствующего индекса.

load (chunk [, chunkname [, mode [, env]]])

Загружает блок.

Если chunk является строкой, блоком является эта строка. Если chunk является функцией, load вызывает её повторно для получения частей блока. Каждый вызов chunk должен возвращать строку, которая присоединяется к предыдущим результатам. Возврат пустой строки, nil или отсутствие значения сигнализирует о конце блока.

Если синтаксических ошибок нет, load возвращает скомпилированный блок в виде функции; в противном случае возвращает fail плюс сообщение об ошибке.

Когда вы загружаете главный блок, результирующая функция всегда будет иметь ровно одну внешнюю переменную (upvalue) — переменную _ENV (см. §2.2). Однако когда вы загружаете двоичный блок, созданный из функции (см. string.dump), результирующая функция может иметь произвольное число внешних переменных, и нет гарантии, что её первая внешняя переменная будет переменной _ENV. (Функция, не являющаяся главной, может даже не иметь внешней переменной _ENV.)

Независимо от этого, если результирующая функция имеет какие-либо внешние переменные, её первая внешняя переменная устанавливается в значение env, если этот параметр задан, или в значение глобальной среды. Остальные внешние переменные инициализируются значением nil. Все внешние переменные являются новыми, то есть они не разделяются с какой-либо другой функцией.

chunkname используется как имя блока для сообщений об ошибках и отладочной информации (см. §4.7). Если он отсутствует, по умолчанию используется chunk, если chunk является строкой, или "=(load)" в противном случае.

Строка mode управляет тем, может ли блок быть текстовым или двоичным (то есть предварительно скомпилированным блоком). Она может быть строкой "b" (только двоичные блоки), "t" (только текстовые блоки) или "bt" (и двоичные, и текстовые). По умолчанию используется "bt".

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

loadfile ([filename [, mode [, env]]])

Аналогична load, но получает блок из файла filename или из стандартного ввода, если имя файла не задано.

next (table [, index])

Позволяет программе обойти все поля таблицы. Её первый аргумент — таблица, а второй аргумент — индекс в этой таблице. Вызов next возвращает следующий индекс таблицы и связанное с ним значение. При вызове с nil в качестве второго аргумента next возвращает начальный индекс и связанное с ним значение. При вызове с последним индексом или с nil в пустой таблице next возвращает nil. Если второй аргумент отсутствует, он интерпретируется как nil. В частности, вы можете использовать next(t), чтобы проверить, пуста ли таблица.

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

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

pairs (t)

Если t имеет метаметод __pairs, вызывает его с t в качестве аргумента и возвращает первые четыре результата вызова.

В противном случае возвращает функцию next, таблицу t и два значения nil, так что конструкция

     for k,v in pairs(t) do body end

будет перебирать все пары ключ–значение таблицы t.

См. функцию next для получения дополнительных сведений об обходе.

pcall (f [, arg1, ···])

Вызывает функцию f с заданными аргументами в защищённом режиме. Это означает, что любая ошибка внутри f не передаётся дальше; вместо этого pcall перехватывает ошибку и возвращает код состояния. Её первый результат — код состояния (логическое значение), который равен true, если вызов завершился без ошибок. В таком случае pcall также возвращает все результаты вызова после этого первого результата. В случае любой ошибки pcall возвращает false плюс объект ошибки. Обратите внимание, что ошибки, перехваченные pcall, не вызывают обработчик сообщений.

print (···)

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

rawequal (v1, v2)

rawget (table, index)

rawlen (v)

rawset (table, index, value)

Эта функция возвращает table.

select (index, ···)

Если index является числом, возвращает все аргументы после аргумента с номером index; отрицательное число индексирует с конца (-1 — последний аргумент). В противном случае index должен быть строкой "#", и select возвращает общее число полученных дополнительных аргументов.

setmetatable (table, metatable)

Устанавливает метатаблицу для заданной таблицы. Если metatable равна nil, удаляет метатаблицу заданной таблицы. Если исходная метатаблица имеет поле __metatable, вызывает ошибку.

Эта функция возвращает table.

Чтобы изменить метатаблицу других типов из кода Lua, необходимо использовать библиотеку отладки (§6.11).

tonumber (e [, base])

При вызове без base tonumber пытается преобразовать свой аргумент в число. Если аргумент уже является числом или строкой, преобразуемой в число, то tonumber возвращает это число; в противном случае возвращает fail.

Преобразование строк может давать целые числа или числа с плавающей точкой в соответствии с лексическими соглашениями Lua (см. §3.1). Строка может содержать ведущие и завершающие пробелы и знак.

При вызове с base e должен быть строкой, интерпретируемой как целочисленная запись числа в этой системе счисления. Основание может быть любым целым числом от 2 до 36 включительно. В системах счисления с основанием выше 10 буква 'A' (в верхнем или нижнем регистре) обозначает 10, 'B' обозначает 11 и так далее, а 'Z' обозначает 35. Если строка e не является допустимой записью числа в заданной системе счисления, функция возвращает fail.

tostring (v)

Принимает значение любого типа и преобразует его в строку в удобочитаемом формате.

Если метатаблица v имеет поле __tostring, то tostring вызывает соответствующее значение с v в качестве аргумента и использует результат вызова как свой результат. В противном случае, если метатаблица v имеет поле __name со строковым значением, tostring может использовать эту строку в окончательном результате.

Для полного контроля над тем, как преобразуются числа, используйте string.format.

type (v)

Возвращает тип своего единственного аргумента в виде строки. Возможные результаты этой функции: "nil" (строка, а не значение nil), "number", "string", "boolean", "table", "function", "thread" и "userdata".

_VERSION

Глобальная переменная (не функция), которая содержит строку с версией работающего Lua. Текущее значение этой переменной — "Lua 5.5".

warn (msg1, ···)

Выдаёт предупреждение с сообщением, составленным путём объединения всех его аргументов (которые должны быть строками).

По соглашению сообщение из одного фрагмента, начинающееся с '@', предназначено быть управляющим сообщением, то есть сообщением самой системе предупреждений. В частности, стандартная функция предупреждений в Lua распознаёт управляющие сообщения "@off" для остановки выдачи предупреждений и "@on" для (повторного) запуска выдачи; неизвестные управляющие сообщения она игнорирует.

xpcall (f, msgh [, arg1, ···])

Эта функция аналогична pcall, за исключением того, что она устанавливает новый обработчик сообщений msgh.

6.3 – Управление корутинами

Эта библиотека содержит операции для работы с корутинами, которые находятся в таблице coroutine. Общее описание корутин см. в §2.6.

coroutine.close ([co])

Закрывает корутину co, то есть закрывает все её ожидающие переменные, подлежащие закрытию, и переводит корутину в мёртвое состояние. По умолчанию co — выполняющаяся корутина.

Заданная корутина должна быть мёртвой, приостановленной или быть выполняющейся корутиной. Для выполняющейся корутины эта функция не возвращает управление. Вместо этого возвращает управление тот вызов resume, который (повторно) запустил корутину.

Для других корутин в случае ошибки (либо исходной ошибки, остановившей корутину, либо ошибок в методах закрытия) эта функция возвращает false и объект ошибки; в противном случае она возвращает true.

coroutine.create (f)

Создаёт новую корутину с телом f. f должна быть функцией. Возвращает эту новую корутину — объект с типом "thread".

coroutine.isyieldable ([co])

Возвращает true, когда корутина co может передавать управление. По умолчанию co — выполняющаяся корутина.

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

coroutine.resume (co [, val1, ···])

Запускает или продолжает выполнение корутины co. При первом возобновлении корутины она начинает выполнение своего тела. Значения val1, ... передаются как аргументы функции тела. Если корутина приостановлена, resume перезапускает её; значения val1, ... передаются как результаты из yield.

Если корутина выполняется без ошибок, resume возвращает true и любые значения, переданные в yield (когда корутина приостанавливается), или любые значения, возвращённые функцией тела (когда корутина завершается). Если возникла ошибка, resume возвращает false и сообщение об ошибке.

coroutine.running ()

Возвращает выполняющуюся корутину и логическое значение — true, когда выполняющаяся корутина является главной.

coroutine.status (co)

Возвращает статус корутины co в виде строки: "running", если корутина выполняется (то есть это та, которая вызвала status); "suspended", если корутина приостановлена в вызове yield или ещё не начала выполняться; "normal", если корутина активна, но не выполняется (то есть она возобновила другую корутину); и "dead", если корутина завершила функцию тела или остановилась с ошибкой.

coroutine.wrap (f)

Создаёт новую корутину с телом f; f должна быть функцией. Возвращает функцию, которая возобновляет корутину при каждом вызове. Любые аргументы, переданные этой функции, действуют как дополнительные аргументы для resume. Функция возвращает те же значения, что и resume, за исключением первого логического значения. В случае ошибки функция закрывает корутину и распространяет ошибку.

coroutine.yield (···)

Приостанавливает выполнение вызывающей корутины. Любые аргументы yield передаются как дополнительные результаты в resume.

6.4 – Модули

Библиотека package предоставляет базовые средства для загрузки модулей в Lua. Она экспортирует одну функцию непосредственно в глобальную среду: require. Всё остальное экспортируется в таблице package.

require (modname)

Загружает заданный модуль. Функция начинает с просмотра таблицы package.loaded, чтобы определить, не загружен ли уже modname. Если загружен, то require возвращает значение, хранящееся в package.loaded[modname]. (Отсутствие второго результата в этом случае означает, что этому вызову не пришлось загружать модуль.) В противном случае она пытается найти загрузчик для модуля.

Для поиска загрузчика require руководствуется таблицей package.searchers. Каждый элемент этой таблицы — это функция поиска, которая ищет модуль определённым образом. Изменяя эту таблицу, мы можем изменить то, как require ищет модуль. Следующее объяснение основано на конфигурации по умолчанию для package.searchers.

Сначала require запрашивает package.preload[modname]. Если там есть значение, это значение (которое должно быть функцией) является загрузчиком. В противном случае require ищет Lua-загрузчик, используя путь, хранящийся в package.path. Если и это не удаётся, она ищет C-загрузчик, используя путь, хранящийся в package.cpath. Если и это не удаётся, она пробует загрузчик «всё в одном» (см. package.searchers).

Как только загрузчик найден, require вызывает загрузчик с двумя аргументами: modname и дополнительным значением, данными загрузчика, также возвращаемыми искателем. Данные загрузчика могут быть любым значением, полезным модулю; для искателей по умолчанию они указывают, где был найден загрузчик. (Например, если загрузчик был получен из файла, это дополнительное значение — путь к файлу.) Если загрузчик возвращает любое значение, отличное от nil, require присваивает возвращённое значение package.loaded[modname]. Если загрузчик не возвращает значение, отличное от nil, и не присвоил никакого значения package.loaded[modname], то require присваивает true этой записи. В любом случае require возвращает итоговое значение package.loaded[modname]. Помимо этого значения, require также возвращает вторым результатом данные загрузчика, возвращённые искателем, которые указывают, как require нашёл модуль.

Если при загрузке или выполнении модуля возникает какая-либо ошибка или если для модуля не удаётся найти ни одного загрузчика, то require вызывает ошибку.

package.config

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

• Первая строка — это строка разделителя каталогов. По умолчанию — '\' для Windows и '/' для всех остальных систем.
• Вторая строка — это символ, разделяющий шаблоны в пути. По умолчанию — ';'.
• Третья строка — это строка, обозначающая точки подстановки в шаблоне. По умолчанию — '?'.
• Четвёртая строка — это строка, которая в пути в Windows заменяется каталогом исполняемого файла. По умолчанию — '!'.
• Пятая строка — это метка, указывающая игнорировать весь текст после неё при построении имени функции luaopen_. По умолчанию — '-'.

package.cpath

Строка с путём, используемым require для поиска C-загрузчика.

Lua инициализирует C-путь package.cpath так же, как она инициализирует Lua-путь package.path, используя переменную среды LUA_CPATH_5_5, или переменную среды LUA_CPATH, или путь по умолчанию, определённый в luaconf.h.

package.loaded

Таблица, используемая require для управления тем, какие модули уже загружены. Когда вы запрашиваете модуль modname и package.loaded[modname] не равно false, require просто возвращает значение, хранящееся там.

Эта переменная — лишь ссылка на настоящую таблицу; присваивания этой переменной не изменяют таблицу, используемую require. Настоящая таблица хранится в реестре C (см. §4.3), индексируемая ключом LUA_LOADED_TABLE, который является строкой.

package.loadlib (libname, funcname)

Динамически связывает хост-программу с C-библиотекой libname.

Если funcname равно "*", то функция только выполняет связывание с библиотекой, делая символы, экспортируемые библиотекой, доступными другим динамически связанным библиотекам. В противном случае она ищет функцию funcname внутри библиотеки и возвращает эту функцию как C-функцию. Таким образом, функция funcname должна соответствовать прототипу lua_CFunction (см. lua_CFunction).

Это низкоуровневая функция. Она полностью обходит систему пакетов и модулей. В отличие от require, она не выполняет никакого поиска по пути и не добавляет расширения автоматически. libname должно быть полным именем файла C-библиотеки, включая, если необходимо, путь и расширение. funcname должно быть точным именем, экспортируемым C-библиотекой (которое может зависеть от используемых компилятора и компоновщика C).

Эта функциональность не поддерживается ISO C. Поэтому функция loadlib доступна только на некоторых платформах: Linux, Windows, Mac OS X, Solaris, BSD, а также в других Unix-системах, поддерживающих стандарт dlfcn.

Эта функция по своей сути небезопасна, так как позволяет Lua вызывать любую функцию из любой читаемой динамической библиотеки в системе. (Lua вызывает любую функцию, предполагая, что функция имеет правильный прототип и соблюдает правильный протокол (см. lua_CFunction). Поэтому вызов произвольной функции из произвольной динамической библиотеки чаще всего приводит к нарушению доступа.)

package.path

Строка с путём, используемым require для поиска Lua-загрузчика.

При запуске Lua инициализирует эту переменную значением переменной среды LUA_PATH_5_5 или переменной среды LUA_PATH или путём по умолчанию, определённым в luaconf.h, если эти переменные среды не определены. Строка ";;" в значении переменной среды заменяется путём по умолчанию.

package.preload

Таблица для хранения загрузчиков конкретных модулей (см. require).

Эта переменная — лишь ссылка на настоящую таблицу; присваивания этой переменной не изменяют таблицу, используемую require. Настоящая таблица хранится в реестре C (см. §4.3), индексируемая ключом LUA_PRELOAD_TABLE, который является строкой.

package.searchers

Таблица, используемая 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. Первый искатель всегда возвращает строку ":preload:".

Искатели не должны возбуждать ошибок и не должны иметь побочных эффектов в Lua. (Они могут иметь побочные эффекты в C, например, связывая приложение с библиотекой.)

package.searchpath (name, path [, sep [, rep]])

Ищет заданное 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 в указанном порядке.

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

6.5 – Манипуляции со строками

Эта библиотека предоставляет общие функции для работы со строками, такие как поиск и извлечение подстрок и сопоставление с шаблонами. При индексировании строки в Lua первый символ находится в позиции 1 (а не в 0, как в C). Индексы могут быть отрицательными и интерпретируются как индексирование в обратном направлении, от конца строки. Таким образом, последний символ находится в позиции -1 и так далее.

Библиотека string предоставляет все свои функции в таблице string. Она также задаёт метатаблицу для строк, в которой поле __index указывает на таблицу string. Поэтому вы можете использовать функции string в объектно-ориентированном стиле. Например, string.byte(s,i) можно записать как s:byte(i).

Библиотека string предполагает однобайтовые кодировки символов.

string.byte (s [, i [, j]])

Числовые коды не обязательно переносимы между платформами.

string.char (···)

Числовые коды не обязательно переносимы между платформами.

string.dump (function [, strip])

Возвращает строку, содержащую двоичное представление (двоичный фрагмент) заданной функции, так что последующий load для этой строки возвращает копию функции (но с новыми upvalue). Если strip — истинное значение, двоичное представление может не включать всю отладочную информацию о функции, чтобы сэкономить место.

У функций с upvalue сохраняется только количество upvalue. При (пере)загрузке эти upvalue получают новые экземпляры. (См. функцию load для подробностей о том, как инициализируются эти upvalue. Вы можете использовать библиотеку debug, чтобы сериализовать и перезагрузить upvalue функции подходящим для ваших нужд способом.)

string.find (s, pattern [, init [, plain]])

Ищет первое совпадение с pattern (см. §6.5.1) в строке s. Если он находит совпадение, то find возвращает индексы s, где это вхождение начинается и заканчивается; в противном случае он возвращает fail. Третий необязательный числовой аргумент init задаёт, где начинать поиск; его значение по умолчанию — 1, и оно может быть отрицательным. Значение true в качестве четвёртого необязательного аргумента plain отключает средства сопоставления с шаблонами, так что функция выполняет обычную операцию «поиск подстроки», при этом ни один символ в pattern не считается магическим.

Если шаблон имеет захваты, то при успешном совпадении захваченные значения также возвращаются после двух индексов.

string.format (formatstring, ···)

Возвращает отформатированную версию своего переменного числа аргументов в соответствии с описанием, заданным в первом аргументе, который должен быть строкой. Строка форматирования подчиняется тем же правилам, что и функция sprintf стандарта ISO C. Принимаемые спецификаторы преобразования: A, a, c, d, E, e, f, G, g, i, o, p, s, u, X, x и '%', а также не-C-спецификатор q. Принимаемые флаги: '-', '+', '#', '0' и ' ' (пробел). И ширина, и точность, если они присутствуют, ограничены двумя цифрами.

Спецификатор q форматирует логические значения, nil, числа и строки так, что результат является допустимой константой в исходном коде Lua. Логические значения и nil записываются очевидным образом (true, false, nil). Числа с плавающей точкой записываются в шестнадцатеричном виде для сохранения полной точности. Строка записывается в двойных кавычках, при необходимости используя escape-последовательности, чтобы гарантировать, что интерпретатор 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 ожидают целое число. Если Lua скомпилирована компилятором C89, спецификаторы A и a (шестнадцатеричные числа с плавающей точкой) не поддерживают модификаторы.

Спецификатор s ожидает строку; если его аргумент не является строкой, он преобразуется в строку по тем же правилам, что и в tostring. Если спецификатор имеет какой-либо модификатор, соответствующий строковый аргумент не должен содержать встроенных нулей.

Спецификатор p форматирует указатель, возвращённый lua_topointer. Это даёт уникальный строковый идентификатор для таблиц, userdata, потоков, строк и функций. Для других значений (чисел, nil, логических значений) этот спецификатор даёт строку, представляющую указатель NULL.

string.gmatch (s, pattern [, init])

В качестве примера следующий цикл переберёт все слова из строки 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

Для этой функции символ '^' в начале шаблона не работает как якорь, так как это препятствовало бы итерации.

string.gsub (s, pattern, repl [, n])

Если repl является строкой, то её значение используется для замены. Символ % работает как escape-символ: любая последовательность в 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.5"}
     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
     -- x="lua-5.5.tar.gz"

string.len (s)

Принимает строку и возвращает её длину. Пустая строка "" имеет длину 0. Встроенные нули учитываются, поэтому "a\000bc\000" имеет длину 5.

string.lower (s)

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

string.match (s, pattern [, init])

Ищет первое совпадение с pattern (см. §6.5.1) в строке s. Если он его находит, то match возвращает захваты из шаблона; в противном случае он возвращает fail. Если pattern не задаёт захваты, то возвращается всё совпадение целиком. Третий необязательный числовой аргумент init задаёт, где начинать поиск; его значение по умолчанию — 1, и оно может быть отрицательным.

string.pack (fmt, v1, v2, ···)

Возвращает двоичную строку, содержащую значения v1, v2 и т. д., сериализованные в двоичной форме (упакованные) согласно строке форматирования fmt (см. §6.5.2).

string.packsize (fmt)

Возвращает длину строки, получающейся в результате string.pack с заданным форматом. Строка форматирования не может содержать опции переменной длины 's' или 'z' (см. §6.5.2).

string.rep (s, n [, sep])

Возвращает строку, являющуюся конкатенацией n копий строки s, разделённых строкой sep. Значение по умолчанию для sep — пустая строка (то есть без разделителя). Возвращает пустую строку, если n не положительно.

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

string.reverse (s)

Возвращает строку, являющуюся строкой s в обратном порядке.

string.sub (s, i [, j])

Возвращает подстроку s, которая начинается с i и продолжается до j; i и j могут быть отрицательными. Если j отсутствует, то предполагается, что он равен -1 (что совпадает с длиной строки). В частности, вызов string.sub(s,1,j) возвращает префикс s длиной j, а string.sub(s,-i) (для положительного i) возвращает суффикс s длиной i.

Если после преобразования отрицательных индексов i меньше 1, он корректируется до 1. Если j больше длины строки, он корректируется до этой длины. Если после этих корректировок i больше j, функция возвращает пустую строку.

string.unpack (fmt, s [, pos])

Возвращает значения, упакованные в строке s (см. string.pack), согласно строке форматирования fmt (см. §6.5.2). Необязательный pos задаёт, где начинать чтение в s (по умолчанию 1). После прочитанных значений эта функция также возвращает индекс первого непрочитанного байта в s.

string.upper (s)

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

6.5.1 – Шаблоны

Шаблоны в Lua описываются обычными строками, которые интерпретируются как шаблоны функциями сопоставления с шаблонами string.find, string.gmatch, string.gsub и string.match. В этом разделе описываются синтаксис и значение (то есть с чем они сопоставляются) этих строк.

Класс символов:

Класс символов используется для представления набора символов. При описании класса символов допускаются следующие комбинации:

• x: (где x — не один из магических символов ^$()%.[]*+-?) представляет сам символ x.
• .: (точка) представляет все символы.
• %a: представляет все буквы.
• %c: представляет все управляющие символы.
• %d: представляет все цифры.
• %g: представляет все печатные символы, кроме пробела.
• %l: представляет все строчные буквы.
• %p: представляет все знаки пунктуации.
• %s: представляет все пробельные символы.
• %u: представляет все заглавные буквы.
• %w: представляет все буквенно-цифровые символы.
• %x: представляет все шестнадцатеричные цифры.
• %x: (где x — любой не буквенно-цифровой символ) представляет символ x. Это стандартный способ экранирования магических символов. Любой не буквенно-цифровой символ (включая все знаки пунктуации, даже немагические) может стоять после '%', чтобы представлять себя в шаблоне.
• [set]: представляет класс, являющийся объединением всех символов в set. Диапазон символов можно задать, разделяя конечные символы диапазона в порядке возрастания символом '-'. Все классы %x, описанные выше, также могут использоваться как компоненты set. Все остальные символы в set представляют сами себя. Например, [%w_] (или [_%w]) представляет все буквенно-цифровые символы плюс символ подчёркивания, [0-7] представляет восьмеричные цифры, а [0-7%l%-] представляет восьмеричные цифры плюс строчные буквы плюс символ '-'.

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

  Взаимодействие между диапазонами и классами не определено. Поэтому шаблоны вроде [%a-z] или [a-%%] не имеют смысла.

• [^set]: представляет дополнение к set, где set интерпретируется, как указано выше.

Для всех классов, представленных отдельными буквами (%a, %c и т. д.), соответствующая заглавная буква представляет дополнение к классу. Например, %S представляет все непробельные символы.

Определения буквы, пробела и других групп символов зависят от текущей локали. В частности, класс [a-z] может не быть эквивалентен %l.

Элемент шаблона:

Элемент шаблона может быть

• одним классом символов, который соответствует любому одиночному символу из класса;
• одним классом символов, за которым следует '*', что соответствует последовательностям из нуля или более символов из класса. Такие элементы повторения всегда будут соответствовать самой длинной возможной последовательности;
• одним классом символов, за которым следует '+', что соответствует последовательностям из одного или более символов из класса. Такие элементы повторения всегда будут соответствовать самой длинной возможной последовательности;
• одним классом символов, за которым следует '-', что также соответствует последовательностям из нуля или более символов из класса. В отличие от '*', такие элементы повторения всегда будут соответствовать самой короткой возможной последовательности;
• одним классом символов, за которым следует '?', что соответствует нулю или одному вхождению символа из класса. Он всегда соответствует одному вхождению, если это возможно;
• %n, для n от 1 до 9; такой элемент соответствует подстроке, равной n-й захваченной строке (см. ниже);
• %bxy, где x и y — два различных символа; такой элемент соответствует строкам, которые начинаются с x, заканчиваются на y и в которых x и y сбалансированы. Это означает, что если читать строку слева направо, прибавляя +1 для x и -1 для y, то конечный y — это первый y, при котором счётчик достигает 0. Например, элемент %b() соответствует выражениям со сбалансированными круглыми скобками.
• %f[set], шаблон границы; такой элемент соответствует пустой строке в любой позиции, где следующий символ принадлежит set, а предыдущий символ не принадлежит set. Набор set интерпретируется, как описано ранее. Начало и конец исходной строки обрабатываются так, как если бы они были символом '\0'.

Шаблон:

Шаблон — это последовательность элементов шаблона. Символ '^' в начале шаблона привязывает совпадение к началу исходной строки. Символ '$' в конце шаблона привязывает совпадение к концу исходной строки. В других позициях '^' и '$' не имеют особого значения и представляют сами себя.

Захваты:

Шаблон может содержать подшаблоны, заключённые в круглые скобки; они описывают захваты. Когда сопоставление успешно, подстроки исходной строки, соответствующие захватам, сохраняются (захватываются) для дальнейшего использования. Захваты нумеруются в соответствии с их открывающими круглыми скобками. Например, в шаблоне "(a*(.)%w(%s*))" часть строки, соответствующая "a*(.)%w(%s*)", сохраняется как первый захват и, следовательно, имеет номер 1; символ, соответствующий ".", захватывается с номером 2, а часть, соответствующая "%s*", имеет номер 3.

В особом случае захват () захватывает текущую позицию в строке (число). Например, если применить шаблон "()aa()" к строке "flaaap", будет два захвата: 3 и 5.

Множественные совпадения:

Функция string.gsub и итератор string.gmatch сопоставляют несколько вхождений заданного шаблона в исходной строке. Для этих функций новое совпадение считается допустимым, только если оно заканчивается как минимум на один байт после конца предыдущего совпадения. Иными словами, механизм сопоставления с шаблонами никогда не принимает пустую строку как совпадение сразу после другого совпадения. В качестве примера рассмотрим результаты следующего кода:

     > string.gsub("abc", "()a*()", print);
     --> 1   2
     --> 3   3
     --> 4   4

Второй и третий результаты получаются, когда Lua сопоставляет пустую строку после 'b' и ещё одну после 'c'. Lua не сопоставляет пустую строку после 'a', потому что она заканчивалась бы в той же позиции, что и предыдущее совпадение.

6.5.2 – Строки форматирования для pack и unpack

Первый аргумент string.pack, string.packsize и string.unpack — это строка форматирования, которая описывает расположение создаваемой или читаемой структуры.

Строка форматирования — это последовательность опций преобразования. Опции преобразования таковы:

• <: устанавливает порядок байтов little endian
• >: устанавливает порядок байтов big endian
• =: устанавливает собственный порядок байтов
• ![n]: устанавливает максимальное выравнивание равным n (по умолчанию — собственное выравнивание)
• b: знаковый байт (char)
• B: беззнаковый байт (char)
• h: знаковый short (нативного размера)
• H: беззнаковый short (нативного размера)
• l: знаковый long (нативного размера)
• L: беззнаковый long (нативного размера)
• j: lua_Integer
• J: lua_Unsigned
• T: size_t (нативного размера)
• i[n]: знаковый int размером n байт (по умолчанию — нативного размера)
• I[n]: беззнаковый int размером n байт (по умолчанию — нативного размера)
• f: float (нативного размера)
• d: double (нативного размера)
• n: lua_Number
• cn: строка фиксированного размера из n байт
• z: строка с завершающим нулём
• s[n]: строка, перед которой записана её длина, закодированная как беззнаковое целое размером n байт (по умолчанию — size_t)
• x: один байт заполнения
• Xop: пустой элемент, который выравнивается в соответствии с опцией op (которая в остальном игнорируется)
• ' ': (пробел) игнорируется

(Запись «[n]» означает необязательное целое число.) За исключением заполнения, пробелов и конфигураций (опций «xX <=>!»), каждая опция соответствует аргументу в string.pack или результату в string.unpack.

Для опций «!n», «sn», «in» и «In» n может быть любым целым числом от 1 до 16. Все целочисленные опции проверяют переполнения; string.pack проверяет, помещается ли заданное значение в заданный размер; string.unpack проверяет, помещается ли прочитанное значение в целое число Lua. Для беззнаковых опций целые числа Lua также рассматриваются как беззнаковые значения.

Любая строка форматирования начинается так, как если бы перед ней стоял префикс «!1=», то есть с максимальным выравниванием 1 (без выравнивания) и собственным порядком байтов.

Собственный порядок байтов предполагает, что вся система является либо big-endian, либо little-endian. Функции упаковки не будут правильно эмулировать поведение форматов со смешанным порядком байтов.

Выравнивание работает следующим образом: для каждой опции в формат добавляется дополнительное заполнение, пока данные не начнутся со смещения, кратного минимуму из размера опции и максимального выравнивания; этот минимум должен быть степенью 2. Опции «c» и «z» не выравниваются; опция «s» следует выравниванию своего начального целого.

Все байты заполнения заполняются нулями при string.pack и игнорируются при string.unpack.

6.6 – Поддержка UTF-8

Эта библиотека обеспечивает базовую поддержку кодировки UTF-8. Она предоставляет все свои функции внутри таблицы utf8. Эта библиотека не обеспечивает никакой поддержки Unicode, кроме обработки кодировки. Любая операция, требующая значения символа, например классификация символов, выходит за её рамки.

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

Функции, создающие байтовые последовательности, принимают все значения до 0x7FFFFFFF, как определено в исходной спецификации UTF-8; это подразумевает байтовые последовательности длиной до шести байтов.

Функции, интерпретирующие байтовые последовательности, принимают только допустимые последовательности (корректно сформированные и не избыточные). По умолчанию они принимают только байтовые последовательности, которые дают допустимые кодовые точки Unicode, отклоняя значения больше 10FFFF и суррогаты. Логический аргумент lax, если он доступен, снимает эти проверки, так что принимаются все значения до 0x7FFFFFFF. (Некорректно сформированные и избыточные последовательности по-прежнему отклоняются.)

utf8.char (···)

Принимает ноль или более целых чисел, преобразует каждое из них в соответствующую байтовую последовательность UTF-8 и возвращает строку с конкатенацией всех этих последовательностей.

utf8.charpattern

Шаблон (строка, а не функция) "[\0-\x7F\xC2-\xFD][\x80-\xBF]*" (см. §6.5.1), который сопоставляется ровно с одной байтовой последовательностью UTF-8, при условии, что исходная строка является допустимой строкой UTF-8.

utf8.codes (s [, lax])

Возвращает значения так, что конструкция

     for p, c in utf8.codes(s) do body end

будет перебирать все символы UTF-8 в строке s, где p — позиция (в байтах), а c — кодовая точка каждого символа. Она вызывает ошибку, если встречает любую недопустимую байтовую последовательность.

utf8.codepoint (s [, i [, j [, lax]]])

Возвращает кодовые точки (в виде целых чисел) для всех символов в s, которые начинаются между байтовыми позициями i и j (обе включительно). Значение по умолчанию для i равно 1, а для j — i. Она вызывает ошибку, если встречает любую недопустимую байтовую последовательность.

utf8.len (s [, i [, j [, lax]]])

Возвращает количество символов UTF-8 в строке s, которые начинаются между позициями i и j (обе включительно). Значение по умолчанию для i равно 1, а для j — -1. Если она находит любую недопустимую байтовую последовательность, возвращает fail плюс позицию первого недопустимого байта.

utf8.offset (s, n [, i])

Возвращает позицию n-го символа s (считая от байтовой позиции i) в виде двух целых чисел: индекс (в байтах), где начинается его кодировка, и индекс (в байтах), где она заканчивается.

Если указанный символ находится сразу после конца s, функция ведёт себя так, как если бы там был '\0'. Если указанный символ не находится ни в исходной строке, ни сразу после её конца, функция возвращает fail.

Отрицательное n задаёт символы перед позицией i. Значение по умолчанию для i равно 1, когда n неотрицательно, и #s + 1 в противном случае, так что utf8.offset(s,-n) получает смещение n-го символа от конца строки.

В особом случае, когда n равно 0, функция возвращает начало и конец кодировки символа, который содержит i-й байт s.

Эта функция предполагает, что s является допустимой строкой UTF-8.

6.7 – Манипулирование таблицами

Эта библиотека предоставляет общие функции для манипулирования таблицами. Все её функции находятся внутри таблицы table.

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

table.concat (list [, sep [, i [, j]]])

Для списка, все элементы которого являются строками или числами, возвращает строку list[i]..sep..list[i+1] ··· sep..list[j]. Значением по умолчанию для sep является пустая строка, для i — 1, а для j — #list. Если i больше j, возвращается пустая строка.

table.create (nseq [, nrec])

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

Параметр nseq — это подсказка, сколько элементов таблица будет содержать как последовательность. Необязательный параметр nrec — это подсказка, сколько других элементов будет в таблице; по умолчанию он равен нулю.

table.insert (list, [pos,] value)

Вставляет элемент value в позицию pos в list, сдвигая вверх элементы list[pos],list[pos+1],···,list[#list]. Значение по умолчанию для pos — #list+1, поэтому вызов table.insert(t,x) вставляет x в конец списка t.

table.move (a1, f, e, t [,a2])

Перемещает элементы из таблицы a1 в таблицу a2, выполняя эквивалент следующего множественного присваивания: a2[t],··· = a1[f],···,a1[e]. Значение по умолчанию для a2 — a1. Диапазон назначения может перекрываться с исходным диапазоном. Количество перемещаемых элементов должно умещаться в целое число Lua. Если f больше e, ничего не перемещается.

Возвращает таблицу назначения a2.

table.pack (···)

Возвращает новую таблицу, в которой все аргументы сохранены в ключах 1, 2 и т. д., а также поле "n" с общим числом аргументов. Обратите внимание, что получившаяся таблица может не быть последовательностью, если некоторые аргументы равны nil.

table.remove (list [, pos])

Удаляет из list элемент в позиции pos, возвращая значение удалённого элемента. Когда pos — целое число в диапазоне от 1 до #list, функция сдвигает вниз элементы list[pos+1],list[pos+2],···,list[#list] и стирает элемент list[#list]; индекс pos также может быть равен 0, когда #list равно 0, или #list + 1.

Значение по умолчанию для pos — #list, поэтому вызов table.remove(l) удаляет последний элемент списка l.

table.sort (list [, comp])

Сортирует элементы списка в заданном порядке, на месте, от list[1] до list[#list]. Если задана comp, то она должна быть функцией, которая получает два элемента списка и возвращает true, когда первый элемент должен идти перед вторым в окончательном порядке, так что после сортировки из i <= j следует not comp(list[j],list[i]). Если comp не задана, вместо неё используется стандартный оператор Lua <.

Функция comp должна задавать согласованный порядок; более формально, функция должна задавать строгий слабый порядок. (Слабый порядок похож на полный порядок, но может приравнивать разные элементы для целей сравнения.)

Алгоритм сортировки не является устойчивым: разные элементы, считающиеся равными в заданном порядке, могут изменить своё относительное расположение в результате сортировки.

table.unpack (list [, i [, j]])

Возвращает элементы из заданного списка. Эта функция эквивалентна

     return list[i], list[i+1], ···, list[j]

По умолчанию i равно 1, а j — #list.

6.8 – Математические функции

Эта библиотека предоставляет базовые математические функции. Она предоставляет все свои функции и константы в таблице math. Функции с аннотацией "integer/float" дают целочисленные результаты для целочисленных аргументов и результаты с плавающей точкой для нецелочисленных аргументов. Функции округления math.ceil, math.floor и math.modf возвращают целое число, когда результат помещается в диапазон целого числа, или число с плавающей точкой в противном случае.

math.abs (x)

Возвращает максимальное значение между x и -x. (integer/float)

math.acos (x)

Возвращает арккосинус x (в радианах).

math.asin (x)

Возвращает арксинус x (в радианах).

math.atan (y [, x])

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

Значение x по умолчанию равно 1, так что вызов math.atan(y) возвращает арктангенс y.

math.ceil (x)

Возвращает наименьшее целое значение, большее или равное x.

math.cos (x)

Возвращает косинус x (предполагается, что x выражен в радианах).

math.deg (x)

Преобразует угол x из радианов в градусы.

math.exp (x)

Возвращает значение e^x (где e — основание натуральных логарифмов).

math.floor (x)

Возвращает наибольшее целое значение, меньшее или равное x.

math.fmod (x, y)

Возвращает остаток от деления x на y, при котором частное округляется в сторону нуля. (integer/float)

math.frexp (x)

Возвращает два числа m и e, такие что x = m2^e, где e — целое число. Когда x равен нулю, NaN, +inf или -inf, m равен x; в противном случае абсолютное значение m находится в диапазоне [0.5, 1) .

math.huge

Значение с плавающей точкой HUGE_VAL, значение, большее любого другого числового значения.

math.ldexp (m, e)

Возвращает m2^e, где e — целое число.

math.log (x [, base])

Возвращает логарифм x по заданному основанию. Значение base по умолчанию равно e (так что функция возвращает натуральный логарифм x).

math.max (x, ···)

Возвращает аргумент с максимальным значением в соответствии с оператором Lua <.

math.maxinteger

math.min (x, ···)

Возвращает аргумент с минимальным значением в соответствии с оператором Lua <.

math.mininteger

math.modf (x)

Возвращает целую часть x и дробную часть x. Её второй результат всегда является числом с плавающей точкой.

math.pi

Значение π.

math.rad (x)

Преобразует угол x из градусов в радианы.

math.random ([m [, n]])

При вызове без аргументов возвращает псевдослучайное число с плавающей точкой, равномерно распределённое в диапазоне [0, 1). При вызове с двумя целыми числами m и n math.random возвращает псевдослучайное целое число, равномерно распределённое в диапазоне [m, n]. Вызов math.random(n) для положительного n эквивалентен math.random(1,n). Вызов math.random(0) создаёт целое число, все биты которого (псевдо)случайны.

Эта функция использует алгоритм xoshiro256** для генерации псевдослучайных 64-битных целых чисел, являющихся результатами вызовов с аргументом 0. Другие результаты (диапазоны и числа с плавающей точкой) извлекаются из этих целых чисел без смещения.

Lua инициализирует свой генератор псевдослучайных чисел эквивалентом вызова math.randomseed без аргументов, так что math.random должен генерировать разные последовательности результатов при каждом запуске программы.

math.randomseed ([x [, y]])

При вызове по крайней мере с одним аргументом целочисленные параметры x и y объединяются в начальное значение, которое используется для повторной инициализации генератора псевдослучайных чисел; одинаковые начальные значения дают одинаковые последовательности чисел. Значение y по умолчанию равно нулю.

При вызове без аргументов Lua генерирует начальное значение, предпринимая слабую попытку обеспечить случайность.

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

Чтобы обеспечить требуемый уровень случайности начального состояния (или, наоборот, получить детерминированную последовательность, например при отладке программы), следует вызывать math.randomseed с явными аргументами.

math.sin (x)

Возвращает синус x (предполагается, что x выражен в радианах).

math.sqrt (x)

Возвращает квадратный корень из x. (Вы также можете использовать выражение x^0.5 для вычисления этого значения.)

math.tan (x)

Возвращает тангенс x (предполагается, что x выражен в радианах).

math.tointeger (x)

Если значение x может быть преобразовано в целое число, возвращает это целое число. В противном случае возвращает fail.

math.type (x)

Возвращает "integer", если x является целым числом, "float", если оно является числом с плавающей точкой, или fail, если x не является числом.

math.ult (m, n)

Возвращает логическое значение, true тогда и только тогда, когда целое число m меньше целого числа n при их сравнении как беззнаковых целых чисел.

6.9 – Средства ввода и вывода

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

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

Метатаблица файловых дескрипторов предоставляет метаметоды для __gc и __close, которые пытаются закрыть файл при вызове.

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

Если не указано иное, все функции ввода-вывода возвращают fail при неудаче, а также сообщение об ошибке в качестве второго результата и зависящий от системы код ошибки в качестве третьего результата, и некоторое значение, отличное от false, при успехе. В системах, отличных от POSIX, вычисление сообщения об ошибке и кода ошибки в случае ошибок может быть не потокобезопасным, поскольку они полагаются на глобальную переменную C errno.

io.close ([file])

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

io.flush ()

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

io.input ([file])

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

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

io.lines ([filename, ···])

Открывает заданное имя файла в режиме чтения и возвращает функцию-итератор, которая работает как file:lines(···) для открытого файла. Когда функции-итератору не удаётся прочитать какое-либо значение, она автоматически закрывает файл. Помимо функции-итератора, io.lines возвращает три других значения: два значения nil в качестве заполнителей и созданный файловый дескриптор. Поэтому при использовании в общем цикле for файл также закрывается, если цикл прерывается ошибкой или break.

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

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

io.open (filename [, mode])

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

Строка mode может быть любой из следующих:

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

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

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 — закрытый файловый дескриптор, или fail, если obj не является файловым дескриптором.

io.write (···)

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

file:close ()

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

При закрытии файлового дескриптора, созданного с помощью io.popen, file:close возвращает те же значения, которые возвращает os.execute.

file:flush ()

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

file:lines (···)

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

     for c in file:lines(1) do body end

выполнит итерацию по всем символам файла, начиная с текущей позиции. В отличие от io.lines, эта функция не закрывает файл при завершении цикла.

file:read (···)

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

Доступны следующие форматы:

• "n": читает число и возвращает его как число с плавающей точкой или целое, следуя лексическим соглашениям Lua. (Число может иметь ведущие пробелы и знак.) Этот формат всегда читает самую длинную входную последовательность, которая является допустимым префиксом числа; если этот префикс не образует допустимое число (например, пустая строка, "0x" или "3.4e-") или он слишком длинный (более 200 символов), он отбрасывается, и формат возвращает fail.
• "a": читает весь файл, начиная с текущей позиции. В конце файла возвращает пустую строку; этот формат никогда не завершается неудачей.
• "l": читает следующую строку, пропуская конец строки, и возвращает fail в конце файла. Это формат по умолчанию.
• "L": читает следующую строку, сохраняя символ конца строки (если он присутствует), и возвращает fail в конце файла.
• number: читает строку длиной до этого числа байтов, возвращая fail в конце файла. Если number равен нулю, ничего не читает и возвращает пустую строку или fail в конце файла.

Форматы "l" и "L" следует использовать только для текстовых файлов.

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

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

• "set": база — позиция 0 (начало файла);
• "cur": база — текущая позиция;
• "end": база — конец файла;

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

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

file:setvbuf (mode [, size])

Устанавливает режим буферизации для файла. Доступны три режима:

• "no": без буферизации.
• "full": полная буферизация.
• "line": построчная буферизация.

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

Конкретное поведение каждого режима не является переносимым; для получения дополнительных сведений обратитесь к базовой функции setvbuf ISO C в вашей платформе.

file:write (···)

Записывает значение каждого из своих аргументов в file. Аргументы должны быть строками или числами.

В случае успеха эта функция возвращает file. В противном случае она возвращает четыре значения: fail, сообщение об ошибке, код ошибки и количество байтов, которые ей удалось записать.

6.10 – Средства операционной системы

Эта библиотека реализована через таблицу os.

os.clock ()

Возвращает приблизительное количество секунд процессорного времени, использованного программой, как возвращает базовая функция ISO C clock.

os.date ([format [, time]])

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

Если аргумент time присутствует, это время, которое нужно отформатировать (описание этого значения см. в функции os.time). В противном случае date форматирует текущее время.

Если format начинается с '!', дата форматируется по всемирному координированному времени. После этого необязательного символа, если format — строка "*t", date возвращает таблицу со следующими полями: year, month (1–12), day (1–31), hour (0–23), min (0–59), sec (0–61, из-за дополнительных секунд), wday (день недели, 1–7, воскресенье — 1), yday (день года, 1–366), и isdst (флаг перехода на летнее время, логическое значение). Это последнее поле может отсутствовать, если информация недоступна.

Если format не равен "*t", date возвращает дату в виде строки, отформатированной по тем же правилам, что и функция ISO C strftime.

Если format отсутствует, по умолчанию используется "%c", что даёт удобочитаемое представление даты и времени с использованием текущей локали.

В системах, отличных от POSIX, эта функция может быть не потокобезопасной, поскольку полагается на функцию C gmtime и функцию C localtime.

os.difftime (t2, t1)

Возвращает разницу в секундах от времени t1 до времени t2 (где времена — значения, возвращённые os.time). В POSIX, Windows и некоторых других системах это значение в точности равно t2-t1.

os.execute ([command])

Эта функция эквивалентна функции ISO C system. Она передаёт command на выполнение оболочке операционной системы. Её первый результат — true, если команда завершилась успешно, или fail в противном случае. После этого первого результата функция возвращает строку и число следующим образом:

• "exit": команда завершилась нормально; следующее число — статус завершения команды.
• "signal": команда была завершена сигналом; следующее число — сигнал, который завершил команду.

При вызове без command os.execute возвращает логическое значение, истинное, если оболочка доступна.

os.exit ([code [, close]])

Вызывает функцию ISO C exit для завершения принимающей программы. Если code — true, возвращаемый статус — EXIT_SUCCESS; если code — false, возвращаемый статус — EXIT_FAILURE; если code — число, возвращаемый статус — это число. Значение code по умолчанию — true.

Если необязательный второй аргумент close истинен, функция закрывает состояние Lua перед завершением (см. lua_close).

os.getenv (varname)

Возвращает значение переменной среды процесса varname или fail, если переменная не определена.

os.remove (filename)

Удаляет файл (или пустой каталог в POSIX-системах) с заданным именем. Если эта функция завершается неудачно, она возвращает fail плюс строку с описанием ошибки и код ошибки. В противном случае она возвращает true.

os.rename (oldname, newname)

Переименовывает файл или каталог с именем oldname в newname. Если эта функция завершается неудачно, она возвращает fail, плюс строку с описанием ошибки и код ошибки. В противном случае она возвращает true.

os.setlocale (locale [, category])

Устанавливает текущую локаль программы. locale — зависящая от системы строка, задающая локаль; category — необязательная строка, описывающая, какую категорию изменить: "all", "collate", "ctype", "monetary", "numeric" или "time"; категория по умолчанию — "all". Функция возвращает имя новой локали или fail, если запрос не может быть выполнен.

Если locale — пустая строка, текущая локаль устанавливается в определяемую реализацией собственную локаль. Если locale — строка "C", текущая локаль устанавливается в стандартную локаль C.

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

Эта функция может быть не потокобезопасной, поскольку полагается на функцию C setlocale.

os.time ([table])

Возвращает текущее локальное время при вызове без аргументов или время, представляющее локальные дату и время, заданные данной таблицей. Эта таблица должна иметь поля year, month и day, и может иметь поля hour (по умолчанию 12), min (по умолчанию 0), sec (по умолчанию 0) и isdst (по умолчанию nil). Другие поля игнорируются. Описание этих полей см. в функции os.date.

При вызове функции значения в этих полях не обязаны находиться в своих допустимых диапазонах. Например, если sec равен -10, это означает 10 секунд до времени, заданного другими полями; если hour равен 1000, это означает 1000 часов после времени, заданного другими полями.

Возвращаемое значение — число, смысл которого зависит от вашей системы. В POSIX, Windows и некоторых других системах это число отсчитывает количество секунд с некоторого заданного начального времени («эпохи»). В других системах смысл не определён, и число, возвращённое time, можно использовать только как аргумент для os.date и os.difftime.

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

os.tmpname ()

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

В POSIX-системах эта функция также создаёт файл с таким именем, чтобы избежать рисков безопасности. (Кто-то другой может создать файл с неправильными правами доступа за время между получением имени и созданием файла.) Вам всё равно нужно открыть файл, чтобы использовать его, и удалить его (даже если вы его не используете).

Когда возможно, вы можете предпочесть io.tmpfile, который автоматически удаляет файл при завершении программы.

6.11 – Библиотека отладки

Эта библиотека предоставляет программам на Lua функциональность интерфейса отладки (§4.7).

При использовании этой библиотеки следует соблюдать осторожность. Некоторые из её функций нарушают базовые предположения о коде Lua (например, о том, что локальные переменные функции не могут быть доступны извне; что метатаблицы userdata не могут изменяться кодом Lua; что программы на Lua не завершаются аварийно) и поэтому могут скомпрометировать в остальном безопасный код. Кроме того, некоторые функции этой библиотеки могут быть медленными. Хорошей практикой является всегда явно подключать эту библиотеку через require перед её использованием.

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

debug.debug ()

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

Обратите внимание, что команды для debug.debug лексически не вложены ни в какую функцию и поэтому не имеют прямого доступа к локальным переменным.

debug.gethook ([thread])

Возвращает текущие настройки hook для thread в виде трёх значений: текущую функцию hook, текущую маску hook и текущий счётчик hook, установленные функцией debug.sethook.

Возвращает fail, если активный hook отсутствует.

debug.getinfo ([thread,] f [, what])

Возвращает таблицу с информацией о функции. Можно передать функцию напрямую или передать число в качестве значения f, что означает функцию, выполняющуюся на уровне f стека вызовов заданного thread: уровень 0 — текущая функция (сама getinfo); уровень 1 — функция, вызвавшая getinfo (кроме хвостовых вызовов, которые не учитываются в стеке); и так далее. Если f — число, большее числа активных функций, то getinfo возвращает fail.

Возвращаемая таблица может содержать все поля, возвращаемые lua_getinfo, причём строка what описывает, какие поля заполнять. По умолчанию what означает получение всей доступной информации, кроме таблицы допустимых строк. Опция 'f' добавляет поле с именем func, содержащее саму функцию. Опция 'L' добавляет поле с именем activelines с таблицей допустимых строк, при условии, что функция является функцией Lua. Если функция не имеет отладочной информации, таблица пуста.

Например, выражение debug.getinfo(1,"n").name возвращает имя текущей функции, если может быть найдено подходящее имя, а выражение debug.getinfo(print) возвращает таблицу со всей доступной информацией о функции print.

debug.getlocal ([thread,] f, local)

Эта функция возвращает имя и значение локальной переменной с индексом local функции на уровне f стека. Эта функция обращается не только к явным локальным переменным, но также к параметрам и временным значениям.

Первый параметр или локальная переменная имеет индекс 1 и так далее, в порядке их объявления в коде, при этом учитываются только переменные, активные в текущей области видимости функции. Константы времени компиляции могут отсутствовать в этом списке, если они были оптимизированы компилятором. Отрицательные индексы относятся к аргументам vararg; -1 — первый аргумент vararg. Эти отрицательные индексы доступны только в том случае, когда таблица vararg была устранена оптимизатором; в противном случае аргументы vararg доступны в таблице vararg.

Функция возвращает fail, если переменной с заданным индексом нет, и вызывает ошибку при вызове с уровнем вне диапазона. (Можно вызвать debug.getinfo, чтобы проверить, допустим ли уровень.)

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

Параметр f также может быть функцией. В этом случае getlocal возвращает только имена параметров функции.

debug.getmetatable (value)

Возвращает метатаблицу заданного value или nil, если у него нет метатаблицы.

debug.getregistry ()

Возвращает таблицу реестра (см. §4.3).

debug.getupvalue (f, up)

Эта функция возвращает имя и значение upvalue с индексом up функции f. Функция возвращает fail, если upvalue с заданным индексом нет.

(Для функций Lua upvalue — это внешние локальные переменные, которые использует функция и которые, следовательно, включены в её замыкание.)

Для функций C эта функция использует пустую строку "" как имя для всех upvalue.

Имя переменной '?' (знак вопроса) обозначает переменные с неизвестными именами (переменные из чанков, сохранённых без отладочной информации).

debug.getuservalue (u, n)

Возвращает n-е пользовательское значение, связанное с userdata u, а также логическое значение, false, если у userdata нет этого значения.

debug.sethook ([thread,] hook, mask [, count])

Устанавливает заданную функцию как hook отладки. Строка mask и число count описывают, когда будет вызываться hook. Строка mask может содержать любую комбинацию следующих символов со следующими значениями:

• 'c': hook вызывается каждый раз, когда Lua вызывает функцию;
• 'r': hook вызывается каждый раз, когда Lua возвращается из функции;
• 'l': hook вызывается каждый раз, когда Lua переходит на новую строку кода.

Кроме того, при count, отличном от нуля, hook также вызывается после каждых count инструкций.

При вызове без аргументов debug.sethook отключает hook.

При вызове hook его первым параметром является строка, описывающая событие, вызвавшее его вызов: "call", "tail call", "return", "line" и "count". Для событий line hook также получает новый номер строки в качестве второго параметра. Внутри hook можно вызвать getinfo с уровнем 2, чтобы получить больше информации о выполняющейся функции. (Уровень 0 — функция getinfo, а уровень 1 — функция hook.)

debug.setlocal ([thread,] level, local, value)

Эта функция присваивает значение value локальной переменной с индексом local функции на уровне level стека. Функция возвращает fail, если нет локальной переменной с заданным индексом, и вызывает ошибку при вызове с level вне диапазона. (Можно вызвать getinfo, чтобы проверить, допустим ли уровень.) В противном случае она возвращает имя локальной переменной.

См. debug.getlocal для получения дополнительной информации об индексах и именах переменных.

debug.setmetatable (value, table)

Устанавливает метатаблицу для заданного value в заданную table (которая может быть nil). Возвращает value.

debug.setupvalue (f, up, value)

Эта функция присваивает значение value upvalue с индексом up функции f. Функция возвращает fail, если нет upvalue с заданным индексом. В противном случае она возвращает имя upvalue.

См. debug.getupvalue для получения дополнительной информации об upvalue.

debug.setuservalue (udata, value, n)

Устанавливает заданное value как n-е пользовательское значение, связанное с заданным udata. udata должен быть полным userdata.

Возвращает udata или fail, если у userdata нет этого значения.

debug.traceback ([thread,] [message [, level]])

Если message присутствует, но не является строкой и не nil, эта функция возвращает message без дальнейшей обработки. В противном случае она возвращает строку с трассировкой стека вызовов. Необязательная строка message добавляется в начало трассировки. Необязательное число level указывает, с какого уровня начинать трассировку (по умолчанию 1 — функция, вызывающая traceback).

debug.upvalueid (f, n)

Возвращает уникальный идентификатор (в виде light userdata) для upvalue с номером n из заданной функции.

Эти уникальные идентификаторы позволяют программе проверять, совместно ли используют разные замыкания upvalue. Замыкания Lua, совместно использующие upvalue (то есть обращающиеся к одной и той же внешней локальной переменной), будут возвращать одинаковые идентификаторы для этих индексов upvalue.

debug.upvaluejoin (f1, n1, f2, n2)

Заставляет n1-й upvalue замыкания Lua f1 ссылаться на n2-й upvalue замыкания Lua f2.