HN 日本語サマリー

← 一覧へ戻る
プログラミング

組み合わせの複雑さから線形な優雅さへ:変換エンジンの設計

From Combinatorial Mess to Linear Elegance: Architecting a Conversion Engine (blog.minimal.app)

22 pointsby arthurofbabylon4 コメント

要約

Minimalアプリは、Markdown、Rich Text、HTML、PDFなど複数のファイル形式に対応したインポート/エクスポート機能を提供します。この記事では、ファイル形式間の変換における複雑さを管理するため、中間表現(IR)と呼ばれる統一されたシステムを導入した経緯を説明しています。IRを使うことで、N^2の複雑さを持つ直接変換ではなく、N*2の線形な関係で新しい形式への対応が可能になり、システムの拡張性とメンテナンス性が向上しました。

全文翻訳

Swiftでのコンバージョンエンジンのアーキテクチャ設計

Minimalは現在、Markdown、Rich Text、HTML、PDF、プレーンテキスト、および独自のMNMLフォーマット間のインポートとエクスポートをサポートしています。この記事では、Swiftプログラミング言語でこのシステムをどのように実現したかを説明します。人間中心のデザインと、この新技術をiOSおよびmacOSアプリにどのように組み込んだかについては、デザイン中心の記事をお読みください。

こちら

。

あるファイルフォーマットを別のフォーマットに強制的に変換することは容易ではなく、ますます多くのファイルフォーマットのサポートを追加することは、さらに複雑になります。この複雑さを管理するために、私たちはファイルフォーマット間の仲介役として中間表現(IR)に依存する、まとまりのあるシステムを構築しました。この中間表現(または「IR」)により、考えられるすべてのファイルフォーマットのペア間で変換するのではなく、指定されたファイルフォーマットをIRに変換したり、IRから変換したりするだけで済みます。

中間表現

ノートを直接あるフォーマットから別のフォーマットに変換しようとすると、フォーマットが増えるにつれてますます複雑になる、複雑な変換の網に捕らわれてしまいます。この混乱を避けるために、まず中間表現と呼ばれるシステムを構築しました。

[画像]

混乱とエレガンス。 IRがない場合、6つのファイルフォーマットは30の関係(N^2 - N)を生み出します。IRがある場合、6つのファイルフォーマットは12の異なる関係(N * 2)を生み出します。

IRはすべてのファイルフォーマットの中間に位置します。このアーキテクチャにより、新しいフォーマットのサポートを追加するには、他のファイルフォーマットを一切気にすることなく、そのフォーマット固有のコンバーターを構築するだけで済みます。データ型のサポートを新しいタイプに拡張するにつれて、複雑さは線形に増加します。

自然界もこれを行う

生物学者はこれをボウタイまたは砂時計アーキテクチャと呼びます。要するに、単純化された仲介段階により、相互作用の両側が独立して複雑になることができます。

例えば、細胞は信じられないほど多様な分子を消費し、それをより小さな共有中間体のセットに分解します(異化作用)。反対側では、細胞はこれらの仲介体を複雑な分子の配列に組み立て直し、細胞が利用します(同化作用)。もし細胞がすべての入力分子を入力として必要な出力分子にマッピングする必要があったら、完全に代謝するために現在の数倍の内部プロセスが必要になるでしょう。中間表現はそれを単純化し、操作のどちらの側もより進化しやすくします。

しかし、自然界はプログラマーやデザイナーに強力な教訓を与えています。共有された仲介体に依存するシステムは、しばしば凍結してしまいます。IRは方程式のどちらの側も独自に進化しやすくしますが、より広範なシステムを進化させることをより困難にします。IRの定義を変更すると、それとやり取りするすべてが新しい形状に更新する必要があります。

アーキテクチャロックインの優れた例は、しばしば「凍結された事故」と説明される遺伝暗号です。核酸情報(DNAに保存されRNAとしてコピーされる)は、コドンと呼ばれる3単位のシーケンスで読み取られ、各コドンはアミノ酸鎖の組み立ての指示となります。これらの記号の意味は生命の機械に深く埋め込まれているため、単純に変更したり再解釈したりすることはできません。コドンの意味が変更された場合、細胞によってタンパク質が誤って構築されてしまいます。

遺伝暗号 – コドンとアミノ酸の共有マッピング – は、生物学的中間表現のようなものです。それは核酸シーケンスとタンパク質の構築の間に位置し、標準化されたコードを介して複雑な生命がどのように表現されるかを決定します。この標準が生命全体でほぼ普遍的であるのには理由があります。一度それが細胞機械の表現の中心となると、共有ロジックとルールが変更される可能性はますます低くなりました。

コード

以下は、Swiftで書かれたIRの中間表現のドキュメント構造です。専用パッケージを作成せずに名前の衝突を防ぐために、「IR」名前空間に配置しました(このコードは他のコードと一緒に存在します)。

/// 中間表現のための名前空間。
enum IR {
    // ケースは意図的にありません。下の型をスコープするためだけに存在します。
}


// MARK: - Document

extension IR {
    
    /// 方言に依存しない形式で解析されたノート。
    struct Document: Equatable {
        
        /// 垂直に積み重ねられる`Block`のシーケンス。各`Block`は、水平に積み重ねられる`Inline`のシーケンスを含みます。
        var blocks: [Block]
        
        var resources: [String: Resource]
        
        init(blocks: [Block] = [],
             resources: [String: Resource] = [:]) {
            ...
        }
    }
}


// MARK: - Blocks

extension IR {
    
    /// 垂直に積み重ねられるテキストコンテンツの単位。
    indirect enum Block: Equatable {
        case blankLine
        case paragraph([Inline])
        case codeBlock(language: String?, content: String)
        case heading(level: Int, inlines: [Inline])
        case bulletList([ListItem])
        case orderedList(items: [ListItem], start: Int)
        case todoList([TodoItem])
        case blockquote([Block])
        case pullquote([Inline])
        case horizontalRule
        case embed(resourceId: String)
    }
    
    struct ListItem: Equatable {
        var blocks: [Block]
        init(blocks: [Block]) { self.blocks = blocks }
    }
    
    struct TodoItem: Equatable {
        var checked: Bool
        var blocks: [Block]
        init(checked: Bool, blocks: [Block]) {
            ...
        }
    }
}


// MARK: - Inlines

extension IR {
    
    /// ブロック内で水平に流れるコンテンツ。
    indirect enum Inline: Equatable {
        case text(String)
        case strong([Inline])
        case emphasis([Inline])
        case underline([Inline])
        case link(url: String, inlines: [Inline])
        case inlineCode(String)
        case folder(name: String)
        case embed(resourceId: String)
        case lineBreak
    }
}


// MARK: - Resources

extension IR {
    
    /// 埋め込みペイロード。ツリーからオフセットされ、IDで参照されます。
    struct Resource: Equatable {
        
        var kind: String
        
        var mimeType: String?
        
        var data: Data?
        
        var url: String?
        
        var attributes: [String: String]
        
        init(kind: String,
             mimeType: String? = nil,
             data: Data? = nil,
             url: String? = nil,
             attributes: [String: String] = [:]) {
            ...
        }
    }
}

IR(中間表現)構造を記述した実際のコード。

すべてのファイルフォーマットが同じ規約をサポートしているわけではありません(例:Markdownは色付きテキストを表現できず、MNMLはテーブルをサポートしていません)。そのため、変換中にしばしば譲歩(concessions)が発生します。

/// 変換中にエンジンが単純化、ダウングレード、または脇に置いたものの記録。
struct Concession: Equatable {
    
    var category: Category
    
    var description: String
    
    var count: Int?
    
    init(category: Category,
         description: String,
         count: Int? = nil) {
        ...
    }
    
    enum Category: Equatable {
        case unsupportedFormatting
        case downgraded
        case dropped
        case truncated
    }
}

extension Array where Element == Concession {
    
    mutating func appendOrIncrement(_ concession: Concession) {
        ...
    }
}

譲歩の集約とレポートの構造を記述した実際のコード。

パーシングとレンダリング

変換は、ソースファイルをIRにパースすることから始まり、IRをターゲットファイルフォーマットにレンダリングすることで終わります。以下はDocumentParserおよびDocumentRendererプロトコルです。各ファイルフォーマットは、これらのプロトコルの専用実装を作成することで、パースとレンダリングのロジックを実装する必要があります。

/// 特定の`Format`のソーステキストから`IR.Document`を生成するためのプロトコル。
/// 各パーサーは正確に1つの入力フォーマットを処理します — `DocumentParserMinimal`はMNMLを読み込み、`DocumentParserHTML`はHTMLを読み込みます。オーケストレーターは、呼び出し元の`Format`に基づいて適切なパーサーを選択します。
/// パーサーはレンダリングを行いません。唯一の出力は中間表現と、発生した譲歩です。
protocol DocumentParser {
    
    /// このパーサーが処理する入力フォーマット。
    var format: Format { get }
    
    /// `source`をIRドキュメントにパースします。
    /// IRが表現できないコンテンツは、結果の譲歩に記録されます。
    func parse(_ source: String) throws -> ParseResult
}

/// パースの結果:IRドキュメントと、単純化されたものの記録。
struct ParseResult: Equatable {
    var document: IR.Document
    var concessions: [Concession]
    
    init(document: IR.Document, concessions: [Concession] = []) {
        self.document = document
        self.concessions = concessions
    }
}

DocumentParserプロトコル。実際のコード。

/// `IR.Document`から特定の`Format`の出力を生成するためのプロトコル。
/// 各レンダラーは正確に1つの出力フォーマットを処理します:`HTMLRenderer`はHTMLを出力し、`MNMLRenderer`はMNMLを出力します。オーケストレーターは、呼び出し元の`Format`に基づいて適切なレンダラーを選択します。
/// レンダラーはパースを行いません。唯一の入力は中間表現であり、唯一の出力はレンダリングされた形式と、それを生成する際に発生した譲歩です(`RenderResult`を参照)。
protocol DocumentRenderer {
    
    /// このレンダラーが生成する出力フォーマット。
    var format: Format { get }
    
    /// `document`をこのレンダラーのフォーマットにレンダリングします。
    /// ターゲットフォーマットが表現できないIRコンテンツは、結果の譲歩に記録されます。
    func render(_ document: IR.Document) throws -> RenderResult
}

/// レンダリングの結果:出力ペイロードと、単純化されたものの記録。
/// 出力は`Data`として渡されるため、この構造体はテキストフォーマットとバイナリフォーマットの両方に使用できます。
/// テキストフォーマット(HTML、Markdown、MNML、プレーンテキスト、RTF)は`data`をUTF-8バイトで埋め、バイナリフォーマット(PDF)は直接埋め込みます。
struct RenderResult: Equatable {
    var data: Data
    var concessions: [Concession]
    
    init(data: Data, concessions: [Concession] = []) {
        self.data = data
        self.concessions = concessions
    }
}

DocumentRendererプロトコル。実際のコード。

例えば、HTMLをサポートするためにDocumentParserHTMLとDocumentRendererHTMLを実装し、MarkdownをサポートするためにDocumentParserMarkdownとDocumentRendererMarkdownを実装することで、HTMLとMarkdownファイル間で変換できるようになりました。各ファイルタイプのパーサーとレンダラーを構築することで、それらを簡単に相互に変換できます。

HTMLファイルをMarkdownに変換する方法は次のとおりです。

let content = try readFile(at: url)
let parseResult = try? DocumentParserHTML().parse(content)
let renderResult = try? DocumentRendererMarkdown().render(parseResult.document)
let renderedMarkdownText = String(decoding: renderResult.data, as: UTF8.self)

深いモジュールと浅いインターフェース(John Ousterhoutに敬意を表して)により、コンバージョンエンジンの使用は非常に簡単です。

Notesアプリへの統合

Minimalアプリ内でコンバージョンエンジンを高く評価される機能にするには、慎重な検討が必要でした。明らかなケースは単純です。ノートのエクスポートとインポートですが、より微妙な機能の機会があることに気づきました。これは、私たちのアプリがすべてである機会です(インターフェースなしで機能を提供できれば、私たちは満足です)。

[画像]

1つ以上のノートをエクスポートします。1つ以上のファイルをインポートします。

当初、コンバージョンエンジンは、他のライティングアプリからのインポートをサポートし、Macファイルシステムへのエクスポートをサポートしてほしいという大量のリクエストに応えるために構築されました。コンバージョンエンジンが動作するようになると、正式な「エクスポート」または「インポート」ダイアログだけでなく、Minimal全体で使用されるべきだと気づきました。

以下のインポートのサーフェスエリアに遭遇し、それぞれのケースにファーストクラスのサポートを構築しました。

  • ノートリストへのドラッグ
  • ノートへのドラッグ
  • ノートリストへのペースト
  • ノートへのファイルのペースト、およびノートへのリッチテキストのペースト(例:PagesからコピーしてMinimalにペースト)
  • システム共有をサポートするアプリからの共有拡張機能を使用したノートのインポート
  • メニュー > ファイル > インポート

エクスポートについても同様です。

  • ノートアクションボタン > エクスポート
  • ノートリスト > 右クリック/長押し > エクスポート
  • コマンド-シフト-E エクスポートキーボードショートカット
  • コマンド-オプション-E を介した、最も最近使用されたエクスポート設定を使用してノートを即座にエクスポートするクイックエクスポート
  • メニュー > ファイル > エクスポート

[画像]

ライターはファイルをノートリストにドラッグするだけで、元のフォーマットと構造を維持した、エレガントで新しいノートを作成できます。

これらのすべてのシナリオに対応するために、ファイルタイプの検出、フォルダの再帰的な処理、譲歩の生成とインポート/エクスポートの劣化の報告、バルクインポート/エクスポート中のファイルのステージング、およびラウンドトリップエクスポート・インポートフローのサポートを行う一連のユーティリティを構築しました。

エクスポート・インポートのラウンドトリップをサポートするために、独自の.mnmlファイルタイプを構築しました。ライターがこれらのファイルをインポートすると、Minimalはノートをそのままインポートすることを認識し、譲歩を一切回避しながら、100%の確率で完全に再インポートします。

extension UTType {

	 // (Info.plistで`UTExportedTypeDeclarations`経由で宣言)
    
    /// Minimalのファーストクラスファイルフォーマット。MNML規約をそのまま保持します。
    /// 完全な忠実度でMinimalを介したラウンドトリップが可能です。
    static let mnml: UTType = UTType("app.minimal.mnml") ?? .plainText
    
    /// Markdownツール全体で広く採用されている事実上のMarkdown UTI。
    static let markdown = UTType(importedAs: "net.daringfireball.markdown")
}

独自のMNMLファイルタイプ。実際のコード。

リッチテキストのコピー&ペーストをサポートするために、複数のフォーマットに対応し、アプリ内ペーストが損失の多いコンバージョンエンジンのラウンドトリップを回避することを保証する独自のペーストボードを構築しました。

/// ライターがMinimalからコピーしてどこにでもペーストできるように、さまざまなデータタイプ(プレーンテキスト、RTF、HTML、ネイティブMinimalプレーンテキスト)を提供します。
/// アプリ内コピー&ペーストがRTFを介したラウンドトリップを回避するための、ネイティブMinimal固有のデータタイプが含まれています。
enum MinimalPasteboard {
    
    /// ペーストを有効にするペーストボードタイプ。リッチなものから順に。
    static let pasteableTypeIdentifiers: [String] = [
        UTType.rtf.identifier,
        UTType.html.identifier,
        UTType.utf8PlainText.identifier,
        UTType.plainText.identifier,
        UTType.text.identifier,
    ]
    
    /// `source`(ライターの言語でのテキスト)をコピーするためのペーストボードアイテムを構築します。
    /// ネイティブ表現とプレーン表現は常に存在します。RTF/HTMLはベストエフォートです。
    static func pasteboardItem(for source: String) -> [String: Any] {
        var item = MinimalPasteboard.nativeItem(for: source)
        item[UTType.utf8PlainText.identifier] = source
        if let document = try? StyleSettings.preferredParser().parse(source).document {
            if let rtf  = try? DocumentRendererRTF().render(document).data  { item[UTType.rtf.identifier]  = rtf }
            if let html = try? DocumentRendererHTML().render(document).data { item[UTType.html.identifier] = html }
        }
        return item
    }
    
    
    // MARK: Native Source
    
    private static let nativeType = UTType.mnml.identifier
    
    /// コピー時にペーストボードアイテムにマージされるネイティブエントリ。
    private static func nativeItem(for source: String) -> [String: Any] { [nativeType: Data(source.utf8)] }
    
    /// ペーストボードに存在する場合の、Minimal独自のソース。
    static func nativeSource(from pasteboard: UIPasteboard) -> String? {
        guard let data = pasteboard.data(forPasteboardType: nativeType) else { return nil }
        return String(data: data, encoding: .utf8)
    }
}

多数のファイルフォーマットに対応するためのペーストボードオーバーライド。実際のコード。

これらの機能は強力に組み合わさります。例えば、ライターはApple IDを変更したり、ノートを仕事用コンピュータから個人用デバイスに移動したりする際に、数千のノートを自信を持って一括エクスポートできます。別の例として、ライターはMinimalに技術文書を保存し、クイックエクスポートキーボードショートカットを使用して、MarkdownファイルをClaudeやChatGPTのようなLLMに直接すばやくコピー&ペーストできます。

let quickExport = UIKeyCommand(title: "Quick Export",
                                       action: #selector(quickExportNoteViaCommand),
                                       input: "E",
                                       modifierFlags: [.command, .alternate],
                                       discoverabilityTitle: "Quick Export")

クイックエクスポート用のUIKeyCommand。実際のコード。

これはクイックエクスポートの結果です。Claudeはファイルをコンテキストに読み込み、より関連性の高い応答を生成する準備ができています。

[画像]

コマンド-オプション-E(クイックエクスポート)とコマンド-V(ペースト)を使用すると、ノートを.mdファイルとして大規模言語モデルとすばやく共有できます。


コンバージョンエンジン自体は強力なコードですが、真のユーティリティは、エンジンがMinimalアプリ全体に統合される場所に存在します。設計上の選択についてはこちらでお読みいただけます。

人間によって書かれました。