XML

Um arquivo XML é carregado inteiro para a memória e vira uma árvore de nós. Todas as funções desta página trabalham em cima de um handle de nó — o que xmlLoadFile devolve é o handle do nó raiz do documento, e a partir dele você chega em todos os outros.

O ciclo é sempre este: carregar → ler ou alterar → gravar → descarregar. Nada é escrito no disco enquanto você não chamar xmlSaveFile; e enquanto você não chamar xmlUnloadFile, o documento continua ocupando memória.

Um ciclo completo

local caminho = "config/lojas.xml"

-- 1. carrega o arquivo; se ele ainda não existir, começa um documento novo
local raiz = xmlLoadFile(caminho) or xmlCreateFile(caminho, "lojas")
if not raiz then return end

-- 2. lê o que já está lá
for _, loja in ipairs(xmlNodeGetChildren(raiz)) do
    outputDebugString(xmlNodeGetAttribute(loja, "nome") .. " em " .. xmlNodeGetValue(loja))
end

-- 3. acrescenta uma entrada
local nova = xmlCreateChild(raiz, "loja")
xmlNodeSetAttribute(nova, "nome", "Ammu-Nation")
xmlNodeSetValue(nova, "1366.0, -1279.0, 13.5")

-- 4. grava no disco e libera a memória
xmlSaveFile(raiz)
xmlUnloadFile(raiz)

Quem recebe caminho e quem recebe nó

Só três funções conhecem arquivos: xmlLoadFile e xmlCreateFile recebem um caminho, e xmlCopyFile recebe um nó e um caminho novo. Todas as outras trabalham exclusivamente com handles de nó.

Regras de caminho

Todo caminho é resolvido a partir da pasta do resource que está rodando o script, exatamente como nas funções de arquivo. Não existe forma de sair dela.

São recusados caminhos absolutos (começando com /), qualquer caminho com :, segmentos . ou .., barras duplicadas e caminho vazio. Barras invertidas viram / e um @ no começo é ignorado. Ao gravar, as pastas que faltarem no caminho são criadas.

Nota

xmlSaveFile e xmlUnloadFile só aceitam o nó raiz do documento. Passar um nó de dentro da árvore para elas não faz nada e devolve false.

Depois de xmlUnloadFile, todos os handles daquele documento — inclusive os filhos que você tinha guardado em variáveis — param de funcionar. O mesmo vale para os nós que estavam abaixo de um nó apagado com xmlDestroyNode.

Como as falhas aparecem

Quando o handle não é um nó válido, quando o documento já foi descarregado ou quando um argumento é do tipo errado, a função devolve false e escreve um aviso no console de debug. Nenhuma delas interrompe o script com erro.

Estas 18 funções existem no servidor e no cliente. Você pode usá-las em scripts declarados em server_files, client_files ou shared_files.

xmlLoadFile Carrega um arquivo XML do resource.

xmlLoadString Interpreta um XML que já está em memória, sem passar por arquivo nenhum.

xmlCreateFile Começa um documento novo, do zero.

xmlSaveFile Grava o documento no arquivo dele.

xmlCopyFile Duplica um nó, com tudo que está abaixo dele, para um documento novo.

xmlUnloadFile Descarrega o documento da memória.

xmlCreateChild Cria um nó filho.

xmlDestroyNode Apaga um nó e tudo que está abaixo dele.

xmlFindChild Procura um filho por nome de tag.

xmlNodeGetName Lê o nome da tag de um nó.

xmlNodeSetName Renomeia a tag de um nó.

xmlNodeGetValue Lê o texto que está entre as tags do nó.

xmlNodeSetValue Define o texto que fica entre as tags do nó.

xmlNodeGetParent Devolve o nó pai.

xmlNodeGetChildren Lista os filhos de um nó, ou pega um filho específico.

xmlNodeGetAttributes Lê todos os atributos de um nó de uma vez.

xmlNodeGetAttribute Lê um atributo.

xmlNodeSetAttribute Cria, altera ou remove um atributo.