Lua руководство на русском

Роберто Иерусалимши,Луис Энрике де Фигейредо,Вальдемар Селес.

1-Введение

Lua-это мощный,эффективный,легкий,встраиваемый язык сценариев.Он поддерживает процедурное программирование,объектно-ориентированное программирование,функциональное программирование,программирование на основе данных и описание данных.

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

Lua реализован как библиотека, написанная на чистом C , общем подмножестве Standard C и C ++. Дистрибутив Lua включает хост-программу под названием lua , которая использует библиотеку Lua для предоставления полного автономного интерпретатора Lua для интерактивного или пакетного использования. Lua предназначен для использования как мощного, легкого, встраиваемого языка сценариев для любой программы, которая в нем нуждается, и как мощный, но легкий и эффективный автономный язык.

Как язык расширения Lua не имеет понятия «основная» программа: он работает встроенным в хост-клиент, называемый программой встраивания или просто хостом . (Часто этот хост является автономной программой lua .) Хост-программа может вызывать функции для выполнения части кода Lua, может записывать и читать переменные Lua и может регистрировать функции C для вызова кодом Lua. Благодаря использованию функций C, Lua может быть расширен, чтобы справиться с широким спектром различных доменов, тем самым создавая настраиваемые языки программирования, разделяющие синтаксическую структуру.

Lua является бесплатным программным обеспечением и предоставляется, как обычно, без каких-либо гарантий, как указано в его лицензии. Реализация, описанная в этом руководстве, доступна на официальном веб-сайте www.lua.org .

Как и любое другое справочное руководство, этот документ местами пересох. Для обсуждения решений, лежащих в основе дизайна Lua, см. Технические документы, доступные на веб-сайте Lua. Подробное введение в программирование на Lua см. В книге Роберто « Программирование на Lua» .

2-Основные понятия

В этом разделе описаны основные понятия языка.

2.1-Значения и типы

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

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

В Lua есть восемь основных типов: nil , boolean , number , string , function , userdata , thread и table . Тип nil имеет одно единственное значение, nil , основное свойство которого должно отличаться от любого другого значения; это часто означает отсутствие полезной ценности. Тип boolean имеет два значения: false и true . И nil, и false делают условие ложным; все вместе они называются ложными ценностями . Любое другое значение делает условие истинным.

Тип номер представляет собой как целые числа и вещественные ( с плавающей точкой) числа, используя два подтипа: целые и с плавающей точкой . Стандартный Lua использует 64-битные целые числа и числа с плавающей запятой двойной точности (64-битные), но вы также можете скомпилировать Lua, чтобы он использовал 32-битные целые числа и / или одинарные (32-битные) числа с плавающей запятой. Вариант с 32 битами для целых чисел и чисел с плавающей запятой особенно привлекателен для небольших машин и встроенных систем. (См. Макрос LUA_32BITS в файле luaconf.h .)

Если не указано иное, любое переполнение при манипулировании целочисленными значениями происходит циклически в соответствии с обычными правилами арифметики с двумя дополнениями. (Другими словами, фактический результат — это уникальное представимое целое число, равное по модулю 2 ⁿ математическому результату, где n — количество битов целочисленного типа.)

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

Строка типа представляет неизменяемые последовательности байтов. Lua является 8-битным чистым: строки могут содержать любое 8-битное значение, включая встроенные нули (‘ ‘). Lua также не зависит от кодирования; он не делает никаких предположений о содержимом строки. Длина любой строки в Lua должна соответствовать целому числу Lua.

Lua может вызывать (и манипулировать) функциями, написанными на Lua, и функциями, написанными на C (см. §3.4.10 ). Оба представлены функцией типа .

Тип userdata позволяет хранить произвольные данные C в переменных Lua. Значение пользовательских данных представляет собой блок необработанной памяти. Существует два вида пользовательских данных: полные пользовательские данные , которые представляют собой объект с блоком памяти, управляемый Lua, и легкие пользовательские данные , которые представляют собой просто значение указателя C. Пользовательские данные не имеют предопределенных операций в Lua, кроме присваивания и проверки подлинности. Используя метатаблицы , программист может определить операции для полных значений пользовательских данных (см. §2.4 ). Значения пользовательских данных не могут быть созданы или изменены в Lua, только через C API. Это гарантирует целостность данных, принадлежащих основной программе и библиотекам C.

Тип thread представляет независимые потоки выполнения и используется для реализации сопрограмм (см. §2.6 ). Потоки Lua не связаны с потоками операционной системы. Lua поддерживает сопрограммы во всех системах, даже в тех, которые изначально не поддерживают потоки.

Тип таблиц реализует ассоциативные массивы, то есть массивы , которые могут иметь в качестве индексов не только цифры, но любое значение Lua , кроме нуля и NaN. ( Not a Number — это специальное значение с плавающей запятой, используемое стандартом IEEE 754 для представления неопределенных числовых результатов, таких как 0/0 .) Таблицы могут быть неоднородными ; то есть они могут содержать значения всех типов (кроме nil ). Любой ключ, связанный со значением nil , не считается частью таблицы. И наоборот, любой ключ, не являющийся частью таблицы, имеет связанное значение nil .

Таблицы — единственный механизм структурирования данных в Lua; их можно использовать для представления обычных массивов, списков, таблиц символов, наборов, записей, графиков, деревьев и т. д. Для представления записей Lua использует имя поля в качестве индекса. Язык поддерживает это представление, предоставляя a.name в качестве синтаксического сахара для a["name"] . В Lua есть несколько удобных способов создания таблиц (см. §3.4.9 ).

Как и индексы, значения полей таблицы могут быть любого типа. В частности, поскольку функции являются значениями первого класса, поля таблицы могут содержать функции. Таким образом, таблицы также могут содержать методы (см. §3.4.11 ).

Индексация таблиц соответствует определению необработанного равенства в языке. Выражения a[i] и a[j] обозначают один и тот же элемент таблицы тогда и только тогда, когда i и j необработанные равны (то есть равны без метаметодов). В частности, числа с плавающей запятой с целыми значениями равны соответствующим им целым числам (например, 1.0 == 1 ). Чтобы избежать двусмысленности, любое число с плавающей запятой, используемое в качестве ключа, равное целому числу, преобразуется в это целое число. Например, если вы напишете a[2.0] = true , фактический ключ, вставленный в таблицу, будет целым числом 2 .

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

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

2.2-Окружающая среда и глобальная среда

Как мы обсудим далее в §3.2 и §3.3.3 , любая ссылка на свободное имя (т. е. имя, не связанное с каким-либо объявлением) var синтаксически преобразуется в _ENV.var . Более того, каждый фрагмент компилируется в области действия внешней локальной переменной с именем _ENV (см. §3.3.2 ), поэтому само _ENV никогда не является свободным именем в фрагменте.

Несмотря на существование этой внешней переменной _ENV и перевод свободных имен, _ENV — вполне обычное имя. В частности, вы можете определить новые переменные и параметры с этим именем. Каждая ссылка на свободное имя использует _ENV _ENV видимый в этой точке программы, в соответствии с обычными правилами видимости Lua (см. §3.5 ).

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

Lua поддерживает особую среду, называемую глобальной средой . Это значение хранится в специальном индексе в реестре C (см. §4.3 ). В Lua глобальная переменная _G инициализируется этим же значением. ( _G никогда не используется внутри, поэтому изменение его значения повлияет только на ваш собственный код.)

Когда Lua загружает кусок, значение по умолчанию для его _ENV переменной глобальной окружающей среды (см load ). Поэтому по умолчанию свободные имена в коде Lua относятся к записям в глобальной среде и, следовательно, они также называются глобальными переменными . Более того, все стандартные библиотеки загружаются в глобальную среду, и некоторые функции работают в этой среде. Вы можете использовать load (или loadfile ) для загрузки фрагмента с другой средой. (В C вы должны загрузить фрагмент, а затем изменить значение его первого повышающего значения; см. lua_setupvalue .)

2.3-Обработка ошибок

Некоторые операции в Lua могут вызвать ошибку. Ошибка прерывает нормальный поток программы, который может продолжиться, перехватив ошибку.

Код Lua может явно вызвать ошибку, вызвав функцию error . (Эта функция никогда не возвращается.)

Чтобы отловить ошибки в Lua, вы можете сделать защищенный вызов , используя pcall (или xpcall ). Функция pcall вызывает заданную функцию в защищенном режиме . Любая ошибка при запуске функции останавливает ее выполнение, и управление немедленно возвращается в pcall , который возвращает код состояния.

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

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

Когда вы используете xpcall (или lua_pcall в C), вы можете указать обработчик сообщений, который будет вызываться в случае ошибок. Эта функция вызывается с исходным объектом ошибки и возвращает новый объект ошибки. Он вызывается до того, как ошибка раскручивает стек, чтобы он мог собрать больше информации об ошибке, например, путем проверки стека и создания трассировки стека. Этот обработчик сообщений по-прежнему защищен защищенным вызовом; поэтому ошибка внутри обработчика сообщений снова вызовет обработчик сообщений. Если этот цикл длится слишком долго, Lua прерывает его и возвращает соответствующее сообщение. Обработчик сообщений вызывается только для обычных ошибок времени выполнения. Он не вызывается ни для ошибок выделения памяти, ни для ошибок при запуске финализаторов или других обработчиков сообщений.

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

2.4-Метатаблицы и метаметоды

Каждое значение в Lua может иметь метатаблицу . Эта метатаблица представляет собой обычную таблицу Lua, которая определяет поведение исходного значения при определенных событиях. Вы можете изменить несколько аспектов поведения значения, задав определенные поля в его метатаблице. Например, когда нечисловое значение является операндом добавления, Lua проверяет функцию в поле « __add » метатаблицы значения. Если он его находит, Lua вызывает эту функцию для выполнения добавления.

Ключом для каждого события в метатаблице является строка с именем события, которому предшествуют два символа подчеркивания; соответствующее значение называется метазначением . Для большинства событий метазначение должно быть функцией, которая затем называется метаметодом . В предыдущем примере ключ — это строка « __add », а метаметод — это функция, выполняющая добавление. Если не указано иное, метаметод может фактически быть любым вызываемым значением, которое является либо функцией, либо значением с __call .

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

Вы можете заменить метатаблицу таблиц с помощью функции setmetatable . Вы не можете изменить метатаблицу других типов из кода Lua, кроме как с помощью библиотеки отладки ( §6.10 ).

Таблицы и полные пользовательские данные имеют отдельные метатаблицы, хотя несколько таблиц и пользовательских данных могут совместно использовать свои метатаблицы. Значения всех других типов совместно используют одну единственную метатаблицу для каждого типа; то есть существует одна единственная метатаблица для всех чисел, одна для всех строк и т. д. По умолчанию значение не имеет метатаблицы, но библиотека строк устанавливает метатаблицу для строкового типа (см. §6.4 ) .

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

• __add : операция сложения ( + ). Если какой-либо операнд для добавления не является числом, Lua попытается вызвать метаметод. Он начинается с проверки первого операнда (даже если это число); если этот операнд не определяет __add для __add , то Lua проверит второй операнд. Если Lua может найти метаметод, он вызывает метаметод с двумя операндами в качестве аргументов, и результат вызова (с поправкой на одно значение) является результатом операции. В противном случае, если метаметод не найден, Lua выдаст ошибку.
• __sub : операция вычитания ( - ). Поведение аналогично операции сложения.
• __mul : операция умножения ( * ). Поведение аналогично операции сложения.
• __div : операция деления ( / ). Поведение аналогично операции сложения.
• __mod : операция по модулю ( % ). Поведение аналогично операции сложения.
• __pow : операция возведения в степень ( ^ ). Поведение аналогично операции сложения.
• __unm : операция отрицания (унарная - ). Поведение аналогично операции сложения.
• __idiv : операция деления этажа ( // ). Поведение аналогично операции сложения.
• __band : операция побитового И ( & ). Поведение аналогично операции сложения, за исключением того, что Lua попытается использовать метаметод, если какой-либо операнд не является ни целым числом, ни числом с плавающей запятой, которое можно привести к целому числу (см. §3.4.3 ).
• __bor : побитовая операция ИЛИ ( | ). Поведение аналогично побитовой операции И.
• __bxor : побитовая операция исключающее ИЛИ (двоичное ~ ). Поведение аналогично побитовой операции И.
• __bnot : побитовая операция НЕ (унарная ~ ). Поведение аналогично побитовой операции И.
• __shl : операция побитового сдвига влево ( << ). Поведение аналогично побитовой операции И.
• __shr : операция побитового сдвига вправо ( >> ). Поведение аналогично побитовой операции И.
• __concat : операция конкатенации ( .. ). Поведение аналогично операции сложения, за исключением того, что Lua будет пробовать метаметод, если какой-либо операнд не является ни строкой, ни числом (которое всегда может быть приведено к строке).
• __len : длина ( # ) операции. Если объект не является строкой, Lua попробует свой метаметод. Если есть метаметод, Lua вызывает его с объектом в качестве аргумента, а результат вызова (всегда настроенный на одно значение) является результатом операции. Если метаметода нет, но объект является таблицей, то Lua использует операцию длины таблицы (см. §3.4.7 ). В противном случае Lua выдает ошибку.
• __eq : операция равенства ( == ). Поведение аналогично операции сложения, за исключением того, что Lua будет пробовать метаметод только тогда, когда сравниваемые значения являются либо обеими таблицами, либо обоими полными пользовательскими данными, и они примитивно не равны. Результат вызова всегда преобразуется в логическое значение.
• __lt : операция «меньше» ( < ). Поведение аналогично операции сложения, за исключением того, что Lua будет пробовать метаметод только тогда, когда сравниваемые значения не являются ни числами, ни обеими строками. Более того, результат вызова всегда преобразуется в логическое значение.
• __le : операция меньшего равенства ( <= ). Поведение аналогично операции «меньше чем».
• __index : Таблица операций доступа к индексированию table[key] . Это событие происходит , когда table не является таблицей или когда key не присутствует в table . Метазначение ищется в метатаблице table .

  Метазначение для этого события может быть функцией, таблицей или любым значением с __index __index. Если это функция, она вызывается с table и key качестве аргументов, а результат вызова (с поправкой на одно значение) является результатом операции. В противном случае окончательный результат будет результатом индексации этого метазначения с помощью key . Это индексирование является обычным, а не исходным, и поэтому может вызвать другое __index __index.

• __newindex : Таблица присвоения индексации table[key] = value . Как и событие index, это событие происходит, когда table не является таблицей или когда key отсутствует в table . Метазначение ищется в метатаблице table .

  Как и в случае с индексированием, мета-значение для этого события может быть функцией, таблицей или любым значением с __newindex __newindex. Если это функция, она вызывается с table , key и value качестве аргументов. В противном случае Lua повторяет присвоение индексации для этого метазначения с тем же ключом и значением. Это обычное назначение, а не исходное, поэтому оно может вызвать другое __newindex __newindex.

  Каждый раз, когда __newindex __newindex, Lua не выполняет примитивное присваивание. При необходимости сам rawset может вызвать rawset для выполнения назначения.

• __call : функция вызова func(args) . Это событие происходит, когда Lua пытается вызвать значение, не являющееся функцией (то есть func не является функцией). Метаметод ищется в func . Если присутствует, метаметод вызывается с func в качестве первого аргумента, за которым следуют аргументы исходного вызова ( args ). Все результаты вызова являются результатами операции. Это единственный метаметод, позволяющий получить несколько результатов.

В дополнение к предыдущему списку интерпретатор также учитывает следующие ключи в метатаблицах: __gc (см. §2.5.3 ), __close (см. §3.3.8 ), __mode (см. §2.5.4 ) и __name . (Запись __name , если она содержит строку, может использоваться tostring и в сообщениях об ошибках.)

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

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

Хорошей практикой является добавление всех необходимых метаметодов в таблицу перед ее установкой в ​​качестве метатаблицы какого-либо объекта. В частности, метаметод __gc работает только при соблюдении этого порядка (см. §2.5.3 ). Также хорошей практикой является установка метатаблицы объекта сразу после его создания.

2.5-Сбор мусора

Lua выполняет автоматическое управление памятью. Это означает, что вам не нужно беспокоиться о выделении памяти для новых объектов или ее освобождении, когда объекты больше не нужны. Lua автоматически управляет памятью, запустив сборщик мусора для сбора всех мертвых объектов. Вся память, используемая Lua, подлежит автоматическому управлению: строки, таблицы, пользовательские данные, функции, потоки, внутренние структуры и т. Д.

Объект считается мертвым , как только сборщик может быть уверен, что к объекту больше не будет доступа при нормальном выполнении программы. («Нормальное выполнение» здесь исключает финализаторы, которые могут воскрешать мертвые объекты (см. §2.5.3 ), а также исключает операции с использованием библиотеки отладки.) Обратите внимание, что время, когда сборщик может быть уверен, что объект мертв, может не совпадать с ожиданиями программиста. Единственная гарантия заключается в том, что Lua не соберет объект, к которому все еще можно получить доступ при нормальном выполнении программы, и в конечном итоге соберет объект, недоступный из Lua. (Здесь недоступные из Luaозначает, что ни переменная, ни другой живой объект не ссылаются на объект.) Поскольку Lua ничего не знает о коде C, он никогда не собирает объекты, доступные через реестр (см. §4.3), который включает глобальную среду (см. §2.2 ).

Сборщик мусора (GC)в Lua может работать в двух режимах:инкрементном и генерационном.

Режим GC по умолчанию с параметрами по умолчанию достаточен для большинства случаев.Однако программы,которые тратят большую часть своего времени на выделение и освобождение памяти,могут извлечь пользу из других настроек.Помните,что поведение GC непортативно как для разных платформ,так и для разных релизов Lua;поэтому оптимальные настройки также непортативны.

Вы можете изменить режим и параметры lua_gc вызвав lua_gc в C или collectgarbage в Lua. Вы также можете использовать эти функции для непосредственного управления сборщиком (например, для его остановки и перезапуска).

2.5.1-Инкрементная сборка мусора

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

Пауза сборщика мусора контролирует, как долго сборщик ждет перед запуском нового цикла. Сборщик начинает новый цикл, когда использование памяти достигает n% от использования после предыдущего сбора. Более высокие значения делают сборщика менее агрессивным. Значения, равные или меньшие 100, означают, что сборщик не будет ждать начала нового цикла. Значение 200 означает, что сборщик ожидает, пока общий объем используемой памяти удвоится, прежде чем начать новый цикл. Значение по умолчанию — 200; максимальное значение — 1000.

Множитель шага сборщика мусора контролирует скорость работы сборщика относительно распределения памяти,то есть,сколько элементов он помечает или зачищает на каждый выделенный килобайт памяти.Большие значения делают сборщик более агрессивным,но также увеличивают размер каждого дополнительного шага.Не следует использовать значения меньше 100,поскольку они делают сборщик слишком медленным и могут привести к тому,что сборщик никогда не завершит цикл.Значение по умолчанию-100;максимальное значение-1000.

Размер шага сборщика мусора контролирует размер каждого инкрементного шага, в частности, сколько байтов выделяет интерпретатор перед выполнением шага. Этот параметр является логарифмическим: значение n означает, что интерпретатор будет выделять 2 ⁿ байтов между шагами и выполнять эквивалентную работу во время шага. Большое значение (например, 60) делает сборщик остановившимся (не инкрементным) сборщиком. Значение по умолчанию — 13, что означает шаг примерно 8 Кбайт.

2.5.2-Генерационная сборка мусора

В режиме генерации сборщик часто выполняет второстепенные коллекции, которые проходят только недавно созданные объекты. Если после второстепенной коллекции использование памяти все еще превышает предел, сборщик выполняет основную коллекцию Stop-the-world , которая проходит по всем объектам. В режиме генерации используются два параметра: младший множитель и старший множитель .

Младший множитель контролирует частоту второстепенных сборов. Для второстепенного множителя x новая второстепенная коллекция будет выполнена, когда объем памяти станет на x% больше, чем объем используемой памяти после предыдущей основной коллекции. Например, для множителя 20 сборщик будет выполнять второстепенный сбор, когда использование памяти становится на 20% больше, чем использование после предыдущей основной коллекции. Значение по умолчанию — 20; максимальное значение — 200.

Главный множитель контролирует частоту крупных сборов. Для основного множителя x новая основная коллекция будет выполнена, когда объем памяти станет на x% больше, чем объем памяти, используемой после предыдущей основной коллекции. Например, для множителя 100 сборщик будет выполнять основную сборку, когда использование памяти становится больше, чем в два раза после предыдущего сбора. Значение по умолчанию — 100; максимальное значение — 1000.

2.5.3-Метаметоды сбора мусора

Вы можете установить метаметоды сборщика мусора для таблиц и, используя C API, для полных пользовательских данных (см. §2.4 ). Эти метаметоды, называемые финализаторами , вызываются, когда сборщик мусора обнаруживает, что соответствующая таблица или пользовательские данные мертвы. Финализаторы позволяют координировать сборку мусора Lua с управлением внешними ресурсами, такими как закрытие файлов, подключение к сети или базе данных или освобождение собственной памяти.

Чтобы объект (таблица или пользовательские данные) был завершен при сборе, вы должны пометить его для завершения. Вы помечаете объект для завершения, когда устанавливаете его метатаблицу, и метатаблица имеет поле, проиндексированное строкой « __gc ». Обратите внимание, что если вы установите метатаблицу без поля __gc , а затем создадите это поле в метатаблице, объект не будет помечен для завершения.

Когда отмеченный объект становится мертвым, сборщик мусора не собирает его немедленно. Вместо этого Lua помещает его в список. После сбора Lua просматривает этот список. Для каждого объекта в списке он проверяет __gc объекта __gc : если он присутствует, Lua вызывает его с объектом в качестве единственного аргумента.

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

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

Когда вы закрываете состояние (см. lua_close ), Lua вызывает финализаторы всех объектов, отмеченных для завершения, следуя порядку, обратному тому, в котором они были отмечены. Если какой-либо финализатор помечает объекты для сбора на этом этапе, эти отметки не действуют.

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

Любая ошибка при выполнении финализатора вызывает предупреждение;ошибка не распространяется.

2.5.4-Слабые таблицы

Слабая таблица представляет собой таблицу, элементы которой являются слабыми ссылками . Слабая ссылка игнорируется сборщиком мусора. Другими словами, если единственными ссылками на объект являются слабые ссылки, то сборщик мусора соберет этот объект.

Слабая таблица может иметь слабые ключи, слабые значения или и то, и другое. Таблица со слабыми значениями позволяет собирать свои значения, но не позволяет собирать ключи. Таблица со слабыми ключами и слабыми значениями позволяет собирать как ключи, так и значения. В любом случае, если собирается ключ или значение, вся пара удаляется из таблицы. Слабость таблицы контролируется полем __mode ее метатаблицы. Это метазначение, если оно присутствует, должно быть одной из следующих строк: « k » для таблицы со слабыми ключами; » v » для таблицы со слабыми значениями; или « kv » для таблицы со слабыми ключами и значениями.

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

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

Из слабых таблиц удаляются только те объекты,которые имеют явную конструкцию.Значения,такие как числа и легкие функции языка C,не подлежат сборке мусора и поэтому не удаляются из слабых таблиц (если только не собираются связанные с ними значения).Хотя строки подвержены сборке мусора,они не имеют явной конструкции,и их равенство осуществляется по значению;они ведут себя скорее как значения,чем как объекты.Поэтому они не удаляются из слабых таблиц.

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

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

2.6-Корутины

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

Вы создаете сопрограмму, вызывая coroutine.create . Его единственный аргумент — это функция, которая является основной функцией сопрограммы. Функция create только создает новую сопрограмму и возвращает ее дескриптор (объект типа thread ); он не запускает сопрограмму.

Вы выполняете сопрограмму, вызывая coroutine.resume . Когда вы впервые вызываете coroutine.resume , передавая в качестве первого аргумента поток, возвращаемый coroutine.create , сопрограмма начинает свое выполнение, вызывая свою основную функцию. Дополнительные аргументы, переданные в coroutine.resume , передаются в качестве аргументов этой функции. После того , как сопрограмма начинает работать, он работает , пока он не закончит или выходы .

Сопрограмма может завершить свое выполнение двумя способами: обычно, когда возвращается ее основная функция (явно или неявно, после последней инструкции); и ненормально, если есть незащищенная ошибка. В случае нормального завершения, coroutine.resume возвращает true плюс любые значения, возвращаемые основной функцией сопрограммы. В случае ошибок coroutine.resume возвращает false плюс объект ошибки. В этом случае сопрограмма не раскручивает свой стек, чтобы можно было проверить его после ошибки с помощью API отладки.

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

Как и coroutine.create , функция coroutine.wrap также создает сопрограмму, но вместо того, чтобы возвращать саму сопрограмму, она возвращает функцию, которая при вызове возобновляет сопрограмму. Любые аргументы, переданные этой функции, передаются в coroutine.resume как дополнительные аргументы . coroutine.wrap возвращает все значения, возвращаемые coroutine.resume , кроме первого (логический код ошибки). В отличие от coroutine.resume , функция, созданная coroutine.wrap , передает любую ошибку вызывающей стороне. В этом случае функция также закрывает сопрограмму (см. coroutine.close ).

В качестве примера того,как работают корутины,рассмотрим следующий код:

function foo (a)
  print("foo", a)
  return coroutine.yield(2*a)
end

co = coroutine.create(function (a,b)
      print("co-body", a, b)
      local r = foo(a+1)
      print("co-body", r)
      local r, s = coroutine.yield(a+b, a-b)
      print("co-body", r, s)
      return b, "end"
end)

print("main", coroutine.resume(co, 1, 10))
print("main", coroutine.resume(co, "r"))
print("main", coroutine.resume(co, "x", "y"))
print("main", coroutine.resume(co, "x", "y"))

При запуске он выдает следующий результат:

co-body 1       10
foo     2
main    true    4
co-body r
main    true    11      -9
co-body x       y
main    true    10      end
main    false   cannot resume dead coroutine

Вы также можете создавать сопрограммы и управлять ими через API C: см. Функции lua_newthread , lua_resume и lua_yield .

3-Язык

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

Языковые конструкции будут объясняться с использованием обычной расширенной нотации BNF, в которой { a } означает 0 или более a , а [ a ] означает необязательное a . Нетерминалы отображаются как нетерминалы, ключевые слова отображаются как kword , а другие терминальные символы отображаются как ‘ = ‘. Полный синтаксис Lua можно найти в §9 в конце этого руководства.

3.1-Лексические конвенции

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

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

Следующие ключевые слова зарезервированы и не могут использоваться в качестве имен:

and       break     do        else      elseif    end
false     for       function  goto      if        in
local     nil       not       or        repeat    return
then      true      until     while

Lua — это язык с учетом регистра: and является зарезервированным словом, но And и AND — два разных допустимых имени. По соглашению программы должны избегать создания имен, которые начинаются с подчеркивания, за которым следует одна или несколько заглавных букв (например, _VERSION ).

Следующие строки обозначают другие жетоны:

+     -     *     /     %     ^     
&     ~     |     <<    >>    
==    ~=    <=    >=    <     >     =
(     )     {     }     [     ]     ::
;     :     ,     .     ..    ...

Короткая символьная строка может быть ограничена путем сопоставления одинарные или двойные кавычки, и может содержать следующую C-типа управляющих последовательностей: « a » (колокол), « b » (забой), « f » (форма подачи), ‘ n ‘ (новая строка), ‘ r ‘ (возврат каретки), ‘ t ‘ (горизонтальная табуляция), ‘ v ‘ (вертикальная табуляция), ‘ \ ‘ (обратная косая черта), ‘ " ‘ (кавычки [двойная кавычка]) и ‘ ' ‘(апостроф [одинарная кавычка]). Обратная косая черта, за которой следует разрыв строки, приводит к новой строке в строке. Управляющая последовательность’ z ‘пропускает следующий диапазон пробелов, включая разрывы строк; особенно полезно разбивать длинную буквальную строку на несколько строк и делать отступы без добавления новых строк и пробелов в содержимое строки. Короткая буквальная строка не может содержать неэкранированные разрывы строк или экранированные символы, не образующие допустимую escape-последовательность.

Мы можем указать любой байт в короткой литеральной строке, включая встроенные нули, по его числовому значению. Это можно сделать с помощью escape-последовательности xXX , где XX — это последовательность ровно из двух шестнадцатеричных цифр, или с помощью escape-последовательности ddd , где ddd — это последовательность до трех десятичных цифр. (Обратите внимание, что если за десятичной escape-последовательностью должна следовать цифра, она должна быть выражена с использованием ровно трех цифр.)

Кодировка UTF-8 символа Unicode может быть вставлена ​​в буквальную строку с помощью escape-последовательности u{XXX} (с обязательными закрывающими фигурными скобками), где XXX — это последовательность из одной или нескольких шестнадцатеричных цифр, представляющих кодовую точку символа. Эта кодовая точка может иметь любое значение меньше 2 ³¹ . (Здесь Lua использует исходную спецификацию UTF-8, которая не ограничивается допустимыми кодовыми точками Unicode.)

Литеральные строки также могут быть определены с использованием длинного формата, заключенного в длинные скобки . Мы определяем открывающую длинную скобку уровня n как открывающую квадратную скобку, за которой следуют n знаков равенства, за которыми следует еще одна открывающая квадратная скобка. Итак, открывающая длинная скобка уровня 0 записывается как [[ , открывающая длинная скобка уровня 1 записывается как [=[ и так далее. Закрытия длинный кронштейн определяется аналогично; например, закрывающая длинная скобка уровня 4 записывается как ]====] . Долго буквальнымначинается с открывающей длинной скобки любого уровня и заканчивается первой закрывающей длинной скобкой того же уровня. Он может содержать любой текст, кроме закрывающей скобки того же уровня. Литералы в этой заключенной в квадратные скобки форме могут занимать несколько строк, не интерпретируют никаких управляющих последовательностей и игнорируют длинные скобки любого другого уровня. Любая последовательность конца строки (возврат каретки, новая строка, возврат каретки с последующим переводом строки или новая строка с последующим возвратом каретки) преобразуется в простой символ новой строки. Когда за открывающей длинной скобкой сразу следует перевод строки, новая строка не включается в строку.

Например, в системе, использующей ASCII (в которой ‘ a ‘ кодируется как 97, новая строка кодируется как 10, а ‘ 1 ‘ кодируется как 49), пять литеральных строк ниже обозначают одну и ту же строку:

a = 'alon123"'
a = "alon123""
a = '97lo104923"'
a = [[alo
123"]]
a = [==[
alo
123"]==]

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

Числовая константа (или цифра ) может быть записана с помощью дополнительного дробной части и дополнительный десятичное показатель, отмеченный буквой « e » или « E ». Lua также принимает шестнадцатеричные константы, которые начинаются с 0x или 0X . Шестнадцатеричные константы также принимают необязательную дробную часть плюс необязательную двоичную экспоненту, отмеченную буквой « p » или « P ».

Числовая константа с точкой счисления или показателем степени обозначает число с плавающей запятой; в противном случае, если его значение соответствует целому числу или является шестнадцатеричной константой, оно обозначает целое число; в противном случае (то есть десятичное целое число, которое выходит за пределы), оно обозначает число с плавающей запятой. Шестнадцатеричные числа без точки счисления или показателя степени всегда обозначают целочисленное значение; если значение переполняется, оно оборачивается, чтобы соответствовать действительному целому числу.

Примерами допустимых целочисленных констант являются

3   345   0xff   0xBEBADA

Примерами действующих констант поплавка являются

3.0     3.1416     314.16e-2     0.31416E1     34e1
0x0.1E  0xA23p-4   0X1.921FB54442D18P+1

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

3.2-Переменные

Переменные-это места,где хранятся значения.В Lua есть три типа переменных:глобальные переменные,локальные переменные и поля таблиц.

Одно имя может обозначать глобальную или локальную переменную (или формальный параметр функции,которая является определенным видом локальной переменной):

var ::= Name

Имя обозначает идентификаторы (см. §3.1 ).

Любое имя переменной считается глобальным, если оно явно не объявлено как локальное (см. §3.3.7 ). Локальные переменные имеют лексическую область видимости : к локальным переменным могут свободно обращаться функции, определенные внутри их области видимости (см. §3.5 ).

Перед первым присваиванием переменной ее значение равно нулю .

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

var ::= prefixexp ‘[’ exp ‘]’

Значение доступа к полям таблицы можно изменить с помощью метатаблиц (см. §2.4 ).

Синтаксис var.Name — это просто синтаксический сахар для var["Name"] :

var ::= prefixexp ‘.’ Name

Доступ к глобальной переменной x эквивалентен _ENV.x . Из-за того, как компилируются фрагменты, сама переменная _ENV никогда не бывает глобальной (см. §2.2 ).

3.3-Заявления

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

3.3.1-Блоки

Блок-это список операторов,которые выполняются последовательно:

block ::= {stat}

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

stat ::= ‘;’

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

a = b + c
(print or io.write)('done')

Грамматика может рассматривать этот фрагмент двумя способами:

a = b + c(print or io.write)('done')

a = b + c; (print or io.write)('done')

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

;(print or io.write)('done')

Блок может быть четко разграничен для получения одного заявления:

stat ::= do block end

Явные блоки полезны для управления областью объявлений переменных. Явные блоки также иногда используются для добавления оператора возврата в середине другого блока (см. §3.3.4 ).

3.3.2-Чанки

Единица компиляции Lua называется чанком . Синтаксически чанк — это просто блок:

chunk ::= block

Lua обрабатывает фрагмент как тело анонимной функции с переменным числом аргументов (см. §3.4.11 ). Таким образом, куски могут определять локальные переменные, получать аргументы и возвращать значения. Более того, такая анонимная функция компилируется как в области действия внешней локальной переменной с именем _ENV (см. §2.2 ). Результирующая функция всегда имеет _ENV в качестве единственной внешней переменной, даже если она не использует эту переменную.

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

Чанки также могут быть предварительно скомпилированы в двоичную форму; подробности см. в программе luac и в функции string.dump . Программы в исходной и скомпилированной формах взаимозаменяемы; Lua автоматически определяет тип файла и действует соответственно (см. load ).

3.3.3-Назначение

Луа допускает множественные назначения.Поэтому синтаксис присваивания определяет список переменных слева и список выражений справа.Элементы в обоих списках разделены запятыми:

stat ::= varlist ‘=’ explist
varlist ::= var {‘,’ var}
explist ::= exp {‘,’ exp}

Выражения обсуждаются в §3.4 .

Перед присваиванием список значений подгоняется под длину списка переменных. Если значений больше, чем необходимо, лишние значения отбрасываются. Если значений меньше, чем необходимо, список дополняется nil . Если список выражений заканчивается вызовом функции, то все значения, возвращаемые этим вызовом, попадают в список значений перед корректировкой (кроме случаев, когда вызов заключен в круглые скобки; см. §3.4 ) .

Оператор присваивания сначала оценивает все свои выражения,и только затем выполняются присваивания.Таким образом,код

i = 3
i, a[i] = i+1, 20

устанавливает a[3] в 20, не влияя a[4] потому что i в a[i] оценивается (до 3) до того, как ему присваивается 4. Аналогично, строка

x, y = y, x

меняет местами значения x и y , и

x, y, z = y, z, x

циклически переставляет значения x , y и z .

Присвоение глобальному имени x = val эквивалентно присвоению _ENV.x = val (см. §2.2 ).

Значение присвоений полям таблицы и глобальным переменным (которые на самом деле тоже являются полями таблицы) можно изменить с помощью метатаблиц (см. §2.4 ).

3.3.4-Структуры управления

Управляющие структуры if , while и repeat имеют обычный смысл и знакомый синтаксис:

stat ::= while exp do block end
stat ::= repeat block until exp
stat ::= if exp then block {elseif exp then block} [else block] end

В Lua также есть оператор for в двух вариантах (см. §3.3.5 ).

Выражение условия управляющей структуры может возвращать любое значение. И ложь и ноль тест ложно. Все значения отличны от nil и false test true. В частности, число 0 и пустая строка также проверяют истинность.

В цикле Repeat — until внутренний блок не заканчивается на ключевом слове until , а только после условия. Таким образом, условие может ссылаться на локальные переменные, объявленные внутри блока цикла.

Оператор goto передает управление программой метке. По синтаксическим причинам метки в Lua тоже считаются операторами:

stat ::= goto Name
stat ::= label
label ::= ‘::’ Name ‘::’

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

Этикетки и пустые заявления называются недействительным заявление , так как они не выполняют никаких действий.

Оператор break завершает выполнение цикла while , repeat или for , переходя к следующему оператору после цикла:

stat ::= break

Перерыв заканчивает самую внутреннюю охватывающую петлю.

Оператор return используется для возврата значений из функции или фрагмента (который обрабатывается как анонимная функция). Функции могут возвращать более одного значения, поэтому синтаксис оператора возврата следующий :

stat ::= return [explist] [‘;’]

Оператор возврата может быть записан только как последний оператор блока. Если необходимо выполнить возврат в середине блока, то можно использовать явный внутренний блок, как в идиоме do return end , потому что теперь return является последним оператором в его (внутреннем) блоке.

3.3.5-Для заявления

Оператор for имеет две формы: числовую и общую.

Числовой цикл for

Числовой цикл for повторяет блок кода, в то время как управляющая переменная проходит через арифметическую прогрессию. Он имеет следующий синтаксис:

stat ::= for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end

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

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

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

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

Для целочисленных циклов управляющая переменная никогда не оборачивается;вместо этого цикл завершается в случае переполнения.

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

Общий цикл for

Общий оператор for работает с функциями, называемыми итераторами . На каждой итерации вызывается функция итератора для создания нового значения, которая останавливается, когда это новое значение равно нулю . Общий цикл for имеет следующий синтаксис:

stat ::= for namelist in explist do block end
namelist ::= Name {‘,’ Name}

Для заявления как

for var_1, ···, var_n in explist do body end

работает следующим образом.

Имена var_i объявляют переменные цикла, локальные для тела цикла. Первая из этих переменных — это управляющая переменная .

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

Затем на каждой итерации Lua вызывает функцию-итератор с двумя аргументами: состоянием и управляющей переменной. Затем результаты этого вызова присваиваются переменным цикла в соответствии с правилами множественного присваивания (см. §3.3.3 ). Если управляющая переменная становится равной nil , цикл завершается. В противном случае выполняется тело и цикл переходит к следующей итерации.

Закрывающее значение ведет себя как подлежащая закрытию переменная (см. §3.3.8 ), которую можно использовать для высвобождения ресурсов после завершения цикла. В противном случае он не мешает петле.

Не следует изменять значение управляющей переменной во время цикла.

3.3.6-Вызовы функций как утверждения

Для обеспечения возможных побочных эффектов вызовы функций могут выполняться в виде операторов:

stat ::= functioncall

В этом случае все возвращаемые значения отбрасываются. Вызовы функций объясняются в §3.4.10 .

3.3.7-Локальные декларации

Локальные переменные могут быть объявлены в любом месте блока.Объявление может включать инициализацию:

stat ::= local attnamelist [‘=’ explist]
attnamelist ::=  Name attrib {‘,’ Name attrib}

Если присутствует, начальное присвоение имеет ту же семантику множественного присвоения (см. §3.3.3 ). В противном случае все переменные инициализируются nil .

Имя каждой переменной может быть постфиксировано атрибутом (имя в угловых скобках):

attrib ::= [‘<’ Name ‘>’]

Возможны два атрибута: const , который объявляет константную переменную, то есть переменную, которой нельзя присвоить значение после ее инициализации; и close , которая объявляет подлежащую закрытию переменную (см. §3.3.8 ). Список переменных может содержать не более одной подлежащей закрытию переменной.

Блок также является блоком (см. §3.3.2 ), поэтому локальные переменные могут быть объявлены в блоке вне любого явного блока.

Правила видимости для локальных переменных объясняются в §3.5 .

3.3.8-Переменные,которые должны быть закрыты

Закрытая переменная ведет себя как постоянная локальная переменная, за исключением того, что ее значение закрывается всякий раз, когда переменная выходит за пределы области видимости, включая нормальное завершение блока, выход из блока с помощью break / goto / return или выход по ошибке.

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

Значение, присвоенное закрываемой переменной, должно иметь __close или быть ложным. ( nil и false игнорируются как закрываемые значения.)

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

Если при выполнении закрывающего метода возникает какая-либо ошибка,она обрабатывается как ошибка в обычном коде,в котором была определена переменная.Однако Lua может вызвать метод еще раз.

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

Если сопрограмма завершается и больше никогда не возобновляется, некоторые переменные могут никогда не выйти за пределы области видимости, и, следовательно, они никогда не будут закрыты. (Эти переменные созданы внутри сопрограммы и в области видимости в точке, где сопрограмма выдала ошибку.) Точно так же, если сопрограмма завершается ошибкой, она не разворачивает свой стек, поэтому не закрывает никакую переменную. В обоих случаях вы можете использовать финализаторы или вызвать coroutine.close , чтобы закрыть переменные. Однако, если сопрограмма была создана через coroutine.wrap , то соответствующая функция закроет сопрограмму в случае ошибки.

3.4-Выражения

Основные выражения в Lua следующие:

exp ::= prefixexp
exp ::= nil | false | true
exp ::= Numeral
exp ::= LiteralString
exp ::= functiondef
exp ::= tableconstructor
exp ::= ‘...’
exp ::= exp binop exp
exp ::= unop exp
prefixexp ::= var | functioncall | ‘(’ exp ‘)’

Численные и литеральные строки объясняются в §3.1 ; переменные объясняются в §3.2 ; определения функций объясняются в §3.4.11 ; вызовы функций объясняются в §3.4.10 ; конструкторы таблиц объясняются в §3.4.9 . Выражения vararg, обозначаемые тремя точками (‘ ... ‘), могут использоваться только непосредственно внутри функции vararg; они объясняются в §3.4.11 .

Бинарные операторы включают арифметические операторы (см. §3.4.1 ), побитовые операторы (см. §3.4.2 ), операторы отношения (см. §3.4.4 ), логические операторы (см. §3.4.5 ) и оператор конкатенации (см. §3.4.5 ). 3.4.6 ). Унарные операторы включают унарный минус (см. §3.4.1 ), унарное побитовое НЕ (см. §3.4.2 ), унарное логическое НЕ (см. §3.4.5 ) и унарный оператор длины (см. §3.4.7 ). .

И вызовы функций, и выражения vararg могут привести к нескольким значениям. Если вызов функции используется как оператор (см. §3.3.6 ), то его возвращаемый список корректируется до нулевых элементов, таким образом отбрасывая все возвращаемые значения. Если выражение используется в качестве последнего (или единственного) элемента списка выражений, корректировка не выполняется (если только выражение не заключено в круглые скобки). Во всех других контекстах Lua корректирует список результатов до одного элемента, либо отбрасывая все значения, кроме первого, либо добавляя один ноль , если значений нет.

Вот несколько примеров:

f()                
g(f(), x)          
g(x, f())          
a,b,c = f(), x     
a,b = ...          
                   
                   

a,b,c = x, f()     
a,b,c = f()        
return f()         
return ...         
return x,y,f()     
{f()}              
{...}              
{f(), nil}         

Любое выражение, заключенное в круглые скобки, всегда дает только одно значение. Таким образом, (f(x,y,z)) всегда является одним значением, даже если f возвращает несколько значений. (Значение (f(x,y,z)) — это первое значение, возвращаемое f или nil, если f не возвращает никаких значений.)

3.4.1-Арифметические операторы

Lua поддерживает следующие арифметические операторы:

• +: addition
• -: subtraction
• *: multiplication
• / : деление с плавающей запятой
• // : разделение этажей
• %: modulo
• ^: exponentiation
• - : унарный минус

За исключением возведения в степень и деления с плавающей запятой, арифметические операторы работают следующим образом: Если оба операнда являются целыми числами, операция выполняется над целыми числами, и результатом является целое число. В противном случае, если оба операнда являются числами, они преобразуются в числа с плавающей запятой, операция выполняется в соответствии с правилами машины для арифметики с плавающей запятой (обычно стандарт IEEE 754), и результатом является число с плавающей запятой. (Библиотека строк приводит строки к числам в арифметических операциях; подробности см. в §3.4.3 .)

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

Деление по полу ( // ) — это деление, округляющее частное до минус бесконечности, в результате чего получается нижний предел деления его операндов.

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

В случае переполнения в целочисленной арифметике все операции переносятся .

3.4.2-Побитовые операторы

Lua поддерживает следующие битовые операторы:

• & : побитовое И
• | : побитовое ИЛИ
• ~ : побитовое исключающее ИЛИ
• >> : сдвиг вправо
• << : сдвиг влево
• ~ : унарное побитовое НЕ

Все побитовые операции преобразуют свои операнды в целые числа (см. §3.4.3 ), работают со всеми битами этих целых чисел и приводят к целому числу.

Сдвиги вправо и влево заполняют пустые биты нулями.Отрицательные смещения смещаются в другую сторону;смещения с абсолютными значениями,равными или превышающими число битов в целочисленном выражении,приводят к нулю (так как все биты смещаются).

3.4.3-Коэрцитивы и преобразования

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

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

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

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

Тем не менее всегда рекомендуется не полагаться на эти неявные приведения, поскольку они не всегда применяются; в частности, "1"==1 ложно, а "1"<1 вызывает ошибку (см. §3.4.4 ). Эти приведения существуют в основном для совместимости и могут быть удалены в будущих версиях языка.

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

Преобразование чисел в строки использует неуказанный удобочитаемый формат. Чтобы преобразовать числа в строки определенным образом, используйте функцию string.format .

3.4.4-Реляционные операторы

Lua поддерживает следующие реляционные операторы:

• ==: equality
• ~=: inequality
• < : меньше чем
• > : больше чем
• <= : меньше или равно
• >= : больше или равно

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

Равенство ( == ) сначала сравнивает тип своих операндов. Если типы разные, то результат ложный . В противном случае сравниваются значения операндов. Строки равны, если они имеют одинаковое байтовое содержимое. Числа равны, если они обозначают одно и то же математическое значение.

Таблицы,пользовательские данные и потоки сравниваются по ссылке:два объекта считаются равными,только если они являются одним и тем же объектом.Каждый раз,когда вы создаете новый объект (таблицу,пользовательские данные или поток),этот новый объект отличается от любого ранее существовавшего объекта.Функция всегда равна самой себе.Функции с любым обнаруживаемым различием (разное поведение,разное определение)всегда различны.Функции,созданные в разное время,но не имеющие обнаруживаемых различий,могут быть классифицированы как равные или нет (в зависимости от деталей внутреннего кэширования).

Вы можете изменить способ, которым Lua сравнивает таблицы и пользовательские данные, используя метаметод __eq (см. §2.4 ).

Сравнение на равенство не преобразует строки в числа и наоборот. Таким образом, "0"==0 оценивается как ложь , а t[0] и t["0"] обозначают разные записи в таблице.

Оператор ~= в точности отрицает равенство ( == ).

Операторы заказа работают следующим образом. Если оба аргумента являются числами, то они сравниваются в соответствии с их математическими значениями, независимо от их подтипов. В противном случае, если оба аргумента являются строками, то их значения сравниваются в соответствии с текущей локалью. В противном случае Lua пытается вызвать метаметод __lt или __le (см. §2.4 ). Сравнение a > b преобразуется в b < a , а a >= b преобразуется в b <= a .

В соответствии со стандартом IEEE 754,специальное значение NaN считается ни меньше,ни равным,ни больше любого значения,включая себя.

3.4.5-Логические операторы

Логические операторы в Lua — это и , или , и не . Подобно управляющим структурам (см. §3.3.4 ), все логические операторы рассматривают как false , так и nil как false, а все остальное как true.

Оператор отрицания не всегда возвращает false или true . Оператор соединения и возвращает свой первый аргумент, если это значение ложно или равно нулю ; в противном случае и возвращает свой второй аргумент. Оператор дизъюнкции or возвращает свой первый аргумент, если это значение отличается от nil и false ; в противном случае или возвращает свой второй аргумент. Оба and и or используют оценку короткого замыкания; то есть второй операнд оценивается только в случае необходимости. Вот некоторые примеры:

10 or 20            
10 or error()       
nil or "a"          
nil and 10          
false and error()   
false and nil       
false or nil        
10 and 20           

3.4.6-Конкатенация

Оператор конкатенации строк в Lua обозначается двумя точками (‘ .. ‘). Если оба операнда являются строками или числами, то числа преобразуются в строки в неуказанном формате (см. §3.4.3 ). В противном случае вызывается метаметод __concat (см.§2.4 ).

3.4.7-Оператор длины

Оператор длины обозначается унарным префиксным оператором # .

Длина строки-это количество байтов в ней.(Это обычное значение длины строки,когда каждый символ равен одному байту).

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

(border == 0 or t[border] ~= nil) and t[border + 1] == nil

Другими словами,граница-это любой (натуральный)индекс,присутствующий в таблице,за которым следует отсутствующий индекс (или ноль,когда индекс 1 отсутствует).

Таблица с одной границей называется последовательностью . Например, таблица {10, 20, 30, 40, 50} является последовательностью, так как у нее только одна граница (5). Таблица {10, 20, 30, nil, 50} имеет две границы (3 и 5), поэтому она не является последовательностью. ( Ноль в индексе 4 называется дырой .) Таблица {nil, 20, 30, nil, nil, 60, nil} имеет три границы (0, 3 и 6) и три дыры (в индексах 1, 4, и 5), так что это тоже не последовательность. Таблица {} представляет собой последовательность с границей 0. Обратите внимание, что неестественные ключи не влияют на то, является ли таблица последовательностью.

Когда t — последовательность, #t возвращает ее единственную границу, которая соответствует интуитивному представлению о длине последовательности. Когда t не является последовательностью, #t может возвращать любую из своих границ. (Точный зависит от деталей внутреннего представления таблицы, которое, в свою очередь, может зависеть от того, как таблица была заполнена, и адресов памяти ее нечисловых ключей.)

Вычисление длины таблицы имеет гарантированно худшее время O (log n) , где n — наибольший естественный ключ в таблице.

Программа может изменить поведение оператора длины для любого значения, кроме строк, с помощью метаметода __len (см. §2.4 ).

3.4.8-Приоритет

Приоритет оператора в Lua следует из нижеследующей таблицы,от более низкого к более высокому приоритету:

or
and
<     >     <=    >=    ~=    ==
|
~
&
<<    >>
..
+     -
*     /     
unary operators (not   #     -     ~)
^

Как обычно, вы можете использовать круглые скобки для изменения приоритета выражения. Операторы конкатенации (‘ .. ‘) и возведения в степень (‘ ^ ‘) являются правоассоциативными. Все остальные бинарные операторы левоассоциативны.

3.4.9-Конструкторы таблиц

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

tableconstructor ::= ‘{’ [fieldlist] ‘}’
fieldlist ::= field {fieldsep field} [fieldsep]
field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp
fieldsep ::= ‘,’ | ‘;’

Каждое поле формы [exp1] = exp2 добавляет в новую таблицу запись с ключом exp1 и значением exp2 . Поле формы name = exp эквивалентно ["name"] = exp . Поля формы exp эквивалентны [i] = exp , где i — последовательные целые числа, начинающиеся с 1; поля в других форматах не влияют на этот подсчет. Например,

a = { [f(1)] = g

равносильно

do
  local t = {}
  t[f(1)] = g
  t[1] = "x"         
  t[2] = "y"         
  t.x = 1            
  t[3] = f(x)        
  t[30] = 23
  t[4] = 45          
  a = t
end

Порядок заданий в конструкторе не определен.(Этот порядок будет релевантен только при наличии повторяющихся клавиш).

Если последнее поле в списке имеет вид exp , а выражение является вызовом функции или выражением vararg, то все значения, возвращаемые этим выражением, входят в список последовательно (см. §3.4.10 ).

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

3.4.10-Вызовы функций

Вызов функции в Луа имеет следующий синтаксис:

functioncall ::= prefixexp args

При вызове функции оцениваются первое префиксное выражение и аргументы. Если значение prefixexp имеет тип function , то эта функция вызывается с заданными аргументами. В противном случае, если он присутствует, вызывается метаметод prefixexp __call : его первым аргументом является значение prefixexp, за которым следуют исходные аргументы вызова (см. §2.4 ).

The form

functioncall ::= prefixexp ‘:’ Name args

может использоваться для имитации методов. Вызов v:name(args) является синтаксическим сахаром для v.name(v,args) , за исключением того, что v вычисляется только один раз.

Аргументы имеют следующий синтаксис:

args ::= ‘(’ [explist] ‘)’
args ::= tableconstructor
args ::= LiteralString

Все выражения аргументов оцениваются перед вызовом. Вызов формы f{fields} является синтаксическим сахаром для f({fields}) ; то есть список аргументов — это одна новая таблица. Вызов формы f'string' (или f"string" или f[[string]] ) является синтаксическим сахаром для f('string') ; то есть список аргументов представляет собой одну буквальную строку.

Вызов формы return functioncall вне области действия закрываемой переменной называется хвостовым вызовом . Lua реализует правильные хвостовые вызовы (или правильную хвостовую рекурсию ): в хвостовом вызове вызываемая функция повторно использует запись в стеке вызывающей функции. Следовательно, нет ограничений на количество вложенных хвостовых вызовов, которые может выполнить программа. Однако хвостовой вызов стирает любую отладочную информацию о вызывающей функции. Обратите внимание, что хвостовой вызов происходит только с определенным синтаксисом, где returnимеет один единственный вызов функции в качестве аргумента, и он выходит за рамки любой закрываемой переменной. Этот синтаксис заставляет вызывающую функцию возвращать в точности результаты вызываемой функции без каких-либо промежуточных действий. Итак, ни один из следующих примеров не является хвостовым вызовом:

return (f(x))        
return 2 * f(x)      
return x, f(x)       
f(x); return         
return x or f(x)     

3.4.11-Определения функций

Синтаксис для определения функции

functiondef ::= function funcbody
funcbody ::= ‘(’ [parlist] ‘)’ block end

Следующий синтаксический сахар упрощает определение функций:

stat ::= function funcname funcbody
stat ::= local function Name funcbody
funcname ::= Name {‘.’ Name} [‘:’ Name]

The statement

function f () body end

translates to

f = function () body end

The statement

function t.a.b.c.f () body end

translates to

t.a.b.c.f = function () body end

The statement

local function f () body end

translates to

local f; f = function () body end

not to

local f = function () body end

(Это имеет значение только в том случае, если тело функции содержит ссылки на f .)

Определение функции — это исполняемое выражение, значение которого имеет тип function . Когда Lua прекомпилирует чанк, все его тела функций также прекомпилированы, но они еще не созданы. Затем, когда Lua выполняет определение функции, функция создается (или закрывается ). Этот экземпляр функции или закрытие является последним значением выражения.

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

parlist ::= namelist [‘,’ ‘...’] | ‘...’

Когда вызывается функция Lua, она корректирует свой список аргументов в соответствии с длиной своего списка параметров, если только функция не является функцией vararg , что обозначено тремя точками (‘ ... ‘) в конце ее списка параметров. . Функция vararg не изменяет свой список аргументов; вместо этого он собирает все дополнительные аргументы и передает их функции через выражение vararg, который также записывается в виде трех точек. Значение этого выражения представляет собой список всех фактических дополнительных аргументов, аналогичный функции с несколькими результатами. Если выражение vararg используется внутри другого выражения или в середине списка выражений, то его возвращаемый список корректируется до одного элемента. Если выражение используется как последний элемент списка выражений, корректировка не производится (если последнее выражение не заключено в круглые скобки).

В качестве примера рассмотрим следующие определения:

function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end

Далее,у нас есть следующее отображение от аргументов к параметрам и к выражению vararg:

CALL             PARAMETERS

f(3)             a=3, b=nil
f(3, 4)          a=3, b=4
f(3, 4, 5)       a=3, b=4
f(r(), 10)       a=1, b=10
f(r())           a=1, b=2

g(3)             a=3, b=nil, ... 
g(3, 4)          a=3, b=4,   ... 
g(3, 4, 5, 8)    a=3, b=4,   ... 
g(5, r())        a=5, b=1,   ... 

Результаты возвращаются с помощью оператора return (см. §3.3.4 ). Если управление достигает конца функции, не встречая оператора return , то функция возвращается без результатов.

Существует системно-зависимое ограничение на количество значений,которые может вернуть функция.Это ограничение гарантированно больше 1000.

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

function t.a.b.c:f (params) body end

синтаксический сахар для

t.a.b.c.f = function (self, params) body end

3.5-Правила видимости

Луа-это лексически скопированный язык.Область действия локальной переменной начинается с первого утверждения после ее объявления и продолжается до последнего неотвратимого утверждения самого внутреннего блока,который включает в себя объявление.Рассмотрим следующий пример:

x = 10                
do                    
  local x = x         
  print(x)            
  x = x+1
  do                  
    local x = x+1     
    print(x)          
  end
  print(x)            
end
print(x)              

Обратите внимание, что в таком объявлении, как local x = x , новый объявляемый x еще не входит в область видимости, и поэтому второй x относится к внешней переменной.

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

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

a = {}
local x = 20
for i = 1, 10 do
  local y = 0
  a[i] = function () y = y + 1; return x + y end
end

Цикл создает десять замыканий (то есть десять экземпляров анонимной функции). Каждое из этих замыканий использует различную переменную y , в то время как все они имеют один и тот же x .

4-Интерфейс прикладных программ

В этом разделе описывается C API для Lua, то есть набор функций C, доступных главной программе для связи с Lua. Все функции API и связанные с ними типы и константы объявлены в заголовочном файле lua.h .

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

Как и в большинстве библиотек C, функции Lua API не проверяют свои аргументы на достоверность или согласованность. Однако вы можете изменить это поведение, скомпилировав Lua с определенным макросом LUA_USE_APICHECK .

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

Каждое состояние Lua имеет один или несколько потоков, которые соответствуют независимым, кооперативным линиям выполнения. Тип lua_State (несмотря на название) относится к потоку. (Косвенно, через поток, это также относится к состоянию Lua, связанному с потоком.)

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

4.1-Стек

Lua использует виртуальный стек для передачи значений в и из C. Каждый элемент в этом стеке представляет значение Lua ( ноль , число, строка и т. Д.). Функции в API могут обращаться к этому стеку через параметр состояния Lua, который они получают.

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

Для удобства большинство операций запросов в API не подчиняются строгой дисциплине стека. Вместо этого они могут ссылаться на любой элемент в стеке с помощью индекса : положительный индекс представляет собой абсолютную позицию в стеке, начиная с 1 как нижней части стека; отрицательный индекс представляет собой смещение относительно вершины стека. Более конкретно, если в стеке n элементов, то индекс 1 представляет первый элемент (то есть элемент, который был помещен в стек первым), а индекс n представляет последний элемент; index -1 также представляет последний элемент (то есть элемент вверху), а index -n представляет первый элемент.

4.1.1-Размер стека

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

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

Когда вы вызываете функцию Lua без фиксированного количества результатов (см. lua_call ), Lua гарантирует, что в стеке достаточно места для всех результатов, но не гарантирует дополнительного места. Итак, прежде чем lua_checkstack что-либо в стек после такого вызова, вы должны использовать lua_checkstack .

4.1.2-Допустимые и приемлемые индексы

Любая функция в API, которая получает индексы стека, работает только с действительными индексами или допустимыми индексами .

Действительный индекс — это индекс, ссылающийся на позицию, в которой хранится изменяемое значение Lua. Он содержит индексы стека от 1 до вершины стека ( 1 ≤ abs(index) ≤ top ) плюс псевдоиндексы , которые представляют некоторые позиции, доступные коду C, но не находящиеся в стеке. Псевдоиндексы используются для доступа к реестру (см. §4.3 ) и значениям вверх функции C (см. §4.2 ).

Функции, которым не требуется конкретная изменяемая позиция, а только значение (например, функции запросов), могут вызываться с допустимыми индексами. Приемлемым индексом может быть любой допустимый индекс, но он также может быть любым положительным индексом после вершины стека в пределах пространства, выделенного для стека, то есть индексы до размера стека. (Обратите внимание, что 0 никогда не является приемлемым индексом.) Индексы повышающих значений (см. §4.2 ), превышающие реальное количество повышающих значений в текущей функции C, также допустимы (но недействительны). Если не указано иное, функции в API работают с допустимыми индексами.

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

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

4.1.3-Указатели на строки

Некоторые функции в API возвращают указатели ( const char* ) на строки Lua в стеке. (См. lua_pushfstring , lua_pushlstring , lua_pushstring и lua_tolstring . См. Также luaL_checklstring , luaL_checkstring и luaL_tolstring во вспомогательной библиотеке.)

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

Некоторые функции в интерфейсе отладки также возвращают указатели на строки, а именно lua_getlocal , lua_getupvalue , lua_setlocal и lua_setupvalue . Для этих функций указатель гарантированно действителен, пока вызывающая функция активна и данное закрытие (если оно было задано) находится в стеке.

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

4.2-Закрытия C

Когда создается функция C, с ней можно связать некоторые значения, создавая таким образом замыкание на C (см. lua_pushcclosure ); эти значения называются upvalues и доступны функции всякий раз, когда она вызывается.

Всякий раз, когда вызывается функция C, ее восходящие значения располагаются по определенным псевдоиндексам. Эти псевдоиндексы создаются макросом lua_upvalueindex . Первое повышающее значение, связанное с функцией, имеет индекс lua_upvalueindex(1) и так далее. Любой доступ к lua_upvalueindex(n) , где n больше, чем количество повышающих значений текущей функции (но не больше 256, что составляет единицу плюс максимальное количество повышающих значений в закрытии), создает приемлемый, но недопустимый индекс.

Замыкание C также может изменять значения соответствующих ему ап-значений.

4.3-Реестр

Lua предоставляет реестр , предопределенную таблицу, которая может использоваться любым кодом C для хранения любых значений Lua, которые ему необходимы. Таблица реестра всегда доступна по псевдоиндексу LUA_REGISTRYINDEX . Любая библиотека C может хранить данные в этой таблице, но она должна позаботиться о том, чтобы выбрать ключи, отличные от тех, которые используются другими библиотеками, чтобы избежать коллизий. Как правило, вы должны использовать в качестве ключа строку, содержащую имя вашей библиотеки, или легкие пользовательские данные с адресом объекта C в вашем коде, или любого объекта Lua, созданного вашим кодом. Как и в случае с именами переменных, строковые ключи, начинающиеся с подчеркивания, за которым следуют прописные буквы, зарезервированы для Lua.

Целочисленные ключи в реестре используются ссылочным механизмом (см. luaL_ref ) и некоторыми предопределенными значениями. Следовательно, целочисленные ключи в реестре нельзя использовать для других целей.

Когда вы создаете новое состояние Lua, его реестр поставляется с некоторыми предопределенными значениями. Эти предопределенные значения , индексируются с целыми ключами , определенных как константы в lua.h . Определены следующие константы:

• LUA_RIDX_MAINTHREAD : поэтому индексу в реестре есть главный поток состояния. (Основной поток создается вместе с состоянием.)
• LUA_RIDX_GLOBALS : вэтом индексе реестр имеет глобальную среду.

4.4-Обработка ошибок в C

Внутренне Lua использует средство C longjmp для обработки ошибок. (Lua будет использовать исключения, если вы скомпилируете его как C ++; LUAI_THROW ищите LUAI_THROW в исходном коде.) Когда Lua сталкивается с какой-либо ошибкой, такой как ошибка выделения памяти или ошибка типа, возникает ошибка; то есть делает прыжок в длину. В защищенной среде для установки точки восстановления используется setjmp ; при любой ошибке выполняется переход к самой последней активной точке восстановления.

Внутри функции C вы можете явно вызвать ошибку, вызвав lua_error .

Большинство функций в API могут вызвать ошибку,например,из-за ошибки выделения памяти.Документация по каждой функции указывает,может ли она вызвать ошибку.

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

Функция паники, как следует из ее названия, является механизмом последней инстанции. Программы должны избегать этого. Как правило, когда функция C вызывается Lua с состоянием Lua, она может делать все, что захочет, в этом состоянии Lua, поскольку она уже должна быть защищена. Однако, когда код C работает с другими состояниями Lua (например, аргументом Lua-состояния функции, состоянием Lua, хранящимся в реестре, или результатом lua_newthread ), он должен использовать их только в вызовах API, которые не могут вызывать ошибки.

Функция паники работает так, как если бы она была обработчиком сообщений (см. §2.3 ); в частности, объект ошибки находится на вершине стека. Однако нет никаких гарантий относительно пространства в стеке. Чтобы поместить что-либо в стек, функция panic должна сначала проверить доступное пространство (см. §4.1.1 ).

4.4.1-Коды состояния

Некоторые функции,сообщающие об ошибках в API,используют следующие коды состояния для обозначения различных видов ошибок или других условий:

• LUA_OK (0):ошибок нет.
• LUA_ERRRUN :ошибка времени выполнения.
• LUA_ERRMEM :ошибка выделения памяти. Для таких ошибок Lua не вызывает обработчик сообщений.
• LUA_ERRERR :ошибка при запуске обработчика сообщений.
• LUA_ERRSYNTAX :синтаксическая ошибка во время предварительной компиляции.
• LUA_YIELD :поток (сопрограмма) уступает.
• LUA_ERRFILE :ошибка, связанная с файлом; например, он не может открыть или прочитать файл.

Эти константы определены в файле заголовка lua.h .

4.5-Работа с доходностью в C

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

Чтобы избежать такого рода проблем, Lua выдает ошибку всякий раз, когда пытается выполнить уступку через вызов API, за исключением трех функций: lua_yieldk , lua_callk и lua_pcallk . Все эти функции получают функцию продолжения (как параметр с именем k ), чтобы продолжить выполнение после yield.

Нам нужно установить некоторую терминологию для объяснения продолжений. У нас есть функция C, вызываемая из Lua, которую мы будем вызывать исходной функцией . Затем эта исходная функция вызывает одну из этих трех функций в C API, которую мы будем называть вызываемой функцией , которая затем возвращает текущий поток. Это может произойти, когда вызываемая функция — это lua_yieldk , или когда вызываемая функция — это либо lua_callk , либо lua_pcallk , а функция, вызванная ими, дает результат.

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

В качестве иллюстрации рассмотрим следующую функцию:

int original_function (lua_State *L) {
  ...     
  status = lua_pcall(L, n, m, h);  
  ...     
}

Теперь мы хотим разрешить выполнение кода Lua с помощью lua_pcall . Во-первых, мы можем переписать нашу функцию, как здесь:

int k (lua_State *L, int status, lua_KContext ctx) {
  ...  
}

int original_function (lua_State *L) {
  ...     
  return k(L, lua_pcall(L, n, m, h), ctx);
}

В приведенном выше коде новая функция k является функцией продолжения (с типом lua_KFunction ), которая должна выполнять всю работу, которую выполняла исходная функция после вызова lua_pcall . Теперь мы должны сообщить Lua, что он должен вызвать k , если код Lua, выполняемый lua_pcall , каким-то образом прерывается (ошибки или уступка), поэтому мы переписываем код, как здесь, заменяя lua_pcall на lua_pcallk :

int original_function (lua_State *L) {
  ...     
  return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
}

Обратите внимание на внешний явный вызов продолжения: Lua вызовет продолжение только в случае необходимости, то есть в случае ошибок или возобновления после yield. Если вызываемая функция нормально возвращается без каких-либо изменений, lua_pcallk (и lua_callk ) также вернется нормально. (Конечно, вместо вызова продолжения в этом случае вы можете выполнить аналогичную работу непосредственно внутри исходной функции.)

Помимо состояния Lua, функция продолжения имеет два других параметра: окончательный статус вызова и значение контекста ( ctx ), которое изначально было передано lua_pcallk . Lua не использует это значение контекста; он передает это значение только из исходной функции в функцию продолжения. Для lua_pcallk статус — это то же значение, которое было бы возвращено lua_pcallk , за исключением того, что это LUA_YIELD при выполнении после yield (вместо LUA_OK ). Для lua_yieldk и lua_callk статус всегда LUA_YIELD когда Lua вызывает продолжение. (Для этих двух функций Lua не будет вызывать продолжение в случае ошибок, потому что они не обрабатывают ошибки.) Аналогично, при использовании lua_callk вы должны вызывать функцию продолжения с LUA_OK в качестве статуса. (Для lua_yieldk нет особого смысла в прямом вызове функции продолжения, потому что lua_yieldk обычно не возвращает.)

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

4.6 – Функции и типы[-o, +p, x ]

Здесь перечислены все функции и типы из C API в алфавитном порядке.У каждой функции есть такой индикатор:

Первое поле o — это количество элементов, извлекаемых функцией из стека. Второе поле, p , показывает, сколько элементов функция помещает в стек. (Любая функция всегда выталкивает свои результаты после извлечения своих аргументов.) Поле в форме x|y означает, что функция может выталкивать (или выталкивать) элементы x или y , в зависимости от ситуации; знак допроса » ? ‘означает, что мы не можем узнать, сколько элементов функция выталкивает / выталкивает, глядя только на ее аргументы. (Например, они могут зависеть от того, что находится в стеке.) Третье поле, x , сообщает, может ли функция вызывать ошибки: ‘ - ‘ означает, что функция никогда не вызывает никаких ошибок; ‘ m ‘означает, что функция может вызывать только ошибки нехватки памяти; ‘ v ‘ означает, что функция может вызывать ошибки, описанные в тексте; ‘ e ‘ означает, что функция может запускать произвольный код Lua напрямую или с помощью метаметодов и, следовательно, может вызывать любые ошибки.

lua_absindex[-0, +0, –]

int lua_absindex (lua_State *L, int idx);

Преобразует допустимый индекс idx в эквивалентный абсолютный индекс (то есть тот, который не зависит от вершины стека).

lua_Alloc

typedef void * (*lua_Alloc) (void *ud,
                             void *ptr,
                             size_t osize,
                             size_t nsize);

Тип функции распределения памяти, используемой Lua. Функция распределителя должна обеспечивать функциональность, аналогичную realloc , но не в точности такую ​​же. Его аргументы — ud , непрозрачный указатель, переданный lua_newstate ; ptr , указатель на блок, который выделяется / перераспределяется / освобождается; osize , исходный размер блока или некоторый код о том, что выделяется; и nsize — новый размер блока.

Когда ptr не равен NULL , osize — это размер блока, на который указывает ptr , то есть размер, заданный при его выделении или перераспределении.

Когда ptr равен NULL , osize кодирует тип объекта, который выделяет Lua. osize — это любое из LUA_TSTRING , LUA_TTABLE , LUA_TFUNCTION , LUA_TUSERDATA или LUA_TTHREAD , когда (и только когда) Lua создает новый объект этого типа. Когда osize — это какое-то другое значение, Lua выделяет память для чего-то еще.

Луа принимает следующее поведение от функции аллокатора:

Когда nsize равен нулю, распределитель должен вести себя как free а затем возвращать NULL .

Когда nsize не равен нулю, распределитель должен вести себя как realloc . В частности, распределитель возвращает NULL тогда и только тогда, когда он не может выполнить запрос.

Вот простая реализация функции распределителя. Он используется во вспомогательной библиотеке luaL_newstate .

static void *l_alloc (void *ud, void *ptr, size_t osize,
                                           size_t nsize) {
  (void)ud;  (void)osize;  
  if (nsize == 0) {
    free(ptr);
    return NULL;
  }
  else
    return realloc(ptr, nsize);
}

Обратите внимание, что Стандарт C гарантирует, что free(NULL) имеет никакого эффекта и что realloc(NULL,size) эквивалентен malloc(size) .

lua_arith[-(2|1), +1, e]

void lua_arith (lua_State *L, int op);

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

Значение op должно быть одной из следующих констант:

• LUA_OPADD :выполняет сложение ( + )
• LUA_OPSUB :выполняет вычитание ( - )
• LUA_OPMUL :выполняет умножение ( * )
• LUA_OPDIV :выполняет деление с плавающей запятой ( / )
• LUA_OPIDIV :выполняет разделение этажа ( // )
• LUA_OPMOD :выполняет по модулю ( % )
• LUA_OPPOW :возведение в степень ( ^ )
• LUA_OPUNM :выполняет математическое отрицание (унарный - )
• LUA_OPBNOT :побитовое НЕ ( ~ )
• LUA_OPBAND :выполняет побитовое И ( & )
• LUA_OPBOR :выполняет побитовое ИЛИ ( | )
• LUA_OPBXOR :выполняет побитовое исключающее ИЛИ ( ~ )
• LUA_OPSHL :выполняет сдвиг влево ( << )
• LUA_OPSHR :выполняет сдвиг вправо ( >> )

lua_atpanic[-0, +0, –]

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

Устанавливает новую функцию паники и возвращает старую (см. §4.4 ).

lua_call[-(nargs+1), +nresults, e]

void lua_call (lua_State *L, int nargs, int nresults);

Вызывает функцию. Как и обычные вызовы Lua, lua_call уважает __call . Итак, здесь слово «функция» означает любое вызываемое значение.

Чтобы выполнить вызов, вы должны использовать следующий протокол: сначала вызываемая функция помещается в стек; затем аргументы вызова передаются в прямом порядке; то есть первым передается первый аргумент. Наконец, вы вызываете lua_call ; nargs — это количество аргументов, которые вы поместили в стек. Когда функция возвращается, все аргументы и значение функции выталкиваются, а результаты вызова помещаются в стек. Количество результатов корректируется до nresults , если nresults не LUA_MULTRET . В этом случае все результаты функции передаются; Lua заботится о том, чтобы возвращаемые значения помещались в пространство стека, но не обеспечивает дополнительного места в стеке. Результаты функции помещаются в стек в прямом порядке (первый результат помещается первым), так что после вызова последний результат находится на вершине стека.

Любая ошибка при вызове и запуске функции распространяется вверх (с помощью longjmp ).

Следующий пример показывает,как хост-программа может делать эквивалент этого кода Lua:

a = f("how", t.x, 14)

Вот он в Си:

lua_getglobal(L, "f");                  
lua_pushliteral(L, "how");                       
lua_getglobal(L, "t");                    
lua_getfield(L, -1, "x");        
lua_remove(L, -2);                  
lua_pushinteger(L, 14);                          
lua_call(L, 3, 1);     
lua_setglobal(L, "a");                         

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

lua_callk[-(nargs + 1), +nresults, e]

void lua_callk (lua_State *L,
                int nargs,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

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

lua_CFunction

typedef int (*lua_CFunction) (lua_State *L);

Тип для функций С.

Чтобы правильно взаимодействовать с Lua, функция C должна использовать следующий протокол, который определяет способ передачи параметров и результатов: функция C получает свои аргументы из Lua в своем стеке в прямом порядке (первый аргумент помещается первым). Итак, когда функция запускается, lua_gettop(L) возвращает количество аргументов, полученных функцией. Первый аргумент (если есть) имеет индекс 1, а его последний аргумент — индекс lua_gettop(L) . Чтобы вернуть значения в Lua, функция C просто помещает их в стек в прямом порядке (первый результат помещается первым) и возвращает в C количество результатов. Любое другое значение в стеке под результатами будет правильно отброшено Lua. Как и функция Lua, функция C, вызываемая Lua, также может возвращать множество результатов.

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

static int foo (lua_State *L) {
  int n = lua_gettop(L);    
  lua_Number sum = 0.0;
  int i;
  for (i = 1; i <= n; i++) {
    if (!lua_isnumber(L, i)) {
      lua_pushliteral(L, "incorrect argument");
      lua_error(L);
    }
    sum += lua_tonumber(L, i);
  }
  lua_pushnumber(L, sum/n);        
  lua_pushnumber(L, sum);         
  return 2;                   
}

lua_checkstack[-0, +0, –]

int lua_checkstack (lua_State *L, int n);

Гарантирует, что в стеке есть место как минимум для n дополнительных элементов, то есть вы можете безопасно вставить в него до n значений. Он возвращает false, если он не может выполнить запрос, либо потому, что это приведет к тому, что стек будет больше фиксированного максимального размера (обычно, по крайней мере, несколько тысяч элементов), либо потому, что он не может выделить память для дополнительного пространства. Эта функция никогда не сжимает стек; если в стеке уже есть место для дополнительных элементов, он остается без изменений.

lua_close[-0, +0, –]

void lua_close (lua_State *L);

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

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

lua_compare[-0, +0, e]

int lua_compare (lua_State *L, int index1, int index2, int op);

Сравнивает два значения Lua. Возвращает 1, если значение в индексе index1 удовлетворяет op при сравнении со значением в индексе index2 , следуя семантике соответствующего оператора Lua (то есть он может вызывать метаметоды). В противном случае возвращает 0. Также возвращает 0, если какой-либо из индексов недействителен.

Значение op должно быть одной из следующих констант:

• LUA_OPEQ :сравнивает на равенство ( == )
• LUA_OPLT :сравнивает меньше чем ( < )
• LUA_OPLE :сравнивает меньше или равно ( <= )

lua_concat[-n, +1, e]

void lua_concat (lua_State *L, int n);

Объединяет n значений в верхней части стека, извлекает их и оставляет результат наверху. Если n равно 1, результатом является единственное значение в стеке (то есть функция ничего не делает); если n равно 0, результатом является пустая строка. Конкатенация выполняется в соответствии с обычной семантикой Lua (см. §3.4.6 ).

lua_copy[-0, +0, –]

void lua_copy (lua_State *L, int fromidx, int toidx);

Копирует элемент с индексом fromidx в действительный индекс toidx , заменяя значение в этой позиции. Значения на других позициях не затронуты.

lua_createtable[-0, +1, m]

void lua_createtable (lua_State *L, int narr, int nrec);

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

lua_dump[-0, +0, –]

int lua_dump (lua_State *L,
                        lua_Writer writer,
                        void *data,
                        int strip);

Выгружает функцию как двоичный фрагмент. Получает функцию Lua наверху стека и создает двоичный фрагмент, который при повторной загрузке приводит к функции, эквивалентной сброшенной. Как она производит части куска, lua_dump вызывает функцию writer (см lua_Writer ) с заданными data , чтобы записать их.

Если strip имеет значение true, двоичное представление может не включать всю отладочную информацию о функции для экономии места.

Возвращаемое значение-это код ошибки,возвращенный последним звонком писателю;0 означает отсутствие ошибок.

Эта функция не выводит функцию Lua из стека.

lua_error[-1, +0, v]

int lua_error (lua_State *L);

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

lua_gc[-0, +0, –]

int lua_gc (lua_State *L, int what, ...);

Управляет сборщиком мусора.

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

• LUA_GCCOLLECT : выполняет полный цикл сборки мусора.
• LUA_GCSTOP : останавливает сборщик мусора.
• LUA_GCRESTART : перезапускает сборщик мусора.
• LUA_GCCOUNT : возвращает текущий объем памяти (в килобайтах), используемый Lua.
• LUA_GCCOUNTB : возвращает остаток от деления текущего количества байтов памяти, используемой Lua, на 1024.

LUA_GCSTEP (int stepsize) : выполняет инкрементный шаг сборки мусора, соответствующий выделению stepsize килобайтах.

• LUA_GCISRUNNING : возвращает логическое значение, которое сообщает, работает ли сборщик (т. Е. Не остановлен).
• LUA_GCINC (int pause, int stepmul, stepsize): переводит сборщик в инкрементальный режим с заданными параметрами (см. §2.5.1 ). Возвращает предыдущий режим ( LUA_GCGEN или LUA_GCINC ).
• LUA_GCGEN (int minormul, int majormul): переводит сборщик в режим генерации с заданными параметрами (см. §2.5.2 ). Возвращает предыдущий режим ( LUA_GCGEN или LUA_GCINC ).

Дополнительные сведения об этих параметрах см . В разделе collectgarbage .

lua_getallocf[-0, +0, –]

lua_Alloc lua_getallocf (lua_State *L, void **ud);

Возвращает функцию выделения памяти для данного состояния. Если ud не NULL , Lua сохраняет в *ud непрозрачный указатель, заданный при установке функции распределения памяти.

lua_getfield[-0, +1, e]

int lua_getfield (lua_State *L, int index, const char *k);

Помещает в стек значение t[k] , где t — значение по данному индексу. Как и в Lua, эта функция может запускать метаметод для события «index» (см. §2.4 ).

Возвращает тип подтолкнутого значения.

void *lua_getextraspace (lua_State *L);

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

В каждом новом потоке эта область инициализируется копией области основного потока.

По умолчанию эта область имеет размер указателя на void, но вы можете перекомпилировать Lua с другим размером для этой области. (См. LUA_EXTRASPACE в luaconf.h .)

lua_getglobal[-0, +1, e]

int lua_getglobal (lua_State *L, const char *name);

Помещает в стек значение глобального name . Возвращает тип этого значения.

lua_geti[-0, +1, e]

int lua_geti (lua_State *L, int index, lua_Integer i);

Помещает в стек значение t[i] , где t — значение по данному индексу. Как и в Lua, эта функция может запускать метаметод для события «index» (см. §2.4 ).

Возвращает тип подтолкнутого значения.

lua_getmetatable[-0, +(0|1), –]

int lua_getmetatable (lua_State *L, int index);

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

lua_gettable[-1, +1, e]

int lua_gettable (lua_State *L, int index);

Помещает в стек значение t[k] , где t — значение по данному индексу, а k — значение на вершине стека.

Эта функция извлекает ключ из стека, помещая полученное значение на его место. Как и в Lua, эта функция может запускать метаметод для события «index» (см. §2.4 ).

Возвращает тип подтолкнутого значения.

lua_gettop[-0, +0, –]

int lua_gettop (lua_State *L);

Возвращает индекс верхнего элемента в стеке.Так как индексы начинаются с 1,то этот результат равен количеству элементов в стеке;в частности,0 означает пустой стек.

lua_getiuservalue[-0, +1, –]

int lua_getiuservalue (lua_State *L, int index, int n);

Помещает в стек n -е пользовательское значение, связанное с полными пользовательскими данными по заданному индексу, и возвращает тип помещенного значения.

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

lua_insert[-1, +1, –]

void lua_insert (lua_State *L, int index);

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

lua_Integer

typedef ... lua_Integer;

Тип целых чисел в Луа.

По умолчанию этот тип long long (обычно 64-битное целое число с двумя дополнениями), но его можно изменить на long или int (обычно 32-битное целое число с двумя дополнениями). (См. LUA_INT_TYPE в luaconf.h .)

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

lua_isboolean[-0, +0, –]

int lua_isboolean (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является булевым,и 0 в противном случае.

lua_iscfunction[-0, +0, –]

int lua_iscfunction (lua_State *L, int index);

Возвращает 1,если значение на данном индексе является функцией C,и 0 в противном случае.

lua_isfunction[-0, +0, –]

int lua_isfunction (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является функцией (либо C,либо Lua),и 0 в противном случае.

lua_isinteger[-0, +0, –]

int lua_isinteger (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является целым числом (то есть значение является числом и представлено в виде целого числа),и 0 в противном случае.

lua_islightuserdata[-0, +0, –]

int lua_islightuserdata (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является легким пользовательским,и 0 в противном случае.

lua_isnil[-0, +0, –]

int lua_isnil (lua_State *L, int index);

Возвращает 1, если значение данного индекса равно нулю , и 0 в противном случае.

lua_isnone[-0, +0, –]

int lua_isnone (lua_State *L, int index);

Возвращает 1,если данный индекс недействителен,и 0 в противном случае.

lua_isnoneornil[-0, +0, –]

int lua_isnoneornil (lua_State *L, int index);

Возвращает 1, если данный индекс недействителен или если значение этого индекса равно нулю , и 0 в противном случае.

lua_isnumber[-0, +0, –]

int lua_isnumber (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является числом или строкой,конвертируемой в число,и 0 в противном случае.

lua_isstring[-0, +0, –]

int lua_isstring (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является строкой или числом (которое всегда конвертируется в строку),и 0 в противном случае.

lua_istable[-0, +0, –]

int lua_istable (lua_State *L, int index);

Возвращает 1,если значение по данному индексу является табличным,и 0 в противном случае.

lua_isthread[-0, +0, –]

int lua_isthread (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является нитью,и 0 в противном случае.

lua_isuserdata[-0, +0, –]

int lua_isuserdata (lua_State *L, int index);

Возвращает 1,если значение в данном индексе является пользовательским (либо полным,либо светлым),и 0 в противном случае.

lua_isyieldable[-0, +0, –]

int lua_isyieldable (lua_State *L);

Возвращает 1,если данный корутин может давать,и 0 в противном случае.

lua_KContext

typedef ... lua_KContext;

Тип контекстов функции продолжения. Это должен быть числовой тип. Этот тип определяется как intptr_t , когда доступен intptr_t , поэтому он также может хранить указатели. В противном случае он определяется как ptrdiff_t .

lua_KFunction

typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);

Введите для функций продолжения (см. §4.5 ).

lua_len[-0, +1, e]

void lua_len (lua_State *L, int index);

Возвращает длину значения по заданному индексу. Он эквивалентен оператору ‘ # ‘ в Lua (см. §3.4.7 ) и может запускать метаметод для события «length» (см. §2.4 ). Результат помещается в стек.

lua_load[-0, +1, –]

int lua_load (lua_State *L,
              lua_Reader reader,
              void *data,
              const char *chunkname,
              const char *mode);

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

lua_load функция использует предоставленный пользователем для reader функцию , чтобы прочитать кусок (см lua_Reader ). data аргумент непрозрачное значение , переданное в функцию устройства считывания.

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

lua_load автоматически определяет, является ли фрагмент текстовым или двоичным, и загружает его соответственно (см. программу luac ). Строковый mode работает так же, как и функция load , с той лишь NULL значение NULL эквивалентно строке « bt ».

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

lua_load может возвращать LUA_OK , LUA_ERRSYNTAX или LUA_ERRMEM . Функция также может возвращать другие значения, соответствующие ошибкам, вызванным функцией чтения (см. §4.4.1 ).

Если результирующая функция имеет повышающие значения, ее первое повышающее значение устанавливается равным значению глобальной среды, хранящемуся в индексе LUA_RIDX_GLOBALS в реестре (см. §4.3 ). При загрузке основных фрагментов этим значением upvalue будет переменная _ENV (см. §2.2 ). Другие upvalue инициализируются nil .

lua_newstate[-0, +0, –]

lua_State *lua_newstate (lua_Alloc f, void *ud);

Создает новое независимое состояние и возвращает его основной поток. Возвращает NULL , если не может создать состояние (из-за нехватки памяти). Аргумент f — это функция распределения; Lua будет выделять всю память для этого состояния через эту функцию (см. lua_Alloc ). Второй аргумент ud — это непрозрачный указатель, который Lua передает распределителю при каждом вызове.

lua_newtable[-0, +1, m]

void lua_newtable (lua_State *L);

Создает новую пустую таблицу и помещает ее в стек. Это эквивалентно lua_createtable(L, 0, 0) .

lua_newthread[-0, +1, m]

lua_State *lua_newthread (lua_State *L);

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

Нити подлежат сборке мусора,как и любой объект Lua.

lua_newuserdatauv[-0, +1, m]

void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);

Эта функция создает и помещает в стек новые полные пользовательские данные со связанными с nuvalue значениями Lua, называемыми user values , плюс связанный блок необработанной памяти с size байтах. (Пользовательские значения могут быть установлены и прочитаны с помощью функций lua_setiuservalue и lua_getiuservalue .)

Функция возвращает адрес блока памяти. Lua гарантирует, что этот адрес действителен до тех пор, пока живы соответствующие пользовательские данные (см. §2.5 ). Более того, если пользовательские данные помечены для финализации (см. §2.5.3 ), их адрес действителен, по крайней мере, до вызова его финализатора.

lua_next[-1, +(2|0), v]

int lua_next (lua_State *L, int index);

Извлекает ключ из стека и выталкивает пару ключ-значение из таблицы по заданному индексу, «следующую» пару после данного ключа. Если в таблице больше нет элементов, то lua_next возвращает 0 и ничего не подталкивает.

Типичный обход таблицы выглядит следующим образом:

lua_pushnil(L);  
while (lua_next(L, t) != 0) {
  
  printf("%s - %sn",
         lua_typename(L, lua_type(L, -2)),
         lua_typename(L, lua_type(L, -1)));
  
  lua_pop(L, 1);
}

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

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

lua_Number

typedef ... lua_Number;

Тип поплавков в Луа.

По умолчанию это двойной тип, но его можно изменить на одинарное с плавающей запятой или длинное двойное. (См. LUA_FLOAT_TYPE в luaconf.h .)

lua_numbertointeger

int lua_numbertointeger (lua_Number n, lua_Integer *p);

Пытается преобразовать число с плавающей запятой Lua в целое число Lua; float n должен иметь целое значение. Если это значение находится в диапазоне целых чисел Lua, оно преобразуется в целое число и присваивается *p . Результатом макроса является логическое значение, указывающее, было ли преобразование успешным. (Обратите внимание, что этот тест диапазона может быть сложно выполнить правильно без этого макроса из-за округления.)

Данный макрос может оценивать свои аргументы не один раз.

lua_pcall[-(nargs + 1), +(nresults|1), –]

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

Вызывает функцию (или вызываемый объект)в защищенном режиме.

И nargs , и nresults имеют то же значение, что и lua_call . Если во время вызова ошибок нет, lua_pcall ведет себя точно так же, как lua_call . Однако, если есть какая-либо ошибка, lua_pcall перехватывает ее , помещает в стек единственное значение (объект ошибки) и возвращает код ошибки. Как и lua_call , lua_pcall всегда удаляет функцию и ее аргументы из стека.

Если msgh равно 0, то объект ошибки, возвращаемый в стеке, является в точности исходным объектом ошибки. В противном случае msgh — это индекс стека обработчика сообщений . (Этот индекс не может быть псевдо-индексом.) В случае ошибок времени выполнения этот обработчик будет вызываться с объектом ошибки, и его возвращаемое значение будет объектом, возвращенным в стеке lua_pcall .

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

Функция lua_pcall возвращает один из следующих кодов состояния: LUA_OK , LUA_ERRRUN , LUA_ERRMEM или LUA_ERRERR .

lua_pcallk[-(nargs + 1), +(nresults|1), –]

int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);

Эта функция ведет себя точно так же, как lua_pcall , за исключением того, что она позволяет вызываемой функции возвращаться (см. §4.5 ).

lua_pop[-n, +0, –]

void lua_pop (lua_State *L, int n);

Извлекает n элементов из стека.

lua_pushboolean[-0, +1, –]

void lua_pushboolean (lua_State *L, int b);

Помещает логическое значение со значением b в стек.

lua_pushcclosure[-n, +1, m]

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

Помещает новое замыкание C в стек. Эта функция получает указатель на функцию C и помещает в стек Lua-значение типа function , которое при вызове вызывает соответствующую функцию C. Параметр n сообщает, сколько значений up будет иметь эта функция (см. §4.2 ).

Любая функция, вызываемая Lua, должна следовать правильному протоколу, чтобы получать свои параметры и возвращать результаты (см. lua_CFunction ).

Когда C-функция создается, с ней можно связать некоторые значения, так называемые upvalues; эти повышающие значения затем доступны для функции всякий раз, когда она вызывается. Эта ассоциация называется C-замыканием (см. §4.2 ). Чтобы создать C-замыкание, сначала в стек должны быть помещены начальные значения его upvalue. (При наличии нескольких значений upvalue сначала помещается первое значение.) Затем вызывается lua_pushcclosure n , указывающим, сколько значений будет связано с функцией. lua_pushcclosure также извлекает эти значения из стека.

Максимальное значение n — 255.

Когда n равно нулю, эта функция создает легкую функцию C , которая является просто указателем на функцию C. В этом случае он никогда не вызывает ошибку памяти.

lua_pushcfunction[-0, +1, –]

void lua_pushcfunction (lua_State *L, lua_CFunction f);

Помещает функцию C в стек. Эта функция эквивалентна lua_pushcclosure без повышающих значений.

lua_pushfstring[-0, +1, v]

const char *lua_pushfstring (lua_State *L, const char *fmt, ...);

Помещает в стек отформатированную строку и возвращает указатель на эту строку (см. §4.1.3 ). Она похожа на функцию ISO C sprintf , но имеет два важных отличия. Во-первых, вам не нужно выделять место под результат; результатом является строка Lua, и Lua позаботится о выделении памяти (и освобождении памяти посредством сборки мусора). Во-вторых, спецификаторы преобразования весьма ограничены. Здесь нет флагов, ширины или точности. Спецификаторы преобразования могут быть только ‘ %% ‘ (вставляет символ ‘ % ‘), ‘ %s ‘ (вставляет заканчивающуюся нулем строку без ограничений по размеру), ‘ %f ‘ (вставляет lua_Number ), ‘ %I ‘ lua_Integer ), ‘ %p ‘ (вставляет указатель), ‘ %d ‘ (вставляет целое int ), ‘ %c ‘ (вставляет целое int как однобайтовый символ) и ‘ %U ‘ (вставляет long int как последовательность байтов UTF-8).

Эта функция может вызвать ошибки из-за переполнения памяти или неверного спецификатора преобразования.

lua_pushglobaltable[-0, +1, –]

void lua_pushglobaltable (lua_State *L);

Выталкивает глобальную окружающую среду в стек.

lua_pushinteger[-0, +1, –]

void lua_pushinteger (lua_State *L, lua_Integer n);

Помещает целое число со значением n в стек.

lua_pushlightuserdata[-0, +1, –]

void lua_pushlightuserdata (lua_State *L, void *p);

Выталкивает легкие пользовательские данные на стек.

Пользовательские данные представляют значения C в Lua. Свет UserData представляет собой указатель, а void* . Это значение (например, число): вы не создаете его, у него нет индивидуальной метатаблицы, и он не собирается (поскольку никогда не создавался). Легкие пользовательские данные равны «любым» легким пользовательским данным с тем же адресом C.

lua_pushliteral[-0, +1, m]

const char *lua_pushliteral (lua_State *L, const char *s);

Этот макрос эквивалентен lua_pushstring , но должен использоваться только тогда, когда s — это буквальная строка. (Lua может оптимизировать этот случай.)

lua_pushlstring[-0, +1, m]

const char *lua_pushlstring (lua_State *L, const char *s, size_t len);

Помещает строку, на которую указывает s , размером len в стек. Lua создаст или повторно использует внутреннюю копию данной строки, поэтому память в s может быть освобождена или повторно использована сразу после возврата из функции. Строка может содержать любые двоичные данные, включая встроенные нули.

Возвращает указатель на внутреннюю копию строки (см. §4.1.3 ).

lua_pushnil[-0, +1, –]

void lua_pushnil (lua_State *L);

Толкает нулевое значение в стек.

lua_pushnumber[-0, +1, –]

void lua_pushnumber (lua_State *L, lua_Number n);

Помещает в стек поплавок со значением n .

lua_pushstring[-0, +1, m]

const char *lua_pushstring (lua_State *L, const char *s);

Помещает строку с завершающим нулем, на которую указывает s , в стек. Lua создаст или повторно использует внутреннюю копию данной строки, поэтому память в s может быть освобождена или повторно использована сразу после возврата из функции.

Возвращает указатель на внутреннюю копию строки (см. §4.1.3 ).

Если s равно NULL , помещает nil и возвращает NULL .

lua_pushthread[-0, +1, –]

int lua_pushthread (lua_State *L);

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

lua_pushvalue[-0, +1, –]

void lua_pushvalue (lua_State *L, int index);

Выталкивает копию элемента в данном индексе на стек.

lua_pushvfstring[-0, +1, v]

const char *lua_pushvfstring (lua_State *L,
                              const char *fmt,
                              va_list argp);

Эквивалентен lua_pushfstring , за исключением того, что он получает va_list вместо переменного числа аргументов.

lua_rawequal[-0, +0, –]

int lua_rawequal (lua_State *L, int index1, int index2);

Возвращает 1 , если два значения индексов index1 и index2 примитивно равно (то есть равный без вызова __eq метаметода). В противном случае возвращает 0. Также возвращает 0, если какой-либо из индексов недействителен.

lua_rawget[-1, +1, –]

int lua_rawget (lua_State *L, int index);

Подобно lua_gettable , но имеет прямой доступ (т.е. без метаметодов).

lua_rawgeti[-0, +1, –]

int lua_rawgeti (lua_State *L, int index, lua_Integer n);

Помещает в стек значение t[n] , где t — таблица по данному индексу. Доступ является необработанным, то есть не использует __index __index.

Возвращает тип подтолкнутого значения.

lua_rawgetp[-0, +1, –]

int lua_rawgetp (lua_State *L, int index, const void *p);

Помещает в стек значение t[k] , где t — таблица с заданным индексом, а k — указатель p , представленный как легкие пользовательские данные. Доступ сырой; то есть он не использует __index __index.

Возвращает тип подтолкнутого значения.

lua_rawlen[-0, +0, –]

lua_Unsigned lua_rawlen (lua_State *L, int index);

Возвращает необработанную «длину» значения по заданному индексу: для строк это длина строки; для таблиц это результат использования оператора длины (‘ # ‘) без метаметодов; для пользовательских данных это размер блока памяти, выделенного для пользовательских данных. Для других значений этот вызов возвращает 0.

lua_rawset[-2, +0, m]

void lua_rawset (lua_State *L, int index);

Аналогично lua_settable , но выполняет необработанное присваивание (т.е. без метаметодов).

lua_rawseti[-1, +0, m]

void lua_rawseti (lua_State *L, int index, lua_Integer i);

Выполняет эквивалент t[i] = v , где t — таблица с заданным индексом, а v — значение на вершине стека.

Эта функция извлекает значение из стека. Присвоение является необработанным, то есть в нем не используется __newindex __newindex.

lua_rawsetp [-1, +0, м ]

void lua_rawsetp (lua_State *L, int index, const void *p);

Выполняет эквивалент t[p] = v , где t — это таблица с заданным индексом, p кодируется как легкие пользовательские данные, а v — значение на вершине стека.

Эта функция извлекает значение из стека. Присвоение является необработанным, то есть в нем не используется __newindex __newindex.

lua_Reader

typedef const char * (*lua_Reader) (lua_State *L,
                                    void *data,
                                    size_t *size);

Функция чтения, используемая lua_load . Каждый раз, когда lua_load требуется еще одна часть чанка, он вызывает читателя, передавая его параметр data . Считыватель должен вернуть указатель на блок памяти с новой частью фрагмента и установить size равным размеру блока. Блок должен существовать до тех пор, пока функция чтения не будет вызвана снова. Чтобы сигнализировать о конце фрагмента, считыватель должен вернуть NULL или установить size равным нулю. Функция чтения может возвращать фрагменты любого размера больше нуля.

lua_register[-0, +0, e]

void lua_register (lua_State *L, const char *name, lua_CFunction f);

Устанавливает C-функцию f как новое значение глобального name . Он определяется как макрос:

#define lua_register(L,n,f) 
       (lua_pushcfunction(L, f), lua_setglobal(L, n))

lua_remove[-1, +0, –]

void lua_remove (lua_State *L, int index);

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

lua_replace[-1, +0, –]

void lua_replace (lua_State *L, int index);

Перемещает верхний элемент в заданный действительный индекс,не смещая ни одного элемента (таким образом,заменяя значение в этом индексе),а затем всплывает верхний элемент.

lua_resetthread[-0, +?, –]

int lua_resetthread (lua_State *L);

Сбрасывает поток, очищая его стек вызовов и закрывая все ожидающие закрытия переменные. Возвращает код состояния: LUA_OK при отсутствии ошибок в методах закрытия или статус ошибки в противном случае. В случае ошибки оставляет объект ошибки наверху стека,

lua_resume[-?, +?, –]

int lua_resume (lua_State *L, lua_State *from, int nargs,
                          int *nresults);

Запуск и возобновляет сопрограмму в данной нити L .

Чтобы запустить сопрограмму, вы помещаете основную функцию и любые аргументы в пустой стек потока. затем вы вызываете lua_resume , где nargs — это количество аргументов. Этот вызов возвращается, когда сопрограмма приостанавливает или заканчивает свое выполнение. Когда он возвращается, *nresults обновляется, и вершина стека содержит значения *nresults , переданные в lua_yield или возвращенные функцией body. lua_resume возвращает LUA_YIELD , если сопрограмма уступает, LUA_OK , если сопрограмма завершает свое выполнение без ошибок, или код ошибки в случае ошибок (см. §4.4.1) .). В случае ошибок объект ошибки находится на вершине стека.

Чтобы возобновить сопрограмму, вы удаляете полученные значения *nresults из ее стека, отправляете значения, которые должны быть переданы как результаты из yield , а затем вызываете lua_resume .

Параметр from представляет собой сопрограмму , что возобновляет L . Если такой сопрограммы нет, этот параметр может иметь NULL .

lua_rotate[-0, +0, –]

void lua_rotate (lua_State *L, int idx, int n);

Поворачивает элементы стека между допустимым индексом idx и вершиной стека. Элементы поворачиваются на n позиций в направлении верха, для положительного n , или -n позиций в направлении низа, для отрицательного n . Абсолютное значение n не должно быть больше, чем размер вращаемого среза. Эта функция не может быть вызвана с псевдоиндексом, потому что псевдоиндекс не является фактической позицией в стеке.

lua_setallocf[-0, +0, –]

void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);

Изменяет функцию распределения заданного состояния на f с пользовательскими данными ud .

lua_setfield[-1, +0, e]

void lua_setfield (lua_State *L, int index, const char *k);

Эквивалентно t[k] = v , где t — значение по данному индексу, а v — значение на вершине стека.

Эта функция извлекает значение из стека. Как и в Lua, эта функция может запускать метаметод для события «newwindex» (см. §2.4 ).

lua_setglobal[-1, +0, e]

void lua_setglobal (lua_State *L, const char *name);

Извлекает значение из стека и устанавливает его как новое значение глобального name .

lua_seti[-1, +0, e]

void lua_seti (lua_State *L, int index, lua_Integer n);

Эквивалентно t[n] = v , где t — значение по данному индексу, а v — значение на вершине стека.

Эта функция извлекает значение из стека. Как и в Lua, эта функция может запускать метаметод для события «newwindex» (см. §2.4 ).

lua_setiuservalue[-1, +0, –]

int lua_setiuservalue (lua_State *L, int index, int n);

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

lua_setmetatable[-1, +0, –]

int lua_setmetatable (lua_State *L, int index);

Извлекает таблицу или nil из стека и устанавливает это значение в качестве новой метатаблицы для значения по данному индексу. ( nil означает отсутствие метатаблицы.)

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

lua_settable[-2, +0, e]

void lua_settable (lua_State *L, int index);

Эквивалентно t[k] = v , где t — значение по данному индексу, v — значение наверху стека, а k — значение чуть ниже вершины.

Эта функция извлекает из стека и ключ, и значение. Как и в Lua, эта функция может запускать метаметод для события «newwindex» (см. §2.4 ).

lua_settop[-?, +?, –]

void lua_settop (lua_State *L, int index);

Принимает любой индекс или 0 и устанавливает вершину стека на этот индекс. Если новая вершина больше старой, то новые элементы заполняются нулем . Если index равен 0, то удаляются все элементы стека.

lua_setwarnf[-0, +0, –]

void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);

Устанавливает функцию предупреждения, которая будет использоваться Lua для lua_WarnFunction предупреждений (см. Lua_WarnFunction ). Параметр ud устанавливает значение ud , передаваемое функции предупреждения.

lua_State

typedef struct lua_State lua_State;

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

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

lua_status[-0, +0, –]

int lua_status (lua_State *L);

Возвращает состояние нити L .

Статус может быть LUA_OK для нормального потока, кодом ошибки, если поток завершил выполнение lua_resume с ошибкой, или LUA_YIELD , если поток приостановлен.

Вы можете вызывать функции только в потоках со статусом LUA_OK . Вы можете возобновить потоки со статусом LUA_OK (для запуска новой сопрограммы) или LUA_YIELD (для возобновления сопрограммы).

lua_stringtonumber[-0, +1, –]

size_t lua_stringtonumber (lua_State *L, const char *s);

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

lua_toboolean[-0, +0, –]

int lua_toboolean (lua_State *L, int index);

Преобразует значение Lua по заданному индексу в логическое значение C (0 или 1). Как и все тесты в Lua, lua_toboolean возвращает true для любого значения Lua, отличного от false и nil ; в противном случае возвращается false. (Если вы хотите принимать только фактические логические значения, используйте lua_isboolean для проверки типа значения.)

lua_tocfunction[-0, +0, –]

lua_CFunction lua_tocfunction (lua_State *L, int index);

Преобразует значение по заданному индексу в функцию C. Это значение должно быть функцией C; в противном случае возвращает NULL .

lua_toclose[-0, +0, m]

void lua_toclose (lua_State *L, int index);

Отмечает данный индекс в стеке как подлежащую закрытию «переменную» (см. §3.3.8 ). Подобно переменной, подлежащей закрытию в Lua, значение по этому индексу в стеке будет закрыто, когда оно выйдет за пределы области видимости. Здесь, в контексте функции C, выход за пределы области видимости означает, что работающая функция возвращается в Lua, возникает ошибка или индекс удаляется из стека через lua_settop или lua_pop . Индекс, помеченный как подлежащий закрытию, не должен удаляться из стека какой-либо другой функцией API, кроме lua_settop или lua_pop .

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

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

Обратите внимание, что как в случае ошибок, так и при обычном возврате, к моменту __close стек C уже был развернут, так что любая автоматическая переменная C, объявленная в вызывающей функции, будет вне области видимости.

lua_tointeger[-0, +0, –]

lua_Integer lua_tointeger (lua_State *L, int index);

Эквивалентно lua_tointegerx с isnum равным NULL .

lua_tointegerx[-0, +0, –]

lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);

Преобразует значение Lua по заданному индексу в целочисленный тип со знаком lua_Integer . Значение Lua должно быть целым числом, либо числом, либо строкой, преобразуемой в целое число (см. §3.4.3 ); в противном случае lua_tointegerx возвращает 0.

Если isnum не NULL , его референту присваивается логическое значение, указывающее, успешно ли выполнена операция.

lua_tolstring[-0, +0, m]

const char *lua_tolstring (lua_State *L, int index, size_t *len);

Преобразует значение Lua по заданному индексу в строку C. Если len не NULL , он устанавливает *len с длиной строки. Значение Lua должно быть строкой или числом; в противном случае функция возвращает NULL . Если значение является числом, то lua_tolstring также изменяет фактическое значение в стеке на строку . (Это изменение сбивает с толку lua_next , когда lua_tolstring применяется к ключам во время обхода таблицы.)

lua_tolstring возвращает указатель на строку внутри состояния Lua (см. §4.1.3 ). Эта строка всегда имеет ноль (‘ ‘) после последнего символа (как в C), но может содержать и другие нули в своем теле.

lua_tonumber[-0, +0, –]

lua_Number lua_tonumber (lua_State *L, int index);

Эквивалентен lua_tonumberx с isnum равным NULL .

lua_tonumberx[-0, +0, –]

lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);

Преобразует значение Lua по заданному индексу в тип C lua_Number (см. lua_Number ). Значение Lua должно быть числом или строкой, преобразуемой в число (см. §3.4.3 ); в противном случае lua_tonumberx возвращает 0.

Если isnum не NULL , его референту присваивается логическое значение, указывающее, успешно ли выполнена операция.

lua_topointer[-0, +0, –]

const void *lua_topointer (lua_State *L, int index);

Преобразует значение по заданному индексу в общий указатель C ( void* ). Значение может быть пользовательскими данными, таблицей, потоком, строкой или функцией; в противном случае lua_topointer возвращает NULL . Разные объекты будут давать разные указатели. Невозможно преобразовать указатель обратно в исходное значение.

Обычно эта функция используется только для хэширования и отладки информации.

lua_tostring[-0, +0, m]

const char *lua_tostring (lua_State *L, int index);

Эквивалентен lua_tolstring с len , равным NULL .

lua_tothread[-0, +0, –]

lua_State *lua_tothread (lua_State *L, int index);

Преобразует значение по заданному индексу в поток Lua (представленный как lua_State* ). Это значение должно быть потоком; в противном случае функция возвращает NULL .

lua_touserdata[-0, +0, –]

void *lua_touserdata (lua_State *L, int index);

Если значение в данном индексе является полными пользовательскими данными, возвращает его адрес блока памяти. Если значение — легкие пользовательские данные, возвращает его значение (указатель). В противном случае возвращает NULL .

lua_type[-0, +0, –]

int lua_type (lua_State *L, int index);

Возвращает тип значения в данном допустимом индексе или LUA_TNONE для недопустимого, но приемлемого индекса. Типы, возвращаемые lua_type , кодируются следующими константами, определенными в lua.h : LUA_TNIL , LUA_TNUMBER , LUA_TBOOLEAN , LUA_TSTRING , LUA_TTABLE , LUA_TFUNCTION , LUA_TUSERDATA , LUA_TTHREAD и LUA_TLIGHTUSERDATA .

lua_typename[-0, +0, –]

const char *lua_typename (lua_State *L, int tp);

Возвращает имя типа, закодированного значением tp , которое должно быть одним из значений, возвращаемых lua_type .

lua_Unsigned

typedef ... lua_Unsigned;

Беззнаковая версия lua_Integer .

lua_upvalueindex[-0, +0, –]

int lua_upvalueindex (int i);

Возвращает псевдоиндекс, представляющий i -е значение повышения текущей функции (см. §4.2 ). i должен быть в диапазоне [1,256] .

lua_version[-0, +0, –]

lua_Number lua_version (lua_State *L);

Возвращает номер версии данного ядра.

lua_WarnFunction

typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);

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

См. warn для получения дополнительных сведений о предупреждениях.

lua_warning[-0, +0, –]

void lua_warning (lua_State *L, const char *msg, int tocont);

Выдает предупреждение с данным сообщением. Сообщение в вызове с tocont true должно быть продолжено в другом вызове этой функции.

См. warn для получения дополнительных сведений о предупреждениях.

lua_Writer

typedef int (*lua_Writer) (lua_State *L,
                           const void* p,
                           size_t sz,
                           void* ud);

Тип функции записи, используемой lua_dump . Каждый раз, когда lua_dump создает новый фрагмент, он вызывает модуль записи , передавая буфер для записи ( p ), его размер ( sz ) и параметр ud , передаваемый в lua_dump .

Писатель возвращает код ошибки: 0 означает отсутствие ошибок; любое другое значение означает ошибку и не позволяет lua_dump снова вызывать писателя.

lua_xmove[-?, +?, –]

void lua_xmove (lua_State *from, lua_State *to, int n);

Обмен значениями между различными потоками одного и того же состояния.

Эта функция выскакивает n значений из стека from , и помещает их в стек to .

lua_yield[-?, +?, v]

int lua_yield (lua_State *L, int nresults);

Эта функция эквивалентна lua_yieldk , но не имеет продолжения (см. §4.5 ). Поэтому, когда поток возобновляется, он продолжает функцию, вызвавшую функцию, вызвавшую lua_yield . Чтобы избежать неожиданностей, эту функцию следует вызывать только в хвостовом вызове.

lua_yieldk[-?, +?, v]

int lua_yieldk (lua_State *L,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

Дает корутин (нить).

Когда функция C вызывает lua_yieldk , работающая сопрограмма приостанавливает свое выполнение, и возвращается вызов lua_resume , запустивший эту сопрограмму. Параметр nresults — это количество значений из стека, которые будут переданы в качестве результатов в lua_resume .

Когда сопрограмма снова возобновляется, Lua вызывает заданную функцию продолжения k , чтобы продолжить выполнение функции C, которая завершилась (см. §4.5 ). Эта функция-продолжение получает тот же стек, что и предыдущая функция, с удалением n результатов и их заменой аргументами, переданными в lua_resume . Более того, функция продолжения получает значение ctx , которое было передано в lua_yieldk .

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

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

4.7-Интерфейс отладки

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

lua_Debug

typedef struct lua_Debug {
  int event;
  const char *name;           
  const char *namewhat;       
  const char *what;           
  const char *source;         
  size_t srclen;              
  int currentline;            
  int linedefined;            
  int lastlinedefined;        
  unsigned char nups;         
  unsigned char nparams;      
  char isvararg;              
  char istailcall;            
  unsigned short ftransfer;   
  unsigned short ntransfer;   
  char short_src[LUA_IDSIZE]; 
  
  other fields
} lua_Debug;

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

Поля lua_Debug имеют следующее значение:

• source : источник фрагмента, создавшего функцию. Если source начинается с « @ », это означает, что функция была определена в файле, имя которого следует за « @ ». Если source начинается с ‘ = ‘, остальная часть его содержимого описывает источник в зависимости от пользователя. В противном случае функция была определена в строке, где source является эта строка.
• srclen : длина source строки .
• short_src : » печатная » версия source , которая будет использоваться в сообщениях об ошибках.
• linedefined : номер строки, с которой начинается определение функции.
• lastlinedefined : номер строки, на которой заканчивается определение функции.
• what : строка "Lua" если функция является функцией Lua, "C" если это функция C, "main" если это основная часть чанка.
• currentline : текущая строка, в которой выполняется данная функция. Если информация о строке недоступна, для currentline устанавливается значение -1.
• name : разумное имя для данной функции. Поскольку функции в Lua являются первоклассными значениями, они не имеют фиксированного имени: некоторые функции могут быть значениями нескольких глобальных переменных, а другие могут храниться только в поле таблицы. Функция lua_getinfo проверяет, как функция была вызвана, чтобы найти подходящее имя. Если не может найти имя, тогда name устанавливается в NULL .
• namewhat : объясняет поле name . Значение namewhat может быть "global" , "local" , "method" , "field" , "upvalue" или "" (пустая строка), в зависимости от того, как была вызвана функция. (Lua использует пустую строку, когда кажется, что другой вариант не подходит.)
• istailcall : true, если этот вызов функции был вызван хвостовым вызовом. В этом случае вызывающего этого уровня нет в стеке.
• nups : количество повышающих значений функции.
• nparams : количество параметров функции (всегда 0 для функций C).
• isvararg : true, если функция является функцией vararg (всегда верно для функций C).
• ftransfer : индекс в стеке первого «переданного» значения, то есть параметров в вызове или возвращаемых значений в возврате. (Остальные значения находятся в последовательных индексах.) Используя этот индекс, вы можете получить доступ и изменить эти значения через lua_getlocal и lua_setlocal . Это поле имеет смысл только во время ловушки вызова, обозначающей первый параметр, или ловушки возврата, обозначающей первое возвращаемое значение. (Для обработчиков вызовов это значение всегда равно 1.)
• ntransfer : количество передаваемых значений (см. предыдущий пункт). (Для вызовов функций Lua это значение всегда равно nparams .)

lua_gethook[-0, +0, –]

lua_Hook lua_gethook (lua_State *L);

Возвращает текущую функцию крючка.

lua_gethookcount[-0, +0, –]

int lua_gethookcount (lua_State *L);

Возвращает текущее количество крючков.

lua_gethookmask[-0, +0, –]

int lua_gethookmask (lua_State *L);

Возвращает текущую маску крючка.

lua_getinfo[-(0|1), +(0|1|2), m]

int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);

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

Чтобы получить информацию о вызове функции, параметр ar должен быть допустимой записью активации, которая была заполнена предыдущим вызовом lua_getstack или передана в качестве аргумента lua_Hook (см. Lua_Hook ).

Чтобы получить информацию о функции, вы помещаете ее в стек и начинаете строку what с символа ‘ > ‘. (В этом случае lua_getinfo выталкивает функцию из вершины стека.) Например, чтобы узнать, в какой строке была определена функция f , вы можете написать следующий код:

lua_Debug ar;
lua_getglobal(L, "f");  
lua_getinfo(L, ">S", &ar);
printf("%dn", ar.linedefined);

Каждый символ в строке , what выбирает некоторые поля структуры ar должны быть заполнены или значение , которое будет в стек:

• ‘ n ‘: заполняет name поля и namewhat ;
• ‘ S ‘: заполняет поля source , short_src , linedefined , lastlinedefined , и what ;
• ‘ l ‘: заполняет поле currentline ;
• ‘ t ‘: заполняет поле istailcall ;
• ‘ u ‘: заполняет поля nups , nparams и isvararg ;
• ‘ f ‘: помещает в стек функцию, которая выполняется на данном уровне;
• ‘ L ‘: помещает в стек таблицу, индексы которой являются номерами строк, допустимых для функции. ( Допустимая строка — это строка с некоторым связанным кодом, то есть строка, в которой вы можете поставить точку останова. Недействительные строки включают пустые строки и комментарии.)

  Если этот параметр указан вместе с параметром « f », его таблица помещается после функции.

  Это единственный вариант,который может вызвать ошибку памяти.

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

lua_getlocal[-0, +(0|1), –]

const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);

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

В первом случае параметр ar должен быть допустимой записью активации, которая была заполнена предыдущим вызовом lua_getstack или передана в качестве аргумента ловушки (см. lua_Hook ). Индекс n выбирает, какую локальную переменную проверять; см. debug.getlocal для получения подробной информации об индексах и именах переменных.

lua_getlocal помещает значение переменной в стек и возвращает ее имя.

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

Возвращает NULL (и ничего не отправляет), если индекс больше, чем количество активных локальных переменных.

lua_getstack[-0, +0, –]

int lua_getstack (lua_State *L, int level, lua_Debug *ar);

Получает информацию о стеке времени выполнения интерпретатора.

Эта функция заполняет части структуры lua_Debug идентификатором записи активации функции, выполняющейся на заданном уровне. Уровень 0 — это текущая запущенная функция, тогда как уровень n + 1 — это функция, которая вызвала уровень n (за исключением хвостовых вызовов, которые не учитываются в стеке). При вызове с уровнем, превышающим глубину стека, lua_getstack возвращает 0; в противном случае возвращается 1.

lua_getupvalue[-0, +(0|1), –]

const char *lua_getupvalue (lua_State *L, int funcindex, int n);

Получает информацию о n -м повышающем значении закрытия по индексу funcindex . Он помещает значение upvalue в стек и возвращает его имя. Возвращает NULL (и ничего не выталкивает), когда индекс n больше, чем количество повышающих значений.

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

lua_Hook

typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);

Тип для отладки функций крюка.

Всякий раз, когда вызывается ловушка, ее аргумент ar имеет свое event поля, установленное на конкретное событие, которое инициировало ловушку. Lua идентифицирует эти события с помощью следующих констант: LUA_HOOKCALL , LUA_HOOKRET , LUA_HOOKTAILCALL , LUA_HOOKLINE и LUA_HOOKCOUNT . Более того, для линейных событий также устанавливается поле currentline . Чтобы получить значение любого другого поля в ar , ловушка должна вызвать lua_getinfo .

Для событий вызова event может быть LUA_HOOKCALL , нормальным значением, или LUA_HOOKTAILCALL , для хвостового вызова; в этом случае не будет соответствующего события возврата.

Пока Луа работает с крючком,он отключает другие звонки на крючки.Таким образом,если крюк вызывает Lua для выполнения функции или фрагмента,это выполнение происходит без обращения к крюкам.

Функции- lua_yieldk не могут иметь продолжения, то есть они не могут вызывать lua_yieldk , lua_pcallk или lua_callk с ненулевым k .

Функции перехвата могут давать результат при следующих условиях: Только события count и line могут давать результат; чтобы уступить, функция-перехватчик должна завершить свое выполнение, вызвав lua_yield с nresults , равными нулю (то есть без значений).

lua_setcstacklimit[-0, +0, –]

int (lua_setcstacklimit) (lua_State *L, unsigned int limit);

Устанавливает новый предел для стека C. Этот предел контролирует, насколько глубоко вложенные вызовы могут быть в Lua, с целью избежать переполнения стека. Возвращает старый предел в случае успеха или ноль в случае ошибки. Для получения дополнительных сведений об этой функции см. debug.setcstacklimit , его эквивалент в стандартной библиотеке.

lua_sethook[-0, +0, –]

void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);

Устанавливает функцию отладочного крюка.

Аргумент f — это функция перехвата. mask определяет, для каких событий будет вызвана ловушка: она формируется побитовым ИЛИ констант LUA_MASKCALL , LUA_MASKRET , LUA_MASKLINE и LUA_MASKCOUNT . count аргументов имеет смысл только , когда маска включает в себя LUA_MASKCOUNT . Для каждого события хук вызывается, как описано ниже:

• Ловушка вызова: вызывается, когда интерпретатор вызывает функцию. Хук вызывается сразу после того, как Lua входит в новую функцию.
• Ловушка возврата: вызывается, когда интерпретатор возвращается из функции. Хук вызывается непосредственно перед выходом Lua из функции.
• Перехватчик строки: вызывается, когда интерпретатор собирается начать выполнение новой строки кода или когда он возвращается в код (даже на ту же строку). Это событие происходит только тогда, когда Lua выполняет функцию Lua.
• Ловушка счетчика: вызывается после того, как интерпретатор выполняет все инструкции count . Это событие происходит только тогда, когда Lua выполняет функцию Lua.

Хуки отключаются установкой mask на ноль.

lua_setlocal[-(0|1), +0, –]

const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);

Устанавливает значение локальной переменной данной записи активации.Она присваивает переменной значение на вершине стека и возвращает ее имя.Она также извлекает значение из стека.

Возвращает NULL (и ничего не выдает), если индекс больше, чем количество активных локальных переменных.

Параметры ar и n такие же, как в функции lua_getlocal .

lua_setupvalue[-(0|1), +0, –]

const char *lua_setupvalue (lua_State *L, int funcindex, int n);

Устанавливает значение верхнего значения закрытия.Он присваивает значение на вершине стека значению upvalue и возвращает его имя.Она также извлекает значение из стека.

Возвращает NULL (и ничего не выдает ), если индекс n больше, чем количество повышающих значений.

Параметры funcindex и n такие же, как в функции lua_getupvalue .

lua_upvalueid[-0, +0, –]

void *lua_upvalueid (lua_State *L, int funcindex, int n);

Возвращает уникальный идентификатор для повышенного значения с номером n из закрытия по индексу funcindex .

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

Параметры funcindex и n такие же, как в функции lua_getupvalue , но n не может быть больше, чем количество повышающих значений.

lua_upvaluejoin[-0, +0, –]

void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
                                    int funcindex2, int n2);

Сделайте n1 -е восходящее значение закрытия Lua по индексу funcindex1 ссылкой на n2 -е восходящее значение закрытия Lua по индексу funcindex2 .

5-Вспомогательная библиотека

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

Все функции и типы из вспомогательной библиотеки определены в заголовочном файле lauxlib.h и имеют префикс luaL_ .

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

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

Несколько функций из вспомогательной библиотеки используются для проверки аргументов функции C. Поскольку сообщение об ошибке отформатировано для аргументов (например, « bad argument #1 »), вы не должны использовать эти функции для других значений стека.

Функции luaL_check* всегда вызывают ошибку, если проверка не выполняется.

5.1-Функции и типы

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

luaL_addchar[-?, +?, m]

void luaL_addchar (luaL_Buffer *B, char c);

Добавляет байт c в буфер B (см. luaL_Buffer ).

luaL_addgsub[-0, +0, m]

const void luaL_addgsub (luaL_Buffer *B, const char *s,
                         const char *p, const char *r);

Добавляет копию строки s в буфер B (см. luaL_Buffer ), заменяя любое вхождение строки p строкой r .

luaL_addlstring[-?, +?, m]

void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);

Добавляет строку, luaL_Buffer s , длиной l в буфер B (см. LuaL_Buffer ). Строка может содержать встроенные нули.

luaL_addsize[-?, +?, –]

void luaL_addsize (luaL_Buffer *B, size_t n);

Добавляет в буфер B строку длины n , ранее скопированную в буферную область (см. luaL_prepbuffer ).

luaL_addstring[-?, +?, m]

void luaL_addstring (luaL_Buffer *B, const char *s);

Добавляет строку с завершающим нулем, на которую указывает s , в буфер B (см. luaL_Buffer ).

luaL_addvalue[-1, +?, m]

void luaL_addvalue (luaL_Buffer *B);

Добавляет значение наверху стека в буфер B (см. luaL_Buffer ). Выдвигает значение.

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

luaL_argcheck[-0, +0, v]

void luaL_argcheck (lua_State *L,
                    int cond,
                    int arg,
                    const char *extramsg);

Проверяет, истинно ли cond . Если это не так, luaL_argerror ошибку стандартным сообщением (см. LuaL_argerror ).

luaL_argerror[-0, +0, v]

int luaL_argerror (lua_State *L, int arg, const char *extramsg);

Вызывает ошибку, сообщающую о проблеме с аргументом arg extramsg его функции C, используя стандартное сообщение, которое включает extramsg в качестве комментария:

bad argument #arg to 'funcname' (extramsg)

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

luaL_argexpected[-0, +0, v]

void luaL_argexpected (lua_State *L,
                       int cond,
                       int arg,
                       const char *tname);

Проверяет, истинно ли cond . Если это не так, выдает ошибку о типе аргумента arg со стандартным сообщением (см. luaL_typeerror ).

luaL_Buffer

typedef struct luaL_Buffer luaL_Buffer;

Тип строкового буфера .

Строковый буфер позволяет C-коду строить строки Lua по частям.Схема его использования выглядит следующим образом:

• Сначала объявите переменную b типа luaL_Buffer .
• Затем инициализируйте его вызовом luaL_buffinit(L, &b) .
• Затем добавьте в буфер кусочки строки, вызывая любую из функций luaL_add* .
• Завершите, вызвав luaL_pushresult(&b) . Этот вызов оставляет последнюю строку наверху стека.

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

• Сначала объявите переменную b типа luaL_Buffer .
• Затем инициализируйте его и предварительно выделите пространство размером sz с помощью вызова luaL_buffinitsize(L, &b, sz) .
• Затем вставьте струну в это пространство.
• Завершите вызовом luaL_pushresultsize(&b, sz) , где sz — это общий размер результирующей строки, скопированной в это пространство (которая может быть меньше или равна предварительно выделенному размеру).

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

luaL_buffaddr[-0, +0, –]

char *luaL_buffaddr (luaL_Buffer *B);

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

luaL_buffinit[-0, +0, –]

void luaL_buffinit (lua_State *L, luaL_Buffer *B);

Инициализирует буфер B (см. luaL_Buffer ). Эта функция не выделяет места; буфер должен быть объявлен как переменная.

luaL_bufflen[-0, +0, –]

size_t luaL_bufflen (luaL_Buffer *B);

Возвращает длину текущего содержимого буфера B (см. luaL_Buffer ).

luaL_buffinitsize[-?, +?, m]

char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);

Эквивалент последовательности luaL_buffinit , luaL_prepbuffsize .

luaL_buffsub[-0, +0, –]

void luaL_buffsub (luaL_Buffer *B, int n);

Удаляет n байтов из буфера B (см. luaL_Buffer ). В буфере должно быть не менее этого количества байтов.

luaL_callmeta[-0, +(0|1), e]

int luaL_callmeta (lua_State *L, int obj, const char *e);

Это называется метаметод.

Если объект с индексом obj имеет метатаблицу, а эта метатаблица имеет поле e , эта функция вызывает это поле, передавая объект в качестве единственного аргумента. В этом случае эта функция возвращает истину и помещает в стек значение, возвращаемое вызовом. Если нет метатаблицы или метаметода, эта функция возвращает false, не помещая какое-либо значение в стек.

luaL_checkany[-0, +0, v]

void luaL_checkany (lua_State *L, int arg);

Проверяет, имеет ли функция аргумент любого типа (включая nil ) в позиции arg .

luaL_checkinteger[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int arg);

Проверяет, является ли аргумент функции arg целым числом (или может быть преобразовано в целое число) и возвращает это целое число.

luaL_checklstring[-0, +0, v]

const char *luaL_checklstring (lua_State *L, int arg, size_t *l);

Проверяет, является ли аргумент функции arg строкой и возвращает эту строку; если l не NULL заполняет референт длиной строки.

Эта функция использует lua_tolstring для получения результата, поэтому здесь применяются все преобразования и предупреждения этой функции.

luaL_checknumber[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int arg);

Проверяет, является ли аргумент функции arg числом, и возвращает это число, преобразованное в lua_Number .

luaL_checkoption[-0, +0, v]

int luaL_checkoption (lua_State *L,
                      int arg,
                      const char *def,
                      const char *const lst[]);

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

Если def не равен NULL , функция использует def как значение по умолчанию, когда нет аргумента arg или когда этот аргумент равен nil .

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

luaL_checkstack[-0, +0, v]

void luaL_checkstack (lua_State *L, int sz, const char *msg);

Увеличивает размер стека до элементов top + sz , вызывая ошибку, если стек не может вырасти до этого размера. msg — это дополнительный текст для сообщения об ошибке (или NULL ,если дополнительный текст не используется).

luaL_checkstring[-0, +0, v]

const char *luaL_checkstring (lua_State *L, int arg);

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

Эта функция использует lua_tolstring для получения результата, поэтому здесь применяются все преобразования и предупреждения этой функции.

luaL_checktype[-0, +0, v]

void luaL_checktype (lua_State *L, int arg, int t);

Проверяет, имеет ли аргумент функции arg тип t . См. lua_type для кодировки типов для t .

luaL_checkudata[-0, +0, v]

void *luaL_checkudata (lua_State *L, int arg, const char *tname);

Проверяет, является ли аргумент функции arg пользовательскими данными типа tname (см. luaL_newmetatable ) и возвращает адрес блока памяти пользовательских данных (см. lua_touserdata ).

luaL_checkversion[-0, +0, v]

void luaL_checkversion (lua_State *L);

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

luaL_dofile[-0, +?, m]

int luaL_dofile (lua_State *L, const char *filename);

Загружает и запускает данный файл.Он определяется как следующий макрос:

(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))

Он возвращает LUA_OK , если ошибок нет, или код ошибки в случае ошибок (см. §4.4.1 ).

luaL_dostring[-0, +?, –]

int luaL_dostring (lua_State *L, const char *str);

Загружает и запускает данную строку.Определяется как следующий макрос:

(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))

Он возвращает LUA_OK , если ошибок нет, или код ошибки в случае ошибок (см. §4.4.1 ).

luaL_error[-0, +0, v]

int luaL_error (lua_State *L, const char *fmt, ...);

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

Эта функция никогда не возвращается, но использовать ее в функциях C как return luaL_error(args) — это идиома .

luaL_execresult [-0, +3, м ]

int luaL_execresult (lua_State *L, int stat);

Эта функция производит возвращаемые значения для связанных с процессами функций в стандартной библиотеке ( os.execute и io.close ).

luaL_fileresult[-0, +(1|3), m]

int luaL_fileresult (lua_State *L, int stat, const char *fname);

Эта функция производит возвращаемые значения для файловых функций в стандартной библиотеке ( io.open , os.rename , file:seek и т. Д.).

luaL_getmetafield [-0, + (0 | 1), м ]

int luaL_getmetafield (lua_State *L, int obj, const char *e);

Помещает в стек поле e из метатаблицы объекта по индексу obj и возвращает тип помещенного значения. Если у объекта нет метатаблицы или если метатаблица не имеет этого поля, ничего не LUA_TNIL и возвращает LUA_TNIL .

luaL_getmetatable[-0, +1, m]

int luaL_getmetatable (lua_State *L, const char *tname);

Помещает в стек метатаблицу, связанную с именем tname в реестре (см. luaL_newmetatable ), или nil, если с этим именем не связана метатаблица. Возвращает тип переданного значения.

luaL_getsubtable[-0, +1, e]

int luaL_getsubtable (lua_State *L, int idx, const char *fname);

Гарантирует, что значение t[fname] , где t — значение индекса idx , является таблицей, и помещает эту таблицу в стек. Возвращает истину, если находит там предыдущую таблицу, и ложь, если создает новую таблицу.

luaL_gsub[-0, +1, m]

const char *luaL_gsub (lua_State *L,
                       const char *s,
                       const char *p,
                       const char *r);

Создает копию строки s , заменяя любое вхождение строки p строкой r . Помещает получившуюся строку в стек и возвращает ее.

luaL_len[-0, +0, e]

lua_Integer luaL_len (lua_State *L, int index);

Возвращает «длину» значения по заданному индексу в виде числа; он эквивалентен оператору ‘ # ‘ в Lua (см. §3.4.7 ). Выдает ошибку, если результат операции не является целым числом. (Этот случай может произойти только с помощью метаметодов.)

luaL_loadbuffer[-0, +1, –]

int luaL_loadbuffer (lua_State *L,
                     const char *buff,
                     size_t sz,
                     const char *name);

Эквивалентен luaL_loadbufferx с mode равным NULL .

luaL_loadbufferx[-0, +1, –]

int luaL_loadbufferx (lua_State *L,
                      const char *buff,
                      size_t sz,
                      const char *name,
                      const char *mode);

Загружает буфер как блок Lua. Эта функция использует lua_load для загрузки фрагмента в буфер, на который указывает buff , размером sz .

Эта функция возвращает те же результаты, что и lua_load . name — это имя блока, используемое для отладочной информации и сообщений об ошибках. Строковый mode работает как в функции lua_load .

luaL_loadfile[-0, +1, m]

int luaL_loadfile (lua_State *L, const char *filename);

Эквивалентен luaL_loadfilex с mode равным NULL .

luaL_loadfilex[-0, +1, m]

int luaL_loadfilex (lua_State *L, const char *filename,
                                            const char *mode);

Загружает файл в виде блока Lua. Эта функция использует lua_load для загрузки фрагмента в файл с именем filename . Если filename имеет NULL , он загружается из стандартного ввода. Первая строка в файле игнорируется, если она начинается с символа # .

Строковый mode работает как в функции lua_load .

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

Как и lua_load , эта функция загружает только чанк; он его не запускает.

luaL_loadstring[-0, +1, –]

int luaL_loadstring (lua_State *L, const char *s);

Загружает строку как фрагмент Lua. Эта функция использует lua_load для загрузки фрагмента в строке s с нулевым символом в конце .

Эта функция возвращает те же результаты, что и lua_load .

Также как lua_load , эта функция загружает только фрагмент; он его не запускает.

luaL_newlib[-0, +1, m]

void luaL_newlib (lua_State *L, const luaL_Reg l[]);

Создает новую таблицу и регистрирует в ней функции из списка l .

Он реализован в виде следующего макроса:

(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))

Массив l должен быть фактическим массивом, а не указателем на него.

luaL_newlibtable[-0, +1, m]

void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);

Создает новую таблицу с размером, оптимизированным для хранения всех записей в массиве l (но фактически не сохраняет их). Он предназначен для использования вместе с luaL_setfuncs (см. luaL_newlib ).

Он реализован как макрос. Массив l должен быть фактическим массивом, а не указателем на него.

luaL_newmetatable[-0, +1, m]

int luaL_newmetatable (lua_State *L, const char *tname);

Если в реестре уже есть ключ tname , возвращает 0. В противном случае создает новую таблицу, которая будет использоваться в качестве метатаблицы для пользовательских данных, добавляет в эту новую таблицу пару __name = tname , добавляет в реестр пару [tname] = new table и возвращает 1.

В обоих случаях функция помещает в стек последнее значение, связанное с tname в реестре.

luaL_newstate[-0, +0, –]

lua_State *luaL_newstate (void);

Создает новое состояние Lua. Он вызывает lua_newstate с распределителем, основанным на стандартных функциях распределения C, а затем устанавливает функцию предупреждения и функцию паники (см. §4.4 ), которые выводят сообщения в стандартный вывод ошибок.

Возвращает новое состояние или NULL , если есть ошибка выделения памяти.

luaL_openlibs[-0, +0, e]

void luaL_openlibs (lua_State *L);

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

luaL_opt[-0, +0, –]

T luaL_opt (L, func, arg, dflt);

Этот макрос определяется следующим образом:

(lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))

На словах, если аргумент arg равен нулю или отсутствует, макрос dflt значение по умолчанию dflt . В противном случае это приводит к результату вызова func с состоянием L и индексом аргумента arg в качестве аргументов. Обратите внимание, что он оценивает выражение dflt только в случае необходимости.

luaL_optinteger[-0, +0, v]

lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);

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

luaL_optlstring[-0, +0, v]

const char *luaL_optlstring (lua_State *L,
                             int arg,
                             const char *d,
                             size_t *l);

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

Если l не NULL , заполняет референт длиной результата. Если результатом является NULL (возможно только при возврате d и d == NULL ), его длина считается нулевой.

Эта функция использует lua_tolstring для получения результата, поэтому здесь применяются все преобразования и предупреждения этой функции.

luaL_optnumber[-0, +0, v]

lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);

Если аргумент функции arg является числом, возвращает это число как lua_Number . Если этот аргумент отсутствует или равен нулю , возвращает d . В противном случае выдает ошибку.

luaL_optstring[-0, +0, v]

const char *luaL_optstring (lua_State *L,
                            int arg,
                            const char *d);

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

luaL_prepbuffer[-?, +?, m]

char *luaL_prepbuffer (luaL_Buffer *B);

Эквивалентно luaL_prepbuffsize с предопределенным размером LUAL_BUFFERSIZE .

luaL_prepbuffsize[-?, +?, m]

char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);

Возвращает адрес в пространство размером sz , где вы можете скопировать строку для добавления в буфер B (см. luaL_Buffer ). После копирования строки в это пространство вы должны вызвать luaL_addsize с размером строки, чтобы фактически добавить ее в буфер.

luaL_pushfail[-0, +1, –]

void luaL_pushfail (lua_State *L);

Помещает значение ошибки в стек (см. §6 ).

luaL_pushresult[-?, +1, m]

void luaL_pushresult (luaL_Buffer *B);

Завершает использование буфера B , оставляя последнюю строку наверху стека.

luaL_pushresultsize[-?, +1, m]

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);

Эквивалентно последовательности luaL_addsize , luaL_pushresult .

luaL_ref[-1, +0, m]

int luaL_ref (lua_State *L, int t);

Создает и возвращает ссылку в таблице с индексом t для объекта на вершине стека (и выталкивает объект).

Ссылка — это уникальный целочисленный ключ. Пока вы не добавляете вручную целочисленные ключи в таблицу t , luaL_ref гарантирует уникальность возвращаемого ключа. Вы можете получить объект, на который ссылается ссылка r , вызвав lua_rawgeti(L, t, r) . Функция luaL_unref освобождает ссылку.

Если объект на вершине стека равен нулю , luaL_ref возвращает константу LUA_REFNIL . Константа LUA_NOREF гарантированно отличается от любой ссылки, возвращаемой luaL_ref .

luaL_Reg

typedef struct luaL_Reg {
  const char *name;
  lua_CFunction func;
} luaL_Reg;

Тип для массивов функций, которые будут зарегистрированы luaL_setfuncs . name — это имя функции, а func — указатель на функцию. Любой массив luaL_Reg должен заканчиваться контрольной записью, в которой и name , и func равны NULL .

luaL_requiref[-0, +1, e]

void luaL_requiref (lua_State *L, const char *modname,
                    lua_CFunction openf, int glb);

Если package.loaded[modname] не истинно, вызывает функцию openf со строкой modname в качестве аргумента и устанавливает результат вызова в package.loaded[modname] , как если бы эта функция была вызвана через require .

Если glb истинно, модуль также сохраняется в глобальном имени modname .

Оставляет копию модуля на стеке.

luaL_setfuncs[-nup, +0, m]

void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);

Регистрирует все функции в массиве l (см. luaL_Reg ) в таблице наверху стека (ниже необязательных повышающих значений, см. Далее).

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

luaL_setmetatable[-0, +0, –]

void luaL_setmetatable (lua_State *L, const char *tname);

Устанавливает метатаблицу объекта на вершине стека как метатаблицу, связанную с именем tname в реестре (см. luaL_newmetatable ).

luaL_Stream

typedef struct luaL_Stream {
  FILE *f;
  lua_CFunction closef;
} luaL_Stream;

Стандартное представление для файловых дескрипторов,используемое стандартной библиотекой ввода-вывода.

LUA_FILEHANDLE файла реализован как полные пользовательские данные с метатаблицей под названием LUA_FILEHANDLE (где LUA_FILEHANDLE — это макрос с фактическим именем метатаблицы). Метатаблица создается библиотекой ввода-вывода (см. luaL_newmetatable ).

Эти пользовательские данные должны начинаться со структуры luaL_Stream ; он может содержать другие данные после этой начальной структуры. Поле f указывает на соответствующий поток C (или оно может иметь NULL чтобы указать не полностью созданный дескриптор). Поле closef указывает на функцию Lua, которая будет вызываться для закрытия потока при закрытии или сборе дескриптора; эта функция получает дескриптор файла в качестве единственного аргумента и должна возвращать либо истинное значение в случае успеха, либо ложное значение плюс сообщение об ошибке в случае ошибки. Как только Lua вызывает это поле, он изменяет значение поля на NULL , чтобы сигнализировать, что дескриптор закрыт.

luaL_testudata[-0, +0, m]

void *luaL_testudata (lua_State *L, int arg, const char *tname);

Эта функция работает так luaL_checkudata , как luaL_checkudata , за исключением того, что в случае сбоя теста она возвращает NULL вместо того, чтобы вызывать ошибку.

luaL_tolstring[-0, +1, e]

const char *luaL_tolstring (lua_State *L, int idx, size_t *len);

Преобразует любое значение Lua по заданному индексу в строку C в приемлемом формате. Результирующая строка помещается в стек и также возвращается функцией (см. §4.1.3 ). Если len не равно NULL , функция также устанавливает *len с длиной строки.

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

luaL_traceback[-0, +1, m]

void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
                     int level);

Создает и отправляет обратную трассировку стека L1 . Если msg не NULL , оно добавляется в начале трассировки. Параметр level сообщает, с какого уровня начать трассировку.

luaL_typeerror[-0, +0, v]

const char *luaL_typeerror (lua_State *L,
                                      int arg,
                                      const char *tname);

Вызывает ошибку типа для аргумента arg вызывающей его функции C, используя стандартное сообщение; tname — это «имя» ожидаемого типа. Эта функция никогда не возвращается.

luaL_typename[-0, +0, –]

const char *luaL_typename (lua_State *L, int index);

Возвращает имя типа значения в данном индексе.

luaL_unref[-0, +0, –]

void luaL_unref (lua_State *L, int t, int ref);

Освобождает ссылку ref из таблицы по индексу t (см. luaL_ref ). Запись удаляется из таблицы, чтобы можно было собрать упомянутый объект. Ссылка ref также может быть использована снова.

Если ref — LUA_NOREF или LUA_REFNIL , luaL_unref ничего не делает.

luaL_where[-0, +1, m]

void luaL_where (lua_State *L, int lvl);

Помещает в стек строку, определяющую текущую позицию элемента управления на уровне lvl в стеке вызовов. Обычно эта строка имеет следующий формат:

chunkname:currentline:

Уровень 0-выполняющаяся функция,уровень 1-функция,вызывающая выполняющуюся функцию,и т.д.

Эта функция используется для построения префикса для сообщений об ошибках.

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

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

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

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

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

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

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

Чтобы получить доступ к этим библиотекам, хост-программа C должна вызвать функцию luaL_openlibs , которая открывает все стандартные библиотеки. В качестве альтернативы хост-программа может открывать их по отдельности, используя luaL_requiref для вызова luaopen_base (для базовой библиотеки), luaopen_package (для библиотеки пакетов), luaopen_coroutine (для библиотеки сопрограмм), luaopen_string (для строковой библиотеки), luaopen_utf8 (для Библиотека UTF-8), luaopen_table (для библиотеки таблиц), luaopen_math (для математической библиотеки), luaopen_io (для библиотеки ввода-вывода), luaopen_os (для библиотеки операционной системы) и luaopen_debug (для библиотеки отладки). Эти функции объявлены в lualib.h .

6.1-Основные функции

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

assert (v [, message])

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

collectgarbage ([opt [, arg]])

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

• » collect «: выполняет полный цикл сборки мусора. Это вариант по умолчанию.
• « stop »: останавливает автоматическое выполнение сборщика мусора. Сборщик будет работать только при явном вызове до тех пор, пока не будет вызван его перезапуск.
• « restart »: перезапускает автоматическое выполнение сборщика мусора.
• « count »: возвращает общий объем памяти, используемый Lua в килобайтах. Значение имеет дробную часть, поэтому умножение на 1024 дает точное количество байтов, используемых Lua.
• » step «: Выполняет сборку мусора. «Размер» шага контролируется arg . При нулевом значении коллектор выполнит один базовый (неделимый) шаг. Для ненулевых значений сборщик будет работать так, как если бы этот объем памяти (в килобайтах) был выделен Lua. Возвращает истину, если шаг завершил цикл сбора.
• » isrunning «: возвращает логическое значение, которое сообщает, работает ли сборщик (т. е. не остановлен).
• « incremental »: измените режим коллектора на инкрементный. За этой опцией могут следовать три числа: пауза сборщика мусора, множитель шага и размер шага (см. §2.5.1 ). Ноль означает не изменять это значение.
• « generational »: Измените режим коллектора на «Generation». За этой опцией могут следовать два числа: второстепенный множитель сборщика мусора и старший множитель (см. §2.5.2 ). Ноль означает не изменять это значение.

См. §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 не имеет метатаблицы, возвращает ноль . В противном случае, если метатаблица объекта имеет поле __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 возвращает скомпилированный фрагмент как функцию; в противном случае возвращается ошибка плюс сообщение об ошибке.

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

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

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

Строковый mode определяет, может ли фрагмент быть текстовым или двоичным (то есть предварительно скомпилированным фрагментом). Это может быть строка « b » (только двоичные фрагменты), « t » (только текстовые фрагменты) или « bt » (двоичные и текстовые). По умолчанию — « bt ».

Загружать искаженные двоичные фрагменты безопасно; load сигнализирует о соответствующей ошибке. Однако Lua не проверяет целостность кода внутри двоичных фрагментов; запуск злонамеренно созданного байт-кода может привести к сбою интерпретатора.

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

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

next (table [, index])

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

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

Поведение next не определено, если во время обхода вы присваиваете какое-либо значение несуществующему полю в таблице. Однако вы можете изменить существующие поля. В частности, вы можете установить для существующих полей значение 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 перехватывает ошибку и возвращает код состояния. Его первым результатом является код состояния (логическое значение), который является истинным, если вызов завершается успешно без ошибок. В таком случае pcall также возвращает все результаты вызова после этого первого результата. В случае какой-либо ошибки pcall возвращает false плюс объект ошибки. Обратите внимание, что ошибки, обнаруженные pcall , не вызывают обработчик сообщений.

print (···)

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

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

rawequal (v1, v2)

Проверяет, равен ли v1 v2 , без вызова __eq . Возвращает логическое значение.

rawget (table, index)

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

rawlen (v)

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

rawset (table, index, value)

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

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

select (index, ···)

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

setmetatable (table, metatable)

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

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

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

tonumber (e [, base])

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

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

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

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.4 ».

warn (msg1, ···)

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

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

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

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

6.2-Манипулирование корутинами

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

coroutine.close (co)

Закрывает сопрограмму co , то есть закрывает все ее ожидающие закрытия переменные и переводит сопрограмму в мертвое состояние. Данная сопрограмма должна быть мертвой или приостановленной. В случае ошибки закрытия какой-либо переменной возвращает false плюс объект ошибки; в противном случае возвращает истину .

coroutine.create (f)

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

coroutine.isyieldable ([co])

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

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

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

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

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

coroutine.running ()

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

coroutine.status (co)

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

coroutine.wrap (f)

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

coroutine.yield (···)

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

6.3-Модули

Библиотека пакетов предоставляет базовые возможности для загрузки модулей в 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 и дополнительное значение, данные загрузчика , также возвращаемые поисковиком. Данные загрузчика могут иметь любое значение, полезное для модуля; для поисковиков по умолчанию он указывает, где был найден загрузчик. (Например, если загрузчик пришел из файла, это дополнительное значение — это путь к файлу.) Если загрузчик возвращает любое значение, package.loaded[modname] nil, require присваивает возвращаемое значение package.loaded [modname] . Если загрузчик не возвращает значение, 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_4 , переменную среды LUA_CPATH или путь по умолчанию, определенный в luaconf.h .

package.loaded

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

Эта переменная всего лишь ссылка на реальную таблицу; присвоения этой переменной не изменяют таблицу, используемую require .

package.loadlib (libname, funcname)

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

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

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

Эта функция не поддерживается стандартом C. Таким образом, она доступна только на некоторых платформах (Windows, Linux, Mac OS X, Solaris, BSD и другие системы Unix, поддерживающие стандарт dlfcn ).

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

package.path

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

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

package.preload

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

Эта переменная всего лишь ссылка на реальную таблицу; присвоения этой переменной не изменяют таблицу, используемую require .

package.searchers

Таблица, используемая require для управления поиском модулей.

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

Луа инициализирует эту таблицу четырьмя функциями поиска.

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

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

6.4-Манипулирование строками

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

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

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

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

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

string.format (formatstring, ···)

Возвращает отформатированную версию своего переменного числа аргументов после описания, данного в его первом аргументе, который должен быть строкой. Строка формата следует тем же правилам, что и функция ISO C sprintf . Единственное отличие состоит в том, что спецификаторы и модификаторы преобразования * , h , L , l и n не поддерживаются и что есть дополнительный спецификатор q .

Спецификатор q форматирует логические значения, nil, числа и строки таким образом, чтобы результат был допустимой константой в исходном коде Lua. Логические значения и nil записываются очевидным образом ( true , false , nil ). Для сохранения полной точности числа с плавающей запятой записываются в шестнадцатеричном формате. Строка записывается в двойных кавычках с использованием управляющих последовательностей при необходимости, чтобы гарантировать, что она может быть безопасно прочитана интерпретатором 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.4.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.4.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 = string.gsub("hello world", "%w+", "%0 %0", 1)


x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")


x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)


x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
      return load(s)()
    end)


local t = {name="lua", version="5.4"}
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)

string.len (s)

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

string.lower (s)

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

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

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

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

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

string.packsize (fmt)

Возвращает размер строки, полученной из string.pack в заданном формате. Строка формата не может иметь опции переменной длины ‘ s ‘ или ‘ z ‘ (см. §6.4.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.4.2 ). Необязательный pos отмечает, где начать чтение в s (по умолчанию 1). После прочитанных значений эта функция также возвращает индекс первого непрочитанного байта в s .

string.upper (s)

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

6.4.1-Узоры

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

Character Class:

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

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

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

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

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

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

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

Pattern Item:

Элемент модели может быть

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

Pattern:

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

Captures:

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

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

Multiple matches:

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

> string.gsub("abc", "()a*()", print);

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

6.4.2-Строки формата для упаковки и распаковки

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

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

• < : устанавливает прямой порядок байтов
• > : устанавливает прямой порядок байтов
• = : устанавливает исходный порядок байтов
• ![n] : устанавливает максимальное выравнивание равным n (по умолчанию — собственное выравнивание)
• b : байт со знаком ( char )
• B : беззнаковый байт ( char )
• h : short подписанный (собственный размер)
• H : беззнаковый short (собственный размер)
• l : long знак со знаком (собственный размер)
• L : беззнаковый long (собственный размер)
• j: a lua_Integer
• J: a 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,либо little endian.Функции упаковки не будут корректно эмулировать поведение форматов со смешанным эндианом.

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

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

6.5-Поддержка UTF-8

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

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

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

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

utf8.char (···)

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

utf8.charpattern

Шаблон (строка, а не функция) » [-x7FxC2-xFD][x80-xBF]* » (см. §6.4.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. Если обнаруживается недопустимая последовательность байтов, возвращается ошибка плюс позиция первого недопустимого байта.

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

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

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

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

6.6-Манипулирование таблицами

Эта библиотека предоставляет общие функции для управления таблицами. Он предоставляет все свои функции внутри таблицы 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.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.

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

table.pack (···)

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

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

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

math.abs (x)

Возвращает максимальное значение от x до -x . (целое число / число с плавающей запятой)

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 (предполагается, что он выражен в радианах).

math.deg (x)

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

math.exp (x)

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

math.floor (x)

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

math.fmod (x, y)

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

math.huge

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

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 объединяются в 128-битное начальное число , которое используется для повторной инициализации генератора псевдослучайных чисел; равные семена дают равные последовательности чисел. Значение по умолчанию для y равно нулю.

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

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

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

math.sin (x)

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

math.sqrt (x)

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

math.tan (x)

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

math.tointeger (x)

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

math.type (x)

Возвращает « integer », если x является целым числом, « float », если это число с плавающей запятой, или неудачно, если x не является числом.

math.ult (m, n)

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

6.8-Средства ввода и вывода

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

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

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

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

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

io.close ([file])

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

io.flush ()

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

io.input ([file])

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

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

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

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

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

Доступные форматы

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

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

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

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

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

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

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

file:setvbuf (mode [, size])

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

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

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

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

file:write (···)

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

В случае успеха эта функция возвращает file .

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

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

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

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

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

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

Если необязательный второй аргумент close равен true, закрывает состояние Lua перед выходом.

os.getenv (varname)

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

os.remove (filename)

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

os.rename (oldname, newname)

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

os.setlocale (locale [, category])

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

Если locale является пустой строкой, текущий языковой стандарт установлен на собственный языковой стандарт, определенный реализацией. Если locale представляет собой строку « C », текущий языковой стандарт установлен на стандартный языковой стандарт C.

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

Эта функция может быть не поточно из — за своей зависимости от C функции setlocale .

os.time ([table])

Возвращает текущее время при вызове без аргументов или время, представляющее локальную дату и время, указанные в данной таблице. В этой таблице должны быть поля year , month и day , а также могут быть поля: hour (по умолчанию 12), min (по умолчанию 0), sec (по умолчанию 0) и isdst (по умолчанию ноль ). Остальные поля игнорируются. Описание этих полей см. os.date функции 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.10-Библиотека отладки

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

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

debug.debug ()

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

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

debug.gethook ([thread])

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

Возврат не выполняется, если нет активного хука.

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

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

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

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

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

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

Первый параметр или локальная переменная имеет индекс 1 и так далее, следуя порядку, в котором они объявлены в коде, с учетом только тех переменных, которые активны в текущей области действия функции. Константы времени компиляции могут не появиться в этом листинге, если они были оптимизированы компилятором. Отрицательные индексы относятся к аргументам vararg; -1 — это первый аргумент vararg. Функция возвращает ошибку, если нет переменной с данным индексом, и вызывает ошибку при вызове с уровнем вне допустимого диапазона. (Вы можете вызвать debug.getinfo , чтобы проверить, действителен ли уровень.)

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

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

debug.getmetatable (value)

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

debug.getregistry ()

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

debug.getupvalue (f, up)

Эта функция возвращает имя и значение восходящего значения с индексом up функции f . Функция возвращает ошибку, если нет повышающего значения с данным индексом.

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

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

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

debug.getuservalue (u, n)

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

debug.setcstacklimit (limit)

Устанавливает новый предел для стека C.Это ограничение контролирует глубину вложенных вызовов в Lua,чтобы избежать переполнения стека.Слишком маленькое ограничение бессмысленно ограничивает рекурсивные вызовы;слишком большое ограничение подвергает интерпретатор опасности переполнения стека.К сожалению,не существует способа узнать априори максимальный безопасный предел для платформы.

Каждый вызов,выполненный из кода Lua,стоит одну единицу.Другие операции (например,вызовы из языка C в Lua или возобновление работы coroutine)могут иметь более высокую стоимость.

Эта функция имеет следующие ограничения:

• Его можно вызвать только из главной корутины (потока);
• Его нельзя вызывать во время обработки ошибки переполнения стека;
• limit должен быть меньше 40000;
• limit не может быть меньше количества используемого стека C.

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

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

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

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

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

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

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

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

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

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

debug.setmetatable (value, table)

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

debug.setupvalue (f, up, value)

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

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

debug.setuservalue (udata, value, n)

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

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

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

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

debug.upvalueid (f, n)

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

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

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

Сделайте n1 -е повышающее значение замыкания Lua f1 ссылкой на n2 -е повышающее значение замыкания Lua f2 .

7 – Lua Standalone

Хотя Lua был разработан как язык расширения для встраивания в хост-программу C, он также часто используется как автономный язык. Интерпретатор Lua как отдельного языка, называемый просто lua , входит в стандартный дистрибутив. Автономный интерпретатор включает в себя все стандартные библиотеки. Его использование:

lua [options] [script [args]]

Опции есть:

• -e stat : выполнить строку stat ;
• -i : войти в интерактивный режим после запуска скрипта ;
• -l mod : «потребовать» мод и присвоить результат глобальному моду ;
• -v : распечатать информацию о версии;
• -E : игнорировать переменные среды;
• -W : включить предупреждения;
• -- : параметры остановки обработки;
• - : выполнить stdin как файл и прекратить обработку параметров.

После обработки опций lua запускает данный сценарий . При вызове без аргументов lua ведет себя как lua -v -i , когда стандартный ввод ( stdin ) является терминалом, и как lua - противном случае.

При вызове без опции -E , интерпретатор проверяет переменную среды LUA_INIT_5_4 (или LUA_INIT , если имя версии не определено) перед запуском любого аргумента. Если содержимое переменной имеет формат @filename , то lua выполняет файл. В противном случае lua выполняет саму строку.

При вызове с параметром -E Lua не обращается к переменным среды. В частности, значения package.path и package.cpath устанавливаются с путями по умолчанию, определенными в luaconf.h .

Параметры -e , -l и -W обрабатываются в том порядке, в котором они появляются. Например, такой вызов, как

$ lua -e 'a=1' -llib1 script.lua

сначала установит a в 1, затем потребует библиотеку lib1 и, наконец, запустит файл script.lua без аргументов. (Здесь $ — это приглашение оболочки. Ваше приглашение может быть другим.)

Перед запуском любого кода lua собирает все аргументы командной строки в глобальной таблице с именем arg . Имя скрипта переходит в индекс 0, первый аргумент после имени скрипта переходит в индекс 1 и так далее. Любые аргументы перед именем скрипта (то есть имя интерпретатора плюс его параметры) переходят к отрицательным индексам. Например, в звонке

$ lua -la b.lua t1 t2

стол вот такой:

arg = { [-2] = "lua", [-1] = "-la",
        [0] = "b.lua",
        [1] = "t1", [2] = "t2" }

Если в вызове нет скрипта,то имя интерпретатора переходит в индекс 0,за которым следуют остальные аргументы.Например,вызов

$ lua -e "print(arg[1])"

напечатает » -e «. Если есть скрипт, скрипт вызывается с аргументами arg[1] , ···, arg[#arg] . Как и все фрагменты в Lua, скрипт компилируется как функция с переменным числом аргументов.

В интерактивном режиме Lua многократно подсказывает и ждет строку.После прочтения строки,Lua сначала пытается интерпретировать ее как выражение.Если это удаётся,он печатает своё значение.В противном случае он интерпретирует строку как выражение.Если вы пишете незавершенное выражение,интерпретатор ждет его завершения,выдавая другую подсказку.

Если глобальная переменная _PROMPT содержит строку, то ее значение используется в качестве подсказки. Точно так же, если глобальная переменная _PROMPT2 содержит строку, ее значение используется в качестве вторичного приглашения (выдается во время неполных операторов).

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

При нормальном завершении интерпретатор закрывает свое основное состояние Lua (см. lua_close ). Сценарий может избежать этого шага, вызвав os.exit для завершения.

Чтобы разрешить использование Lua в качестве интерпретатора сценариев в системах Unix, Lua пропускает первую строку фрагмента файла, если он начинается с символа # . Следовательно, сценарии Lua можно превратить в исполняемые программы, используя команды chmod +x и #! форма, как в

#!/usr/local/bin/lua

Конечно, расположение интерпретатора Lua на вашем компьютере может быть другим. Если lua находится в вашем PATH , тогда

#!/usr/bin/env lua

является более портативным решением.

8-Несовместимость с предыдущей версией

Здесь мы перечислим несовместимости,которые вы можете обнаружить при переносе программы с Lua 5.3 на Lua 5.4.

Вы можете избежать некоторых несовместимостей, скомпилировав Lua с соответствующими параметрами (см. Файл luaconf.h ). Однако в будущем все эти параметры совместимости будут удалены. Чаще всего проблемы совместимости возникают при удалении этих параметров совместимости. Итак, всякий раз, когда у вас есть возможность, вы должны попробовать протестировать свой код с версией Lua, скомпилированной с отключенными всеми параметрами совместимости. Это упростит переход на новые версии Lua.

Версии Lua всегда могут изменить C API таким образом,что это не повлечет за собой изменения исходного кода программы,например,числовые значения констант или реализация функций в виде макросов.Поэтому никогда не следует полагать,что двоичные файлы совместимы между различными версиями Lua.Всегда перекомпилируйте клиенты API Lua при использовании новой версии.

Аналогично,версии Lua всегда могут изменить внутреннее представление прекомпилированных частей;прекомпилированные части не совместимы между разными версиями Lua.

Стандартные пути в официальном дистрибутиве могут меняться между версиями.

8.1-Несовместимости в языке

• Приведение строк к числам в арифметических и побитовых операциях было удалено из основного языка. Строковая библиотека выполняет аналогичную работу для арифметических (но не для побитовых) операций с использованием строковых метаметодов. Однако, в отличие от предыдущих версий, новая реализация сохраняет неявный тип числа в строке. Например, результат "1" + "2" теперь является целым числом, а не числом с плавающей запятой.
• Буквальные десятичные целочисленные константы,которые переполняются,считываются как плавающие числа,а не обводятся вокруг.Вы можете использовать шестнадцатеричную нотацию для таких констант,если хотите вернуть старое поведение (читать их как целые числа с обводкой).
• Использование __lt для эмуляции __le было удалено. При необходимости этот метаметод должен быть определен явно.
• Семантика числового цикла for по целым числам изменилась в некоторых деталях. В частности, управляющая переменная никогда не повторяется.
• Метка для перехода не может быть объявлена ​​там, где видна метка с тем же именем, даже если эта другая метка объявлена ​​во включающем блоке.
• При финализации объекта Lua не игнорирует __gc , которые не являются функциями. Будет вызываться любое значение, если оно присутствует. (Невозвратные значения будут генерировать предупреждение, как и любая другая ошибка при вызове финализатора.)

8.2-Несовместимости в библиотеках

• Функция print не вызывает tostring для форматирования своих аргументов; вместо этого у него есть эта функциональная возможность. Вы должны использовать __tostring , чтобы изменить способ печати значений.
• Генератор псевдослучайных чисел, используемый функцией math.random , теперь начинается с несколько случайного начального числа. Более того, он использует другой алгоритм.
• По умолчанию функции декодирования в библиотеке utf8 не принимают суррогаты в качестве действительных кодовых точек. Дополнительный параметр в этих функциях делает их более разрешительными.
• Параметры setpause и setstepmul функции collectgarbage устарели. Вы должны использовать новую опцию « incremental », чтобы установить их.
• Функция io.lines теперь возвращает четыре значения вместо одного. Это может быть проблемой, когда он используется в качестве единственного аргумента для другой функции, которая имеет необязательные параметры, например, в load(io.lines(filename, "L")) . Чтобы решить эту проблему, вы можете заключить вызов в круглые скобки, чтобы довести количество результатов до одного.

8.3-Несовместимости в API

• Полные пользовательские данные теперь имеют произвольное количество связанных пользовательских значений. Поэтому функции lua_newuserdata , lua_setuservalue и lua_getuservalue были заменены на lua_newuserdatauv , lua_setiuservalue и lua_getiuservalue , у которых есть дополнительный аргумент.

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

• У функции lua_resume есть дополнительный параметр. Этот параметр out возвращает количество значений наверху стека, которые были выданы или возвращены сопрограммой. (В предыдущих версиях этими значениями был весь стек.)
• Функция lua_version возвращает номер версии вместо адреса номера версии. Ядро Lua должно правильно работать с библиотеками, использующими собственные статические копии одного и того же ядра, поэтому нет необходимости проверять, используют ли они одно и то же адресное пространство.
• Константа LUA_ERRGCMM удалена. Ошибки в финализаторах никогда не распространяются; вместо этого они генерируют предупреждение.
• Параметры LUA_GCSETPAUSE и LUA_GCSETSTEPMUL функции lua_gc устарели. Вы должны использовать новую опцию LUA_GCINC , чтобы установить их.

9-Полный синтаксис Lua

Вот полный синтаксис Lua в расширенном BNF. Как обычно в расширенной BNF, {A} означает 0 или более As, а [A] означает необязательный A. (Приоритеты операций см. в §3.4.8 ; описание терминалов Name, Numeral и LiteralString см. в § 3.1 .)

chunk ::= block

block ::= {stat} [retstat]

stat ::=  ‘;’ | 
	 varlist ‘=’ explist | 
	 functioncall | 
	 label | 
	 break | 
	 goto Name | 
	 do block end | 
	 while exp do block end | 
	 repeat block until exp | 
	 if exp then block {elseif exp then block} [else block] end | 
	 for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end | 
	 for namelist in explist do block end | 
	 function funcname funcbody | 
	 local function Name funcbody | 
	 local attnamelist [‘=’ explist] 

attnamelist ::=  Name attrib {‘,’ Name attrib}

attrib ::= [‘<’ Name ‘>’]

retstat ::= return [explist] [‘;’]

label ::= ‘::’ Name ‘::’

funcname ::= Name {‘.’ Name} [‘:’ Name]

varlist ::= var {‘,’ var}

var ::=  Name | prefixexp ‘[’ exp ‘]’ | prefixexp ‘.’ Name 

namelist ::= Name {‘,’ Name}

explist ::= exp {‘,’ exp}

exp ::=  nil | false | true | Numeral | LiteralString | ‘...’ | functiondef | 
	 prefixexp | tableconstructor | exp binop exp | unop exp 

prefixexp ::= var | functioncall | ‘(’ exp ‘)’

functioncall ::=  prefixexp args | prefixexp ‘:’ Name args 

args ::=  ‘(’ [explist] ‘)’ | tableconstructor | LiteralString 

functiondef ::= function funcbody

funcbody ::= ‘(’ [parlist] ‘)’ block end

parlist ::= namelist [‘,’ ‘...’] | ‘...’

tableconstructor ::= ‘{’ [fieldlist] ‘}’

fieldlist ::= field {fieldsep field} [fieldsep]

field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp

fieldsep ::= ‘,’ | ‘;’

binop ::=  ‘+’ | ‘-’ | ‘*’ | ‘/’ | ‘
	 ‘&’ | ‘~’ | ‘|’ | ‘>>’ | ‘<<’ | ‘..’ | 
	 ‘<’ | ‘<=’ | ‘>’ | ‘>=’ | ‘==’ | ‘~=’ | 
	 and | or

unop ::= ‘-’ | not | ‘#’ | ‘~’

---

Lua

5.4

• Справочное руководство по Lua 5.4