Руководство по языку Lua: Стандартные библиотеки

Оглавление

1. Загрузка библиотек в коде C
2. Базовые функции
3. Управление сопрограммами
4. Модули
5. Манипуляции со строками
6. Поддержка UTF-8
7. Манипуляции с таблицами
8. Математические функции
9. Средства ввода и вывода
10. Средства операционной системы
11. Библиотека отладки

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) позже в программе. Имейте в виду, что сам require предоставляется библиотекой пакетов. Если программа не загружает эту библиотеку, она не сможет ничего затребовать.)

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

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

6.2 – Базовые функции

Базовая библиотека предоставляет ядро функций для 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": Множитель перехода от большой к малой сборке.
  • "minormajor": Множитель перехода от малой к большой сборке.
  • "pause": Пауза сборщика мусора.
  • "stepmul": Множитель шага.
  • "stepsize": Размер шага.

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

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

См. §2.5 для более подробной информации о сборке мусора и некоторых из этих опций.

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

dofile ([filename])

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

error (message [, level])

Вызывает ошибку (см. §2.3) с message в качестве объекта ошибки. Эта функция никогда не возвращает управление.

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

_G

Глобальная переменная (не функция), которая содержит глобальное окружение (см. §2.2). Сама Lua не использует эту переменную; изменение ее значения не влияет ни на какое окружение, и наоборот.

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 (···)

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

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

rawequal (v1, v2)

Проверяет, равен ли v1 v2, без вызова метаметода __eq. Возвращает булево значение.

rawget (table, index)

Получает реальное значение table[index], не используя метазначение __index. table должна быть таблицей; index может быть любым значением.

rawlen (v)

Возвращает длину объекта v, который должен быть таблицей или строкой, без вызова метаметода __len. Возвращает целое число.

rawset (table, index, value)

Устанавливает реальное значение table[index] в value, не используя метазначение __newindex. table должна быть таблицей, index — любым значением, отличным от nil и NaN, а value — любым значением Lua.

Эта функция возвращает 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 должен быть строкой, интерпретируемой как целое число в этой системе счисления. base может быть любым целым числом от 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 может прерваться (yield). По умолчанию 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 – Модули

Библиотека пакетов предоставляет базовые средства для загрузки модулей в 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-подмодулей в одну библиотеку, при этом каждый подмодуль сохраняет свою оригинальную функцию открытия.

Все функции поиска, кроме первой (предзагрузки), возвращают в качестве дополнительного значения путь к файлу, где был найден модуль, как возвращено 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. Она также устанавливает метатаблицу для строк, где поле __index указывает на таблицу string. Поэтому вы можете использовать строковые функции в объектно-ориентированном стиле. Например, string.byte(s,i) можно записать как s:byte(i).

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

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

Возвращает внутренние числовые коды символов s[i], s[i+1], …, s[j]. Значение по умолчанию для i — 1; значение по умолчанию для j — i. Эти индексы корректируются по тем же правилам, что и для функции string.sub.

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

string.char (···)

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

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

string.dump (function [, strip])

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

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

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

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

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

string.format (formatstring, ···)

Возвращает отформатированную версию своего переменного числа аргументов в соответствии с описанием, данным в первом аргументе, который должен быть строкой. Строка формата следует тем же правилам, что и функция ISO C sprintf. Допустимые спецификаторы преобразования: 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. Это дает уникальный строковый идентификатор для таблиц, пользовательских данных, потоков, строк и функций. Для других значений (числа, nil, булевы значения) этот спецификатор дает строку, представляющую указатель NULL.

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

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

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

Возвращает копию s, в которой все (или первые n, если указано) вхождения pattern (см. §6.5.1) были заменены строкой замены, указанной в repl, которая может быть строкой, таблицей или функцией. gsub также возвращает вторым значением общее количество произошедших совпадений. Имя gsub происходит от Global SUBstitution.

Если 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])

Ищет первое совпадение с образцом (см. §6.5.1) в строке s. Если находит, match возвращает захваты из образца; в противном случае возвращает fail. Если образец не указывает захватов, возвращается все совпадение целиком. Третий, необязательный числовой аргумент 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 – Образцы (Patterns)

Образцы в 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 (порядок байтов от старшего к младшему)
• =: устанавливает native-endian (родной порядок байтов)
• ![n]: устанавливает максимальное выравнивание в n (по умолчанию родное выравнивание)
• b: знаковый байт (char)
• B: беззнаковый байт (unsigned 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 порядок. Функции упаковки не будут корректно эмулировать поведение форматов со смешанным порядком байтов.

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

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

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

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

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

Функции, создающие байтовые последовательности, принимают все значения вплоть до 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 = m * 2^e, где e — целое число. Когда x равен нулю, NaN, +inf или -inf, m равен x; в противном случае абсолютное значение m находится в диапазоне [0.5, 1).

math.huge

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

math.ldexp (m, e)

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

math.log (x [, base])

Возвращает логарифм x по заданному основанию base. По умолчанию 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 объединяются в зерно (seed), которое используется для реинициализации генератора псевдослучайных чисел; одинаковые зерна производят одинаковые последовательности чисел. По умолчанию 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(). Без файла закрывает файл вывода по умолчанию.

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. В случае успеха возвращает новый файловый дескриптор.

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

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

Строка режима может также иметь '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: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 в конце файла.
• число: читает строку длиной до этого количества байтов, возвращает fail в конце файла. Если число равно нулю, ничего не читает и возвращает пустую строку или 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 является подсказкой для размера буфера в байтах. По умолчанию используется подходящий размер.

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

file:write (···)

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

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

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

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

os.clock ()

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

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

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

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

Если format начинается с '!', то дата форматируется во Всемирном координированном времени (UTC). После этого необязательного символа, если 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 и localtime.

os.difftime (t2, t1)

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

os.execute ([command])

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

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

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

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

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

Если необязательный второй аргумент close равен true, функция закрывает состояние 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 – Библиотека отладки

Эта библиотека предоставляет функциональность отладочного интерфейса (§4.7) программам Lua. Следует проявлять осторожность при использовании этой библиотеки. Некоторые из ее функций нарушают базовые предположения о коде Lua (например, что к локальным переменным функции нельзя получить доступ извне; что метатаблицы пользовательских данных не могут быть изменены кодом Lua; что программы Lua не падают) и, следовательно, могут скомпрометировать в остальном безопасный код. Более того, некоторые функции в этой библиотеке могут быть медленными.

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

debug.debug ()

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

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

debug.gethook ([thread])

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

Возвращает fail, если активного перехватчика нет.

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

Возвращает таблицу с информацией о функции. Вы можете передать функцию напрямую или передать число в качестве значения f, что означает функцию, выполняющуюся на уровне f стека вызовов данного потока: уровень 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)

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

debug.getregistry ()

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

debug.getupvalue (f, up)

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

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

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

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

debug.getuservalue (u, n)

Возвращает n-е пользовательское значение, связанное с пользовательскими данными u, плюс булево значение, false, если пользовательские данные не имеют этого значения.

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

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

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

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

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

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

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

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

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

debug.setmetatable (value, table)

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

debug.setupvalue (f, up, value)

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

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

debug.setuservalue (udata, value, n)

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

Возвращает udata или fail, если пользовательские данные не имеют этого значения.

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

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

debug.upvalueid (f, n)

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

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

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

Делает так, что n1-е верхнее значение Lua-замыкания f1 ссылается на n2-е верхнее значение Lua-замыкания f2.