org-mode で現在の構文要素に応じて適切なメニューを出す

org-modeには標準でorg-elementというのが入っていて、現在位置の構文要素を簡単に割り出せるようになっています。

バッファ(文書)全体を解析する org-element-parse-buffer という関数もありますが、部分的な解析には org-element-at-point と org-element-context という関数が使いやすいです。この二つの関数は共にセクション(見出しと見出しで区切られた範囲)以上の解析は行わず、現在のポイントの近くにある要素を返す関数です。 org-element-at-point は行内要素を含まない大きな構造のみを返し、org-element-context は内部で org-element-at-point を使用しつつ、行内の細かい要素も解析して一番限定された狭い要素を返します。

なので結論から言えば、現在のポイントにある構文要素に関する情報を得たければ (org-element-context) だけでおしまいです。

org-element-context の結果は、例えば次ような リスト です。

(bold
 (:begin 1739
  :end 1745
  :contents-begin 1740
  :contents-end 1743
  :post-blank 1
  :parent (paragraph
           (:begin 1728
            :end 1750
            :contents-begin 1728
            :contents-end 1749
            :post-blank 1
            :post-affiliated 1728
            :parent nil))))

これは実際に上の太字になっているところで M-: (org-element-context) を実行した結果です。boldで始まるノードの親(:parent)としてparagraphで始まるノードが続いているのが見て取れます。その上はsection、headlineと続くはずなのですが、org-element-context(というかorg-element-at-point)はそこまでは解析しません。

ノードから情報を取得するには org-element-type や org-element-property 関数(アクセッサ)を使用します。次のように。

(let ((datum (org-element-context)))
  (list
    (org-element-type datum) ;; => bold
    (org-element-property :begin datum) ;; => 1739
    (org-element-property :end datum))) ;; => 1745

要素の開始点と終了点は必ず取得できるので、これだけで全ての要素に適用出来るコマンドを記述できます。例えば要素全体のマーク(選択)やカット、コピーを実装するのは簡単です。

(defun my-org-kill-element (datum)
  (interactive (list (org-element-context)))
  (kill-region (org-element-property :begin datum)
               (org-element-property :end datum))) ;;本当は色々細かい問題があるのだけどまぁいいや……

org-element-type関数が返すboldやparagraphといったシンボルは type と呼ばれていて構文要素の種類を表します。

ところで皆さんはorg-modeにどのくらいの種類の構文要素があるかご存じですか？

org-elements.elの中には次のように書かれている部分があります。

(defconst org-element-all-elements
  '(babel-call center-block clock comment comment-block diary-sexp drawer
               dynamic-block example-block export-block fixed-width
               footnote-definition headline horizontal-rule inlinetask item
               keyword latex-environment node-property paragraph plain-list
               planning property-drawer quote-block section
               special-block src-block table table-row verse-block)
  "Complete list of element types.")

(defconst org-element-all-objects
  '(bold citation citation-reference code entity export-snippet
         footnote-reference inline-babel-call inline-src-block italic line-break
         latex-fragment link macro radio-target statistics-cookie strike-through
         subscript superscript table-cell target timestamp underline verbatim)
  "Complete list of object types.")

リストの中のシンボルがtypeの種類を表しています。org-element-all-elementsの中にあるのが30、org-element-all-objectsの中にあるのが24で計54種類にもなります(org-version 9.5.1 時点)。

org-element.elでは、bold等の行内に現れる要素のことを object と呼んでいて(HTMLで言えばインライン要素?)、それ以上の大きな要素のことを element と呼んでいるようです(HTMLで言えばブロックレベル要素?)。両者を合わせたもの(+α)はdatumと呼んでいる箇所が多いですが、普通にelementと呼んでいる場所もありややこしいです。

シンボルの名前だけだと何を意味しているのか分かりにくいので、全てのtypeを使用したorg-mode文書を作成して理解を深めました。

https://raw.githubusercontent.com/misohena/org-cmenu/main/examples/all-types.org

Emacsの中で見ないと構文がハイライトされないので見づらいですね……。参考までにtypeとそれに関連したマニュアルへのリンクも載せておきます。

all-elements

keyword headline section planning drawer property-drawer node-property clock center-block quote-block verse-block example-block comment-block dynamic-block export-block special-block src-block babel-call paragraph footnote-definition fixed-width comment plain-list item table table-row diary-sexp horizontal-rule inlinetask latex-environment

all-objects

bold underline italic code strike-through verbatim subscript superscript entity inline-babel-call inline-src-block line-break link target radio-target statistics-cookie footnote-reference table-cell timestamp macro export-snippet citation citation-reference latex-fragment

沢山あって大変ですが、やりたいことはこの全要素を網羅したorg-mode文書の各地点で適切なメニューを表示するということになります。

transientには条件毎にメニューの項目を無効化する仕組みがあり、それを使ってメニューの内容を現在の文脈に合わせることもできます。つまり一つのメニュー(transient prefix)を定義して、その中に全部のコマンドを追加して所々述語で無効化していくわけです。

しかしそれよりは、まずtypeとそれに対して使えるコマンドの一覧表があって、そこからtypeごとのメニューを生成してしまった方がずっと楽な気がします。雑然とコマンドが並んでも分かりづらいので、カテゴリー分けするための情報はある程度持たせる必要はありますが。

なので次のような構造を考えました。

type -> group -> ( command[key desc func] | string | group(入れ子) )

まず事前にtypeとgroupに対してcommandを登録していきます。commandが使用できるtypeに対してのみ登録していきます。例えばリンクを開くコマンドはlinkというidを持つtype内の適当なグループに追加します。上のmy-org-kill-elementのように沢山の種類の要素に適用出来るコマンドもあるので、追加先はリストやallのような別名でも指定できるようにしておきます。

そしてメニューを開くときに、org-elementで現在のtypeを割り出し、そのtypeに応じたメニューをgroupから組み立ててtransient-define-prefixで定義して実行します。

そんな感じのやり方で作ったのがorg-cmenuです。

misohena/org-cmenu: Context Sensitive Menu for Emacs Org Mode

org-cmenu-setup.elというファイルが前述の「typeとgroupに対してcommandを登録していく」処理になり、ここがメニューの内容を決めています。既存のorg-modeのコマンドを分類して追加しているほか、新たに欲しい機能はorg-cmenu-tools.elの方に書いてから追加しています。

メニューの構造を管理したり実際にメニューを表示する部分はorg-cmenu.elに入っています。コアの部分ですがこれだけでは何も表示されません。

これらを使うための設定は次のようになります。

;; メニューを開くorg-cmenuコマンド実行時にorg-cmenu.elを読み込む
(autoload 'org-cmenu "org-cmenu")
;; org-mode内にorg-cmenuコマンドを起動するキーを割り当てる
(add-hook 'org-mode-hook
          (lambda ()
            ;; お好きなキーを設定してください
            (define-key org-mode-map (kbd "C-^") #'org-cmenu)))

;; org-cmenu.elが読み込まれたらorg-cmenuコマンドが起動する前にメニュー内容を登録する
(with-eval-after-load "org-cmenu"
  (require 'org-cmenu-setup) ;;自分専用のsetupファイルに差し替えることもできる
  ;; ここで自分専用のコマンドを追加することもできる
)

まだまだ手つかずの構文要素が残っていますが全て埋める必要は無いでしょう。

考えていくといくらでもアイデアが出てきてキリがありません。必要になったときにちょくちょく追加していくことにします。

スニペットの挿入のような個人的なものも後から簡単に追加できるのが良いですね。