이 문서는 한국어 위키백과의 정보문입니다. 이 문서는 정책과 지침은 아니지만, 위키백과의 규범과 관습 측면에서 공동체의 확립된 관행을 설명하고 있습니다. 공동체의 총의나 검토를 어느 정도 반영하고 있습니다.

단축 백:모듈

루아는 위키백과에서 모듈을 제작할 때 사용할 수 있는 프로그래밍 언어입니다. 루아 코드는 모듈:Bananas처럼 모듈 이름공간에 저장됩니다. 모듈 기능은 미디어위키의 Scribunto 확장 기능을 통해 구현되었으며 현재 루아 언어만 지원하고 있습니다.

모듈은 틀 문서에서 Scribunto의 기능 중 하나인 {{#invoke:모듈 이름|함수 이름|...}} 문법을 이용하여 한 번의 호출마다 1개의 함수씩 사용할 수 있습니다.^[1]

모듈은 모듈 이름공간을 제외한 모든 이름공간에서 {{#invoke:모듈 이름}}을 사용하여 실행할 수 있습니다. 매개변수로 준 입력값들을 기반으로 처리한 결과값을 받을 수 있다는 점에서 {{틀 이름}} 문법으로 틀이 동작하는 방식과 {{#invoke:모듈 이름}} 문법으로 모듈이 동작하는 방식은 비슷합니다. 하지만 몇 가지 차이점이 있는데, 그 중 대표적인 차이점은 모듈을 사용하고자 할 땐 사용하려는 하는 모듈 안 ‘함수 이름’을 적어줘야 한다는 점입니다. 여기서 ‘함수’의 의미란 값들을 입력받아 처리한 후에 그 결과값을 반환하는 명령문들을 모아놓은 것을 말합니다.^[2] 또 다른 차이점으로는 1개의 틀 문서에는 1개의 틀만 정의할 수 있는 반면, 1개의 루아 모듈 문서에는 여러 개의 함수를 정의할 수 있다는 점입니다.^[3]

그뿐만 아니라 단독으로 사용할 수 있는 틀과는 달리 루아 모듈은 그 자체만 가지고는 직접 실행할 수 없으며 한 번의 invoke당 하나의 함수만 실행할 수 있다는 차이점도 있습니다. 모듈은 함수들을 모아놓은 것에 불과하며 모듈 자체로는 아무것도 하지 못합니다.^[4] 결국 루아 엔진이 모듈을 불러왔을 때 함수 이름을 기재하지 않은 경우 모듈 그 자체를 실행할 수 없는데다 모듈 안의 함수 중에서 어떤 함수를 실행해야 할 지 모르기 때문에, 모듈을 사용하고자 할 땐 사용하려는 함수 이름을 같이 넣어주어야 합니다.

위키 문서에서 모듈을 실행하는 가장 간단한 방법은 다음과 같습니다.

{{#invoke:모듈 이름|함수 이름}}

예를 하나 들자면, 모듈:Bananas에 있는 "hello"란 이름을 가진 함수는 아래의 구문과 같은 방식으로 실행할 수 있습니다.

• {{#invoke:Bananas|hello}} → Hello, world!

매개변수는 틀에 전달되는 방식과 동일한 방식을 이용하여 모듈에 전달됩니다. 하지만 주의해야 할 것이 있는데, 첫 번째 수직선 문자(|)의 뒤에 위치해야 하는 것은 반드시 함수 이름이여야 하며, 모듈로 전달될 첫 번째 매개변수는 두 번째 수직선 문자(|)의 뒤에 위치해야 한다는 것입니다.

{{#invoke:모듈 이름|함수 이름|첫 번째 변수|두 번째 변수|변수 이름=값}}

예를 몇개 들자면, 모듈:BananasArgs의 "hello" 함수는 다음의 코드처럼 첫 번째 매개변수에 따라 서로 다른 사람들에게 인사합니다.

• {{#invoke:BananasArgs|hello|서연}} → 안녕하세요, 서연님!
• {{#invoke:BananasArgs|hello|민준}} → 안녕하세요, 민준님!

또한 BananasArgs엔 바나나와 사과란 (이름을 가진) 매개변수를 사용하여 사용자가 가지고 있는 바나나와 사과의 갯수를 입력받는 "count_fruit"란 함수가 존재하며 다음과 같이 동작합니다.

• {{#invoke:BananasArgs|count_fruit|사과=3|바나나=4}} → 저는 바나나 4개와 사과 3개를 가지고 있습니다.
• {{#invoke:BananasArgs|count_fruit|바나나=5|사과=2}} → 저는 바나나 5개와 사과 2개를 가지고 있습니다.

대부분의 모듈은 사용할 수 있는 매개변수들과 그 매개변수들이 어떤 역할을 하는지를 잘 설명한 설명문서를 가지고 있습니다.

• 모듈:Bananas: 가장 간단한 구문으로, 매개변수가 없는 함수 하나를 제공합니다.
• 모듈:BananasArgs: 변수에 접근하여 사용하는 방법을 설명합니다.

루아를 이용해서 틀을 만드는데 도움을 얻고 싶다면 위키백과토론:루아나 위키백과:사랑방 (기술)에 요청을 남겨 주세요.

Brad Jorsch's short presentation for a basic example of how to convert a wikitext template into a Lua module (PDF)도 참고하세요

루아는 자료를 분석하고, 수식을 계산하며, 함수와 객체지향 프로그래밍을 사용한 결과를 서식화하는 스크립트 언어입니다. 어떤 루아 스크립트는 간단하지만, 표, 동적 함수, 연관 배열을 사용해서 컴퓨터 과학자들에게 흥미를 끌 정도로 복잡한 구문도 만들 수 있습니다.루아는 함수를 재귀적으로 사용할 수 있기 때문에 다른 사용자들이 모듈을 편집하는데 혼란을 줄 정도로 복잡하게 만들어서는 안됩니다. 아래는 모듈:HelloWorld에서 볼 수 있으며 "hello" 함수를 만드는 소스코드입니다:

-- 위키백과의 모든 모듈은 테이블 변수를 정의해주는 것부터 시작해야 합니다.
-- 이 변수는 모듈 외부에서 접근하는 함수들이 이 모듈을 쓸 수 있게끔 해줍니다.
my_object = {};

-- 테이블 변수에 함수를 추가합니다. 함수를 쓸땐 #invoke 명령어로 쓸수 있습니다.
-- "frame"엔 위키백과에서 함수를 호출했을 때 같이 전달된 데이터(매개변수 등)가
-- 포함되어 있을 것입니다.
my_object.hello = function( frame ) 
 
    -- 지역 변수를 선언한 뒤 데이터를 넣습니다.
    -- (이 과정을 '값을 대입한다'라고 표현하기도 합니다.)
    local str = "Hello World!"  
 
    -- 함수를 종료함과 동시에 "str"의 데이터를 위키백과로 반환합니다.
    -- "print" 함수는 허용되지 않으므로 위키백과로 출력할 데이터들은 이 방법처럼
    -- 문자열로 반환해야 합니다.
    return str
 
-- 함수의 끝입니다.
end
 
-- 위키백과의 모든 모듈은 함수가 포함된 변수를 반환하는 것으로 끝나야 합니다.
return my_object
 
-- 이제 {{#invoke: HelloWorld | hello }}를 통해 이 모듈을 쓸 수 있습니다.
-- #invoke 명령어를 쓸 땐 모듈의 이름(HelloWorld)을 넣고,
-- 쓰고자 하는 함수의 이름(hello)을 매개변수로 넣어줍니다.

루아 코드의 샘플은 <syntaxhighlight lang="lua">...</syntaxhighlight> 태그를 사용하여 나타낼 수 있습니다. 루아에 대한 더 자세한 설명은 루아 (프로그래밍 언어)에서 찾을 수 있습니다. 미디어 위키에서 루아를 사용하는 방법은 mw:Extension:Scribunto/Lua reference manual에서 찾을 수 있습니다.

위키백과엔 모듈:UnitTests이라는 루아 스크립트를 위한 유닛 테스팅 프레임워크가 있습니다. 이 프레임워크는 여러 개의 입력값을 여러분의 스크립트에 넣은 뒤 결과값이 기대한대로 잘 출력되는지 확인할 수 있게 해줍니다. 또한 유닛 테스트 기법을 사용하기 때문에 스크립트를 수정하면서 발생한 새로운 문제들, 즉 회귀 버그를 빠르게 잡아낼 수 있어서 매우 유용합니다.

유닛 테스트를 수행하는 모듈은 영어 위키백과의 관례에 따라 테스트 대상 모듈의 '시험장' 하위문서에 저장하며, 그 하위문서의 토론문서에서 유닛 테스트를 실행합니다. 예로 들어 모듈:Bananas 같은 모듈이 있을 경우, 이 모듈의 유닛 테스트는 모듈:Bananas/시험장에 위치하게 되며, 모듈토론:Bananas/시험장에서 {{#invoke: Bananas/testcases | run_tests}}식으로 실행시킵니다. 또한 테스트 메소드의 이름은 반드시 "test"로 시작해야 합니다. 아래는 모듈:Bananas/시험장에서 가져온 간단한 예제입니다.

-- [[모듈:Bananas]]의 테스트 케이스입니다. 테스트를 하려면 '토론'을 클릭하세요.
local p = require('Module:UnitTests')

function p:test_hello()
    self:preprocess_equals('{{#invoke:Bananas | hello}}', 'Hello, world!')
end

return p

유닛 테스트를 수행하는 모든 모듈들을 보려면 특수:가리키는문서/모듈:UnitTests을 참조하세요.

또한 모듈:ScribuntoUnit이라 불리는 헝가리어 위키백과에서 유래한 대용 유닛 테스팅 프레임워크가 있습니다. 모듈:UnitTests와 기능이 매우 비슷하나 코딩 스타일이 다를 뿐더러 보호된 호출(pcall)로 잡은 실제 오류를 던져줍니다. 또한 주어진 정밀도 내에서 실수를 비교하는 메소드도 가지고 있습니다.

무엇보다 먼저, 루아는 {{#invoke:}}를 통하여 문자열만을 변수로 전달받을 수 있습니다. 또한 frame:expandTemplate, frame:preprocess 등을 통과한 문자열들만 전달받을 수 있습니다. 또한 위키백과의 루아는 저장 전 변환^[5]이나, 틀 또는 {{...}} 구문들을 포함한 문자열은 정상적으로 출력할 수 없습니다. 또한, 한 문서에 포함되는 모든 루아 프로그램은 CPU 시간^[6]이 10초를 넘어서는 안됩니다. 그리고 Scribunto 확장 루아는 표준 루아에 비해서 몇몇 함수가 부족합니다.^[7]

Scribunto 루아 코드는 문서를 해석할 때에만 실행됩니다. 그러므로 사용자 입력은 문서를 편집함으로써만 할 수 있습니다. 키보드로 수치를 입력 받아 제곱근을 구하는 함수를 만들 수도 없고, 만델브로 집합의 일부분을 마우스로 클릭하면 그 부분을 다시 계산해서 보여주는 함수를 만들 수도 없습니다. 루아 입력은 틀처럼 포함할 수 있는 문자열 문서^[8]를 담을 수 있지만, 그림 파일,^[9] 분류 문서에 보이는 문서의 목록, 또는 위키백과:특수 문서로 볼 수 있는 내용은 입력할 수 없습니다.

루아를 사용하는 틀에 {{루아}}를 붙여 주세요. 루아의 사용과 틀의 편집에 관한 의사소통에 도움을 줍니다. 그 틀은 아래와 같습니다:

이 틀은 루아를 사용합니다. 모듈:Bananas

분류:루아 틀에서 루아를 사용하는 틀을 모두 보실 수 있습니다.

• 특수기능:접두어찾기/모듈: - 루아 모듈 목록
• 특수기능:접두어찾기/모듈:연습장 - 루아 모듈 연습장 목록
• (영어) mw:Extension:Scribunto/Lua reference manual - 루아 레퍼런스 매뉴얼