Lua Academy · Aula

A função require

Carregue módulos externos com require e compreenda o armazenamento em cache de módulos.

A função require é uma aula grátis de Lua Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Lua Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Lua Academy inclui 4 aulas no total.

Como require funciona

require(modname) carrega e retorna um módulo. Ele pesquisa package.path em busca de um arquivo .lua e package.cpath em busca de uma biblioteca C. O resultado é armazenado em cache em package.loaded[modname] — chamadas posteriores retornam o valor armazenado em cache sem executar o arquivo novamente.

-- First require: loads and executes math_utils.lua
local math_utils = require("math_utils")

-- Second require: returns cached value (file not re-run)
local math_utils2 = require("math_utils")

print(math_utils == math_utils2)   -- true (same object)
print(package.loaded["math_utils"] == math_utils)  -- true

Valor retornado pelo módulo

Um arquivo de módulo deve retornar um valor — normalmente uma tabela de funções. Esse valor retornado é o que require devolve ao chamador. Se o arquivo não retornar nada (ou retornar true), é isso que require retornará.

-- mymodule.lua:
-- local M = {}
-- function M.hello() print("Hello from module!") end
-- return M

-- In main script:
local m = require("mymodule")
m.hello()   -- Hello from module!

-- The module table is the interface

Armazenamento em cache em package.loaded

package.loaded é uma tabela que associa nomes de módulos aos valores carregados. Você pode definir manualmente uma entrada para pré-carregar um objeto simulado ou defini-la como nil para forçar um novo carregamento (o arquivo do módulo será executado novamente no próximo require).

-- Force reload by clearing cache
package.loaded["mymodule"] = nil
local fresh = require("mymodule")  -- re-executes the file

-- Preload a mock for testing
package.loaded["db"] = {
  query = function() return {} end,
  close = function() end,
}
local db = require("db")  -- gets the mock

Formato de package.path

package.path é uma lista de padrões separados por ponto e vírgula. O marcador ? é substituído pelo nome do módulo (com os pontos substituídos pelos separadores de caminho). Você pode adicionar diretórios à pesquisa colocando-os no início de package.path.

print(package.path)
-- typically: ./?.lua;./?.luac;/usr/share/lua/5.4/?.lua;...

-- Add local lib directory
package.path = "./lib/?.lua;" .. package.path

-- Now require("utils") will look in ./lib/utils.lua

require versus dofile versus loadfile

require: armazena em cache e pesquisa package.path. dofile(path): executa um arquivo imediatamente, sem armazenamento em cache, usando um caminho direto. loadfile(path): compila, mas não executa, e retorna uma função. Use require para módulos; dofile para scripts executados uma única vez.

-- dofile: no caching, direct path
dofile("./scripts/setup.lua")

-- loadfile: compile only, returns function
local fn, err = loadfile("./config.lua")
if fn then
  local result = fn()   -- execute when ready
end

-- require: best for modules
local json = require("json")

require com pontos para diretórios

Use pontos nos nomes de módulos para referenciar arquivos em subdiretórios. require("utils.string") é mapeado para utils/string.lua (com ? no padrão de caminho). É assim que bibliotecas com vários arquivos são organizadas.

-- Directory structure:
-- lib/
--   utils/
--     string.lua
--     table.lua
--   init.lua

package.path = "./lib/?.lua;" .. package.path

local strUtils = require("utils.string")   -- loads lib/utils/string.lua
local tblUtils = require("utils.table")    -- loads lib/utils/table.lua

Efeitos colaterais da inicialização de módulos

Os arquivos de módulo são executados uma vez, quando são exigidos pela primeira vez. Qualquer código no nível superior (fora das funções) é executado no momento do require. Isso é útil para inicializações únicas, mas tenha cuidado — efeitos colaterais como conexões de rede ou operações de arquivo são executados no momento da importação.

-- counter.lua:
-- local count = 0   -- initialized once on first require
-- local M = {}
-- function M.increment() count = count + 1 end
-- function M.get() return count end
-- return M

local c = require("counter")
c.increment()
c.increment()
print(c.get())   -- 2

local c2 = require("counter")
print(c2.get())  -- 2 (same instance, cached)

Tratamento de erros em require

Se um arquivo de módulo tiver um erro de sintaxe ou gerar um erro durante o carregamento, require gerará um erro. A mensagem de erro inclui o nome do módulo e o erro ocorrido dentro do arquivo. Use pcall para tratar falhas no carregamento de módulos com elegância.

local ok, mod = pcall(require, "possibly_missing")
if not ok then
  print("Module not available:", mod)
  -- fall back to alternative or default implementation
  mod = {feature = function() return "fallback" end}
end

print(mod.feature())

package.preload

package.preload é uma tabela na qual o senhor pode registrar funções de carregamento por nome de módulo. Quando require("name") é chamado, Lua verifica primeiro o preload. Isso permite registrar módulos sem arquivos — útil para Lua incorporado ou testes.

package.preload["mymath"] = function()
  return {
    double = function(n) return n * 2 end,
    triple = function(n) return n * 3 end,
  }
end

local m = require("mymath")
print(m.double(5))   -- 10
print(m.triple(5))   -- 15

Require circular

As dependências circulares (A requer B, B requer A) são parcialmente tratadas: Lua armazena um marcador true em package.loaded antes de executar o módulo. Se B tentar usar a tabela inacabada de A, poderá obter resultados incompletos. Evite dependências circulares no projeto dos módulos.

-- a.lua: local b = require("b"); local M = {}; M.name = "A"; return M
-- b.lua: local a = require("a"); print("a.name:", a.name); return {}

-- When a.lua is loaded:
-- 1. a starts executing
-- 2. requires b -> b starts executing
-- 3. b requires a -> gets partial a (still loading!)
-- 4. a.name may be nil at step 3

print("Avoid circular requires in module design")

Verificação rápida

O que acontece quando o senhor chama require("mod") uma segunda vez?

Recapitulação: require

Resumo:

require(name) carrega uma vez e armazena em cache em package.loaded
O arquivo do módulo retorna sua interface pública (geralmente uma tabela)
Limpe package.loaded[name] para forçar o recarregamento
Adicione diretórios de pesquisa personalizados a package.path
Use package.preload para módulos mantidos na memória
Evite dependências circulares

Perguntas Frequentes

A aula “A função require” é grátis?

Sim — o texto completo de “A função require” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Lua Academy, atualize para CoddyKit PRO. O curso de Lua Academy inclui 4 aulas no total.

O que vou aprender em “A função require”?

Carregue módulos externos com require e compreenda o armazenamento em cache de módulos. Você pratica Lua Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Lua Academy?

Nenhuma experiência prévia é necessária. Lua Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “A função require”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Lua Academy?

Sim. Cada aula de Lua Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Lua Academy