Lua 필터 변경 사항

Quarto v1.4에는 Lua 필터를 위한 다음 새 기능이 포함됩니다:

필터에서 상호 참조 가능한 요소 지원

Quarto v1.4는 그림, 표, 목록 등 처리에 중요한 변경 사항을 도입했습니다. 이러한 변경은 해당 요소를 대상으로 하는 Lua 필터 작성을 단순화하지만, 기존 필터에는 일반적으로 변경이 필요합니다.

FloatRefTarget AST 노드

v1.4에서는 상호 참조 가능한 요소가 모두 단일한 일반 타입인 FloatRefTarget을 가집니다. 이 요소는 Lua 필터에서 명시적으로 생성할 수 있습니다. 또한 Lua 필터에서 처리할 요소로 직접 사용할 수도 있습니다.

-- FloatRefTarget 노드를 대상으로 하는 필터
return {
  FloatRefTarget = function(float)
    if float.caption_long then
      float.caption_long.content:insert(pandoc.Str("[This will appear at the beginning of every caption]"))
      return float
    end
  end
}

FloatRefTarget 노드는 다음 필드를 가집니다:

  • type: 요소의 유형: Figure, Table, Listing 등. Quarto v1.4는 문서 또는 프로젝트 수준에서 선언할 수 있는 사용자 정의 노드 타입을 지원합니다.
  • content: Figure, Table 등의 콘텐츠. Quarto v1.4는 모든 FloatRefTarget 타입에서 어떤 콘텐츠든 허용합니다(표가 이미지로 더 잘 보인다면 그렇게 사용할 수 있습니다).
  • caption_long: 문서 본문에 표시되는 캡션
  • caption_short: 요소 목록(예: 표 목록, 그림 목록 등)에 표시되는 캡션
  • identifier, attributes, classes: spans와 div 같은 Pandoc AST 요소의 Attr 필드와 유사합니다. 추가로 identifier는 상호 참조에 사용되는 문자열이어야 합니다(fig-cars, tbl-votes, lst-query 등).
  • parent_id: FloatRefTarget가 부모 다중 요소 float의 서브플로트인 경우 parent_id에 부모 float의 식별자가 들어갑니다.

사용자 정의 형식과 사용자 정의 렌더러

Quarto v1.4는 FloatRefTarget, Callout 같은 quarto AST 노드의 확장 가능한 렌더러를 지원합니다. 사용자 정의 렌더러를 선언하려면 Lua 필터에 다음을 추가하세요:

local predicate = function(float)
  -- 이 렌더러를 사용해야 하면 true를 반환합니다.
  -- 일반적으로 사용자 정의 형식이 활성화되어 있으면 true를 반환합니다.
end
local renderer = function(float)
  -- 렌더링된 figure의 일반 Pandoc 표현을 반환합니다.
end
quarto._quarto.ast.add_renderer(
  "FloatRefTarget", 
  predicate, 
  renderer)

require() 호출의 상대 경로

더 크고 복잡한 필터에서는 Lua 코드를 모듈로 구조화하는 것이 유용합니다. Quarto v1.4는 require() 호출에서 상대 경로를 지원하므로 작은 모듈을 쉽게 만들고 재사용할 수 있습니다.

예를 들어:

filter.lua
local utility = require('./utils')
function Pandoc(doc)
  -- process 
end

이 방식으로 quarto에서 상대 경로를 사용하면 여러 필터가 실수로 동일한 모듈 이름을 만들어 충돌하는 일을 줄일 수 있습니다(표준 Lua의 require('utils') 문법을 사용하면 결국 이런 문제가 발생할 수 있습니다). 하위 디렉터리와 상위 디렉터리도 참조할 수 있습니다:

filter2.lua
local parsing = require('./utils/parsing')
function Pandoc(doc)
  -- process 
end
utils/parsing.lua
local utils = require("../utils")
-- ...

AST 처리 단계의 정밀한 타깃팅

Quarto 1.4 이전에는 Lua 필터가 “pre” 필터(기본 설정) 또는 “post” 필터였습니다. 이 필터는 다음과 같이 지정했습니다:

# "pre" filters:
filters:
  - pre_filter_1.lua
  - pre_filter_2.lua  
  # ...
# "post" filters:
filters:
  - quarto
  - post_filter_1.lua
  - post_filter_2.lua  
  # ...

이 문법은 1.4에서도 계속 동작합니다. 또한 이제 특정 필터가 삽입될 위치를 더 정밀하게 지정할 수 있습니다. Quarto의 AST 처리 단계는 이제 ast, quarto, render 세 부분으로 나뉩니다.

  • ast: Pandoc 입력 문법을 정규화하고 Callout, FloatRefTarget 등의 구성 요소를 인식합니다.
  • quarto: 정규화된 문법을 처리합니다(예: 상호 참조 해석).
  • render: 처리된 입력에서 형식별 출력을 생성합니다.

Quarto 1.4에서는 Lua 필터를 이 단계들 앞이나 뒤에 삽입할 수 있습니다:

filters:
  - at: pre-ast
    path: filter1.lua
  - at: post-quarto
    path: filter2.lua
  - at: post-render
    path: filter3.lua

각 단계는 pre- 또는 post- 접두사를 붙일 수 있습니다. Quarto 1.4에서는 pre-quarto와 post-ast가 필터 체인의 동일한 삽입 위치를 가리키며, post-quarto와 pre-render도 마찬가지입니다. Quarto 1.3의 “pre”와 “post” 필터 문법은 그대로 유효합니다. “pre” 필터는 pre-quarto 진입 지점에, “post” 필터는 post-render 진입 지점에 주입됩니다.

새 문법도 1.3 필터와 마찬가지로 JSON 필터를 지원합니다. type: json을 명시하거나 .lua로 끝나지 않는 경로를 사용하세요. 반대로 type: lua는 해당 파일을 Lua 필터로 강제합니다.