Справочное руководство по языку Lua 5.1 :: 3.7 - Псевдо-индексы

FarUE3 Lua51

Справочное руководство по языку Lua 5.1



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

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


lua_Alloc

        typedef void * (*lua_Alloc) (void *ud,

                             void *ptr,

                             size_t osize,

                             size_t nsize);
                           

Тип функции выделения памяти, используемый Lua. Функция выделения должна предоставлять функционал, схожий с realloc, но не точно такой же. Ее аргументы: ud, непрозрачный (opaque) указатель, передаваемый lua_newstate, ptr, указатель на блок block выделенной, перевыделенной или освобожденной памяти; osize, исходный размер блока; nsize, новый размер блока. ptr равен NULL тогда и только тогда когда osize нулевой. Когда nsize равен нулю, процедура выделения памяти (allocator) должна вернуть NULL; если osize не ноль, она должна освободить блок, на который указывает ptr. Когда nsize не ноль, процедура возвращает NULL тогда и только тогда она не может выполнить запрос. Если nsize не ноль и osize ноль, процедура должна вести себя как malloc. Если nsize и osize не ноль, процедура ведят себя как realloc. Луа предполагает, что такая процедура никогда не приводит к ошибочной ситуации при osize >= nsize.

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

                           
         static void *l_alloc (void *ud, void *ptr, size_t osize,

                                                size_t nsize) {

                (void)ud;  (void)osize;  /* not used */

                if (nsize == 0) {

                free(ptr);

                return NULL;

       }

       else

         return realloc(ptr, nsize);
       

Этот код предполагает что NULL не имеет эффекта и что realloc(NULL, size) эквивалентна malloc(size). ANSI C соответствует обоим поведениям.


lua_atpanic

       
        lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
       

Устанавливает новую panic function и возвращает старую.

Если происходит ошибка вне любого protected environment, Lua вызывает panic function, а затем exit(EXIT_FAILURE), таким образом выходя из приложения. Ваша panic function может предотвратить выход из программы, если не будет оканчиваться (e.g., при помощи long jump).

Panic function может осуществлять доступ к сообщению об ошибке на вершине стека.


lua_call

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

Вызывает функцию

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

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

Эквивалентыный код в Lua:

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

То же в C:

           
    lua_getfield(L, LUA_GLOBALSINDEX, 'f'); /* function to be called */

     lua_pushstring(L, 'how');                        /* 1st argument */

     lua_getfield(L, LUA_GLOBALSINDEX, 't');   /* table to be indexed */

     lua_getfield(L, -1, 'x');        /* push result of t.x (2nd arg) */

     lua_remove(L, -2);                  /* remove 't' from the stack */

     lua_pushinteger(L, 14);                          /* 3rd argument */

     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */

     lua_setfield(L, LUA_GLOBALSINDEX, 'a');        /* set global 'a' */
   

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


lua_CFunction

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

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

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

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

   
     static int foo (lua_State *L) {

       int n = lua_gettop(L);    /* number of arguments */

       lua_Number sum = 0;

       int i;

       for (i = 1; i <= n; i++) {

         if (!lua_isnumber(L, i)) {

           lua_pushstring(L, 'incorrect argument');

           lua_error(L);

         }

         sum += lua_tonumber(L, i);

       }

       lua_pushnumber(L, sum/n);        /* first result */

       lua_pushnumber(L, sum);         /* second result */

       return 2;                   /* number of results */

     }
   

lua_checkstack

   
    int lua_checkstack (lua_State *L, int extra);
   

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


lua_close

   
    void lua_close (lua_State *L);
   

Уничтожает все объекты в заданном состоянии Lua (Lua state) (вызывая соответствующие garbage-collection метаметоды, если таковые есть) и освобождает всю динамическую память, используемыю этим состоянием (state). На некоторых платформах, вам может не понядобиться вызывать эту функцию, т.к. все ресурсы освобождаются автоматически, когда закрывается программа (host program). С другой стороны, долго работающие программы, такие как демоны или веб-сервера, могут потребовать освобождения состояний, как только они не нужны, для избежания слишком сильного разрастания.


lua_concat

   
    void lua_concat (lua_State *L, int n);
   

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


lua_cpcall

   
    int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
   

Вызывает функцию C func в защищенном режиме (protected mode). func запускается с единственным значением в ее стеке, пользовательскими данными, содержащими ud. В случае ошибок, lua_cpcall возвращает аналогичные коды ошибок как lua_pcall, а также error object на вершине тека; в противном случае, она возвращает 0, и не изменяет стек. Все значения, возвращаемые func игнорируются.


lua_createtable

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

Создает новую пустую таблицу, и вставляет (push)ее в стек. Под новую таблицу выделяется место для narr элементов массива и nrec элементов не массива (non-array elements). Это выделение удобно когда вы знаете точное количество элементов, которое будет помещено в таблицу. В противном случае, вы можете использовать функциюlua_newtable


lua_dump

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

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

Возвращает значение, соответствующее коду ошибки (error code), возвращенному последним обращением к writer; 0 обозначает отсутствие ошибок.

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


lua_equal

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

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


lua_error

   
    int lua_error (lua_State *L);
   

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


lua_gc

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

Контролироет сборщик мусора.

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

  • LUA_GCSTOP: останавливает сборщик.
  • LUA_GCRESTART: перезапускает сборщик.
  • LUA_GCCOLLECT: производит полный цикл сборки мусора.
  • LUA_GCCOUNT: возвращает текущее значение объема памяти (в Kbytes), которое используется Lua.
  • LUA_GCCOUNTB: возвращает остаток деления текущего количества байт памяти, используемого Lua на 1024.
  • LUA_GCSTEP: выполняет инкрементальный шаг сбора мусора. Размер шага "size" контролируется значением data (большие значения означают большее количество шагов), но нет прямого соответствия между занчсением этого параметра и объемом освобождаемой памяти. Если вы хотите контролировать размер шага вам нужно экспериментально подобрать размер data. Эта функция возвращает 1 если шаг закончил цикл сборки мусора.
  • LUA_GCSETPAUSE: выставляет data/100 новым значением для параметра pause сборщика мусора (см. §2.10). Функция возвращает предыдущее значение данного параметра.
  • LUA_GCSETSTEPMUL: выставляет data/100 как новое значение step multiplier сборщика (см.§2.10). Функция возвращает предыдущее значение данного параметра.

lua_getallocf

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

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


lua_getfenv

   
    void lua_getfenv (lua_State *L, int index);
   

Вставляет (Push) в стек таблицуокружения (environment table) значения заданного индекса.


lua_getfield

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

Вставляет (Push) в стек значение t[k], где t – это значение заданного валидного индекса index. Так же, как в Lua, эта йункция может вызывать (trigger) метаметод для события индекса ("index" event) (см. §2.8).


lua_getglobal

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

Вставляет (Push) в стек значение глобальной переменной (value of the global name). Эта функция определяется как следующий макрос:

   
        #define lua_getglobal(L,s)  lua_getfield(L, LUA_GLOBALSINDEX, s)
       

lua_getmetatable

       
        int lua_getmetatable (lua_State *L, int index);
       

Вставляет в стек метатаблицу (metatable) значения в заданном валидном индексе (acceptable index). Если индекс не валиден, или значение не имеет метатаблицы, функция возвращает 0 и ничего не вставляет в стек.


lua_gettable

       
        void lua_gettable (lua_State *L, int index);
       

Вставляет в стек значение t[k], где t – это значение у указанном валидном индексе index и k – это значение на вершине стека.

Эта функция выталкивает ключ из стека (вставляет результат на его место). Также как в Lua, эта функция может вызывать (trigger) метаметод для события индекса (см. §2.8).


lua_gettop

       
        int lua_gettop (lua_State *L);
       

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


lua_insert

       
        void lua_insert (lua_State *L, int index);
       

Перемещает верхний элемент в заданный валидный индекс, сдвигая вверх все элементы, находящиеся выше заданного индекса. Процедура не может быть вызвана с псевдо-индексом (pseudo-index), т.к. псевдо-индекс (pseudo-index) не содержит реального положения в стеке.


lua_Integer

       
        typedef ptrdiff_t lua_Integer;
       

Данный тип используется Lua API для представления целых чисел.

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


lua_isboolean

       
        int lua_isboolean (lua_State *L, int index);
       

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


lua_iscfunction

       
        int lua_iscfunction (lua_State *L, int index);
       

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


lua_isfunction

       
        int lua_isfunction (lua_State *L, int index);
       

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


lua_islightuserdata

       
        int lua_islightuserdata (lua_State *L, int index);
       

Возвращает 1 если значение в заданном допустимом (acceptable) индексе – это пользовательские данные (light userdata), и 0 в противном случае.


lua_isnil

       
        int lua_isnil (lua_State *L, int index);
       

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


lua_isnone

       
        int lua_isnone (lua_State *L, int index);
       

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


lua_isnoneornil

       
        int lua_isnoneornil (lua_State *L, int index);
       

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


lua_isnumber

       
        int lua_isnumber (lua_State *L, int index);
       

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


lua_isstring

       
        int lua_isstring (lua_State *L, int index);
       

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


lua_istable

       
        int lua_istable (lua_State *L, int index);
       

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


lua_isthread

       
        int lua_isthread (lua_State *L, int index);
       

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


lua_isuserdata

       
        int lua_isuserdata (lua_State *L, int index);
       

Возвращает 1 если значение в заданном допустимом (acceptable) индексе – пользовательские данные (userdata) (full или light), и 0 в противном случае.


lua_lessthan

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

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


lua_load

       
        int lua_load (lua_State *L,

              lua_Reader reader,

              void *data,

              const char *chunkname);
             

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

  • 0: нет ошибок;
  • LUA_ERRSYNTAX:ошибка синтаксиса;
  • LUA_ERRMEM: ошибка выделения памяти.

Эта функция только загружает chunk; но не запускает.

lua_load автоматически определяет, является ли chunk текстовым или бинарным, и соответствующе его загружает (см. программу luac).

Функция lua_load использует предоставленную пользователем функцию reader для чтения chunk (см. lua_Reader). Аргумент data – непрзрачное (opaque) значение, передаваемое в функцию reader.

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


lua_newstate

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

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


lua_newtable

             
             void lua_newtable (lua_State *L);
             

Создает новую пустую таблицу и вставляет ее в стек. Действие этой функции эквивалентно lua_createtable(L, 0, 0).


lua_newthread

             
             lua_State *lua_newthread (lua_State *L);
             

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

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


lua_newuserdata

             
             void *lua_newuserdata (lua_State *L, size_t size);
             

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

Пользовательская информация (userdata) представляет значения C в Lua. Полная пользовательская информация (full userdata) представляет блок памяти. Это - объект (такой же как таблица): вы должны создать его, он может облатдать собственной метатаблицей, и вы можете определить, когда она будет собрана (collected). Полная пользовательская информаия (full userdata) равна только самой себе (в соответствии с «сырым» сравнением (under raw equality)).

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


lua_next

             
             int lua_next (lua_State *L, int index);
             

Выталкивает (Pop) ключ из стека, и вставляет пару ключ-значение из таблицы по заданному индексу ("следующую" пару после заданного ключа). Если больше не существует елементов в таблицы, то lua_next возвращает 0 (и ничего не вставляет в стек).

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

             
                 /* table is in the stack at index 't' */

                 lua_pushnil(L);  /* first key */

                 while (lua_next(L, t) != 0) {

                    /* uses 'key' (at index -2) and 'value' (at index -1) */

                    printf('%s - %s\n',

                     lua_typename(L, lua_type(L, -2)),

                     lua_typename(L, lua_type(L, -1)));

                    /* removes 'value'; keeps 'key' for next iteration */

                    lua_pop(L, 1);

                  }
                 

Во время обхода таблицы, не вызывайтеlua_tolstring непосредственно для ключа, если не уверенны точно, что ключ действительно является строкой. Повторный вызов (Recall) lua_tolstring изменяет значение по заданному индесу; это «сбивает с толку» (confuses) следующий вызов lua_next.


lua_Number

                 
                 typedef double lua_Number;
                 

Тип чисел в Lua. По умолчанию – double, но это можно изменить в luaconf.h.

В конфигурационном файле вы можете изменить настройки Lua так, чтобы оперировать другими типами чисел (напр., float или long).


lua_objlen

                 
                 size_t lua_objlen (lua_State *L, int index);
                 

Возвращает длину данных, расположенных по заданному допустимому индексу: для строк, возвращает длину строки; для таблиц – результат выполнения оператора дляины ('#'); для пользовательских данных – размер блока данных, выделенных для пользовательских данных; для других типов – 0.


lua_pcall

                 
                 nt lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
                 

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

Параметры nargs и nresults имеют значение, аналогичное lua_call. Во время вызова не произошло ошибок, lua_pcall ведет себя в точности как lua_call. Однако, если встретились ошибки, lua_pcall перехватывает их, вставляет в стек сообщение об ошибке, и возвращает код ошибки. Также как и lua_call, lua_pcall всегда удаляет функцию и ее аргументы из стека.

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

Чаще всего, функция обработки ошибок (error handler function) используется для добавления дополнительной отладочной информации в сообщение об ошибке, такой как stack traceback. Такая информация не может быть собрана после возврата из lua_pcall, , т.к. в этот момент стек был уже изменен (unwound).

Функция lua_pcall возвращает 0 в случае успешного завершения или один из следующих кодов ошибок (определенных в lua.h):

  • LUA_ERRRUN:ошибка времени выполнения.
  • LUA_ERRMEM:ошибка выделения памяти. Для таких ошибок, Lua не вызвает функию-обработчик ошибок.
  • LUA_ERRERR:ошибка во время выполнения функции-обработчика ошибок.

lua_pop

                 
                 void lua_pop (lua_State *L, int n);
                 

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


lua_pushboolean

                 
                 void lua_pushboolean (lua_State *L, int b);
                 

Вставляет булеву переменную со значением b в стек.


lua_pushcclosure

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

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

Когда функция C создана, есть возможность ассоциировать с ней некоторые значения, т.о. создавая экземпляр функции C (C closure) (см. §3.4); ); эти значения затем доступны функции во время ее вызова. Для того чтобы ассоциировать значения с функцией C, сначала эти значения должны быть вставлены в стек (если есть несколько значений, первое вставляется первым). Затем lua_pushcclosure вызывется для того, чтобы создать и вставить функцию C в стек, с аргументом n, соответствующем количеству ассоциируемых значений. lua_pushcclosure также выталкивает эти значения из стека.


lua_pushcfunction

                 
                 void lua_pushcfunction (lua_State *L, lua_CFunction f);
                 

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

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

lua_pushcfunction определена следующим макросом:

                 
                 #define lua_pushcfunction(L,f)  lua_pushcclosure(L,f,0)
                 

lua_pushfstring

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

Вставляет в стек отформатированную строку и возвращает указатель на эту строку. Эта функция аналогична функции C sprintf, но обладает некоторыми важными отличиями:

  • Вам не нужно выделять память для результата: результат – строка Lua и Lua позаботится о выделении памяти (и освобождении, в процессе сборки мусора).
  • Символы замены довольно ограничены. Не существует флагов, длин, или точностей. Символы замены могут быть только '%%' (вставляет '%' в строку), '%s' (вставляет строку, оканчивающуюся 0, без ограничений на длину), '%f' (вставляет lua_Number), '%p' (вставляет указатель в шестнадцатиричном формате), '%d' (вставляет целое число), и '%c' (вставляет целое число как символ).

lua_pushinteger

                 
                 void lua_pushinteger (lua_State *L, lua_Integer n);
                 

Вставляет число со значением n в стек


lua_pushlightuserdata

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

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

Пользовательские данные представляют значения C в Lua. Light пользовательские данные представляют собой указатель. Это – значение (как число): вы не создаете его, оно не имеет метатаблицы, и оно никогда не собирается сборщиком мусора (т.к.никогда не было создано). Light пользовательские данные эквивалентны любым light пользовательским данным с таким же адресом C.


lua_pushlstring

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

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


lua_pushnil

                 
                 void lua_pushnil (lua_State *L);
                 

Вставляет значение nil в стек.


lua_pushnumber

                 
                 void lua_pushnumber (lua_State *L, lua_Number n);
                 

Вставляет число со значением n в стек.


lua_pushstring

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

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


lua_pushthread

                 
                 int lua_pushthread (lua_State *L);
                 

Вставляет нить L в стек. Возвращает 1 если данная нить – основная в данном состоянии.


lua_pushvalue

                 
                 void lua_pushvalue (lua_State *L, int index);
                 

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


lua_pushvfstring

                 
  const char *lua_pushvfstring (lua_State *L,

                              const char *fmt,

                              va_list argp);
                             

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


lua_rawequal

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

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


lua_rawget

                   
                   void lua_rawget (lua_State *L, int index);
                             

Аналогична lua_gettable, но совершает «сырой» доступ (т.е., без метаметодов).


lua_rawgeti

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

Вставляет в стек значение t[n], где t – это значение в заданном валидном индексе index. Доступ «сырой», т.е. метаметоды не вызыаются.


lua_rawset

                           
                   void lua_rawset (lua_State *L, int index);
                             

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


lua_rawseti

                           
                   void lua_rawseti (lua_State *L, int index, int n);
                             

Выполняет действия, аналогичные t[n] = v, где t – это значение по валидному индексу index, а v – значение на вершине стека.

&Эта функция выталкивает значение из стека. Присваивание – «сырое»; т.е., не вызывает метаметодов.


lua_Reader


       typedef const char * (*lua_Reader) (lua_State *L,

                                                    void *data,

                                                    size_t *size);
                                                   

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


lua_register

                                                   
         void lua_register (lua_State *L,

                                  const char *name,

                                  lua_CFunction f);
                                                               

Выставляет функцию C f новым значением global name. Функция определена как макрос:

               
        #define lua_register(L,n,f) \

            (lua_pushcfunction(L, f), lua_setglobal(L, n))
           

lua_remove

           
            void lua_remove (lua_State *L, int index);
           

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


lua_replace

           
            void lua_replace (lua_State *L, int index);
           

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


lua_resume

           
            int lua_resume (lua_State *L, int narg);
           

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

Для запуска сопрограммы, вы сначала должны создать новую нить (см. lua_newthread); затем вы вставляете в ее стек главную функцию плюс любые аргументы; затем вы вызываетеlua_resume, с narg равным количеству аргументов. Эта функция закончит работу тогда, когда сопрограмма остановится (suspend) или закончит свое исполнение. Когда она остановится, стек будет содержать все значения, переданные lua_yield, или все значения, возвращенный функцией.lua_resume возвращает LUA_YIELD если сопрограмма уступает ресурсы, 0 если сопрограмма заканчивает свое выполнение без ошибок, или код ошибки в случае ошибочной ситуации (см. lua_pcall). В случае ошибок, стек не очищается (unwound), т.о. вы можете использовать API отладки для его анализа. Сообщение об ошибке находится на вершине стека. Для перезапуска сопрограммы, вы передаете в ее стек только значения, которые должны быть переданы как результаты yield, и затем вызываете lua_resume.


lua_setallocf

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

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


lua_setfenv

           
            int lua_setfenv (lua_State *L, int index);
           

Выталкивает таблицу из стека из стека и выставляет ей новое окружение для значения по заданному индексу. Если значение по данному индексу не является функцией, нитью или пользовательскими данными, lua_setfenv возвращает 0. Иначе, она возвращает 1.


lua_setfield

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

Выполняет действие, аналогичное t[k] = v, где t – значение по заданному валидному индексу index и v – значение на вершине стека.

Эта функция выталкивает значение из стека. Также как в Lua, эта функция сожжет вызывать метаметод для события "новый индекс" (см. §2.8).


lua_setglobal

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

Выталкивает значение из стека и приравнивает его глобальной переменной (global) name. Определена как макрос:

           
             #define lua_setglobal(L,s)   lua_setfield(L, LUA_GLOBALSINDEX, s)
             

lua_setmetatable

             
             int lua_setmetatable (lua_State *L, int index);
             

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


lua_settable

             
             void lua_settable (lua_State *L, int index);
             

Выполняет аналогичные t[k] = v действия, где t – это значение по заданному валидному индексу index, v – это значение на вершин стека, и k – это значение, находящееся на одно ниже вершины стека.

Эта функция выталкивает ключ и значение из стека. Также как в Lua, эта функция может вызывать метаметод для события "новый индекс" (см. §2.8).


lua_settop

             
             void lua_settop (lua_State *L, int index);
             

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


>lua_State

             
             typedef struct lua_State lua_State;
             

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

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


lua_status

             
             int lua_status (lua_State *L);
             

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

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


lua_toboolean

             
             int lua_toboolean (lua_State *L, int index);
             

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


lua_tocfunction

             
             lua_CFunction lua_tocfunction (lua_State *L, int index);
             

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


lua_tointeger

             
             lua_Integer lua_tointeger (lua_State *L, int idx);
             

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

Если число не целое, оно обрубается каким-то неопределенным способом (it is truncated in some non-specified way).


lua_tolstring

             
             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 возвращает fully aligned pointer на строку в состоянии Lua. Эта строка всегда имеет ноль ('\0') после последнего символа (как в C), но может содержать также другие нули. Т.к. Lua обладает сборщиком мусора, нет гарантии что указатель, возвращенный lua_tolstring будет валиден после удаления соответствующео значения из стека.


lua_tonumber

             
             lua_Number lua_tonumber (lua_State *L, int index);
             

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


lua_topointer

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

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

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


lua_tostring

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

Эквивалентна lua_tolstring с длиной len равной NULL.


lua_tothread

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

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


lua_touserdata

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

Если знаение по указанному допустимому индексу – это full пользовательские данные, возвращает их адрес блока. Если значение – это light пользовательские данные, возвращает их указатель. В противном случае, возвращает NULL.


lua_type

             
             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

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

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


lua_Writer

             
     typedef int (*lua_Writer) (lua_State *L,

                                const void* p,

                                size_t sz,

                                void* ud);
                          

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

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


lua_xmove

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

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

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


lua_yield

           
            int lua_yield  (lua_State *L, int nresults);
           

Останавливает сопрограмму.

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

           
             return lua_yield (L, nresults);
             

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

Перепечатка материалов только с разрешения владельцев сайта Lua.ru.