Planilhas Excel

Leia e escreva arquivos Microsoft Excel (.xlsx). Crie workbooks, gerencie planilhas, leia valores de celulas e gere relatorios com suporte a formatação.

Carregamento

local excel = require("excel")

Criando Workbooks

Novo Workbook

Cria um novo workbook Excel vazio.

local wb, err = excel.new()
if err then
    return nil, err
end

-- Criar planilhas e adicionar dados
wb:new_sheet("Report")
wb:set_cell_value("Report", "A1", "Title")

wb:close()

Retorna: Workbook, error

Abrir Workbook

Abre um workbook Excel de um objeto reader.

local fs = require("fs")

local vol, err = fs.get("app:data")
if err then
    return nil, err
end

local file, err = vol:open("/reports/sales.xlsx", "r")
if err then
    return nil, err
end

local wb, err = excel.open(file)
if err then
    file:close()
    return nil, err
end

-- Ler dados do workbook
local rows = wb:get_rows("Sheet1")
for i, row in ipairs(rows) do
    print("Row " .. i .. ": " .. table.concat(row, ", "))
end

wb:close()
file:close()

Retorna: Workbook, error

Operações de Planilha

Criar Planilha

Cria uma nova planilha ou retorna indice da planilha existente.

local wb = excel.new()

-- Criar planilhas
local idx1 = wb:new_sheet("Summary")
local idx2 = wb:new_sheet("Details")
local idx3 = wb:new_sheet("Charts")

-- Se planilha existe, retorna seu indice
local existing = wb:new_sheet("Summary")  -- retorna mesmo que idx1

Retorna: integer, error

Listar Planilhas

Retorna lista de todos os nomes de planilhas no workbook.

local wb = excel.new()
wb:new_sheet("Sales")
wb:new_sheet("Expenses")
wb:new_sheet("Summary")

local sheets = wb:get_sheet_list()
-- sheets = {"Sheet1", "Sales", "Expenses", "Summary"}

for _, name in ipairs(sheets) do
    print("Sheet:", name)
end

Retorna: string[], error

Operações de Celula

Definir Valor de Celula

Define valor de uma unica celula.

local wb = excel.new()
wb:new_sheet("Data")

-- Definir diferentes tipos de valor
wb:set_cell_value("Data", "A1", "Product Name")  -- string
wb:set_cell_value("Data", "B1", "Price")         -- string
wb:set_cell_value("Data", "C1", "In Stock")      -- string

wb:set_cell_value("Data", "A2", "Widget")
wb:set_cell_value("Data", "B2", 29.99)           -- numero
wb:set_cell_value("Data", "C2", true)            -- boolean

wb:set_cell_value("Data", "A3", "Gadget")
wb:set_cell_value("Data", "B3", 49.99)
wb:set_cell_value("Data", "C3", false)

-- Referências de celula suportam colunas alem de Z
wb:set_cell_value("Data", "AA1", "Extended Column")
wb:set_cell_value("Data", "AB100", "Far cell")

Retorna: error

Obter Todas as Linhas

Obtem todas as linhas de uma planilha como array 2D.

local wb = excel.new()
wb:new_sheet("Report")
wb:set_cell_value("Report", "A1", "Name")
wb:set_cell_value("Report", "B1", "Score")
wb:set_cell_value("Report", "A2", "Alice")
wb:set_cell_value("Report", "B2", 95)
wb:set_cell_value("Report", "A3", "Bob")
wb:set_cell_value("Report", "B3", 87)

local rows, err = wb:get_rows("Report")
if err then
    return nil, err
end

-- rows[1] = {"Name", "Score"}
-- rows[2] = {"Alice", "95"}
-- rows[3] = {"Bob", "87"}

for i, row in ipairs(rows) do
    if i == 1 then
        print("Headers:", row[1], row[2])
    else
        print("Data:", row[1], "scored", row[2])
    end
end

Retorna: string[][], error

Todos os valores de celula retornados como strings. Booleans como "TRUE" ou "FALSE", numeros como representação string.

Streaming de Linhas

wb:rows(sheet) abre um cursor de streaming sobre uma planilha. A planilha é decodificada incrementalmente em memória constante, ao contrário de get_rows que materializa a planilha inteira:

local cursor, err = wb:rows("Report")
if err then
    return nil, err
end

while true do
    local batch, err = cursor:read(500)
    if err then
        cursor:close()
        return nil, err
    end
    if not batch then
        break                       -- end of sheet
    end
    for _, row in ipairs(batch) do
        process(row)
    end
end
cursor:close()

Valores de celula são formatados de forma idêntica a get_rows. Linhas vazias retornam como tabelas vazias, e linhas vazias finais são preservadas em vez de cortadas. Após o fim da planilha ou um erro, leituras subsequentes continuam retornando esse mesmo estado.

Operações de Arquivo

Escrever em Arquivo

Escreve workbook para um objeto writer.

local fs = require("fs")
local wb = excel.new()

-- Construir relatorio
wb:new_sheet("Monthly Report")
wb:set_cell_value("Monthly Report", "A1", "Month")
wb:set_cell_value("Monthly Report", "B1", "Revenue")
wb:set_cell_value("Monthly Report", "A2", "January")
wb:set_cell_value("Monthly Report", "B2", 45000)
wb:set_cell_value("Monthly Report", "A3", "February")
wb:set_cell_value("Monthly Report", "B3", 52000)

-- Escrever em arquivo
local vol, err = fs.get("app:output")
if err then
    wb:close()
    return nil, err
end

local file, err = vol:open("/reports/monthly.xlsx", "w")
if err then
    wb:close()
    return nil, err
end

local err = wb:write_to(file)
file:close()
wb:close()

if err then
    return nil, err
end

Retorna: error

Fechar Workbook

Fecha workbook e libera recursos.

local wb = excel.new()
-- ... trabalhar com workbook ...
wb:close()

-- Seguro chamar multiplas vezes
wb:close()

Retorna: error

Erros

Veja Error Handling para trabalhar com erros.

Veja Também

• Filesystem - Operações de arquivo para leitura/escrita de arquivos Excel