Lua API 참조

개요

이 문서는 Lua 필터와 쇼트코드를 구현할 때 사용할 수 있는 표준 API를 설명합니다. 사용할 수 있는 주요 API는 다음 세 가지입니다:

  • Lua 기본 API—문자열 처리, 패턴 매칭, 테이블 조작, 파일 입출력을 위한 기본 함수.

  • Pandoc Lua API—Pandoc에서 제공하는 필터 개발용 핵심 API로, pandoc.Div, pandoc.CodeBlock 같은 핵심 AST 타입과 다양한 작업을 위한 보조 함수를 포함합니다.

  • Quarto Lua API—디버깅, 포맷 감지, 인코딩(예: JSON), 문서에 의존성(예: JavaScript 라이브러리, LaTeX 패키지)을 추가하기 위한 추가 함수.

Lua 프로그래밍을 시작하고 권장 도구와 워크플로를 알아보려면 Lua 개발 문서를 참고하세요.

Lua 기본 API

Lua 표준 라이브러리는 문자열, 수학, 테이블, 파일 작업을 위한 핵심 함수를 제공합니다. 여기서는 유용한 표준 라이브러리 몇 가지에 대한 링크를 제공합니다(전체 문서는 Lua Reference Manual에서 확인할 수 있습니다).

라이브러리 설명
string 문자열 조작을 위한 일반 함수(부분 문자열 찾기/추출, 패턴 매칭 등)를 제공합니다.
utf8 UTF-8 인코딩에 대한 기본 지원을 제공합니다.
table 테이블 조작을 위한 일반 함수를 제공합니다.
math 기본 수학 함수를 제공합니다.
io, file I/O 라이브러리는 파일 조작을 위한 두 가지 스타일을 제공합니다. 하나는 암묵적 파일 핸들을, 다른 하나는 명시적 핸들을 사용합니다.
os 날짜/시간, 로케일, 환경 변수 등.

Pandoc Lua API

Pandoc Lua API의 전체 문서는 Pandoc 웹사이트의 Lua Filters 문서에서 확인할 수 있습니다. 다음은 API 구성 요소와 참조 문서 링크입니다:

Lua 모듈 설명
pandoc (ast) 문서 트리 요소 생성자(예: pandoc.Div(), pandoc.Strong() 등)와 핵심 구성요소(예: pandoc.Attr())
pandoc (functions) 지정한 포맷으로 텍스트를 파싱하고, 서브 트리를 필터/수정하며, 하위 프로세스를 실행하는 함수.
pandoc.text UTF-8 인식 텍스트 조작 함수(예: upper(), lower() 등)
pandoc.List Pandoc의 리스트 타입을 정의하는 모듈. 유용한 메서드와 편의 함수(예: find_if(), includes(), filter(), map() 등)를 제공합니다.
pandoc.utils 내부 Pandoc 함수와 유틸리티 함수(예: blocks_to_inlines(), stringify(), citeproc() 등)
pandoc.path 파일 경로 조작을 위한 모듈(예: is_absolute(), is_relative(), join() 등).
pandoc.system 시스템 정보/기능 접근(예: get_working_directory(), list_directory() 등).
pandoc.mediabag Pandoc의 미디어 저장소 접근. “미디어 백”은 pandoc 실행 시 --extract-media 또는(HTML 전용) --embed-resources 옵션을 사용할 때 쓰입니다.
pandoc.template 기본 pandoc 템플릿 컴파일 및 접근(예: compile())
pandoc.types pandoc AST에 포함되지 않는 타입의 생성자(예: Version())

Quarto Lua API

유틸리티 함수

다양한 유틸리티 함수가 제공됩니다:

함수 설명
quarto.version 현재 Quarto 버전을 pandoc.Version 객체로 반환합니다.
quarto.log.output(obj) 전달된 객체의 텍스트 표현을 stdout으로 출력합니다.
quarto.utils.resolve_path(path) 확장의 Lua 스크립트와 함께 설치되는 파일의 전체 경로를 계산합니다. 필터에는 필요하지만 사용자에게 노출되면 안 되는 내부 리소스에 유용합니다.

Quarto는 pandoc-lua-logging 라이브러리를 포함하며, dump 함수보다 이것을 사용하는 것이 좋습니다. 예를 들어, 다음과 같이 필터 함수에 전달된 요소를 확인할 수 있습니다:

function Div(el)
  quarto.log.output(el)
end

포맷 감지

확장은 대상 출력 매체에 맞춘 커스텀 콘텐츠를 만들기 위해 현재 포맷을 감지해야 할 때가 많습니다. quarto.doc.is_format() 함수는 다음과 같습니다:

함수 설명
quarto.doc.is_format(name) 현재 포맷이 name과 일치하는지 감지합니다.
quarto.doc.has_bootstrap() 현재 문서에서 Bootstrap CSS 사용 가능 여부를 확인합니다(표준 html 문서에서는 기본적으로 사용 가능하지만 theme: none 등으로 재정의되었을 수 있습니다).

name 매개변수는 Pandoc 포맷 이름(예: docx, latex 등)에 정확히 일치시킬 수 있으며, 일반적으로 함께 타깃팅되는 포맷을 묶는 별칭과도 매칭할 수 있습니다. 다음 값은 quarto.doc.is_format()에서 특별히 처리되는 포맷 별칭입니다:

별칭 포맷
latex latex, pdf, beamer
pdf latex, pdf, beamer
epub epub*
html html*, epub*, revealjs, dashboard, email
html:js html*, revealjs, dashboard, email
markdown markdown*, commonmark*, gfm, markua, hugo-md, docusaurus-md
odt odt, opendocument
hugo hugo-md
docusaurus docusaurus-md
asciidoc asciidoc, asciidoctor

html:js 별칭은 대상 포맷이 JavaScript를 실행할 수 있음을 뜻합니다(ePub을 제외한 모든 HTML 포맷과 매핑).

그 외에는 dashboard, email, confluence처럼 포맷 이름을 그대로 지정해 사용할 수 있습니다.

예를 들어, PDF와 HTML 출력에 대해 검사하려면 다음과 같이 합니다:

if quarto.doc.is_format("pdf") then
  -- PDF 전용 출력
elseif quarto.doc.is_format("html") then
  -- HTML 전용 출력
else
  -- 기타 포맷 출력
end

LaTeX 출력의 경우 현재 렌더링에 사용되는 인용 도구와 PDF 엔진을 추가로 감지해야 할 수 있습니다. 다음 함수로 이를 확인할 수 있습니다:

함수 설명
quarto.doc.cite_method() 사용 중인 인용 방식(citeproc, natbib, biblatex)을 문자열로 반환합니다.
quarto.doc.pdf_engine() 문서를 렌더링하는 데 사용되는 PDF 엔진(pdflatex, xelatex, lualatex, tectonic)을 문자열로 반환합니다.

포함

확장은 대상 문서에 콘텐츠를 주입해야 할 때가 있습니다. 콘텐츠를 포함할 수 있는 위치는 다음 세 곳입니다(포함 함수의 첫 번째 인자로 이 위치 중 하나를 전달합니다):

위치 설명
in-header 문서 헤더(HTML <head> 태그 또는 LaTeX preamble)
before-body 문서 본문 앞
after-body 문서 본문 뒤

포함되는 콘텐츠는 마크다운이 아니라 대상 포맷의 원시 형태(예: HTML 또는 LaTeX)여야 합니다. 다음 함수를 사용해 텍스트 또는 파일 내용을 포함할 수 있습니다:

함수 설명
quarto.doc.include_text(location, text) 지정한 위치(in-header, before-body, after-body)에 텍스트를 포함합니다.
quarto.doc.include_file(location, file) 지정한 위치(in-header, before-body, after-body)에 파일을 포함합니다. 파일 경로는 이 함수를 호출하는 Lua 스크립트에 상대 경로여야 합니다.

예를 들어, 다음 코드는 렌더링된 문서의 본문 뒤에 HTML 파일을 포함합니다:

quarto.doc.include_file("after-body", "comments.html")

의존성

확장은 외부 의존성(예: JavaScript 라이브러리와 관련 CSS, 또는 LaTeX 패키지)을 추가해야 할 때가 있습니다. 다음 함수로 이를 수행할 수 있습니다:

함수 설명
quarto.doc.add_html_dependency(dep) 문서에 HTML 의존성(추가 리소스와 콘텐츠)을 추가합니다. 자세한 내용은 아래 HTML 의존성 문서를 참고하세요.
quarto.doc.attach_to_dependency(name, attach) 기존 의존성에 파일을 첨부합니다. attach는 Lua 필터에 대한 상대 경로의 파일 경로 또는 path와 name으로 파일 이름을 변경하는 테이블입니다.
quarto.doc.use_latex_package(pkg, opt) LaTeX 출력에 \usepackage 구문을 추가합니다(opt로 옵션 문자열을 지정).
quarto.doc.add_format_resource(path) 문서에 포맷 리소스를 추가합니다. 포맷 리소스는 렌더링된 출력 옆 디렉터리에 복사됩니다. 예를 들어 LaTeX 출력 디렉터리에 복사해야 하는 bst 또는 cls 파일이 있을 때 유용합니다.

예를 들어, 다음과 같이 LaTeX 패키지 의존성을 추가합니다:

quarto.doc.use_latex_package("gamebook")

HTML 의존성

HTML 의존성은 JavaScript, CSS, 그리고 <head>에 주입할 임의의 콘텐츠까지 묶어 포함할 수 있습니다. 이 의존성에는 이름과 버전이 있으며, 문서에 동일한 의존성이 두 번 포함되는 것을 방지하는 데 사용됩니다.

quarto.doc.add_html_dependency()에 전달되는 dep 객체에는 다음 필드가 있습니다:

필드 설명
name 고유한 이름. 필수.
version 버전 문자열. 필수.
scripts 포함할 스크립트 목록(경로는 절대 경로 또는 함수를 호출하는 Lua 파일에 대한 상대 경로). 스크립트는 간단한 경로 또는 스크립트 객체가 될 수 있습니다.
stylesheets 포함할 CSS 스타일시트 목록(경로는 절대 경로 또는 함수를 호출하는 Lua 파일에 대한 상대 경로). 스타일시트는 간단한 경로 또는 스타일시트 객체가 될 수 있습니다.
links 문서에 추가할 link 태그 목록. 각 태그는 rel과 href(필수) 그리고 선택적으로 type을 포함하는 테이블입니다.
resources 입력 디렉터리로 복사할 추가 파일(각 리소스는 name(입력 디렉터리의 대상 파일명)과 path(Lua 스크립트에 대한 상대 경로)로 구성된 객체).
serviceworkers 출력 디렉터리 루트로 복사할 JavaScript 서비스워커 파일(단순 문자열 파일명 또는 path와 name으로 파일명을 바꾸는 테이블).
meta 문서 <head>에 삽입할 선택적 key = value 메타 태그 테이블
head 문서 <head>에 포함할 임의의 문자열

예를 들어, 다음과 같이 JavaScript 라이브러리 의존성을 추가합니다:

quarto.doc.add_html_dependency({
  name = "glightbox",
  version = "3.2.0",
  scripts = {"glightbox.min.js"},
  stylesheets = {"glightbox.min.css"}
})

스크립트 객체

scripts는 간단한 경로로 지정하는 것이 가장 쉽습니다. 그러나 <script> 태그에 속성을 추가하거나 스크립트를 본문 뒤에 배치해야 하는 경우에는 스크립트 객체를 전달합니다:

필드 설명
path 스크립트 경로(호출하는 Lua 스크립트에 대한 상대 경로)
attribs <script> 태그에 추가할 key = value 속성 테이블
afterBody <script> 태그를 본문 뒤에 삽입하도록 지정

예를 들어, 이전 예제에 integrity 속성을 추가하려면 다음과 같이 합니다:

quarto.doc.add_html_dependency({
  name = "glightbox",
  version = "3.2.0",
  scripts = {
    { path = "glightbox.min.js ", attribs = {integrity = "R9GqQ8K/uxy9rx"} }
  },
  stylesheets = {"glightbox.min.css"}
})

스타일시트 객체

stylesheets는 간단한 경로로 지정하는 것이 가장 쉽습니다. 그러나 생성되는 <link> 태그에 속성을 추가해야 하는 경우에는 스타일시트 객체를 전달합니다:

Field Description
path 스타일시트 경로(호출하는 Lua 스크립트에 대한 상대 경로)
attribs <link> 태그에 추가할 key = value 속성 테이블

예를 들어, 이전 예제에 integrity 속성을 추가하려면 다음과 같이 합니다:

quarto.doc.add_html_dependency({
  name = "glightbox",
  version = "3.2.0",
  scripts = {
    { 
      path = "glightbox.min.js ", 
      attribs = {integrity = "R9GqQ8K/uxy9rx"} 
    }
  },
  stylesheets = {
    { 
      path = "glightbox.min.css ", 
      attribs = {integrity = "GYl1kPzQho1wx"} 
    }
  }
})

JSON 인코딩

Quarto에는 경량 JSON 라이브러리인 json.lua 사본이 포함되어 있습니다. JSON 함수는 다음과 같이 사용할 수 있습니다:

Function Description
quarto.json.encode(input) Lua 테이블을 JSON 문자열로 인코딩합니다.
quarto.json.decode(str) JSON 문자열을 Lua 테이블로 파싱합니다.

예를 들어, 다음과 같이 테이블을 인코딩한 뒤 디코딩할 수 있습니다:

local json = quarto.json.encode({foo = "bar"})
local obj = quarto.json.decode(json)

Base64 인코딩

Quarto에는 Base64 인코딩의 순수 Lua 구현인 lbase64 사본이 포함되어 있습니다. Base64 인코딩 함수는 다음과 같이 접근할 수 있습니다:

Function Description
quarto.base64.encode(str) 문자열을 Base64로 인코딩합니다.
quarto.base64.decode(b64str) Base64 문자열을 디코딩합니다.

경로

Quarto는 Lua 확장/필터 작성자에게 유용할 만한 유틸리티의 경로를 제공합니다. 현재는 아래 항목만 지원됩니다:

함수 설명
quarto.paths.rscript() Quarto가 knitr 엔진과 quarto run 스크립트에서 사용하는 Rscript 경로를 반환합니다.
quarto.paths.tinytex_bin_dir() TinyTeX 바이너리 디렉터리(tlmgr, pdflatex 등)의 경로를 반환합니다. Quarto가 TinyTeX를 설치하지 않았거나 찾지 못하면 nil을 반환합니다. 이는 Quarto의 PDF 렌더링이 PATH에 있는 도구를 사용했을 가능성이 있음을 의미합니다.

쇼트코드

Quarto는 쇼트코드 개발자를 위해 다음과 같은 도움 함수를 제공합니다. 일반적으로 쇼트코드 핸들러에서 사용합니다. 자세한 내용은 쇼트코드 개발 문서를 참고하세요:

함수 설명
quarto.shortcode.read_arg(args, [n]) 쇼트코드 호출의 n번째 인자를 반환합니다.
quarto.shortcode.error_output(name, message_or_args, context) Quarto가 이런 출력물을 표시하는 방식과 일관되게, 실행 오류를 나타내기 위한 출력을 생성합니다.

메타데이터 접근

Quarto는 Lua 필터와 스크립트에서 문서/프로젝트 메타데이터에 대한 프로그래밍 방식 접근을 제공합니다. 이는 쇼트코드 컨텍스트가 아니라 필터 로직 내에서 메타데이터 값을 사용해야 할 때 유용합니다.

함수 설명
quarto.metadata.get(key) 메타데이터 항목의 값을 pandoc.MetaValue로 반환하거나 키가 없으면 nil을 반환합니다. 이는 {{< meta key >}} 쇼트코드의 Lua 버전입니다.

key 매개변수는 최상위 메타데이터를 참조하거나 점 표기법으로 중첩 값을 참조할 수 있습니다. 예:

function Meta(meta)
  -- 단순 메타데이터 값 가져오기
  local title = quarto.metadata.get("title")

  -- 값을 사용하기 전에 존재 여부 확인
  local customField = quarto.metadata.get("custom-field")
  if customField then
    -- 메타데이터 값 처리
    local value = pandoc.utils.stringify(customField)
  end

  return meta
end

이 함수는 pandoc.MetaValue를 반환하며, 이는 MetaString, MetaInlines, MetaList, MetaMap 또는 다른 Pandoc 메타데이터 타입일 수 있습니다. 필요할 때 pandoc.utils.stringify()로 문자열로 변환할 수 있습니다:

function Pandoc(doc)
  -- 메타데이터를 MetaValue로 가져오기
  local metaValue = quarto.metadata.get("description")

  -- 처리할 수 있도록 문자열로 변환
  local description = pandoc.utils.stringify(metaValue)

  -- 복잡한 메타데이터 구조 처리
  local keywords = quarto.metadata.get("keywords")
  if type(keywords) == "table" then
    -- 리스트 또는 맵으로 처리
    for k, v in pairs(keywords) do
      quarto.log.output(pandoc.utils.stringify(v))
    end
  end

  return doc
end

변수 접근

Quarto 프로젝트는 _variables.yml 파일에 변수를 정의할 수 있습니다. 이러한 변수는 quarto.variables.get() 함수를 사용해 Lua에서 프로그래밍 방식으로 접근할 수 있습니다.

함수 설명
quarto.variables.get(name) _variables.yml에서 변수를 문자열로 반환하거나, 변수가 정의되지 않았으면 nil을 반환합니다. 이는 {{< var name >}} 쇼트코드의 Lua 버전입니다.

예를 들어 _variables.yml에 다음이 포함되어 있다면:

site-url: https://example.com
api-version: v2.1
feature-enabled: true

Lua 필터에서 다음과 같이 값을 가져올 수 있습니다:

function Pandoc(doc)
  -- 변수 값 가져오기
  local siteUrl = quarto.variables.get("site-url")

  -- 조건 로직에서 사용
  local apiVersion = quarto.variables.get("api-version")
  if apiVersion == "v2.1" then
    -- 버전별 콘텐츠 추가
  end

  -- 변수 존재 여부 확인
  local featureFlag = quarto.variables.get("feature-enabled")
  if featureFlag then
    quarto.log.output("Feature flag: " .. featureFlag)
  end

  return doc
end

변수는 항상 문자열(또는 없으면 nil)로 반환되므로, 숫자나 불리언을 다룰 때는 형 변환이 필요할 수 있습니다:

function Pandoc(doc)
  -- 숫자 변수 가져오기
  local maxItems = quarto.variables.get("max-items")
  if maxItems then
    local count = tonumber(maxItems)
    if count and count > 10 then
      -- 숫자 값으로 처리
    end
  end

  -- 불리언 변수 가져오기
  local enabled = quarto.variables.get("feature-enabled")
  if enabled == "true" then
    -- 기능이 활성화됨
  end

  return meta
end