Skip to content

Commit c45e153

Browse files
manoelcamposmanoelcampos
committed
Updates readme.
1 parent 25c8582 commit c45e153

File tree

1 file changed

+40
-145
lines changed

1 file changed

+40
-145
lines changed

‎README.md‎

Lines changed: 40 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,73 @@
1-
# Introducão [![Build Status](https://travis-ci.org/manoelcampos/JavaXml2Lua.png?branch=master)](https://travis-ci.org/manoelcampos/JavaXml2Lua) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.manoelcampos/xml2lua/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.manoelcampos/xml2lua) [![Javadocs](https://www.javadoc.io/badge/com.manoelcampos/xml2lua.svg)](https://www.javadoc.io/doc/com.manoelcampos/xml2lua) [![GPL licensed](https://img.shields.io/badge/license-GPL-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
1+
# Java Xml2Lua [![Build Status](https://travis-ci.org/manoelcampos/JavaXml2Lua.png?branch=master)](https://travis-ci.org/manoelcampos/JavaXml2Lua) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.manoelcampos/xml2lua/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.manoelcampos/xml2lua) [![Javadocs](https://www.javadoc.io/badge/com.manoelcampos/xml2lua.svg)](https://www.javadoc.io/doc/com.manoelcampos/xml2lua) [![GPL licensed](https://img.shields.io/badge/license-GPL-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
22

3+
The Java Xml2Lua allows parseing a XML file and converting it to [Lua](http://lua.org) file, represented as a [table](https://www.lua.org/pil/2.5.html), the native data structure of the Lua language.
34

4-
XML é um padrão internacional da W3C para intercâmbio de dados, amplamente utilizado e conhecido. Tal formato permite a troca de dados entre sistemas heterogêneos, garantindo a interoperabilidade entre os mesmos. No entanto, em aplicações interativas para o Sistema Brasileiro de TV Digital, desenvolvidas em NCL e Lua, tem-se uma alternativa bem mais simples que o uso de arquivos XML para a representação, armazenamento e troca de dados: os arquivos de dados em formato Lua, como já mostrei [neste post](http://manoelcampos.com/2010/06/08/aplicacao-de-tv-digital-usando-arquivos-de-dados-em-lua/).
5-
6-
O uso de tais arquivos traz vários benefícios como: tamanho menor (menos bytes), simplicidade de manipulação com uso dos recursos nativos da linguagem Lua (os dados armazenados nos arquivos são tratados como tabelas Lua, estrutura de dados disponibilizada pela linguagem, que funciona como vetores e structs), uso mínimo de processamento para manipular os dados (diferente dos parsers XML como o SAX, que demandam maior capacidade de processamento).
7-
8-
Por demandar uma capacidade mínima de processamento, o uso de arquivos de dados em formato Lua é ideal para ambientes de recursos de hardware restritos como os equipamentos de recepção de TV Digital, além de simplificar o código da aplicação para a manipulação de tais dados.
9-
10-
11-
# O problema
12-
13-
O uso de arquivos XML em aplicações NCL/Lua para a TVD (enviadas via broadcast) é perfeitamente possível desde que tenha-se um parser escrito inteiramente em Lua, como o módulo homônimo [xml2lua](https://github.com/manoelcampos/xml2lua), escrito inteiramente em Lua. Tal parser converte um arquivo XML para uma tabela Lua, armazenando a mesma em RAM. Desta forma, a manipulação dos dados fica mais fácil. No link anterior existe uma versão do parser, adaptada por mim, que funciona com Lua 5 (a versão utilizada no subsistema Ginga-NCL do middleware Ginga).
14-
15-
No entanto, tal abordagem pode ser problemática quando se precisa carregar tal arquivo XML do disco, usando Lua. A norma ABNT NBR 15606-2 versão 3 (atualizada em 2009) na seção "10.1 Linguagem Lua - Funções removidas da biblioteca de Lua" mostra que nenhuma função do módulo IO de Lua (que permite a manipulação de arquivos em disco) deve estar disponível para aplicações de TVD. Uma atualização de 2011 da norma (ABNT NBR 15606-2 2011 Ed2) passou a incluir o módulo IO, no entanto, muitas das implementações de Ginga existentes no mercado são anteriores a esta revisão da norma. Assim, se os fabricantes seguiram a norma vigente na época, o módulo IO não deve estar disponível.
16-
17-
Apesar de ser possível a atualização do middleware, sabemos que nem todos os usuários se preocuparão com isso, e as formas de atualização podem variar de fabricante para fabricante, sendo que alguns podem requerer conexão da TV/conversor à Internet para tal atualização.
18-
19-
Desta forma, usar arquivos XML localmente não garante que a aplicação executará em qualquer implementação de Ginga.
20-
21-
22-
# A solução: Java Xml2Lua
23-
24-
Para resolver tal problema, estou disponibilizando uma aplicação console em Java para converter um arquivo XML para o formato Lua. A aplicação utiliza o parser DOM (que se não estou errado é padrão no JDK e JRE) para percorrer os elementos do arquivo XML e assim poder gerar um arquivo Lua com os dados contidos no primeiro.
25-
26-
Para tal conversão, poderia ser utilizada qualquer linguagem de programação, até mesmo Lua, com uso do módulo homônimo [xml2lua](https://github.com/manoelcampos/xml2lua) (para fazer o parse do XML) e o [table.save](http://lua-users.org/wiki/SaveTableToFile) (para salvar a tabela Lua, gerada a partir do XML, em disco). No entanto, o arquivo lua gerado com o table.save não ficou muito organizado e incluiu muito lixo, dificultando a manipulação dos dados. Por este motivo, resolvi implementar a ferramenta em Java.
27-
28-
A implementação realizada está disponível no final do artigo, juntamente com toda a documentação e código fonte.  Ela possui uma ferramenta de linha de comando (para ser usada antes de enviar a aplicação NCL/Lua via broadcast) para fazer a conversão do XML para Lua. Além disto, existe também uma classe Java que pode ser usada em qualquer outra aplicação (Desktop ou Web), permitindo a integração de tal implementação em sistemas já existentes, para, por exemplo, automatizar a conversão dos arquivos XML para Lua, para assim poderem ser enviados pelo carrossel para transmissão em broadcast.
29-
30-
# Documentação
31-
32-
A documentação da API está [disponível online aqui](http://manoelcampos.github.io/Xml2Lua/apidocs).
33-
34-
# Usando a ferramenta
35-
36-
Para usar a ferramenta de linha de comando, basta executar em um terminal:
37-
38-
```bash
39-
java -jar xml2lua.jar NomeArquivoXML
40-
```
41-
42-
Note que deve-se informar o nome de um arquivo XML. A aplicação gerará um arquivo Lua de mesmo nome, dentro do diretório atual.
43-
44-
# Estudo de caso
45-
46-
Para exemplificar o uso da ferramenta, vamos imaginar que temos uma aplicação NCL/Lua de uma loja virtual, que precisa exibir uma lista de produtos na tela. As informações de tais produtos estão em um arquivo XML que será convertido para um arquivo Lua.
47-
48-
Para isto, usaremos um arquivo de nome produtos.xml, com o conteúdo a seguir. Todos os arquivos XML e o código do exemplo apresentado aqui está disponível na pasta [lua-sample-app](lua-sample-app).
5+
It gets a XML file such as the following as input:
496

507
```xml
51-
<produtos>
52-
<produto id="12">
53-
<descricao>TV 32''</descricao>
54-
<marca>Samsung</marca>
55-
<preco>1200</preco>
56-
</produto>
57-
<produto id="150">
58-
<descricao>Netbook</descricao>
59-
<marca>Asus</marca>
60-
<preco>900</preco>
61-
</produto>
62-
<produto id="198">
63-
<descricao>Impressora Laser</descricao>
64-
<marca>Samsung</marca>
65-
<preco>399</preco>
66-
</produto>
67-
<produto id="201">
68-
<descricao>Resma de Papel A4 (500 folhas)</descricao>
69-
<marca>Office</marca>
70-
<preco>9</preco>
71-
</produto>
72-
<produto id="17">
73-
<descricao>Resma de Papel A4 (100 folhas)</descricao>
74-
<marca>Office</marca>
75-
<preco>3</preco>
76-
</produto>
77-
</produtos>
78-
```
79-
80-
Para converter tal arquivo para Lua, entre no diretório bin por um terminal e execute:
81-
82-
```bash
83-
java -jar xml2lua.jar produtos.xml
8+
<products>
9+
<product id="12">
10+
<description>TV 32''</description>
11+
<brand>Samsung</brand>
12+
<price>1200</price>
13+
</product>
14+
<product id="150">
15+
<description>Netbook</description>
16+
<brand>Asus</brand>
17+
<price>900</price>
18+
</product>
19+
</products>
8420
```
8521

86-
Isto considerando que o arquivo produtos.xml está no diretório bin.
87-
88-
Como pode ser visto no XML anterior, cada produto tem um atributo id na tag produto. Este id identifica unicamente cada produto.
89-
Como as tabelas da linguagem Lua possuem a excelente característica de poderem funcionar como vetores e terem índices de qualquer tipo e valor, além de não terem a obrigatoriedade de os mesmos serem sequenciais, a ferramenta Xml2Lua desenvolvida usa tal atributo id do XML como o índice de cada produto na tabela lua (gerada a partir do XML).
90-
91-
Assim, o código Lua gerado no arquivo produtos.lua ficará como mostrado a seguir:
22+
Then, it converts it to a Lua file, representing the XML data as a Lua table:
9223

9324
```lua
94-
return {
25+
products = {
9526
[12]={
96-
descricao = "TV 32''", marca = "Samsung", preco = "1200",
27+
description = "TV 32''", brand = "Samsung", price = "1200",
9728
},
9829
[150]={
99-
descricao = "Netbook", marca = "Asus", preco = "900",
30+
description = "Netbook", brand = "Asus", price = "900",
10031
},
10132
[198]={
102-
descricao = "Impressora Laser", marca = "Samsung", preco = "399",
103-
},
104-
[201]={
105-
descricao = "Resma de Papel A4 (500 folhas)", marca = "Office", preco = "9",
106-
},
107-
[17]={
108-
descricao = "Resma de Papel A4 (100 folhas)", marca = "Office", preco = "3",
33+
description = "Laser Printer", brand = "Samsung", price = "399",
10934
},
11035
}
11136
```
11237

113-
Os valores entre chaves são os índices da tabela. Desta forma, nossa tabela não tem índices sequenciais (1, 2, 3...) e sim 12, 150, 198, 201 e 17. O nome do atributo que será usado como índice da tabela Lua deve ser id, mas o código Java pode ser alterado para o nome de atributo que desejar (ao até mesmo alterado para passar tal informação por parâmetro para a aplicação).
38+
# Using it as a Maven dependency into your own project
11439

115-
Tal recurso é de fundamental importância, considerando agora o seguinte cenário: a aplicação de TVD em NCL/Lua precisa exibir na tela inicial apenas os produtos em destaque. Tais produtos estão relacionados em outro arquivo XML de nome destaques.xml, cujo conteúdo é apresentado a seguir (também disponível no pacote para download).
40+
The library can be added as a Maven dependency into your own project, by adding the following code to your pom.xml file:
11641

11742
```xml
118-
<destaques>
119-
<destaque id="150" />
120-
<destaque id="17" />
121-
<destaque id="198" />
122-
</destaques>
43+
<dependency>
44+
<groupId>com.manoelcampos</groupId>
45+
<artifactId>xml2lua</artifactId>
46+
<version>1.0.0</version>
47+
</dependency>
12348
```
12449

125-
No exemplo, de todos os produtos a serem exibidos na aplicação de TVD (no nosso exemplo são um total de 5), apenas 3 devem ser exibidos na tela inicial. Os outros produtos existentes poderiam ser encontrados pelo usuário por meio de um campo de busca na aplicação.
126-
127-
Com o requisito apresentado, o uso do id do produto como índice da tabela Lua (gerada a partir do XML de produtos) facilita a implementação de tal requisito. Se os índices da tabela produtos fossem sequenciais, para cada produto em destaque, seria preciso fazer um for dentro da tabela de produtos para encontrar tal produto e poder exibir seus dados na tela. Considerando nossos 3 produtos em destaque e 5 produtos cadastrados, teríamos um total de 15 iterações.
50+
Using the `Xml2Lua` class to convert a XML to a Lua file requires just few lines of code:
12851

129-
Usando o id dos produtos como índice da tabela produtos, para exibir os produtos em destaque, precisamos fazer um for apenas na tabela de destaques. Como o arquivo destaques.xml (apresentado anteriormente) não possui nenhum sub-elemento, tendo apenas o atributo id, tal atributo não é usado como índice da tabela destaques e sim como um campo normal. Assim, os índices da tabela destaque serão sequenciais. Desta forma, o código Lua gerado a partir do destaques.xml será como mostrado abaixo:
130-
131-
```lua
132-
return {
133-
{
134-
id=150
135-
},
136-
{
137-
id=17
138-
},
139-
{
140-
id=198
141-
},
142-
}
52+
```java
53+
Xml2Lua parser = new Xml2Lua(xmlFilePath);
54+
parser.convert();
55+
System.out.printf("Lua file %s generated successfully from the %s.\n", parser.getLuaFileName(), parser.getXmlFilePath());
14356
```
14457

145-
A partir de um for em tal tabela, pegando-se o valor do campo id, pode-se acessar a tabela produtos diretamente (sem precisar fazer um for nela) na posição do id da tabela destaques. Assim, serão apenas 3 iterações.
58+
# Using it as a command line tool
14659

60+
You can use the available command tool to convert XML to Lua using the command line.
61+
If you downloaded the project source code, when you build it using `mvn clean install`
62+
or some IDE, a jar file will be created inside the target directory.
14763

148-
## Código da aplicação Lua
64+
Alternatively, you can simply download the jar file from the [releases](https://github.com/manoelcampos/JavaXml2Lua/releases) page.
14965

150-
Após terem sido convertidos os arquivos produtos.xml e destaques.xml para Lua, podemos ter uma aplicação Lua  para carregar tais arquivos Lua e exibir os dados, como pode ser visto no trecho de código a seguir. A aplicação não possui interface gráfica pois isto está fora do escopo do artigo. Ela apenas exibe os dados no terminal. Tal código está disponível no arquivo app.lua, no pacote para download.
151-
152-
```lua
153-
local produtos = dofile("produtos.lua")
154-
local destaques = dofile("destaques.lua")
155-
156-
local prod = {}
157-
for i, dest in pairs(destaques) do
158-
prod = produtos[dest.id]
159-
print("Id: ", dest.id, "Marca:", prod.marca, "Preço:", prod.preco, "Descrição:", prod.descricao)
160-
end
161-
```
162-
163-
As duas primeiras linhas carregam os arquivos de dados Lua e armazenam a tabela contida neles em variáveis locais. Em seguida é feito um for na tabela de destaques, pegando o id de cada produto em destaque, e por meio dele, acessando diretamente os dados do produto na tabela produto, exibindo-os no terminal.
164-
165-
Como tal aplicação é apenas de exemplo e não usa nenhum recurso do Ginga-NCL, a mesma pode ser executada fora dele, em um terminal (obviamente tendo o interpretador Lua instalado) com o comando:
66+
Once you have the jar file, you can run it as below:
16667

16768
```bash
168-
lua app.lua
69+
java -jar xml2lua.jar XmlFilePath
16970
```
17071

72+
The tool will generate a Lua file with the same name of the XML file, inside the directory of the XML file.
17173

172-
# Conclusão
173-
174-
Como as aplicações de TVD (por exemplo, as de comércio eletrônico) podem ser apenas uma nova interface gráfica para sistemas já existentes que usam XML, WebServices e outras tecnologias como a base da arquitetura destes, implementar a geração de arquivos de dados Lua em tais arquiteturas pode ser algo trabalhoso.
175-
176-
Assim, com a implementação apresentada, pode-se utilizar os arquivos XML que por ventura já sejam gerados por sistemas existentes, e convertê-los para arquivos Lua para uso em uma aplicação para a TV Digital, sem precisar necessariamente alterar os sistemas existentes.
177-
178-
Com isto, o equipamento de TVD fica livre do overhead do parse do arquivo XML, por menor que este seja com o uso do módulo homônimo [xml2lua](https://github.com/manoelcampos/xml2lua).

0 commit comments

Comments
 (0)