Lua 개발

개요

filters와 shortcodes를 만드는 데 사용하는 프로그래밍 언어는 가볍고 고수준인 스크립트 언어 Lua입니다. Lua는 Pandoc의 확장 언어이며(내장 Lua 인터프리터 포함), 이는 Quarto 확장이 추가 런타임 의존성이나 요구사항 없이 동작한다는 의미입니다.

이 문서는 Lua를 처음 접하는 분을 위해 Lua 학습 방향을 안내하고, 이어서 생산적인 Lua 개발을 위한 팁을 제공합니다.

확장 개발에 사용할 수 있는 API에 대한 자세한 내용은 Lua API 참조를 참고하세요.

Lua 학습

Lua는 Python, R, Julia, JavaScript와 유사한 스크립트 언어입니다. 이들 중 하나 이상에 익숙하다면 Lua를 어렵지 않게 익힐 수 있습니다.

Quarto에서 Lua를 배우기 위한 권장 접근 방법은 다음과 같습니다:

  1. 언어와 문법을 빠르게 훑기 위해 Learn Lua in 15 Minutes를 읽습니다.

  2. Pandoc Lua Filters 문서의 처음 두 섹션을 읽은 다음, 내용을 더 구체적으로 이해하기 위해 Filter Examples 섹션으로 건너뜁니다.

  3. Lua와 필터의 기본 개념을 잡은 뒤 Pandoc Lua Filters 문서를 전체적으로 훑어 전체 구성 요소를 파악합니다. 모든 내용을 이해하지 못해도 전체 맥락을 이해하는 데 도움이 됩니다.

  4. 마지막으로 Quarto Extensions GitHub 조직에 공개된 확장 소스 코드를 살펴보세요(Quarto 코어 팀이 관리하는 확장입니다). 코드를 읽고 이해할 수 있게 되면 자신만의 확장을 만들 준비가 된 것입니다!

추가로 유용한 학습 자료는 다음과 같습니다:

  1. Lua Quick Reference, 언어와 기본 라이브러리를 간단히 정리한 PDF.

  2. Programming in Lua, 언어의 수석 설계자인 Roberto Ierusalimschy의 책.

  3. Lua Reference Manual, 언어와 기본 라이브러리를 완전히 정의한 문서.

개발 도구

Quarto Preview

Quarto preview(quarto preview)는 확장 내 Lua 소스 파일을 인지하며, Lua 소스가 변경될 때마다 미리보기를 자동으로 다시 로드합니다.

이는 Lua 코드를 점진적으로 개발하고 디버깅하기에 매우 유용합니다(특히 아래에 설명한 native 포맷과 함께 사용할 때 효과적입니다). Lua 파일의 라이브 리로드는 사용하는 편집기(Positron, VS Code, RStudio, Neovim 등)와 무관하게 동작합니다.

VS Code / Positron

quarto preview와 함께 어떤 텍스트 편집기든 사용할 수 있지만, 다음과 같은 추가 도구를 제공하는 VS Code 또는 Positron 사용을 강력히 권장합니다:

  1. 코드 완성과 타입 체크.

  2. 코드에서 흔히 발생하는 문제에 대한 진단.

  3. 사용자 함수에 타입을 추가하는 기능.

코드 완성은 Lua 기본 라이브러리뿐 아니라 Pandoc/Quarto Lua API를 포함하며, 호버 시 문서도 제공합니다:

VS Code에서 Lua 파일을 열고 Lua 함수에 대한 코드 완성 팝업이 표시된 화면.

진단은 nil 체크 누락, 정의되지 않은 전역 값, 로컬 변수 섀도잉, 사용되지 않는 함수 등 흔한 오류를 확인합니다.

VS Code에서 Lua 파일을 열었을 때 코드 편집기 아래 Problems 패널에 진단 오류가 표시된 화면.

설치

VS Code 또는 Positron을 사용한 Lua 확장 개발을 시작하려면 다음 소프트웨어를 설치하세요:

  1. 최신 버전(v1.2 이상)의 Quarto 설치.

  2. 최신 버전(v1.40.0 이상)의 Quarto Extension 설치(OpenVSX 및 Microsoft 마켓플레이스에서 제공).

  3. Lua 코드 인텔리전스를 위한 Lua LSP 확장 설치(OpenVSX 및 Microsoft 마켓플레이스에서 제공).

이 구성요소를 설치하면, Lua 코드가 포함된 Quarto 워크스페이스에서 위 기능이 자동으로 나타납니다.

Lua 완성/진단을 설정할 수 있는 다양한 옵션이 있으며, 사용자 함수에 대한 타입 정보를 제공하는 것도 가능합니다. 자세한 내용은 아래 Positron과 VS Code에서의 Lua 섹션을 참고하세요.

진단 로깅

quarto.log 모듈의 함수를 사용해 확장에 진단 로깅을 추가할 수 있습니다. 특정 문제를 디버깅하기 위한 임시 로그뿐 아니라, quarto render 또는 quarto preview에 --trace 플래그가 전달될 때만 활성화되는 상시 로그도 추가할 수 있습니다.

quarto.log 모듈은 pandoc-lua-logging 프로젝트(@wlupton 제공)를 기반으로 하며, 아래에서 설명하는 함수들은 이 모듈의 함수(logging.output(), logging.warning() 등)와 동일한 패턴입니다. 모든 로그 함수에 대한 문서는 해당 프로젝트의 README를 참고하세요.

quarto.log.output

모든 객체(Pandoc AST 요소 포함)를 로깅하려면 quarto.log.output() 함수를 사용합니다. 예를 들어, 다음은 필터 콜백 함수에서 전달받은 Div와 진단 텍스트를 로깅하는 예시입니다:

filter.lua
function Header(el)
  quarto.log.output("=== Handling Header ===")
  quarto.log.output(el)
end

필터가 실행될 때 터미널에서 확인할 수 있는 로그 출력은 다음과 같습니다:

=== Handling Header ===
Header {
  attr: Attr {
    attributes: AttributeList {}
    classes: List {}
    identifier: "section-one"
  }
  content: Inlines {
    [1] Str "Section"
    [2] Space
    [3] Str "One"
  }
  level: 2
}

quarto.log.warning

quarto.log.warning() 함수는 --quiet 플래그로 숨길 수 있는 경고를 출력합니다:

filter.lua
function RawBlock(el)
  if el.format == "html" then
    quarto.log.warning("Raw HTML not supported")
    return pandoc.Null()
  end
end

예를 들어 위 경고는 다음 quarto render 호출에서는 나타나지 않습니다:

quarto render document.qmd --quiet

quarto.log.debug

quarto.log.debug() 함수는 --trace 플래그가 있을 때만 출력합니다:

filter.lua
function Header(el)
  quarto.log.debug("Header: " .. el.identifier)
end

예를 들어 다음 quarto preview 호출에서는 디버그 메시지가 나타납니다:

quarto preview document.qmd --trace

이 호출은 --trace가 지정되지 않으면 출력이 없으므로, 필터에 그대로 두어도 괜찮습니다.

Native 포맷

Lua 필터나 쇼트코드의 동작을 더 깊이 이해하는 데는 native 포맷(html, pdf 등과 대비됨)을 대상으로 하는 것이 큰 도움이 됩니다. native 포맷은 Pandoc AST의 원시 내용을 보여줍니다. 예를 들어, 간단한 마크다운 문서와 그에 대한 native 출력은 다음과 같습니다:

document.qmd
---
format: native
---

## Heading

Some text below



Pandoc
  Meta
    { unMeta = fromList [] }
  [ Header
      2
      ( "heading" , [] , [] )
      [ Str "Heading" ]
  , Para
      [ Str "Some"
      , Space
      , Str "text"
      , Space
      , Str "below"
      ]
  ]

다음은 모든 헤더를 pandoc.Emph(이탤릭)로 감싸는 간단한 필터를 문서에 추가한 예입니다. native 출력에서 이제 Emph AST 요소가 헤더 텍스트를 감싸고 있음을 확인할 수 있습니다:

document.qmd
---
format: native
filters: [filter.lua]
---

## Heading

Some text below
filter.lua
function Header(el)
  el.content = { 
    pandoc.Emph(el.content)
  }
  return el
end
Pandoc
  Meta
    { unMeta = fromList [] }
  [ Header
      2
      ( “heading” , [] , [] )
      [ Emph [ Str “Heading” ]
      ]
  , Para
      [ Str “Some”
      , Space
      , Str “text”
      , Space
      , Str “below”
      ]
  ]


Positron과 VS Code에서의 Lua

타입 힌트

Quarto는 Pandoc/Quarto Lua API에 대한 타입 정보를 제공하지만, 사용자가 확장 안에서 작성하는 함수에는 적용되지 않습니다. 대신 Annotations를 사용해 타입 정보를 추가할 수 있습니다. 예를 들어, 아래는 함수가 string과 pandoc.List()를 받아 pandoc.List() 또는 nil을 반환한다는 것을 나타냅니다:

---@param text string
---@param blocks pandoc.List
---@return pandoc.List|nil
function check_for_text(text, blocks)
  -- implementation
end

이 타입 선언을 통해 잘못된 타입으로 함수를 호출하면 진단 메시지가 표시됩니다. 또한 호출자가 반환값을 사용하기 전에 nil 여부를 확인하지 않으면 진단이 발생합니다.

사용 가능한 타입 애노테이션에 대한 자세한 내용은 Lua Language Server의 Annotations Reference를 참고하세요.

설정

Lua Language Server 확장은 진단 표시 방식, 완성 항목 등 동작을 커스터마이즈할 수 있는 다양한 옵션을 제공합니다.

사용 가능한 옵션은 Lua Language Server의 Settings Reference에 문서화되어 있습니다.

Quarto는 Lua 확장을 포함하는 워크스페이스 루트에 기본 설정 파일(.luarc.json)을 제공합니다. 이 파일은 현재 설치된 Quarto 버전에 포함된 Pandoc/Quarto Lua 타입 정의를 참조하는 데 필요합니다. 이 파일이 없으면 Lua 확장은 Quarto에 대해 알 수 없으므로 “알 수 없는” Pandoc 모듈 오류를 보고합니다.

예를 들어 Quarto가 /opt/quarto/에 설치되어 있다면 설정 파일의 기본 내용은 다음과 같습니다:

.luarc.json
{
  "Generator": ["Quarto"],
  "Lua.runtime.version": "Lua 5.3",
  "Lua.workspace.checkThirdParty": false,
  "Lua.workspace.library": ["/opt/quarto/share/lua-types"],
  "Lua.runtime.plugin": "/opt/quarto/share/lua-plugin/plugin.lua",
  "Lua.completion.showWord": "Disable",
  "Lua.completion.keywordSnippet": "Both",
  "Lua.diagnostics.disable": ["lowercase-global", "trailing-space"]
}

.luarc.json 파일은 로컬 시스템의 Quarto 절대 경로를 가리키므로 .gitignore에도 자동으로 추가됩니다.

이 파일에서 Lua.workspace.library와 Lua.runtime.plugin을 제외한 나머지 설정은 변경할 수 있습니다(이 둘은 Quarto 확장이 Quarto 설치 위치에 따라 자동으로 관리합니다). 모든 설정에 대한 자세한 내용은 Settings Reference를 참고하세요.

이 파일을 수동으로 관리하려면 Generator 키를 제거하면 됩니다. 그러면 Quarto는 Lua.workspace.library와 Lua.runtime.plugin 설정을 자동으로 업데이트하지 않습니다.

또한 Quarto > Lua: Provide Types 설정을 사용하여 .luarc.json 자동 생성을 전역적으로 비활성화할 수 있습니다.