WASMでTypstプラグインを作ろう

この記事は、Zennにも投稿しています。

最近話題の組版システムのTypstですが、プラグインシステムを備えておりWASMを使って拡張することが可能です。

Plugin Function – Typst Documentation

Documentation for the `plugin` function.

typst.app

プラグインを使うことで従来のTypst言語のみでは難しかった様々な処理を行うことができます。

公式のパッケージリストに掲載されているパッケージの中にも内部でWASMプラグインを使用しているものがあります。例えばQuickJSを利用してJavaScriptを実行する「Jogs」やMarkdownをTypstに変換する「cmarker」、さらにはLaTeXをTypst構文に変換して表示する(!)「mitex」というものもあります。

この記事ではRustを使ってTypstのプラグインを作成することによりTypstプラグインの基本的な仕組みについて解説します。Typstはそれ自体Rustで作られているためRustでプラグインを書くための環境がよく整備されていますが、WASMにコンパイルできる言語であればどのような言語も使用可能です。ただし、WASIはサポートされていないため、WASIが必須な言語やライブラリを使用する際にはwasi-stubを使用する必要があります。

ZigとCの例がここにある他、その他の言語でもTypstのwasm protocolに従って関数をエクスポートすることでTypstプラグインを作成できます。

プラグインとパッケージ

Typstでのプラグインというのはwasmファイルのことを指します。一方、パッケージはプラグインをロードする処理などが記述されたtypファイルなどを含んだ一連のファイル群のことを指します。パッケージはwasmプラグインを含まずに.typファイルのみで構成することもできます。

挨拶プラグイン

まずは引数nameを受け取りHello {name}という文字列を出力するだけのプラグインを作ってみましょう。

cargo new --lib typst-greet
rustup target add wasm32-unknown-unknown

を実行してRustのプロジェクトを作り、wasmにビルドできるようにしておいたら次にCargo.tomlに以下を追記します。

Cargo.toml

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-minimal-protocol = { git = "https://github.com/astrale-sharp/wasm-minimal-protocol/" }

crate-type = ["cdylib"]はwasmにビルドするのに必要です。また、wasm-minimal-protocolクレートでは関数をTypstから呼び出すのに必要な諸々をやってくれます。
また、.cargo/config.tomlファイルを作成し、デフォルトでwasmがコンパイルされるようにしておきます。

.cargo/config.toml

[build]
target = "wasm32-unknown-unknown"

次にlib.rsを以下のように書き換えます。

src/lib.rs

use wasm_minimal_protocol::*;

initiate_protocol!();

#[wasm_func]
pub fn greet(name: &[u8]) -> Vec<u8> {
    [b"Hello, ", name, b"!"].concat()
}

initiate_protocol!()を実行した後、wasm_funcアトリビュートを関数に付与することで関数をTypstにエクスポートすることができます。エクスポートされたgreet関数では、バイト列として受け取った引数にHello,を付加してそれをやはりバイト列として返しています。

Rustには文字列を表すString型がありますが、それは使わずにVec<u8>を関数から返しているのに疑問を持ったかもしれません。これは現状Typstのプラグインは「バイト列を受け取ってバイト列を返すこと」しかできないからです。

では実行するために以下のコマンドでビルドします。

cargo build --release

target/wasm32-unknown-unknown/releaseディレクトリ内にwasmが生成されたはずです。では実際にTypstで読み込んでみましょう。作成プロジェクトのルートに以下のようなTypstファイルを作成します。

sample.typ

#let plugin = plugin("./target/wasm32-unknown-unknown/release/typst_greet.wasm")

#let greet(name) = str(
  plugin.greet(
    bytes(name),
  )
)

#greet("typst")

wasmファイルはplugin関数を用いて読み込み、後は通常のメソッドのように使うことができます。ただし、先程記したようにプラグインとのデータのやり取りはバイト列であるため、bytes関数を使って引数をバイト列とし、str関数を用いて返り値を文字列に戻していることに注意してください。

これを

typst compile sample.typ

でコンパイルすれば…

/images/blog/2024/02/typst-plugin/sample1.png

このようなpdfファイルが生成されているはずです。非常に簡単ですね。

Excel読み込みプラグイン

これだけでは面白くないのでもう少し実用的なものを作りましょう。

自分は表を作る時に雑にExcelで作ることが多いのですが、Typstでxlsxファイルは読み込めないのでCSVにいちいち変換しなければならず面倒です。これを簡略化するためにxlsxファイルを直接読み込むTypstプラグインを作ってみましょう。

一からxlsxファイルを読み込む処理を実装するとなると非常に大変ですが、プラグインを作るのにRustが使えるということは当然Rustのエコシステムを使えるということです。Rustのエコシステムは結構豊富で、今回の目的にドンピシャなcalamineというクレートを見つけました。Pure
Rust製なのでビルドも難しい所はありません(Cライブラリが混ざったRustプロジェクトをwasmにコンパイルするのはまあまあ面倒です)。

では実際にプラグインを作っていきましょう。まずは前節と同様にcargo newでRustプロジェクトを作成してから

cargo add calamine

で依存関係を追加し、以下のコードをlib.rsに書きます。

lib.rs

use calamine::{Reader, Xlsx, XlsxError};
use wasm_minimal_protocol::*;

initiate_protocol!();

fn parse_num(num: &[u8]) -> Result<usize, String> {
    std::str::from_utf8(num)
        .map_err(|e| format!("Invalid number: {e}"))?
        .parse()
        .map_err(|e| format!("Invalid number: {e}"))
}

#[wasm_func]
pub fn get_table(
    data: &[u8],
    sheet: &[u8],
    col: &[u8],
    row: &[u8],
    width: &[u8],
    height: &[u8],
) -> Result<Vec<u8>, String> {
    let sheet = std::str::from_utf8(sheet).map_err(|e| format!("Invalid sheet name: {e}"))?;
    let col = parse_num(col)?;
    let row = parse_num(row)?;
    let width = parse_num(width)?;
    let height = parse_num(height)?;

    let cursor = std::io::Cursor::new(data);
    let mut workbook: Xlsx<_> = calamine::open_workbook_from_rs(cursor)
        .map_err(|e: XlsxError| format!("Failed to open workbook: {e}"))?;
    let sheet_range = workbook
        .worksheet_range(sheet)
        .map_err(|e| format!("Sheet read error: {e}"))?;

    let mut lines = vec![];

    for r in row..row + height {
        let mut line = vec![];
        for c in col..col + width {
            if let Some(cell) =
                sheet_range.get_value((r.try_into().unwrap(), c.try_into().unwrap()))
            {
                line.push(cell.to_string());
            } else {
                line.push("null".to_string());
            }
        }
        lines.push(line.join("\t"));
    }

    Ok(lines.join("\n").into_bytes())
}

get_table関数が実際の処理内容で、calamineクレートでバイト列として受け取ったxlsxファイルの内容を解析し、引数として指定された範囲の内容を読み取っています。
読み取ったデータはTypstで解析できるようにtsvの文字列として返しています。Typstの表データとして直接返せれば良いのですがそのような方法は今は無いようです。

sample.typ

#let plugin = plugin("./target/wasm32-unknown-unknown/release/typst_excel.wasm")

#let get_table(file, sheet, col, row, width, height) = csv.decode(
  plugin.get_table(
    read(file, encoding: none),
    bytes(sheet),
    bytes(str(col)),
    bytes(str(row)),
    bytes(str(width)),
    bytes(str(height))
  ),
  delimiter: "\t"
)

#table(
  columns: 4,
  ..get_table("Book1.xlsx", "Sheet1", 1, 1, 4, 10).flatten()
)

そしてこちらが上のRustコードから生成されたプラグインWASMを実行するためのファイルです。Rust内のget_table関数にxlsxファイルの内容と引数を渡して実行し、tsvとしてパースすることでxlsxファイル内の値を表示しています。

では試しに以下のようなBook1.xlsxを作ってtypst compileを実行してみましょう。

/images/blog/2024/02/typst-plugin/sample2_book.png

するとこのように期待通りの表が得られました！

/images/blog/2024/02/typst-plugin/sample2_pdf.png

今回始めて知ったのですがxlsxでは計算結果もファイルの中に保持してあるようです。数式を取りたければコード内のworksheet_rangeをworksheet_formulaに変えるといいはずです。

ファイルをプラグインから読み込めない理由

先程のコードでは、わざわざTypstからファイルをバイト列として渡していましたが、Rustから直接IOできたりすれば便利なのではないでしょうか？

そのようなことができない直接的な理由は「Typstがサポートしているwasm環境向けターゲットのwasm32-unknown-unknownではファイルを読み込めないから」です。しかしこれは意図的な物であると考えられます。

というのもtypstの関数は純粋でなければならないからです。これによりドキュメントの再現性が確保され、高速な差分コンパイルが実現されています。ここでもしプラグインから外部の環境にアクセスできてしまうと全く純粋ではなくなってしまうわけですね。

なので、プラグイン内で状態を保持することもできません。例えば以下のようなコードを考えてみましょう。

use std::sync::atomic::{AtomicUsize, Ordering};

use wasm_minimal_protocol::*;

initiate_protocol!();

static COUNTER: AtomicUsize = AtomicUsize::new(0);

#[wasm_func]
pub fn count() -> Vec<u8> {
    let count = COUNTER.fetch_add(1, Ordering::SeqCst);
    format!("{}", count).into_bytes()
}

このコードは、countが呼び出される度にCOUNTERに1加算するコードなのですが、これをTypstから複数回呼び出しても結果は全て0になります。これがTypstのプラグインが純粋であるということです。

最後に

いかがでしたか？とても簡単にTypstのプラグインを作成できることがお分かり頂けたかと思います。既存の言語のエコシステムを使って比較的容易に複雑なプラグインを開発することができることはTypstの大きな利点だと思います。

ちなみに、パッケージを作ったらtypst/packagesリポジトリにPRを送ることで公式のプラグインリストに載り、import "@preview/..."でインポートできるようになります。

参考記事:

Typstの日本語Lipsumパッケージを作ってみた件

zenn.dev

また、今回使用したソースコードは

playground/other/typst-plugin at c0fb192f71e71fbbaafcc57673bdc4e931f3dd39 · nazo6/playground

Contribute to nazo6/playground development by creating an account on GitHub.

github.com

で公開しています。

是非みなさんもTypstプラグインを作ってみてください。