루아 레퍼런스 매뉴얼 — 보조 라이브러리
루아 레퍼런스 매뉴얼 — 보조 라이브러리 (The Auxiliary Library)
C 언어로 루아를 확장하다 보면 반복적으로 마주치는 작업이 있어요. 테이블에 함수를 등록한다든지, 인자가 제대로 들어왔는지 검사한다든지, 문자열을 조금씩 쌓아 올린다든지 하는 일이죠. 기본 API만으로도 전부 할 수는 있지만, 매번 그걸 처음부터 다시 쓰기는 번거로워요. 그래서 루아는 이런 공통 작업들을 한 단계 위에서 처리해 주는 보조 라이브러리(auxiliary library) 를 함께 제공해요.
이번 챕터는 그 보조 라이브러리를 살펴보는 장이에요. 기본 API가 C와 루아 사이의 모든 상호작용을 위한 저수준 함수들을 제공한다면, 보조 라이브러리는 자주 쓰는 일을 위한 고수준 함수를 모아 둔 거라고 보면 돼요. 헤더 파일 lauxlib.h에 정의되어 있고, 모든 함수와 타입이 luaL_ 접두사를 붙인다는 게 가장 큰 특징이에요.
출처: Lua 5.4 Reference Manual — Chapter 5: The Auxiliary Library
본문
보조 라이브러리에 속한 모든 함수와 타입은 헤더 파일 lauxlib.h에 정의되어 있고, luaL_ 접두사를 가져요.
보조 라이브러리의 모든 함수는 기본 API 위에 쌓여 있어요. 그래서 기본 API로는 할 수 없는 그 무엇도 추가로 제공하지는 않아요. 그래도 보조 라이브러리를 쓰면 코드의 일관성이 훨씬 좋아져요. 같은 일을 매번 다르게 흉내 내는 대신, 정해진 고수준 함수를 쓰니까요.
보조 라이브러리의 몇몇 함수는 내부적으로 스택 슬롯을 추가로 써요. 그런데 슬롯이 다섯 개 미만으로 필요한 함수는 스택 크기를 검사하지 않고, 그냥 충분한 슬롯이 있다고 가정해요. 이 부분은 함수를 쓸 때 스택 여유를 신경 써 줘야 한다는 뜻이에요.
보조 라이브러리에는 C 함수의 인자를 검사하는 함수가 여럿 있어요. 이 함수들이 만드는 오류 메시지는 인자를 기준으로 만들어져요. 예를 들어 "bad argument #1" 같은 형식이죠. 그래서 이 검사 함수들은 인자(argument)로 쓰일 값에만 써야 해요. 스택의 다른 값에 쓰면 메시지가 이상해져요.
luaL_check*로 시작하는 함수들은 검사가 통과하지 않으면 언제나 오류를 일으켜요. 반환값으로 실패를 알려주는 게 아니라 그 자리에서 멈추는 거예요.
5.1 함수와 타입 (Functions and Types)
이 절에서는 보조 라이브러리의 모든 함수와 타입을 알파벳 순서로 정리해요.
luaL_addchar
[-?, +?, m]
void luaL_addchar (luaL_Buffer *B, char c);
바이트 c를 버퍼 B에 추가해요(luaL_Buffer 참고).
luaL_addgsub
[-?, +?, 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);
s가 가리키고 길이가 l인 문자열을 버퍼 B에 추가해요(luaL_Buffer 참고). 이 문자열은 중간에 널 바이트(0)를 포함할 수 있어요.
luaL_addsize
[-?, +?, –]
void luaL_addsize (luaL_Buffer *B, size_t n);
앞서 버퍼 영역에 복사해 둔 길이 n의 문자열을 버퍼 B에 실제로 추가해요(luaL_prepbuffer 참고).
luaL_addstring
[-?, +?, m]
void luaL_addstring (luaL_Buffer *B, const char *s);
s가 가리키는 널 종료 문자열을 버퍼 B에 추가해요(luaL_Buffer 참고).
luaL_addvalue
[-?, +?, m]
void luaL_addvalue (luaL_Buffer *B);
스택 맨 위의 값을 버퍼 B에 추가하고 그 값을 팝(pop)해요(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
[-0, +0, v]
int luaL_argerror (lua_State *L, int arg, const char *extramsg);
이 함수를 호출한 C 함수의 arg 번째 인자에 문제가 있다고 알리는 오류를 일으켜요. 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;
문자열 버퍼를 위한 타입이에요. 문자열 버퍼(string buffer) 는 C 코드가 루아 문자열을 조금씩 쌓아 만들 수 있게 해주는 도구예요. 쓰는 패턴은 이렇게 돼요:
- 먼저
luaL_Buffer타입의 변수b를 선언해요. - 그다음
luaL_buffinit(L, &b)호출로 초기화해요. - 그다음
luaL_add*류 함수를 호출해 문자열 조각을 버퍼에 추가해요. - 마지막으로
luaL_pushresult(&b)를 호출해서 마무리해요. 이 호출은 최종 문자열을 스택 맨 위에 남겨 줘요.
만약 결과 문자열의 최대 크기를 미리 알고 있다면 버퍼를 이렇게 쓸 수도 있어요:
- 먼저
luaL_Buffer타입의 변수b를 선언해요. - 그다음
luaL_buffinitsize(L, &b, sz)호출로 초기화하면서 크기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, +?, –]
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
[-?, +?, –]
void luaL_buffsub (luaL_Buffer *B, int n);
버퍼 B에서 n바이트를 제거해요(luaL_Buffer 참고). 버퍼에는 최소 그만큼의 바이트가 있어야 해요.
luaL_callmeta
[-0, +(0|1), e]
int luaL_callmeta (lua_State *L, int obj, const char *e);
메타메서드를 호출해요. obj 인덱스에 있는 객체가 메타테이블을 갖고, 그 메타테이블에 필드 e가 있다면, 이 함수는 그 필드를 호출하면서 객체를 유일한 인자로 넘겨줘요. 이 경우 함수는 true를 반환하고 호출이 돌려준 값을 스택에 푸시해요. 메타테이블이 없거나 메타메서드가 없으면, 이 함수는 스택에 아무 값도 푸시하지 않고 false를 반환해요.
luaL_checkany
[-0, +0, v]
void luaL_checkany (lua_State *L, int arg);
arg 위치에 어떤 타입이든(nil 포함) 함수 인자가 있는지 검사해요.
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이 아니면, arg 인자가 없거나 nil일 때 기본값으로 def를 사용해요. 문자열을 C 열거형(enum)에 매핑할 때 아주 유용한 함수예요. (루아 라이브러리에서는 옵션을 고를 때 숫자 대신 문자열을 쓰는 게 일반적인 관례예요.)
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인지 검사해요. t의 타입 부호화 방식은 lua_type을 참고하세요.
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);
호출하는 쪽의 코드와 호출되는 루아 라이브러리가 같은 버전의 루아와 같은 숫자 타입을 쓰는지 검사해요.
luaL_dofile
[-0, +?, m]
int luaL_dofile (lua_State *L, const char *filename);
주어진 파일을 로드해서 실행해요. 다음 매크로로 정의돼 있어요:
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
오류가 없으면 0(LUA_OK)을, 오류가 있으면 1을 반환해요.
luaL_dostring
[-0, +?, –]
int luaL_dostring (lua_State *L, const char *str);
주어진 문자열을 로드해서 실행해요. 다음 매크로로 정의돼 있어요:
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
오류가 없으면 0(LUA_OK)을, 오류가 있으면 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, m]
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), m]
int luaL_getmetafield (lua_State *L, int obj, const char *e);
obj 인덱스에 있는 객체의 메타테이블에서 필드 e를 스택에 푸시하고, 푸시된 값의 타입을 반환해요. 객체가 메타테이블을 갖지 않거나, 메타테이블이 이 필드를 갖지 않으면 아무것도 푸시하지 않고 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 인덱스의 값)이 테이블이 되도록 보장하고, 그 테이블을 스택에 푸시해요. 거기에 이미 테이블이 있었다면 true를, 새로 만든 거라면 false를 반환해요.
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);
주어진 인덱스에 있는 값의 "길이"를 숫자로 반환해요. 루아의 # 연산자와 같은 동작이에요(§3.4.7 참고). 연산 결과가 정수가 아니면 오류를 일으켜요. (이 경우는 메타메서드를 통해서만 일어날 수 있어요.)
luaL_loadbuffer
[-0, +1, –]
int luaL_loadbuffer (lua_State *L,
const char *buff,
size_t sz,
const char *name);
mode가 NULL인 luaL_loadbufferx와 같아요.
luaL_loadbufferx
[-0, +1, –]
int luaL_loadbufferx (lua_State *L,
const char *buff,
size_t sz,
const char *name,
const char *mode);
버퍼를 루아 청크(chunk)로 로드해요. buff가 가리키고 크기가 sz인 버퍼의 청크를 로드하는 데 lua_load를 사용해요. 이 함수는 lua_load와 같은 결과를 반환해요. name은 청크 이름으로, 디버그 정보와 오류 메시지에 쓰여요. 문자열 mode는 lua_load 함수에서처럼 동작해요.
luaL_loadfile
[-0, +1, m]
int luaL_loadfile (lua_State *L, const char *filename);
mode가 NULL인 luaL_loadfilex와 같아요.
luaL_loadfilex
[-0, +1, m]
int luaL_loadfilex (lua_State *L, const char *filename,
const char *mode);
파일을 루아 청크로 로드해요. filename이라는 파일의 청크를 로드하는 데 lua_load를 사용해요. filename이 NULL이면 표준 입력에서 로드하고요. 파일의 첫 줄이 #로 시작하면 그 줄은 무시해요. 문자열 mode는 lua_load 함수에서처럼 동작해요. 이 함수는 lua_load와 같은 결과를, 파일 관련 오류에 대해서는 LUA_ERRFILE을 반환해요. lua_load처럼 이 함수는 청크를 로드만 하고 실행하지는 않아요.
luaL_loadstring
[-0, +1, –]
int luaL_loadstring (lua_State *L, const char *s);
문자열을 루아 청크로 로드해요. 널 종료 문자열 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] = 새 테이블 쌍을 추가한 다음 1을 반환해요. 두 경우 모두 이 함수는 레지스트리에서 tname과 연관된 최종 값을 스택에 푸시해요.
luaL_newstate
[-0, +0, –]
lua_State *luaL_newstate (void);
새 루아 상태를 만들어요. ISO C 할당 함수에 기반을 둔 할당자로 lua_newstate를 호출하고, 그다음 표준 오류 출력으로 메시지를 출력하는 경고 함수와 패닉 함수를 설정해요(§4.4 참고). 새 상태를 반환하고, 메모리 할당 오류가 있으면 NULL을 반환해요.
luaL_openlibs
[-0, +0, e]
void luaL_openlibs (lua_State *L);
주어진 상태에 모든 표준 루아 라이브러리를 열어요.
luaL_opt
[-0, +0, –]
T luaL_opt (L, func, arg, dflt);
이 매크로는 다음과 같이 정의돼 있어요:
(lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
말로 풀면, 인자 arg가 nil이거나 없으면 매크로 결과가 기본값 dflt가 돼요. 그렇지 않으면 상태 L과 인자 인덱스 arg를 인자로 func를 호출한 결과가 돼요. 표현식 dflt는 필요할 때만 평가된다는 점에 주의하세요.
luaL_optinteger
[-0, +0, v]
lua_Integer luaL_optinteger (lua_State *L,
int arg,
lua_Integer d);
arg 번째 함수 인자가 정수면(또는 정수로 변환 가능하면) 그 정수를 반환해요. 인자가 없거나 nil이면 d를 반환하고요. 그 외의 경우에는 오류를 일으켜요.
luaL_optlstring
[-0, +0, v]
const char *luaL_optlstring (lua_State *L,
int arg,
const char *d,
size_t *l);
arg 번째 함수 인자가 문자열이면 그 문자열을 반환해요. 인자가 없거나 nil이면 d를 반환하고, 그 외의 경우에는 오류를 일으켜요. l이 NULL이 아니면 그 값이 가리키는 곳에 결과의 길이를 채워 넣어요. 결과가 NULL이면(d를 반환하는데 d == NULL일 때만 가능해요), 그 길이는 0으로 간주돼요. 이 함수는 결과를 얻기 위해 lua_tolstring을 사용하므로, 그 함수의 변환 규칙과 주의사항이 그대로 적용돼요.
luaL_optnumber
[-0, +0, v]
lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);
arg 번째 함수 인자가 숫자면 그 숫자를 lua_Number로 반환해요. 인자가 없거나 nil이면 d를 반환하고, 그 외의 경우에는 오류를 일으켜요.
luaL_optstring
[-0, +0, v]
const char *luaL_optstring (lua_State *L,
int arg,
const char *d);
arg 번째 함수 인자가 문자열이면 그 문자열을 반환해요. 인자가 없거나 nil이면 d를 반환하고, 그 외의 경우에는 오류를 일으켜요.
luaL_prepbuffer
[-?, +?, m]
char *luaL_prepbuffer (luaL_Buffer *B);
미리 정의된 크기 LUAL_BUFFERSIZE를 쓰는 luaL_prepbuffsize와 같아요.
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);
실패값(fail value)을 스택에 푸시해요(§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 인덱스의 테이블 안에 참조(reference)를 만들고 반환해요(그리고 그 객체를 팝해요). 참조는 유일한 정수 키예요. 테이블 t에 정수 키를 직접 추가하지 않는 한, luaL_ref는 반환하는 키의 유일성을 보장해요. 참조 r이 가리키는 객체는 lua_rawgeti(L, t, r)로 꺼내올 수 있고, luaL_unref로 참조는 해제돼요. 스택 맨 위의 객체가 nil이면 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인 센티널(sentinel) 항목으로 끝나야 해요.
luaL_requiref
[-0, +1, e]
void luaL_requiref (lua_State *L, const char *modname,
lua_CFunction openf, int glb);
package.loaded[modname]이 true가 아니면, 문자열 modname을 인자로 함수 openf를 호출하고 그 호출 결과를 package.loaded[modname]에 설정해요. 마치 그 함수가 require를 통해 호출된 것처럼요. glb가 true면 모듈을 전역 modname에도 저장해요. 모듈의 복사본 하나를 스택에 남겨요.
luaL_setfuncs
[-nup, +0, m]
void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);
배열 l의 모든 함수를 스택 맨 위의 테이블(선택적 업밸류 아래쪽, 다음 설명 참고)에 등록해요(luaL_Reg 참고). nup가 0이 아니면, 모든 함수는 nup개의 업밸류를 갖고 만들어지며, 라이브러리 테이블 위쪽의 스택에 미리 푸시된 nup개 값의 복사본으로 초기화돼요. 이 값들은 등록이 끝난 뒤 스택에서 팝돼요. 값이 NULL인 함수는 자리 표시자(placeholder)로, false로 채워져요.
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;
표준 I/O 라이브러리가 쓰는 파일 핸들의 표준 표현이에요. 파일 핸들은 LUA_FILEHANDLE이라는 메타테이블을 가진 완전 사용자데이터(full userdata)로 구현돼요(여기서 LUA_FILEHANDLE은 실제 메타테이블 이름을 가진 매크로예요). 그 메타테이블은 I/O 라이브러리가 만들어요(luaL_newmetatable 참고). 이 사용자데이터는 luaL_Stream 구조체로 시작해야 하고, 이후에 다른 데이터를 더 담을 수 있어요. 필드 f는 해당 C 스트림을 가리켜요(또는 불완전하게 만들어진 핸들을 나타내도록 NULL일 수도 있어요). 필드 closef는 핸들이 닫히거나 수집될 때 스트림을 닫기 위해 호출될 루아 함수를 가리켜요. 이 함수는 파일 핸들을 유일한 인자로 받고, 성공 시 true 값을, 오류 시 false 값과 오류 메시지를 반환해야 해요. 루아가 이 필드를 한 번 호출하면, 핸들이 닫혔다는 표시로 필드 값을 NULL로 바꿔요.
luaL_testudata
[-0, +0, m]
void *luaL_testudata (lua_State *L, int arg, const char *tname);
이 함수는 luaL_checkudata와 같은 방식으로 동작하되, 검사가 실패하면 오류를 일으키는 대신 NULL을 반환해요.
luaL_tolstring
[-0, +1, e]
const char *luaL_tolstring (lua_State *L, int idx, size_t *len);
주어진 인덱스에 있는 임의의 루아 값을 합리적인 형식의 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]
int luaL_typeerror (lua_State *L, int arg, const char *tname);
이 함수를 호출한 C 함수의 arg 번째 인자에 대해 표준 메시지로 타입 오류를 일으켜요. 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);
t 인덱스의 테이블에서 참조 ref를 해제해요(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은 그 함수를 호출한 함수 등이에요. 이 함수는 오류 메시지의 접두어를 만드는 데 쓰여요.
더 알아보기
- 기본 API와의 관계: 보조 라이브러리가 감싸고 있는 저수준 스택 함수들(스택 조작, 값 만들기, 메타테이블 등)을 보려면 챕터 4 'The Application Program Interface'를 읽어 보세요.
luaL_함수들이 내부적으로 호출하는lua_*함수들이 여기 다 나와요. - 스택 슬롯 표기
[-?, +?, m]: 함수 헤더 위에 붙은[음수값, 양수값, 종류]는 그 함수가 스택을 어떻게 바꾸는지 알려주는 표기예요. 음수는 함수가 팝하는 요소 수, 양수는 푸시하는 요소 수,m(mixed)은 상황에 따라 다름,e(error)는 오류 시 스택 상태를 보장하지 않음,v(variable)는 오류 처리가 스택으로만 이루어짐을 뜻해요. 챕터 4의 도입부에서 자세히 다뤄요. - 관련 표준 라이브러리:
luaL_execresult,luaL_fileresult,luaL_Stream,luaL_requiref같은 함수는 표준 라이브러리와 짝을 이뤄요. 챕터 6 'The Standard Libraries'에서os,io,package라이브러리를 보면 이 보조 함수들이 실제로 어디에 쓰이는지 확인할 수 있어요.