Classe para interface com ambientes Lua. More...

#include <luaEnv.h>

Inheritance diagram for LuaEnv:

Collaboration diagram for LuaEnv:

[legend]

Public Types
enum	StackOption { STACK_POP, STACK_NOPOP, STACK_AUTO }
	Opções de manipulação de pilha. More...

enum	LibraryOptions { LIB_BASE = 0x01, LIB_TABLE = 0x02, LIB_IO = 0x04, LIB_OS = 0x08, LIB_STRING = 0x10, LIB_MATH = 0x20, LIB_DEBUG = 0x40, LIB_PACKAGE = 0x80, LIB_ALL = 0xFF }
	Opçoes de bibliotecas a serem carregadas na inicialização do estado. More...

typedef luaL_Reg	FunctionRegister
	Tipo para tabela de funções a serem registradas no ambiente.

typedef void(*	RedirectedOutputCb) (void *context, QString str)
	Tipo para callback chamada para redirecionamento de output.

typedef QString(*	ScriptNameFilterCb) (void *context, QString scriptName)
	Tipo para callback chamada para ajustar o nome do script usado em mensagens de erro para arquivos carregados pela função dofile substituida por replaceDofile()

Public Member Functions
	LuaEnv ()
	Construtor padrão. Cria objeto com ambiente Lua vazio. More...

	LuaEnv (lua_State *state)
	Construtor. Cria um LuaEnv a partir de um ambiente Lua pré-existente.

	~LuaEnv ()
	Destrutor. Ambiente Lua NÃO é fechado automaticamente.

bool	newState (int libOptions=LIB_ALL)
	Cria um novo ambiente lua e o inicializa com as funções das bibliotecas especificadas Se a biblioteca está compilada com uso de espaço extra, zera este espaço. More...

void	closeState ()
	Fecha o estado Lua.

void	removeSymbols (const QStringList &symbolNames)
	Atribui nil aos símbolos presentes na tabela recebida, removendo-os do ambiente. More...

void	setState (lua_State *state)
	Altera o ambiente Lua armazenado. Ambiente anterior, se existente, NÃO é fechado.

lua_State *	state ()
	Retorna o estado Lua armazenado.

	operator lua_State * ()
	Operador para converter um LuaEnv em um lua_State.

void	redirectOutput (RedirectedOutputCb cb, void *context)
	Redireciona o output produzido pelo script para a callback especificada.

void	replaceDofile (QString table="", ScriptNameFilterCb scriptNameFilter=NULL, void *scriptNameFilterContext=NULL)
	Substitui o método dofile() para que este passe a usar a função runRsrcScript() para carregar arquivos. Se table != "", usa a mesma como ambiente de destino para variáveis globais. Se scriptNameFilter for diferente de NULL, esta função será chamada, a cada dofile, para que o usuário possa alterar o nome do script usado para mensagens de erro.

void	setDofileTable (QString table)
	Updates the table where dofile functions should be executed.

void	setRsrcPath (const QStringList &pathList)
	Altera a lista de paths utilizados para busca de resoures na função runRsrcScript()

const QStringList &	rsrcPath () const
	Retorna lista de paths considerados para carga de resurces por runRsrcScript()

bool	runScript (QString file, QString table, QString &err)
	Carrega e executa script contido no arquivo recebido como parâmetro. More...

bool	runRsrcScript (QString file, QString table, QString &err)
	Carrega e executa script contido no resource recebido como parâmetro. More...

bool	runVerifiedRsrcScript (QString file, QString table, QString hash, bool encoded, QString &err)
	Carrega e executa script contido no resource recebido como parâmetro, decodificando o mesmo (se necessário) e conferindo se o hash do script confere com o hash recebido como parâmetro. More...

bool	runScriptStr (QString script, QString table, QString &err)
	Sobrecarrega runScriptStr() passando "" como nome do script.

bool	runScriptStr (QString script, QString table, QString name, QString &err)
	Carrega e executa script contido na string recebida como parâmetro. More...

bool	runScriptStr (QByteArray &script, QString table, QString name, QString &err)
	Carrega e executa script contido no byte array recebido como parâmetro. More...

void	setLoadTableEnv (int tableRef=LUA_NOREF)
	Cadastra referência para uma tabela que será utilizada como ambiente global pelas diversas funções de carga de scripts. Utilize LUA_NOREF para cancelar o uso desta tabela. Se uma referência válida for setada, esta terá precedência sobre qualquer nome de tabela passado como parâmetro para as funções de carga de script.

void	registerFunctions (const FunctionRegister reg, const char table=NULL)
	Se table for igual a NULL, cadastra funções presentes na lista reg no ambiente global. Caso contrário, cria tabela, seta a mesma na variável global table e cadastra as funções nesta nova tabela.

void	registerFunction (const char globalName, lua_CFunction func, void userdata_1=NULL, void *userdata_2=NULL)
	Associa a função func com a variável global globalName. More...

QVariant	getGlobal (const char *name, StackOption opt=STACK_AUTO)
	Obtem o valor da variavel global recebida como parâmetro. More...

QVariant	getGlobal (QString name, StackOption opt=STACK_AUTO)
	Método sobrecarregado recebendo um QString.

void	setGlobal (const char *name, const QVariant &val)
	Seta variável global com o valor recebido como parâmetro. More...

void	setGlobal (QString name, const QVariant &val)
	Método sobrecarregado recebendo um QString.

QVariant	toVariant (StackOption opt, int index=-1)
	Retorna o valor contido no topo da pilha como um QVariant. Se index for diferente de -1, retorna o valor associado com este índice. More...

void	pushVariant (const QVariant &val)
	Coloca val no topo da pilha.

void	pop (int num=1)
	Remove num elementos da pilha.

int	top ()
	Retorna índice do elemento no topo da pilha.

void	setTop (int index)
	Altera topo da pilha para o indice recebido como parâmetro.

QVariant	getLocal (const char *name, StackOption opt=STACK_AUTO)
	Obtem o valor da variavel local recebida como parâmetro através do uso da interface de debug do Lua. More...

QVariant	getLocal (QString name, StackOption opt=STACK_AUTO)
	Método sobrecarregado recebendo um QString.

Static Public Member Functions
static bool	isIdentifier (QString str)
	Returns true if the given string can be used as a Lua identifier, false if not. More...

static QString	quote (QString str)
	Retorna uma versão da string recebida envolta por aspas ("xxx") e contendo os escape codes necessários.

static QVariant &	clearReferences (QVariant &obj, bool useLists, bool firstLevelIsMap, bool allowFunctions)
	Removes table and function references from the given QVariant. More...

Private Member Functions
void	initState (int libOptions)
	Inicializa o ambiente Lua com carga das bibliotecas padrão.

bool	loadScriptData (QString file, QByteArray &script, QString &err)
	Função auxiliar utilizada por runRsrcScript() e runVerifiedRsrcScript() para carregar os dados do script. More...

bool	runScriptAux (QString table, QString &err)
	Função auxiliar para carga de scripts. Contém código comum a runScript e runScriptStr.

Static Private Member Functions
static int	printCb (lua_State *L)
	Função usada para capturar chamadas a print.

static int	dofile (lua_State *L)
	Função usada para substituir chamadas a dofile.

Private Attributes
lua_State *	_l
	Lua state associado com este objeto.

RedirectedOutputCb	_outputCb
	Callback usada para redirecionamento de mensganes de output.

void *	_outputContext
	Contexto passado para a callback.

QStringList	_rsrcPathList
	Lista de paths base usados para leitura de resources.

QString	_dofileTable
	Nome da tabela de ambiente para operações de dofile se este foi substituido por replaceDofile()

ScriptNameFilterCb	_dofileScriptNameFilter
	The filter function for script names from the overloaded dofile function.

void *	_dofileScriptNameContext
	A user context passed as parameter to _dofileScriptNameFilter.

int	_envTableRef
	Referência para tabela usada como ambiente global na carga de scripts setada por setLoadTableEnv()

Detailed Description

Classe para interface com ambientes Lua.

Encapsula um lua_state e fornece funções auxiliares para manipulação do mesmo.

Ao ser destruído, NÃO fecha o ambiente Lua. Isto permite que a classe seja utilizada para encapsular ambientes Lua já criados (como por exemplo aqueles recebidos nas funções chamadas por Lua)

Member Enumeration Documentation

◆ LibraryOptions

enum LuaEnv::LibraryOptions

Opçoes de bibliotecas a serem carregadas na inicialização do estado.

Enumerator
LIB_BASE	Biblioteca base e tabela de funções coroutine.
LIB_TABLE	Tabela de funções table.
LIB_IO	Tabela de funções io.
LIB_OS	Tabela de funções os.
LIB_STRING	Tabela de funções string.
LIB_MATH	Tabela de funções math.
LIB_DEBUG	Tabela de funções debug.
LIB_PACKAGE	Tabela de funções package.
LIB_ALL	Conjunto de todas as bibliotecas.

◆ StackOption

enum LuaEnv::StackOption

Opções de manipulação de pilha.

Enumerator
STACK_POP	Indica que o valor deve ser removido da pilha.
STACK_NOPOP	Indica que o valor não deve ser removido da pilha.
STACK_AUTO	Valor será ou não removido da pilha dependendo de seu tipo.

Constructor & Destructor Documentation

◆ LuaEnv()

LuaEnv::LuaEnv ( )

inline

Construtor padrão. Cria objeto com ambiente Lua vazio.

Deve ser seguido de uma chamada a newState() ou setState()

Member Function Documentation

◆ clearReferences()

QVariant & LuaEnv::clearReferences	(	QVariant &	obj,
		bool	useLists,
		bool	firstLevelIsMap,
		bool	allowFunctions
	)

static

Removes table and function references from the given QVariant.

When a QVariant object is created by a call to toVariant(), tables and Lua functions are transformed into LuaTable and LuaFunction objects that store references to Lua objects in the current Lua environment.

If we want those QVariant objects to be valid after the Lua environment is closed, we must suppress those references from the QVariant.

This function replaces Lua function references by 'nil' and table references by a QVariantMap or by a QVariantList. This is done recursivelly.

It assumes that tables are always keyed by strings or by numbers and transforms the table into a QVariantMap. If useLists == true and the map has only numeric indices with a sequential numbering starting with 1, the map is replaced by a QVariantList. If firstLevelIsMap == true, then the first table level will never be translated into a list.

If allowFunctions == true, LuaFunction objects won't be translated to nil. Keep in mind that if that option is turned on, the resulting QVariant will be invalid if the Lua environment is closed.

As a convenience, returns obj.

◆ getGlobal()

QVariant LuaEnv::getGlobal	(	const char *	name,
		StackOption	opt = `STACK_AUTO`
	)

Obtem o valor da variavel global recebida como parâmetro.

Retorna um QVariant com o valor lido. Processa numeros, strings, booleanos, tabelas e funções. Outros tipos são ignorados (retornam um QVariant nulo).

Se a variável não existir, também retorna um QVariant nulo.

Parâmetro opt controla se o valor obtido deve ou não ser mantido na pilha. Opções:

STACK_POP: Indica que o valor deve ser removido da pilha
STACK_NOPOP: Indica que o valor não deve ser removido da pilha
STACK_AUTO: Valor será mantido na pilha apenas se seu tipo for uma tabela ou uma função.

Quando o tipo do valor retornado for uma tabela / função, o QVariant retornado conterá um objeto do tipo LuaTable / LuaFunction. Se opt for STACK_POP, o objeto criado guardará uma referência para a tabela. Caso contrário guardará o índice da tabela / função na pilha.

◆ getLocal()

QVariant LuaEnv::getLocal	(	const char *	name,
		StackOption	opt = `STACK_AUTO`
	)

Obtem o valor da variavel local recebida como parâmetro através do uso da interface de debug do Lua.

O valor local é buscado em todos os níveis (Lua) da pilha de chamadas até ser encontrado.

Retorna um QVariant com o valor lido. Processa numeros, strings, booleanos, tabelas e funções. Outros tipos são ignorados (retornam um QVariant nulo).

Se a variável não existir, também retorna um QVariant nulo.

Parâmetro opt controla se o valor obtido deve ou não ser mantido na pilha. Opções:

STACK_POP: Indica que o valor deve ser removido da pilha
STACK_NOPOP: Indica que o valor não deve ser removido da pilha
STACK_AUTO: Valor será mantido na pilha apenas se seu tipo for uma tabela ou uma função.

Quando o tipo do valor retornado for uma tabela / função, o QVariant retornado conterá um objeto do tipo LuaTable / LuaFunction. Se opt for STACK_POP, o objeto criado guardará uma referência para a tabela. Caso contrário guardará o índice da tabela / função na pilha.

◆ isIdentifier()

bool LuaEnv::isIdentifier ( QString str )

static

Returns true if the given string can be used as a Lua identifier, false if not.

A lua identifier begins with an alpha character or _ and contains only alphanumeric characters or _.

◆ loadScriptData()

bool LuaEnv::loadScriptData	(	QString	file,
		QByteArray &	script,
		QString &	err
	)

private

Função auxiliar utilizada por runRsrcScript() e runVerifiedRsrcScript() para carregar os dados do script.

Parameters

file	Arquivo contendo o script a ser carregado. Será concatenado ao path corrente setado via setRsrcPath(). Se o nome do arquivo resultante iniciar com ":/" o arquivo será lido do resource manager do Qt. Caso contrário será lido como um arquivo comum. Se o path corrente possuir mais de uma entrada, todas serão tentadas em sequência.
script	Retorna o conjunto de dados lidos do arquivo. É um byte array para suportar scripts gerados por luac
err	Retorna mensagem de erro se a execução não foi bem sucedida

Returns: Retorna true em caso de sucesso

◆ newState()

bool LuaEnv::newState ( int libOptions = LIB_ALL )

Cria um novo ambiente lua e o inicializa com as funções das bibliotecas especificadas Se a biblioteca está compilada com uso de espaço extra, zera este espaço.

Parameters

libOptions Define as bibliotecas que serão abertas. Valor default LibraryOptions::LIB_ALL inclui todas as libs. Deve ser um "or" das bibliotecas desejadas, composto por valores do enumerado LuaEnv::LibraryOptions.

Returns: Retorna false em casod e erro.

◆ registerFunction()

void LuaEnv::registerFunction	(	const char *	globalName,
		lua_CFunction	func,
		void *	userdata_1 = `NULL`,
		void *	userdata_2 = `NULL`
	)

Associa a função func com a variável global globalName.

Se userdata_x != NULL e , cadastra o valor como um upvalue da função de tipo lightuserdata.

◆ removeSymbols()

void LuaEnv::removeSymbols ( const QStringList & symbolNames )

Atribui nil aos símbolos presentes na tabela recebida, removendo-os do ambiente.

Usado geralmente para retirar funções e tabelas padrão indesejadas do ambiente Aceita o idioma "tabela.simbolo" (com apenas um nível de indireção), com o significado de atribuir nil ao campo simbolo da tabela global tabela

◆ runRsrcScript()

bool LuaEnv::runRsrcScript	(	QString	file,
		QString	table,
		QString &	err
	)

Carrega e executa script contido no resource recebido como parâmetro.

Parameters

file	Arquivo contendo o script a ser executado. Será concatenado ao path corrente setado via setRsrcPath(). Se o nome do arquivo resultante iniciar com ":/" o arquivo será lido do resource manager do Qt. Caso contrário será lido como um arquivo comum. Se o path corrente possuir mais de uma entrada, todas serão tentadas em sequência.
table	Se diferente de "", seta a tabela de nome table (cria se necessario) como o ambiente global para execução do script
err	Retorna mensagem de erro se a execução não foi bem sucedida

Returns: Retorna true se bem sucedido, false caso contrário

◆ runScript()

bool LuaEnv::runScript	(	QString	file,
		QString	table,
		QString &	err
	)

Carrega e executa script contido no arquivo recebido como parâmetro.

Parameters

file	Arquivo contendo o script a ser executado
table	Se diferente de "", seta a tabela de nome table (cria se necessario) como o ambiente global para execução do script
err	Retorna mensagem de erro se a execução não foi bem sucedida

Returns: Retorna true se bem sucedido, false caso contrário

◆ runScriptStr() [1/2]

bool LuaEnv::runScriptStr	(	QString	script,
		QString	table,
		QString	name,
		QString &	err
	)

Carrega e executa script contido na string recebida como parâmetro.

Parameters

script	String contendo o script a ser executado
table	Se diferente de "", seta a tabela de nome table (cria se necessario) como o ambiente global para execução do script
name	Nome dado ao script para ser usado em mensagens de erro
err	Retorna mensagem de erro se a execução não foi bem sucedida

Returns: Retorna true se bem sucedido, false caso contrário

◆ runScriptStr() [2/2]

bool LuaEnv::runScriptStr	(	QByteArray &	script,
		QString	table,
		QString	name,
		QString &	err
	)

Carrega e executa script contido no byte array recebido como parâmetro.

Parameters

script	Byte array contendo o script a ser executado
table	Se diferente de "", seta a tabela de nome table (cria se necessario) como o ambiente global para execução do script
name	Nome dado ao script para ser usado em mensagens de erro
err	Retorna mensagem de erro se a execução não foi bem sucedida

Returns: Retorna true se bem sucedido, false caso contrário

◆ runVerifiedRsrcScript()

bool LuaEnv::runVerifiedRsrcScript	(	QString	file,
		QString	table,
		QString	hash,
		bool	encoded,
		QString &	err
	)

Carrega e executa script contido no resource recebido como parâmetro, decodificando o mesmo (se necessário) e conferindo se o hash do script confere com o hash recebido como parâmetro.

Parameters

file	Arquivo contendo o script a ser executado. Será concatenado ao path corrente setado via setRsrcPath(). Se o nome do arquivo resultante iniciar com ":/" o arquivo será lido do resource manager do Qt. Caso contrário será lido como um arquivo comum. Se o path corrente possuir mais de uma entrada, todas serão tentadas em sequência.
table	Se diferente de "", seta a tabela de nome table (cria se necessario) como o ambiente global para execução do script
hash	Hash code contra o qual o script deve ser verificado
encoded	Se true indica que o script foi codificado (via LuaSecurityEncode())
err	Retorna mensagem de erro se a execução não foi bem sucedida

Returns: Retorna true se bem sucedido, false caso contrário

◆ setGlobal()

void LuaEnv::setGlobal	(	const char *	name,
		const QVariant &	val
	)

Seta variável global com o valor recebido como parâmetro.

Para que o valor setado seja uma tabela, val deve conter um objeto do tipo LuaTable. Para setar uma função, o valor deve ser um LuaFunction. Para setar um userdata, val deve conter um void* que aponte para um objeto descendente de LuaProxy::Base

◆ toVariant()

QVariant LuaEnv::toVariant	(	StackOption	opt,
		int	index = `-1`
	)

Retorna o valor contido no topo da pilha como um QVariant. Se index for diferente de -1, retorna o valor associado com este índice.

Ver observações em getGlobal() para tipos de valores processados, retorno e efeitos do parâmetro opt.

IMPORTANTE: Se index != -1, parâmetro opt será sempre tratado como STACK_NOPOP e nenhum valor será removido da pilha.

The documentation for this class was generated from the following files:

inc/luaEnv.h
src/luaEnv.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ LibraryOptions

◆ StackOption

Constructor & Destructor Documentation

◆ LuaEnv()

Member Function Documentation

◆ clearReferences()

◆ getGlobal()

◆ getLocal()

◆ isIdentifier()

◆ loadScriptData()

◆ newState()

◆ registerFunction()

◆ removeSymbols()

◆ runRsrcScript()

◆ runScript()

◆ runScriptStr() [1/2]

◆ runScriptStr() [2/2]

◆ runVerifiedRsrcScript()

◆ setGlobal()

◆ toVariant()