はじめに

wicket は Wikipedia XML ダンプファイルからプレーンテキストを抽出する高性能ツールです。並列処理と効率的なストリーミングにより高速な処理を実現しています。

主な機能

• ストリーミング XML パース – メモリに全体を読み込まず、数十 GB のダンプに対応
• 並列テキスト抽出 – rayon による複数 CPU コアの活用
• bzip2 自動展開 – .xml.bz2 ダンプファイルの透過的な展開
• 2種類の出力フォーマット – doc フォーマットおよび JSON フォーマット
• ファイル分割 – 出力ファイルの最大サイズを指定可能
• 名前空間フィルタリング – 特定のページ種別のみ抽出（メイン記事、トークページなど）

出力フォーマット

doc フォーマット（デフォルト）

<doc id="1" url="https://en.wikipedia.org/wiki/April" title="April">
April is the fourth month of the year...
</doc>

JSON フォーマット

{"id":"1","url":"https://en.wikipedia.org/wiki/April","title":"April","text":"April is the fourth month of the year..."}

現在のバージョン

wicket v0.1.0 – Rust Edition 2024、最小 Rust バージョン 1.85。

リンク

• GitHub リポジトリ
• crates.io
• API ドキュメント (docs.rs)
• English Documentation

導入

wicket へようこそ！このセクションでは、すぐに使い始められるよう案内します。

wicket は Wikipedia XML ダンプファイルからプレーンテキストを抽出します。MediaWiki XML ダンプ（bzip2 圧縮にも対応）を読み込み、Wiki マークアップを除去し、doc または JSON フォーマットでクリーンなテキストを出力します。

次のステップ

• インストール – ソースまたは crates.io からインストール
• クイックスタート – Wikipedia ダンプからテキストを抽出

インストール

前提条件

• Rust 1.85 以上（stable チャンネル）– rust-lang.org から入手
• Cargo（Rust のパッケージマネージャ、Rust に同梱）

CLI ツールのインストール

crates.io から

cargo install wicket-cli

ソースから

git clone https://github.com/mosuka/wicket.git
cd wicket
cargo build --release

バイナリは ./target/release/wicket に生成されます。

インストールの確認:

./target/release/wicket --help

ライブラリとして使用

プロジェクトの Cargo.toml に追加:

[dependencies]
wicket = "0.1.0"

サポートプラットフォーム

wicket は以下のプラットフォームでテストされています:

クイックスタート

Wikipedia ダンプの入手

https://dumps.wikimedia.org/ から Wikipedia ダンプをダウンロードします。テスト用には、サイズの小さい Simple English Wikipedia ダンプがおすすめです:

wget https://dumps.wikimedia.org/simplewiki/latest/simplewiki-latest-pages-articles.xml.bz2

CLI クイックスタート

基本的な抽出

Wikipedia ダンプからプレーンテキストを抽出:

wicket simplewiki-latest-pages-articles.xml.bz2 -o output/

ダンプを読み込み、メイン名前空間の全記事からプレーンテキストを抽出し、doc フォーマットで output/ ディレクトリに出力します。ファイルは 1 MB ごとに分割されます。

JSON 出力

wicket simplewiki-latest-pages-articles.xml.bz2 -o output/ --json

標準出力に書き出し

wicket simplewiki-latest-pages-articles.xml.bz2 -o - -q | head -50

ライブラリ クイックスタート

ダンプを開いて記事を処理する最小限の Rust プログラム:

use wicket::{open_dump, clean_wikitext, format_page, make_url, OutputFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = open_dump("simplewiki-latest-pages-articles.xml.bz2".as_ref(), &[0])?;
    let url_base = reader.url_base().to_string();

    for result in reader.take(5) {
        let article = result?;
        let text = clean_wikitext(&article.text);
        let url = make_url(&url_base, &article.title);
        let output = format_page(
            article.id, &article.title, &url, &text, OutputFormat::Doc,
        );
        println!("{}", output);
    }

    Ok(())
}

次のステップ

• CLI リファレンス – 全 CLI オプション
• アーキテクチャ – wicket の内部構造

アーキテクチャ概要

wicket は高性能なストリーミング Wikipedia ダンプテキスト抽出ツールとして設計されています。ストリーミング I/O とバッチベースの並列処理を組み合わせて、数十 GB の XML ダンプを処理します。

全体のデータフロー

入力 (.xml / .xml.bz2)
  |
  v
DumpReader (ストリーミング XML パース + 名前空間フィルタ)
  |  Article { id, title, namespace, text } を生成
  v
バッチ (1000 記事)
  |
  v
rayon par_iter (並列処理)
  |  clean_wikitext(text) -> プレーンテキスト
  |  format_page(id, title, url_base, text, format) -> フォーマット済み文字列
  v
OutputSplitter (逐次書き込み、ファイルローテーション)
  |
  v
出力ファイル (AA/wiki_00, AA/wiki_01, ...)

設計原則

• ストリーミング処理 – XML はストリームとしてパースされ、一度にメモリ上に置くのは1記事のみ
• バッチ並列処理 – CPU バウンドな Wikitext クリーニングを rayon で並列化し、I/O は逐次実行
• 構造化出力 – doc フォーマットと JSON フォーマット、整理されたディレクトリ構造
• フェイルソフト – 不正なページはログに記録してスキップし、全体の処理は停止しない
• ライブラリファースト – コア機能は wicket ライブラリクレートに集約。CLI は薄いラッパー

ワークスペース構成

wicket は Cargo workspace で2つのクレートと関連ディレクトリを管理しています。

ディレクトリ構成

wicket/
├── Cargo.toml              # Workspace マニフェスト
├── Cargo.lock              # 依存ロックファイル
├── LICENSE                 # MIT OR Apache-2.0
├── README.md               # プロジェクト概要
├── wicket/                # コアライブラリクレート
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs          # モジュール宣言と再エクスポート
│       ├── dump.rs         # XML ダンプ ストリーミングパーサー
│       ├── cleaner.rs      # Wikitext → プレーンテキスト変換
│       ├── extractor.rs    # 出力フォーマット (doc/JSON)
│       ├── output.rs       # ファイル分割とローテーション
│       └── error.rs        # エラー型
├── wicket-cli/            # CLI バイナリクレート
│   ├── Cargo.toml
│   └── src/
│       └── main.rs         # CLI エントリーポイント
├── docs/                   # mdBook ドキュメント
│   ├── book.toml
│   ├── src/
│   └── ja/                 # 日本語ドキュメント
│       ├── book.toml
│       └── src/
└── .github/
    └── workflows/          # CI/CD パイプライン
        ├── regression.yml  # push/PR 時のテスト
        ├── release.yml     # リリースビルドと公開
        ├── periodic.yml    # 週次安定性テスト
        └── deploy-docs.yml # ドキュメントデプロイ

クレート詳細

wicket (コアライブラリ)

ストリーミング XML パース、Wikitext クリーニング、出力フォーマット、ファイル分割を提供するコアライブラリです。

wicket-cli (CLI バイナリ)

wicket の機能をコマンドラインインターフェースで提供します。

ワークスペース設定

Cargo resolver version 3（Rust Edition 2024）を使用:

[workspace]
resolver = "3"
members = ["wicket", "wicket-cli"]

[workspace.package]
version = "0.1.0"
edition = "2024"
license = "MIT OR Apache-2.0"

共有依存はワークスペースレベルの [workspace.dependencies] で定義し、各クレートでは { workspace = true } で参照します。

モジュール設計

wicket ライブラリクレートは5つのモジュールで構成され、それぞれ明確な責務を持ちます。

モジュール概要

モジュール詳細

dump – XML ダンプリーダー

quick-xml を使用したストリーミング XML パーサー。MediaWiki XML ダンプファイルを読み込み、Article 構造体を生成します。

• Article – id (u64)、title (String)、namespace (i32)、text (String) を持つ Wikipedia ページ
• DumpReader<R: BufRead> – 名前空間フィルタリング付きで XML ソースから記事をストリーミングするイテレータ
• open_dump(path, namespaces) – MultiBzDecoder による .bz2 自動検出付きでダンプファイルを開く

リーダーは <siteinfo><base> を解析して Wiki の URL ベースを抽出し、url_base() で公開します。

cleaner – Wikitext クリーナー

2段階のアプローチで MediaWiki マークアップをプレーンテキストに変換:

1. AST ベースクリーニング – parse_wiki_text_2 で Wikitext を AST にパースし、テキストコンテンツを抽出
2. 正規表現フォールバック – AST パース失敗時や AST で処理できないマークアップに対して正規表現ベースのクリーンアップを適用

主な関数: clean_wikitext(wikitext: &str) -> String

extractor – 出力フォーマッター

抽出された記事を最終的な出力形式にフォーマットします。

• OutputFormat – Doc と Json のバリアントを持つ列挙型
• format_page(id, title, url, text, format) – 1記事をフォーマット
• make_url(url_base, title) – Wikipedia 記事の URL を構築
• parse_file_size(spec) – 1M、500K、1G などのサイズ指定をパース

output – ファイルスプリッター

2文字ディレクトリ命名規則に従い、抽出記事を分割ファイルに書き込みます。

• OutputConfig – 出力パス、最大ファイルサイズ、圧縮の設定
• OutputSplitter – AA/wiki_00 命名によるファイルローテーション管理（1ディレクトリ100ファイル、AA〜ZZ）

stdout 出力（path = "-"）、bzip2 圧縮、ファイルサイズ制限をサポートします。

error – エラー型

thiserror を使用した Error 列挙型:

• Io – I/O エラー
• XmlReader – quick-xml の XML パースエラー
• JsonSerialization – JSON シリアライゼーションエラー

パブリックエクスポート

lib.rs では主要な型を利便性のために再エクスポートしています:

#![allow(unused)]
fn main() {
pub use cleaner::clean_wikitext;
pub use dump::{open_dump, Article, DumpReader};
pub use error::Error;
pub use extractor::{format_page, make_url, parse_file_size, OutputFormat};
pub use output::{OutputConfig, OutputSplitter};
}

データフロー

このページでは、wicket における入力から出力までのデータの流れを説明します。

処理パイプライン

入力 (.xml / .xml.bz2)
  |
  v
DumpReader (ストリーミング XML パース + 名前空間フィルタ)
  |  Article { id, title, namespace, text } を生成
  v
バッチ (1000 記事)
  |
  v
rayon par_iter (並列処理)
  |  clean_wikitext(text) -> プレーンテキスト
  |  format_page(id, title, url_base, text, format) -> フォーマット済み文字列
  v
OutputSplitter (逐次書き込み、ファイルローテーション)
  |
  v
出力ファイル (AA/wiki_00, AA/wiki_01, ...)

各ステージの詳細

1. XML ダンプ読み込み

DumpReader は quick-xml を使用して MediaWiki XML ダンプをストリームとしてパースします。.xml.bz2 ファイルの場合、ストリームは MultiBzDecoder で自動的にラップされ、透過的に展開されます。

リーダーが抽出する情報:

• ページ ID（<page> 内の <id>、<revision> 内のものではない）
• タイトル（<title>）
• 名前空間（<ns>）
• Wikitext 本文（<text>）
• URL ベース（起動時に <siteinfo><base> から1回だけ抽出）

フィルタリスト外の名前空間を持つページはイテレータレベルでスキップされます。

2. バッチ収集

DumpReader イテレータから記事を1000件ずつバッチで収集します。このバッチサイズは、並列化のオーバーヘッドとメモリ使用量のバランスを取っています。

3. 並列処理

各バッチは rayon::par_iter() で処理され、CPU コアに作業を分散します:

1. clean_wikitext(text) – Wikitext マークアップをプレーンテキストに変換。最も CPU 負荷が高いステップ。
2. format_page(id, title, url, text, format) – クリーンなテキストを doc または JSON フォーマットに整形。

結果は順序を保持して収集されます（rayon の par_iter は要素の順序を維持）。

4. 逐次出力

フォーマット済みの文字列は OutputSplitter に逐次書き込まれます:

• 必要に応じてサブディレクトリ（AA、AB、…、ZZ）を作成
• 設定されたサイズ上限に達したら新しいファイルにローテーション
• 有効時は bzip2 圧縮を適用
• パスが "-" の場合は stdout に出力

並列化戦略

wicket はチャネルを使ったパイプラインではなく、バッチベースの並列化アプローチを採用しています:

1. メインスレッドが DumpReader から1000記事ずつバッチで読み込み
2. 各バッチを rayon::par_iter() で並列処理
3. 決定的な出力順序を維持するため、結果を逐次書き込み
4. 全記事の処理が完了するまで繰り返し

このアプローチはシンプルで、出力順序を維持し、CPU バウンドなクリーニング処理を効果的に並列化しつつ、I/O バウンドな読み込みと書き込みは逐次実行します。

ライブラリ API 概要

wicket クレートは、Wikipedia XML ダンプファイルからプレーンテキストを抽出する Rust API を提供します。

インストール

[dependencies]
wicket = "0.1.0"

モジュール一覧

使用例

use wicket::{open_dump, clean_wikitext, format_page, make_url, OutputFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = open_dump("dump.xml.bz2".as_ref(), &[0])?;
    let url_base = reader.url_base().to_string();

    for result in reader {
        let article = result?;
        let text = clean_wikitext(&article.text);
        let url = make_url(&url_base, &article.title);
        let output = format_page(
            article.id, &article.title, &url, &text, OutputFormat::Doc,
        );
        print!("{}", output);
    }

    Ok(())
}

API ドキュメント

完全な API ドキュメントは docs.rs/wicket で参照できます。

dump

dump モジュールは MediaWiki ダンプファイルのストリーミング XML パースを提供します。

型

Article

ダンプから抽出された1つの Wikipedia ページ。

DumpReader<R: BufRead>

XML ダンプソースから Article 値をストリーミングするイテレータ。

• Iterator<Item = Result<Article, Error>> を実装
• イテレータレベルで名前空間フィルタリング
• url_base() で <siteinfo> から取得した Wiki のベース URL を公開

関数

open_dump(path: &Path, namespaces: &[i32]) -> Result<DumpReader<...>>

Wikipedia XML ダンプファイルを読み込み用に開きます。

• .bz2 拡張子を自動検出して MultiBzDecoder を適用
• <siteinfo> を解析して URL ベースを抽出
• 名前空間フィルタリングを設定

使用例

#![allow(unused)]
fn main() {
use wicket::open_dump;

let reader = open_dump("dump.xml.bz2".as_ref(), &[0])?;
println!("URL base: {}", reader.url_base());

for result in reader {
    let article = result?;
    println!("[{}] {}", article.id, article.title);
}
}

cleaner

cleaner モジュールは MediaWiki の Wikitext マークアップをプレーンテキストに変換します。

関数

clean_wikitext(wikitext: &str) -> String

生の Wikitext を、すべての MediaWiki マークアップを除去したクリーンなプレーンテキストに変換します。

クリーニング処理は3段階のアプローチを使用します:

1. AST ベースクリーニング – parse_wiki_text_2 で Wikitext を AST にパースし、関連ノードからテキストコンテンツを抽出
2. 正規表現フォールバック – AST パース失敗時や AST で処理できないマークアップに対して、正規表現ベースのパターン除去を適用
3. 後処理 – 最初の2段階で残ったマークアップ残骸（孤立したテンプレート閉じ括弧 }}、テンプレートパラメータ行、HTML コメント断片など）を除去

パーサーは英語版・日本語版両方の Wikipedia 名前空間に対応しており、 設定変更なしでどちらの言語のダンプも正しく処理できます。

対応するマークアップ

クリーナーは以下の MediaWiki マークアップ要素を処理します:

• 太字/斜体 – '''太字''' および ''斜体''
• 内部リンク – [[記事]] および [[記事|表示テキスト]]
• 外部リンク – [https://example.com テキスト]
• テンプレート – {{テンプレート|...}}
• HTML タグ – <ref>、<nowiki>、<gallery> など
• カテゴリ – [[Category:...]] および [[カテゴリ:...]]
• ファイル – [[File:...]]、[[Image:...]]、[[ファイル:...]]
• テーブル – Wikitext テーブルマークアップ
• コメント – <!-- コメント -->
• マジックワード – __TOC__、__NOTOC__ など
• リダイレクト – #REDIRECT および #転送

使用例

#![allow(unused)]
fn main() {
use wicket::clean_wikitext;

let wikitext = "'''April''' is the [[month|fourth month]] of the year.";
let text = clean_wikitext(wikitext);
assert_eq!(text, "April is the fourth month of the year.");
}

extractor

extractor モジュールは抽出された記事を最終的な出力形式にフォーマットします。

型

OutputFormat

出力フォーマットを指定する列挙型。

関数

format_page(id: u64, title: &str, url: &str, text: &str, format: OutputFormat) -> String

1つの記事を指定されたフォーマットで整形します。

doc フォーマット出力:

<doc id="1" url="https://en.wikipedia.org/wiki/April" title="April">
April is the fourth month of the year...
</doc>

JSON フォーマット出力:

{"id":"1","url":"https://en.wikipedia.org/wiki/April","title":"April","text":"April is the fourth month of the year..."}

make_url(url_base: &str, title: &str) -> String

URL ベースとタイトルから完全な Wikipedia 記事 URL を構築します。タイトル中のスペースはアンダースコアに置換されます。

parse_file_size(spec: &str) -> Result<u64, Error>

人間が読めるファイルサイズ指定をバイト数に変換します。

output

output モジュールは2文字のディレクトリ命名規則に従い、抽出された記事を分割出力ファイルに書き込みます。

型

OutputConfig

出力スプリッターの設定。

OutputSplitter

ファイルローテーションと書き込みを管理します。必要に応じてサブディレクトリとファイルを作成します。

ディレクトリ命名規則

出力ファイルは以下の命名規則で整理されます:

output/
  AA/
    wiki_00
    wiki_01
    ...
    wiki_99
  AB/
    wiki_00
    ...

• 各ディレクトリには最大100ファイルが格納
• ディレクトリ名は AA、AB、…、AZ、BA、…、ZZ のパターン
• compress 有効時はファイル名が wiki_00.bz2 のようになる

特殊モード

• stdout モード – path が "-" の場合、分割せずにすべての出力を stdout に書き込み
• ゼロサイズ – max_file_size が 0 の場合、各記事を個別のファイルに書き込み

error

error モジュールは wicket ライブラリ全体で使用されるエラー型を定義します。

エラー型

Error 列挙型は thiserror を使用して導出され、すべてのエラー条件をカバーします:

Result 型

ライブラリは Result 型エイリアスを提供します:

#![allow(unused)]
fn main() {
pub type Result<T> = std::result::Result<T, Error>;
}

ライブラリのすべてのパブリック関数はこの Result 型を返します。

CLI リファレンス概要

wicket CLI は Wikipedia XML ダンプファイルからプレーンテキストを抽出します。

使い方

wicket [OPTIONS] <INPUT>

クイックリファレンス

詳細ドキュメント

• オプション – 全 CLI オプションの詳細説明
• 使用例 – よくある使用パターンと例

CLI オプション

入力

wicket <INPUT>

入力ファイルは位置引数です。Wikipedia XML ダンプファイルで、非圧縮（.xml）または bzip2 圧縮（.xml.bz2）のいずれかです。圧縮はファイル拡張子で自動検出されます。

出力ディレクトリ

wicket dump.xml.bz2 -o output/
wicket dump.xml.bz2 -o -

-o, --output <PATH> – 出力ディレクトリを指定します。デフォルトは text。

• ディレクトリパスを指定した場合、2文字ディレクトリ命名規則（AA/wiki_00 など）でファイルを作成
• - を指定した場合、ファイル分割せずにすべての出力を stdout に書き込み

ファイルサイズ

wicket dump.xml.bz2 -b 500K
wicket dump.xml.bz2 -b 1M
wicket dump.xml.bz2 -b 1G
wicket dump.xml.bz2 -b 0

-b, --bytes <SIZE> – 出力ファイルの最大バイト数。デフォルトは 1M。

サポートされるサフィックス: K（キロバイト）、M（メガバイト）、G（ギガバイト）。0 を指定すると各記事が個別のファイルに書き込まれます。

圧縮

wicket dump.xml.bz2 -c

-c, --compress – bzip2 で出力ファイルを圧縮。出力ファイルには .bz2 拡張子が付きます。

JSON 出力

wicket dump.xml.bz2 --json

--json – デフォルトの doc フォーマットの代わりに JSON Lines フォーマット（1行1JSON オブジェクト）で出力します。

並列ワーカー数

wicket dump.xml.bz2 --processes 8

--processes <N> – テキストクリーニングの並列ワーカー数。デフォルトは CPU コア数。

静粛モード

wicket dump.xml.bz2 -q

-q, --quiet – stderr への進捗出力を抑制。パイプで他のコマンドに出力を渡す際に便利です。

名前空間フィルタリング

wicket dump.xml.bz2 --namespaces 0
wicket dump.xml.bz2 --namespaces 0,1,2

--namespaces <IDS> – 抽出する名前空間 ID のカンマ区切りリスト。デフォルトは 0（メイン記事のみ）。

主な名前空間 ID:

CLI 使用例

基本的な抽出

Wikipedia ダンプからテキストをデフォルトの text/ ディレクトリに抽出:

wicket simplewiki-latest-pages-articles.xml.bz2

カスタム出力ディレクトリ

wicket dump.xml.bz2 -o output/

標準出力に書き出し

パイプで他のコマンドに直接出力:

wicket dump.xml.bz2 -o - -q | wc -l

JSON 出力 + 圧縮

wicket dump.xml.bz2 -o output/ --json -c

トークページの抽出

名前空間 1（トークページ）を 8 ワーカーで抽出:

wicket dump.xml.bz2 -o output/ --namespaces 1 --processes 8

複数の名前空間

メイン記事とユーザーページを抽出:

wicket dump.xml.bz2 -o output/ --namespaces 0,2

小さいファイルに分割

出力を 500 KB ファイルに分割:

wicket dump.xml.bz2 -o output/ -b 500K

1記事1ファイル

wicket dump.xml.bz2 -o output/ -b 0

出力ディレクトリ構造

抽出後の出力ディレクトリ:

output/
  AA/
    wiki_00
    wiki_01
    ...
    wiki_99
  AB/
    wiki_00
    ...

--compress 使用時:

output/
  AA/
    wiki_00.bz2
    wiki_01.bz2
    ...

ライセンス

wicket はデュアルライセンスで配布されています。

MIT ライセンス

MIT License

Copyright (c) 2025 Minoru OSUKA

Apache License 2.0

Apache License, Version 2.0

Copyright (c) 2025 Minoru OSUKA

ライセンス全文

完全なライセンステキストはリポジトリの LICENSE ファイルで確認できます。