Lua Academy · Lección

La función require

Cargue módulos externos con require y comprenda el almacenamiento en caché de módulos.

La función require es una lección gratuita de Lua Academy en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Lua Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Lua Academy incluye 4 lecciones en total.

Cómo funciona require

require(modname) carga y devuelve un módulo. Busca un archivo .lua en package.path y una biblioteca de C en package.cpath. El resultado se almacena en la caché package.loaded[modname]; las llamadas posteriores devuelven el valor almacenado sin volver a ejecutar el archivo.

-- 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 devuelto por un módulo

Un archivo de módulo debe devolver un valor, normalmente una tabla de funciones. Este valor devuelto es lo que require entrega a quien llama. Si el archivo no devuelve nada (o devuelve true), eso es lo que devuelve require.

-- 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

Almacenamiento en caché en package.loaded

package.loaded es una tabla que asocia nombres de módulos con sus valores cargados. Puede establecer manualmente una entrada para precargar un simulacro, o establecerla en nil para forzar una recarga (el archivo del módulo volverá a ejecutarse en el siguiente 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 es una lista de patrones separados por punto y coma. El marcador ? se sustituye por el nombre del módulo (con los puntos reemplazados por separadores de ruta). Puede añadir directorios de búsqueda anteponiéndolos a 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 frente a dofile y loadfile

require: almacena en caché y busca en package.path. dofile(path): ejecuta un archivo inmediatamente, no almacena el resultado en caché y recibe una ruta directa. loadfile(path): compila el archivo, pero no lo ejecuta, y devuelve una función. Use require para módulos y dofile para scripts puntuales.

-- 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 con puntos para directorios

Use puntos en los nombres de módulos para hacer referencia a archivos de subdirectorios. require("utils.string") se transforma en utils/string.lua (con ? en el patrón de ruta). Así se organizan las bibliotecas compuestas por varios archivos.

-- 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

Efectos secundarios de la inicialización de módulos

Los archivos de módulo se ejecutan una vez, cuando se requieren por primera vez. Cualquier código del nivel superior (fuera de las funciones) se ejecuta en el momento de llamar a require. Esto resulta útil para inicializaciones únicas, pero tenga cuidado: los efectos secundarios, como las conexiones de red o las operaciones con archivos, se ejecutan al importar el módulo.

-- 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)

Gestión de errores en require

Si un archivo de módulo contiene un error de sintaxis o produce un error durante la carga, require lanza un error. El mensaje de error incluye el nombre del módulo y el error producido dentro del archivo. Use pcall para gestionar correctamente los fallos de carga de módulos.

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 es una tabla en la que puede registrar funciones de carga por nombre de módulo. Cuando se llama a require("name"), Lua comprueba primero la precarga. Esto permite registrar módulos sin archivos, lo que resulta útil para Lua embebido o para pruebas.

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

Las dependencias circulares (A requiere B y B requiere A) se gestionan parcialmente: Lua almacena un marcador de posición true en package.loaded antes de ejecutar el módulo. Si B intenta utilizar la tabla sin terminar de A, puede obtener resultados incompletos. Evite las dependencias circulares al diseñar 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")

Comprobación rápida

¿Qué ocurre cuando llama a require("mod") por segunda vez?

Resumen: require

Resumen:

require(name) carga una sola vez y almacena en caché el resultado en package.loaded
El archivo del módulo devuelve su interfaz pública (normalmente una tabla)
Borre package.loaded[name] para forzar la recarga
Añada rutas a package.path para incluir directorios de búsqueda personalizados
Use package.preload para módulos en memoria
Evite las dependencias circulares

Preguntas frecuentes

¿La lección «La función require» es gratis?

Sí — el texto completo de «La función require» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Lua Academy, actualiza a CoddyKit PRO. El curso de Lua Academy incluye 4 lecciones en total.

¿Qué aprenderé en «La función require»?

Cargue módulos externos con require y comprenda el almacenamiento en caché de módulos. Practicas Lua Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Lua Academy?

No se requiere experiencia previa. Lua Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «La función require»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Lua Academy?

Sí. Cada lección de Lua Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a Lua Academy