2024-01-31

Emacsでdiffの文字化けを回避する(様々な文字エンコーディングに対応する)

何だか時代錯誤感のあるタイトルで申し訳ないのですが、私は長年Emacsを使っていてもdiffやらgrepやら基本的なコマンドの使い方が分かっていない人間なのです。ご容赦ください。grepの方は最近はripgrepの登場で大分マシになりましたが。いや、そうじゃ無くて、2024年にもなって文字化けなどと書かねばならないというところですよ!

日常的に複数の文字エンコーディング(文字符号化方式、簡単に言えば文字コード、Emacs用語ではコーディングシステム)を使っている人はdiffをどうしているのでしょうか。まぁ、使う文字エンコーディングが一つに偏っているならそれに合わせて残りは場当たり的に対処すれば良いのでしょう。私もそうしていました。UTF-8以外使うな! などと過激なことを言う方も昨今いらっしゃいますが、私はそうは思いません。長年コンピュータを使ってきた人間にとって、過去に作った物を無かったことには出来ませんからね。

とは言えdiffを取ったときに文字化けしているバッファを見ると煩わしさを感じるのも事実です。

そういうときはdiffのバッファの中で M-x revert-buffer-with-coding-system (C-x RET r) の後、文字エンコーディングを選ぶのが簡単です。diffは取り直しになりますが。

他にもread onlyを解除して、バッファ全体をencode-coding-regionしてからdecode-coding-regionしてやると直せる場合もあります。diffの取り直しは回避できますが、常に直せるかはちょっと分からないです。

ediffで済むならそれを使うという手もあります。

いずれにせよ煩わしいことには変わりないので、ある程度自動的に対処するように次のようなコードを書きました。

(defun my-diff-detect-coding-system (file)
  "FILEのcoding systemを返す。分からなかったらnilを返す。"
  (let ((cs
         (when (file-regular-p file) ;;ディレクトリは除外する
           (with-temp-buffer
             (insert-file-contents file nil nil 1000000) ;;1MBくらい読んでおく?
             ;; これが一番簡単で確実っぽい
             last-coding-system-used))))
    (message "Detected coding system: %s" cs)
    (unless (memq cs '(nil undecided no-conversion)) ;;変なのは返さない
      cs)))

(defun my-diff-around (orig-fun old new &rest args)
  "diffにひっかけるaroundアドバイス。"
  ;; NEWのcoding systemに合わせてdiffを取る
  (let ((coding-system-for-read (or coding-system-for-read ;;すでに指定されている場合はそれを使う
                                    (my-diff-detect-coding-system new))))
    (apply orig-fun old new args)))

(advice-add 'diff :around 'my-diff-around)

要するにファイル(NEW側のみ)の文字エンコーディングを判別して、それをcoding-system-for-readに設定してからdiffを実行するだけです。

my-diffという関数を作ろうか迷いましたが、diffはいろんな場所から呼び出されているような気がしたので全てに適用させるためにdiffに対するadviceにしてみました。

文字エンコーディングを判別しているところですが、insert-file-contentsの後にlast-coding-system-usedを参照するのが見つけた方法の中では一番簡単でした。最初はdetect-coding-regionを使ったのですが、UTF-16が判別できないこととファイルローカル変数の指定が効かないことが問題になりました。UTF-16はどのみち別の問題があるので諦めるとして、 -*- coding:cp932 -*- のような指定は効いてほしいところ。半角カナでCP932(SJIS)で「ミエ」と書いたらUTF-8の「д」と区別が付かないんですよ(どんなシチュエーションだよ)。そんなときにcoding:の指定を入れれば解決できるわけです。set-auto-coding関数を使えばUTF-16(auto-coding-regexp-alist)やファイルローカル変数の判別が可能になるのですが、今度は行末タイプ(unix、dos、mac)が判別できません。行末タイプだけを判別するような関数を探したのですが見当たりませんでした。自分で \r\n を検索すれば良いのでしょうが、そんな面倒なことをするよりもlast-coding-system-usedを参照するだけで済むようでした。それらの判別処理は全てinsert-file-contentsの中で行われていますので。

UTF-16はどうしましょうね。こればっかりはUTF-8にでも変換してからdiffを取るくらいしか思いつきません。--textを指定するとして、diff自身が出力するヘッダーの文字エンコーディングと合いませんからね。

ディレクトリ単位の比較は相変わらず化けるので必要に応じて C-x RET r するということで。

あ、diff自体が出力する日本語メッセージが化けますね。「のみに存在」とかいうやつ。実行前に環境変数も変えようかな……。

こうして今日も一つ直すと何個も直すところが増えていくのでした。

まだまだdiffの事はよく分かりません。

2024-01-28 ,

org-modeでインライン画像化する画像形式を限定する

以前Emacsが扱える画像形式をちゃんと設定して多種多様な画像を表示できるようにしたのですが(「画像形式とimage-converterの設定」のあたり)、その副作用でorg-mode内で余計なファイルリンクまでインライン画像表示されるようになってしまいました。

例えばmp3や動画ファイル、pdfに至るまでorg-modeの中でインライン画像表示されるようになってしまったのです。例えばTODOリスト内にローカルにあるメディアファイルへのリンクを書いてそれを読む(もしくは聞く)ようにメモを書いたとして、そのリンクがインライン画像表示されてしまうわけです。「image-diredでmp3カバー画像を表示する」のようにImage Dired内でサムネイルとして表示される分には全く構わないわけですが、org-mode内でいちいち全てのリンクが画像として表示されてはたまりません。

原因

インライン画像化される画像形式は、org-display-inline-images関数から呼び出されるimage-file-name-regexp関数が返す正規表現によって決まっています。現在私の所でこの関数を呼び出すと……

(image-file-name-regexp)
\.\(3\(?:G[2P]\|g[2p]\)\|A\(?:I\|PNG\|RT\|VIF?\)\|BMP\|C\(?:R[23]\|UR\)\|D\(?:C[MR]\|DS\|NG\|PX\|XT[15]\)\|E\(?:P\(?:DF\|S[FI]\|T[23]\|[IST]\)\|RF\)\|F\(?:ITS\|L\(?:32\|IF\|V\)\|TS\)\|GIF\|H\(?:DR\|EI[CF]\|RZ\)\|I\(?:C\(?:ON\|[BO]\)\|IQ\|PL\)\|J\(?:2[CK]\|B\(?:I?G\)\|N[GX]\|P\(?:EG\|[2CEGMST]\)\)\|K\(?:25\|DC\)\|M\(?:2V\|4[AV]\|EF\|IFF\|KV\|NG\|O\(?:NO\|V\)\|P\(?:EG\|[34CGO]\)\|RW\|TV\|VG\)\|N\(?:EF\|RW\)\|O\(?:RF\|T[BF]\)\|P\(?:AM\|BM\|C\(?:DS\|[DLTX]\)\|DFA?\|EF\|F[ABM]\|G[MX]\|HM\|I\(?:C\(?:ON\|T\)\|X\)\|JPEG\|N[GM]\|PM\|S[BD]?\|TIF\|WP\)\|QOI\|R\(?:A[FS]\|GF\|L[AE]\|MF\|W2\)\|S\(?:FW\|VGZ?\)\|T\(?:GA\|I\(?:FF\(?:64\)?\|[FM]\)\|M2\|T[CF]\)\|V\(?:DA\|I\(?:CAR\|FF\|PS\)\|ST\)\|W\(?:BMP\|EB[MP]\|MV\|PG\)\|X\(?:3F\|BM\|CF\|P[MS]\|V\)\|a\(?:i\|png\|rt\|vif?\)\|bmp\|c\(?:r[23]\|ur\)\|d\(?:c[mr]\|ds\|ng\|px\|xt[15]\)\|e\(?:p\(?:df\|s[fi]\|t[23]\|[ist]\)\|rf\)\|f\(?:its\|l\(?:32\|if\|v\)\|ts\)\|gif\|h\(?:dr\|ei[cf]\|rz\)\|i\(?:c\(?:on\|[bo]\)\|iq\|pl\)\|j\(?:2[ck]\|b\(?:i?g\)\|n[gx]\|p\(?:eg\|[2cegmst]\)\)\|k\(?:25\|dc\)\|m\(?:2v\|4[av]\|ef\|iff\|kv\|ng\|o\(?:no\|v\)\|p\(?:eg\|[34cgo]\)\|rw\|tv\|vg\)\|n\(?:ef\|rw\)\|o\(?:rf\|t[bf]\)\|p\(?:am\|bm\|c\(?:ds\|[dltx]\)\|dfa?\|ef\|f[abm]\|g[mx]\|hm\|i\(?:c\(?:on\|t\)\|x\)\|jpeg\|n[gm]\|pm\|s[bd]?\|tif\|wp\)\|qoi\|r\(?:a[fs]\|gf\|l[ae]\|mf\|w2\)\|s\(?:fw\|vgz?\)\|t\(?:ga\|i\(?:ff\(?:64\)?\|[fm]\)\|m2\|t[cf]\)\|v\(?:da\|i\(?:car\|ff\|ps\)\|st\)\|w\(?:bmp\|eb[mp]\|mv\|pg\)\|x\(?:3f\|bm\|cf\|p[ms]\|v\)\)\'

といった具合なので、そりゃ沢山の形式がインライン画像化されてしまうわけです。

手動でインライン画像表示をしていたらあまり気にならないのかもしれませんが、私はorg-flyimageで自動的にインライン画像表示をさせているので意図しないものまで全て即事に表示されてしまうわけです。

修正方法

これを修正するとして、image-file-name-regexp関数が返す内容を修正すべきでしょうか。それともorg-mode側を修正すべきでしょうか。

image-file-name-regexp関数を修正してしまうと他の部分で画像が表示されなくなってしまうことが予想されます。また、そもそもインライン画像化はエクスポートしたときに画像化される形式に限定すべきでしょう。

org-flyimageの自動表示対象を変更できるようにするという手もありますが(必要なら手動で表示する余地を残す)、そこまでは必要ないでしょう。

というわけでorg-display-inline-images関数の挙動を書き替えれば良いのですが、私の場合以前「org-inline-image-fixのEmacs 29対応」に書いたような経緯でこの関数を完全に置き換えてしまっているので、そちらを修正することになります。org-display-inline-images関数は外から手を加えるのが難しい構造をしていて、色々強引な手を使った挙げ句Emacs29になったタイミングでより良い関数に置き換えたのでした。

Add ability to customize displayed image file names · misohena/org-inline-image-fix@07856aa

上のコミットでorg-better-inline-images-image-file-name-regexpというカスタマイズ変数を追加し、画像化するか判定するための正規表現を変更できるようにしました。設定できる値は、nil(従来通りimage-file-name-regexp関数を使う)、文字列(正規表現)、関数(image-file-name-regexp関数の代わりに正規表現を返す)、拡張子のリストに対応しています。

本当は画像としてエクスポートするファイル名かどうか(org-export-default-inline-image-ruleorg-html-inline-image-rules)を基準にしようとも思ったのですが、tifやxpm等微妙な形式もありますし、ox.elやox-html.el等を必ずロードしなければならないのでやめておきました。数も少ないですし、拡張子のリストが指定出来ればそれで十分でしょう。

これで私はインライン画像表示する形式を、gif、jpg、jpeg、png、svg、webpに限定しました。必要な形式があったらその都度追加するということで。

org-better-inline-images-image-file-name-pというカスタマイズ変数も追加しておきましたが不要でした。

Org 9.6から現在までのインライン画像表示機能に対する変更点の確認

ついでに最近のインライン画像表示機能に対する変更点も確認しておきました。関数を置き換えた以上、本家の方に加えられた変更に目を光らせていなければなりません。

これらはおそらく次のリリース(9.7?)に含まれることになるのでしょう。

注目はインライン画像の幅を制限する機能(org-image-max-width変数)でしょう。待ちわびていた人もいるのではないでしょうか。今のところ高さの制限(org-image-max-height?)は無いように見えます。なので私の改良はまだ意義があるということで。

インライン画像のalign(右寄せ、中央寄せ)も実装されたようです。 #+ATTR_HTML: :align center 等の指定やグローバルオプション(org-image-align)の指定が反映されるようです。個人的には使う予定はありません。

org-elementにいくつか便利な関数が追加されたり、引数の指定方法が改善されたりしたので、それに伴う修正がいくつか入っていました。

環境変数の展開は、そもそもそんなことができること自体知りませんでした。試しに [[file:$APPDATA/Microsoft/Windows/Start Menu/Programs]] と書いたらちゃんとスタートメニューにアクセスできました。私はCorfuでファイル名の補完を有効にしているのですが、 file:$ と打った瞬間に全環境変数が補完候補として出てきます。環境変数を入れた後も、ちゃんとそれを展開した後のディレクトリにあるファイルを補完候補として出してきます!

一部のものは私の改造版にも反映しておきました。残りは9.7が出てからにします。

2024-01-27

複数行にわたるコメントの中のS式を評価する

Emacs Lispで次のようなコードを書いたとします。

;; 使用例:
;; (my-hogehoge-function
;;   1
;;   2
;;   3)

(defun my-hogehoge-function (a b c)
  (+ a b c))

複数行あるコメントの最後、 ) の直後でeval-last-sexp (C-x C-e)を実行すると……

Debugger entered--Lisp error: (scan-error "Unbalanced parentheses" 313 1)

などと出てコメント内のS式を評価できません。

いちいちuncommentしてから評価して元に戻すのも面倒です。

Googleで検索して見ると kensanata/eval-sexp-in-comments: eval sexp in comments, for Emacs というのを見つけました。ソースコードを見るとwith-temp-bufferで別バッファへ移してからコメントを外し、その後eval-last-sexpを実行していました。それだと現在のバッファの中で評価したい場合に困ります。

eval-last-sexpの中身を見てみると、elisp--preceding-sexpという関数でポイントの前にあるS式テキストをlispオブジェクトの形で取り出してから、評価しているようでした。

なので、このelisp--preceding-sexpに細工をしてコメントの中にいるときは別バッファにコピーしてコメントを外し、そこでelisp--preceding-sexpを呼び出してS式を返せば良いと考えました。

;; my-elisp.el

(defun my-elisp-beginning-of-continuous-comments ()
  "現在の連続コメントの先頭を返す。

連続コメントとは、連続改行(空行)を除く空白文字のみで区切られた複
数のコメントのまとまりを指す。そのまとまりの最初の;の位置を返す。

例:
123 ;; line-1
    ;; line-2

    ;; line-3

「line-3」の末尾の場合「;; line-3」の先頭、「line-2」の末尾の場合
「;; line-1」の先頭の位置を返す。

各行;;の先頭はコメントに含まれない。

現在のポイントがコメント内ではない場合nilを返す。

文字列の中の;;には反応しない。
例:
\"
;; line-1 ←ここで実行してもnilを返す。コメントでは無く文字列の中なので。
\"

(以下追記)
同じコメントスタートに限定するかは迷うところ。
 ;; (+
;;     2
;;;    3)
みたいなのも現状では受け入れる。

    ;; line-1
123 ;; line-2
    ;; line-3
みたいなのは無理(;; line-2が先頭になる)。
対応できないことは無いだろうけど
そもそもコメントの前に何かある場合も対応する必要があるかは疑問。

理想的にはコメント開始の水平位置と;の数が揃っている連続行を
抽出すべきなのだと思う。"
  (cond
   ((derived-mode-p 'emacs-lisp-mode)
    (save-excursion
      (let (beginning-of-comment)
        (while (and (comment-beginning)
                    (progn
                      (skip-chars-backward " \t")
                      (skip-chars-backward ";")
                      (setq beginning-of-comment (point))
                      (skip-chars-backward " \t")
                      (bolp))
                    (not (bobp)))
          (backward-char))
        beginning-of-comment)))
   (t
    (save-excursion
      ;; TODO: 現在のメジャーモードでのコメントが先頭にある場合はそれも無視すべき?
      ;; TODO: 「123 ;; (if」から複数行に続く形式に対応していない。123の部分にコメント以外のセミコロン(文字列等)があることを考慮しなければならない。
      (let (beginning-of-comment)
        (forward-line 0)
        (while (looking-at "[ \t]*;+[ \t]*")
          (setq beginning-of-comment (match-end 0))
          (forward-line -1))
        beginning-of-comment)))))

(defun my-elisp-sexp-in-comment (beg end)
  "BEGからENDの中にあるコメントの中にあるS式を返す。"
  (when (and beg end (< beg end))
    (let ((original-buf (current-buffer)))
      (with-temp-buffer
        (emacs-lisp-mode)
        (insert-buffer-substring original-buf beg end)
        (goto-char (point-min))
        ;; ↓これだと最終行のコメントが空でかつEOBの時になぜか「Beginning of buffer」のエラーが出る。
        ;; (uncomment-region (point-min) (point-max))
        (while (re-search-forward "^\\s-*;+" nil t)
          (replace-match "")
          ;; 次の行へ(現在の行にある残りのコメント中コメントは残す)。
          (forward-line 1))
        (goto-char (point-max))
        ;; 1段階コメントを外した後の状態からS式を取り出す。
        ;; コメントの中にコメントがある場合は、
        ;; 再帰的にこの関数が呼び出されることもある。
        ;; ;; ;; (+
        ;; ;; ;;  ;; コメント
        ;; ;; ;;  1 2)
        ;; みたいなのも正しく処理する。
        (elisp--preceding-sexp)))))

(defun my-elisp-preceding-sexp-in-comment ()
  "ポイントがコメント内にあるとき、複数行にわたるコメントを考慮して
ポイントの直前にあるS式を読み取る。"
  (my-elisp-sexp-in-comment (my-elisp-beginning-of-continuous-comments) (point)))

(defun my-elisp-preceding-sexp-around (orig-fun &rest args)
  "elisp--preceding-sexpの:around advice。"
  (let ((end (point))
        (beg (my-elisp-beginning-of-continuous-comments)))
    (if (and beg (< beg end))
        (my-elisp-sexp-in-comment beg end)
      (apply orig-fun args))))

(provide 'my-elisp)

(2024-01-30修正: コメントの中のコメントをうまく処理できるようにしました)

設定方法:

(when (version<= "25.1" emacs-version) ;; Require #'elisp--preceding-sexp
  (autoload 'my-elisp-preceding-sexp-around "my-elisp")
  (advice-add 'elisp--preceding-sexp :around 'my-elisp-preceding-sexp-around))

これで無事複数行にわたるコメント内のS式を評価できるようになりました。

ただ、メジャーモードがemacs-lisp-modeではない場合のことも考えると、少々煮え切らないコードになってしまいました。例えばorg-modeのソースコードブロックの中にコメントがあって、その中のS式を評価したい場合など。C言語やシェルスクリプトのコメント(//や#)の中に複数行にわたってS式を書いてそれを評価したい、なんてケースはあるでしょうか?(実際、別言語のソースコードのコメントの中にelispのコードを書いて、その別言語のコードを生成したことは度々あった気がします) 考え出すと切りがないです。文字列などクォートされたセミコロンを考慮しなければならないので単純な正規表現で処理するのもためらわれたりと色々面倒なところもありました。

2024-01-26

プロパティ一覧編集widgetを作る(Emacs Widget Libraryについて調べる3)

前回の続き。

今回は複数のプロパティを保持するリスト(plistなりalistなり)を編集するwidgetを作成します。

すでにplistやalistという名前のwidgetは定義されているのですが、それの見た目はこんな感じです。

org-link-parametersをカスタマイズするところ(plistのalist)
図1: org-link-parametersをカスタマイズするところ(plistのalist)

違う。そうじゃないんだ。

やりたいことに一番近いのはfaceをカスタマイズする画面です。

customize-faceの画面
図2: customize-faceの画面

つまり、既に決まっている固定のプロパティ種類があり、その値の型もプロパティ種類によって決まっているような状況です。

プロパティの省略も可能で、省略した場合は何らかのデフォルト値が使われるといった具合です。

このfaceをカスタマイズするUIはcus-edit.el内にcustom-face-editという名前のwidgetとして定義されています。Emacs 29.2時点での定義は次の通りです。

(define-widget 'custom-face-edit 'checklist
  "Widget for editing face attributes.
The following properties have special meanings for this widget:

:value is a plist of face attributes.

:default-face-attributes, if non-nil, is a plist of defaults for
face attributes (as specified by a `default' defface entry)."
  :format "%v"
  :extra-offset 3
  :button-args '(:help-echo "Control whether this attribute has any effect.")
  :value-to-internal 'custom-face-edit-fix-value
  :match (lambda (widget value)
           (widget-checklist-match widget
                                   (custom-face-edit-fix-value widget value)))
  :value-create 'custom-face-edit-value-create
  :convert-widget 'custom-face-edit-convert-widget
  :args (mapcar (lambda (att)
                  (list 'group :inline t
                        :format "%v"
                        :sibling-args (widget-get (nth 1 att) :sibling-args)
                        (list 'const :format "" :value (nth 0 att))
                        (nth 1 att)))
                custom-face-attributes))

:value-to-internal:match の部分にはcustom-face-edit-fix-value関数が使われていますが、これはface属性の古い書き方を新しい書き方に直すためのものなので、ここでは無視します。 :extra-offset 3 はwidget先頭に追加するスペース、 :button-args ... はヘルプエコー、 :format "%v" は単にタグ等を消して値部分だけ表示させる指定なので、あまり重要ではありません。 :value-createconvert-widget:args の三つが重要になります。

まずdefine-widgetの第二引数CLASSはchecklistとなっています。これは派生元となるいわゆる基本クラスで、custom-face-editはchecklistの性質を受け継ぎます。

checklistは複数の子widgetの中からいくつかを選ぶようなwidgetです。結果の値は選ばれた子widgetの値だけが含まれるリストになります。例えば次のようなコードを実行して:

(progn
  (pop-to-buffer (generate-new-buffer "*Widget Example*"))
  (widget-create 'checklist
                 :value '("Second" t) ;;初期値
                 :notify (lambda (widget &rest _)
                           (message "通知 value=%s" (widget-value widget)))
                 ;;以下args
                 '(const "First")
                 '(const "Second")
                 '(boolean :on "有効" :off "無効")
                 '(number :value 123))
  (use-local-map widget-keymap)
  (widget-setup))

1番目と4番目のチェックボックスのみを有効にしたら結果は ("First" 123) になります。

faceのカスタマイズではチェックボックスをoffにした部分は結果のplistに含まれないようにしたいので、checklistから派生しているのだと思います。

次に :value-create に指定されたcustom-face-edit-value-create関数を見てみましょう(日本語コメントは私が追記)。

(defun custom-face-edit-value-create (widget)
  (let* ((alist (widget-checklist-match-find
                 widget (widget-get widget :value)))
         (args  (widget-get widget :args))
         (show-all (widget-get widget :show-all-attributes))
         (buttons  (widget-get widget :buttons))
         (defaults (widget-checklist-match-find
                    widget
                    (widget-get widget :default-face-attributes)))
         entry)
    ;; 改行と空白の挿入
    (unless (looking-back "^ *" (line-beginning-position))
      (insert ?\n))
    (insert-char ?\s (widget-get widget :extra-offset)) ;;注意:nilのとき1文字挿入してしまう。バグ? 仕様?
    ;; 値部分の挿入
    (if (or alist defaults show-all)
        (dolist (prop args)
          (setq entry (or (assq prop alist)
                          (assq prop defaults)))
          (if (or entry show-all)
              (widget-checklist-add-item widget prop entry)))
      (insert (propertize "-- Empty face --" 'face 'shadow) ?\n))
    ;; 未使用属性を隠す/表示するボタン
    (let ((indent (widget-get widget :indent)))
      (if indent (insert-char ?\s (widget-get widget :indent))))
    (push (widget-create-child-and-convert
           widget 'visibility
           :help-echo "Show or hide all face attributes."
           :button-face 'custom-visibility
           :pressed-face 'custom-visibility
           :mouse-face 'highlight
           :on "Hide Unused Attributes"    :off "Show All Attributes"
           :on-glyph nil :off-glyph nil
           :always-active t
           :action 'custom-face-edit-value-visibility-action
           show-all)
          buttons)
    (insert ?\n)
    ;; ボタンと子供達を記録
    (widget-put widget :buttons buttons)
    (widget-put widget :children (nreverse (widget-get widget :children)))))

この部分は :format の %v 部分を処理するときに呼び出される関数です。

実はこの部分はcheckboxの :value-create (widget-checklist-value-create)と本質的には大差ありません。違うところと言えば、未使用の属性を隠したり表示したりするボタンを追加しているくらいです。それと :default-face-attributes という指定の処理があるのですがとりあえず置いておきます。

次に :convert-widget に指定されたcustom-face-edit-convert-widget関数

(defun custom-face-edit-convert-widget (widget)
  "Convert :args as widget types in WIDGET."
  (widget-put
   widget
   :args (mapcar (lambda (arg)
                   (widget-convert arg
                                   :deactivate 'custom-face-edit-deactivate
                                   :activate 'custom-face-edit-activate
                                   :delete 'custom-face-edit-delete))
                 (widget-get widget :args)))
  widget)

この部分はwidget-createでwidgetオブジェクトを作成する際に呼び出されるいわばコンストラクタのようなもので完全に理解するにはwidget-createwidget-convertの処理を詳しく知る必要があるのですが、大ざっぱに言えば全ての子widgetに対して :deactivate:activate:delete のプロパティを強制的に追加しています。それによって、チェックボックスがON/OFFされて子widgetがactive、inactiveになったときの処理やwidgetを削除するときの処理を書き替えています。custom-face-editでは見た目を色々変えているので必要になります。あまり詳しく説明する必要は無さそうでしょうか。

そして最後の :args の部分。

  :args (mapcar (lambda (att)
                  (list 'group :inline t
                        :format "%v"
                        :sibling-args (widget-get (nth 1 att) :sibling-args)
                        (list 'const :format "" :value (nth 0 att))
                        (nth 1 att)))
                custom-face-attributes)

これはチェックリストの項目を生成する部分です。

custom-face-attributesという変数にface属性の一覧があるので、そこからmapcarで変換します。custom-face-attributesの各要素は一つのface属性に関する情報を持つリストです。その一つ目の要素は属性キーワード(:family とか :width とか)です。二つ目はその属性を編集するためのwidget型です。三つ目以降もあるのですがここで使うのはそこまでです。mapcar部分を実際に評価してみると次のようになります。

(
 (group :inline t :format "%v" :sibling-args nil (const :format "" :value :family) (string :tag "Font Family" :help-echo "Font family or fontset alias name."))
 (group :inline t :format "%v" :sibling-args nil (const :format "" :value :foundry) (string :tag "Font Foundry" :help-echo "Font foundry name."))
 (group :inline t :format "%v" :sibling-args nil (const :format "" :value :width)
        (choice :tag "Width" :help-echo "Font width." :value normal (const :tag "compressed" condensed) (const :tag "condensed" condensed) ...))
 ...
)

つまり、各項目は (group (const :family) string) やら (group (const :width) (choice ...)) などといったgroup widgetになります。

ここで注目すべきは :inline t という指定です。 :inline というのは決して一つの行内のwidgetという意味ではありません。普通のgroupだと結果の値は (:family "Arial") のようなリストになるので全体としては ((:family "Arial") (:width condensed)) のようになりplistにもalistにもなりません。そこで :inline t を指定すると子の結果が親のリストの中に展開されて (:family "Arial" :width condensed) という形になり、めでたくplistになるわけです。

ちなみにこのgroupをconsにしてやると結果をplistではなくalistにできます。ただし、別の所に少々バグというか問題があってエラーが発生する場合があり、そこを修正してやる必要があります。

以上を踏まえて、決まった型のplistやalistを編集するより汎用的なwidgetを作成し edraw-widget.el にまとめました。これを使うと例えば次のようにalistを編集するwidgetを作成できます。

(progn
  (require 'edraw-widget)
  (pop-to-buffer (generate-new-buffer "*Widget Example*"))
  (widget-create 'edraw-attribute-alist
                 :tag "Props"
                 :format "%v"
                 :notify
                 (lambda (w &rest _) (message "%s" (prin1-to-string (widget-value w))))
                 ;; :greedy nil ←未知の値の扱いに関わる(デフォルトはtにしてある)
                 :value '((stroke-width . 123.45) (stroke . "red") (unknown . "uval") (fill . "green"))
                 '(fill
                   (string :tag "Fill"))
                 '(stroke
                   (string :tag "Stroke"))
                 '(stroke-width
                   (number :tag "Stroke Width"))
                 '(stroke-join
                   (choice :tag "Stroke Join"
                           :value "miter"
                           (const "miter")
                           (const "round")
                           (const "bevel"))))
  (use-local-map widget-keymap)
  (widget-setup))

defcustomの:typeに指定することも出来ます。

(require 'edraw-widget)
(defcustom my-hogehoge-properties
  '((stroke-width . 123.45) (stroke . "red") (fill . "green"))
  "Hoge Hoge no Properties."
  :type '(edraw-attribute-alist
          :tag "My Hogehoge Properties"
          (fill
           (string :tag "Fill"))
          (stroke
           (string :tag "Stroke"))
          (stroke-width
           (number :tag "Stroke Width"))
          (stroke-join
           (choice :tag "Stroke Join"
                   :value "miter"
                   (const "miter")
                   (const "round")
                   (const "bevel")))))
defcustomでedraw-attribute-alistを使ってみたときの見た目
図3: defcustomでedraw-attribute-alistを使ってみたときの見た目

未知のプロパティが現れたときの処理はもう少し改善する余地があると思います。末尾に任意のプロパティとマッチするrepeatを加えてみたりもしたのですが、続く既知のプロパティまで巻き込んでしまうためうまく行きませんでした。マッチングのコードを修正する必要がありそうです。

制作の過程で色々ハマリどころがあって(inactiveなconsとcheckboxの通知タイミング、未指定のextra-offset、等)それについても書いておきたいのですが、長くなるので止めておきます。

2024-01-16

Webカラーwidgetを作る(Emacs Widget Libraryについて調べる2)

前回の続き。

試しにWeb用のカラーコードを入力するためのwidgetを定義してみましょう。

実はEmacs用のカラーコードを入力するためのwidgetは既にあります。

wid-edit.el 4053行目

(define-widget 'color 'editable-field
  "Choose a color name (with sample)."
  :format "%{%t%}: %v (%{sample%})\n"
  :value-create 'widget-color-value-create
  :size (1+ (apply #'max 13 ; Longest RGB hex string.
                   (mapcar #'length (defined-colors))))
  :tag "Color"
  :value "black"
  :completions (defined-colors)
  :sample-face-get 'widget-color-sample-face-get
  :notify 'widget-color-notify
  :match #'widget-color-match
  :validate #'widget-color-validate
  :action 'widget-color-action)

なので、これをちょっと変えてやればすぐに実現出来ます。

;; 実装にはedraw-color.elやedraw-color-picker.elの助けを借ります。
;; https://github.com/misohena/el-easydraw/blob/master/edraw-color.el
;; https://github.com/misohena/el-easydraw/blob/master/edraw-color-picker.el
(require 'edraw-color)
(require 'edraw-color-picker)

(define-widget 'my-web-color 'editable-field
  "Choose a web color (with sample)."
  :value "black"
  ;; タグ: 値 サンプル
  :format "%{%t%}: %v %{      %}\n"
  ;; デフォルトのタグ(%t部分)
  :tag "Color"
  ;; 値部分の作成(%v部分)
  :value-create 'my-widget-web-color-value-create
  :size 26 ;; rgba(255,255,255,1.2345)くらいが収まる長さにしておく
  ;; 補完候補(C-M-i (M-TAB)で補完候補を出せる)
  :completions (mapcar #'car edraw-color-web-keywords)
  ;; 見本部分のface
  :sample-face-get 'my-widget-web-color-sample-face-get
  ;; 見本の更新
  :notify 'my-widget-web-color-notify
  ;; 値の検証
  :match #'my-widget-web-color-match
  :validate #'my-widget-web-color-validate
  ;; ミニバッファからの入力
  :action 'my-widget-web-color-action)

(defun my-widget-web-color-value-create (widget)
  ;; 値を表す部分(:formatの%v部分)をバッファ上に作成します。

  ;; editable-fieldとしての部分を作成。
  (widget-field-value-create widget)
  (widget-insert " ")
  ;; その後にChooseボタンを追加。
  (widget-create-child-and-convert
   widget 'push-button
   :tag " Choose " :action 'my-widget-web-color--choose-action)
  (widget-insert " "))

(defun my-widget-web-color--choose-action (widget &optional _event)
  ;; Chooseボタンが押されたら呼び出されます。
  ;; カラーピッカーで色を入力してもらい、それを親widgetの値として設定します。
  (let* ((wp (widget-get widget :parent))
         (old-color (widget-value wp))
         (new-color (edraw-color-picker-read-color nil old-color)))
    (widget-value-set wp new-color)))

(defun my-widget-web-color-sample-face-get (widget)
  ;; 見本部分(:formatの%{から%}までの間)に適用するfaceを返します。
  (let ((color (condition-case nil
                   (edraw-color-from-string (widget-value widget))
                 (error (widget-get widget :value)))))
    (if color
        (list (cons 'background-color (edraw-to-string-hex (edraw-change-a color 1.0)))) ;; 半透明が表現できないので無理矢理不透明にします。本当はSVGで市松模様背景付きのサンプルを作りたい所。
      'default)))

(defun my-widget-web-color-action (widget &optional event)
  "Prompt for a color."
  ;; フィールド上でRETを押したときに呼び出されます。
  ;; ミニバッファから色を入力してもらい、それをwidgetの値として設定します。
  (let* ((old-color (widget-value widget))
         (new-color (edraw-color-picker-read-color nil old-color)))
    (when new-color
      (widget-value-set widget new-color)
      (widget-setup)
      (widget-apply widget :notify widget event))))

(defun my-widget-web-color-notify (widget child &optional event)
  "Update the sample, and notify the parent."
  ;; 何かイベントが発生したときに呼び出されます。
  ;; たいていの場合テキストが変化したときなので、サンプルのfaceを更新します。
  (overlay-put (widget-get widget :sample-overlay)
               'face (widget-apply widget :sample-face-get))
  (widget-default-notify widget child event))

(defun my-widget-web-color-match (_widget value)
  ;; WIDGETにVALUEを設定可能なら非nilを返します。
  (and (stringp value)
       (or (assoc value edraw-color-web-keywords)
           (string-match edraw-color-string-patterns-re value))))

(defun my-widget-web-color-validate (widget)
  ;; WIDGETの現在の値が正当かチェックします。
  ;; エラーがなければnilを返します。
  (let ((value (widget-value widget)))
    (unless (my-widget-web-color-match widget value)
      (widget-put widget :error (format "Invalid color: %S" value))
      widget)))

試しに表示させてみましょう。

(pop-to-buffer (generate-new-buffer "*Widget Example*"))
(widget-insert "\n")
(widget-create 'my-web-color
               :tag "色"
               "black")
(use-local-map widget-keymap)
(widget-setup)

実行すると次図のようになり、Chooseボタンを押すとカラーピッカー付きで色を入力できます。選択した色もwidgetの右側にサンプルとして表示されます。

Webカラーwidgetを表示させてChooseボタンを押したところ
図1: Webカラーwidgetを表示させてChooseボタンを押したところ

ここで定義したwidgetはdefcustomの:type部分に指定することも出来ます。

(defcustom my-hogehoge-color "#ff0000"
  "My Hogehoge HTML color."
  :type 'my-web-color)

(defun my-hogehoge-html ()
  (format "<span style=\"color: %s\">hogehoge</span>" my-hogehoge-color))

M-x customize-variableでmy-hogehoge-colorを選ぶと次図のようになります。ボタンのスタイルが変わっているのが面白いですね。私はCorfuを入れているので、C-M-iではこのように補完候補が表示されます。

my-hogehoge-colorをcustomizeで変更するところ
図2: my-hogehoge-colorをcustomizeで変更するところ

次は構造を持った値を編集するような複雑なwidgetを作りたいところです。

2024-01-16 ,

Emacs Lisp要素へのorg-modeリンクをエクスポートする

以前Emacs Lisp要素へのリンクをorg-modeに追加するというのを書きました。[[elisp-function:create-image][create-image]]のような形式でEmacs Lispの要素(関数・変数・face)へのリンクを書けるようにするものです。そしてC-c C-oでその要素の定義箇所へジャンプできるようにしました。

しかしエクスポートには対応していませんでした。そのようなリンクを含むOrg文書をHTMLとしてエクスポートしても、意味のあるリンクにはなりません。

元々Emacs内でソースコードを追いかけるときのメモのために用意したのでエクスポートする必要は無かったのですが、こうしたブログに書くときに正しくエクスポートできると便利なことが多々あります。

シンボルから定義の場所を探す

まず要素のシンボルから定義の場所(ファイルと行番号)を割り出します。次のようなコードでできるようです。

(defun my-elisp-element-file-line (symbol finder)
  (ignore-errors
    (let* ((buf-point (funcall finder symbol))
           ;;@todo バッファやポイントの状態を元に戻す。ただし、開きっぱなしの方が連続して変換するときは効率が良い。
           (buffer (car buf-point))
           (point (cdr buf-point)))
      (with-current-buffer buffer
        (cons (expand-file-name (buffer-file-name)) ;;abs-file
              (line-number-at-pos point t)))))) ;;line

(defun my-elisp-function-file-line (symbol)
  (my-elisp-element-file-line symbol #'find-function-noselect))

(defun my-elisp-variable-file-line (symbol)
  (my-elisp-element-file-line symbol #'find-variable-noselect))

(defun my-elisp-face-file-line (symbol)
  (my-elisp-element-file-line symbol
                              (lambda (symbol)
                                (find-definition-noselect symbol 'defface))))

例えば次のように使います。

(my-elisp-function-file-line 'create-image)
("c:/略/share/emacs/29.1/lisp/image.el" . 484)

find-function-noselect関数等を使うとその副作用でバッファが開きっぱなしになったり、もし既に開いていた場合はポイントが動いてしまったりするのですが、とりあえず放っておきます。開きっぱなしの方が連続的に沢山のリンクをエクスポートするときに速いという面はあると思うので。

ファイルと行番号からURLを求める

次にその場所を指すURLを求めるのですが、そのURLはローカルファイルへのURLではなく、世界中から参照できるWorld Wide Web上のURLでなければなりません。でなければこういったブログで使うことはできません。

幸いほとんどのソースコードはWeb上に存在するものです。

EmacsにバンドルされているファイルへのURLを求める

Emacsのソースコードは https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/ から参照できます。

例えばEmacs 29.1時点でのimage.el内の484行目は https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/image.el?h=emacs-29.1#n484 で参照できます。

従って次のような関数を作れば:

(defun my-path-globalize-emacs (abs-file line)
  "Create a URL to a file bundled with Emacs."
  (let ((dirs `((,lisp-directory
                 . "https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/")
                (,find-function-C-source-directory
                 . "https://git.savannah.gnu.org/cgit/emacs.git/tree/src/"))))
    (cl-loop for (dir . url) in dirs
             when (and dir (string-prefix-p (expand-file-name dir) abs-file))
             return
             (concat
              url
              (file-relative-name abs-file dir)
              "?h=emacs-" emacs-version
              (when line (format "#n%d" line))))))

次のような式でローカルファイルへのパスと行番号からWeb上でのURLを作成できます。

(my-path-globalize "c:/略/share/emacs/29.1/lisp/image.el" 484)
"https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/image.el?h=emacs-29.1#n484"

package.elで管理されているファイルへのURLを求める

package.elで管理しているファイルについてもある程度URLを求めることが出来るようです。

(defvar my-path-globalize-package-globalizers
  '(my-path-globalize-package-org
    my-path-globalize-package-github))

(defun my-path-globalize-package (abs-file line)
  "Create a URL to the file managed by package.el."
  (when-let* ((pkg-name-desc (my-path-globalize-package-find abs-file))
              (pkg-name (car pkg-name-desc))
              (pkg-desc (cdr pkg-name-desc))
              (pkg-dir (package-desc-dir pkg-desc))
              (rel-file (file-relative-name abs-file pkg-dir)))
    (seq-some (lambda (globalizer)
                (funcall globalizer rel-file line pkg-name pkg-desc))
              my-path-globalize-package-globalizers)))

(defun my-path-globalize-package-find (abs-file)
  ;;@todo package-user-dirで足切りする? package-directory-listも?
  (cl-loop for (name . descs) in package-alist
           for desc = (cl-loop for desc in descs
                               for dir = (package-desc-dir desc)
                               when (and dir
                                         (string-prefix-p
                                          (expand-file-name dir) abs-file))
                               return desc)
           when desc
           return (cons name desc)))

(defun my-path-globalize-package-org (rel-file line pkg-name pkg-desc)
  (when (eq pkg-name 'org)
    (when-let* ((pkg-extras (package-desc-extras pkg-desc))
                (pkg-commit (alist-get :commit pkg-extras)))
      (concat
       "https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/"
       rel-file
       "?id=" pkg-commit
       (when line (format "#n%d" line))))))

(defun my-path-globalize-package-github (rel-file line _pkg-name pkg-desc)
  (when-let* ((pkg-extras (package-desc-extras pkg-desc))
              (pkg-url (alist-get :url pkg-extras))
              (pkg-commit (alist-get :commit pkg-extras)))
    (when (string-match "\\(https?://github\\.com/[^/]+/[^/]+\\)" pkg-url)
      (concat
       (match-string 1 pkg-url) "/blob/" pkg-commit "/" rel-file
       (when line (format "#L%d" line))))))

パッケージの紹介Webサイト(?)がGitHubの場合は、GitHubにあるソースコードを参照するようにしてみました。また、Org-modeは特別に処理しています。他にも必要に応じてルールを追加する必要があるでしょう。

例えば vertico-mode の場所:

(my-path-globalize-package (expand-file-name "~/.emacs.d/elpa/vertico-20231229.1740/vertico.el") 741)
"https://github.com/minad/vertico/blob/93f709d71e8908617a21ca469fd60123f5037ae4/vertico.el#L741"

org-link-parametersの場所:

(my-path-globalize-package (expand-file-name "~/.emacs.d/elpa/org-9.6.14/ol.el") 92)
"https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/ol.el?id=58c91cbf9f2510700fbbdaaa166efcb1a5582cf7#n92"

両方まとめる

とりあえずこの二つをまとめて次のようにすることで:

(defvar my-path-globalizers
  '(my-path-globalize-emacs
    my-path-globalize-package))

(defun my-path-globalize (file line)
  "Return a URL on the World Wide Web that points to the LINE of the FILE.

FILE is a path to a local file that has the same content on the WWW.

LINE is a line number starting from 1."
  (let ((abs-file (expand-file-name file)))
    (seq-some (lambda (globalizer) (funcall globalizer abs-file line))
              my-path-globalizers)))

(my-path-globalize ファイル名 行番号)でローカルにあるEmacs Lispファイルの場所をWeb上のURLへ変換できるようになりました。

これを使ってシンボルから直接Web URLを求める関数も作成できます。

(defun my-elisp-face-web-url (symbol)
  (my-elisp-element-web-url symbol
                            (lambda (symbol)
                              (find-definition-noselect symbol 'defface))))

(defun my-elisp-variable-web-url (symbol)
  (my-elisp-element-web-url symbol #'find-variable-noselect))

(defun my-elisp-function-web-url (symbol)
  (my-elisp-element-web-url symbol #'find-function-noselect))

(defun my-elisp-element-web-url (symbol finder)
  (when-let ((file-line (my-elisp-element-file-line symbol finder)))
    (my-path-globalize (car file-line) (cdr file-line))))

org-modeでエクスポートする

後はorg-modeのリンクタイプに設定してやるだけです。

エクスポート用の関数を用意し:

(defun my-org-elisp-export-function (path desc format)
  (my-org-elisp-export-element path desc format #'my-elisp-function-web-url))

(defun my-org-elisp-export-variable (path desc format)
  (my-org-elisp-export-element path desc format #'my-elisp-variable-web-url))

(defun my-org-elisp-export-face (path desc format)
  (my-org-elisp-export-element path desc format #'my-elisp-face-web-url))

(defun my-org-elisp-export-element (path desc format path-converter)
  (or (when (eq format 'html)
        (when-let ((url (funcall path-converter (intern path))))
          (format "<a href=\"%s\">%s</a>" url (or desc path))))
      ;; pathが解決できないときはリンクにしない。
      (or desc path)))

org-link-parametersへ登録してやります:

(org-link-set-parameters
 "elisp-function"
 :follow (lambda (name) (find-function (intern name)))
 :export #'my-org-elisp-export-function)

(org-link-set-parameters
 "elisp-variable"
 :follow (lambda (name) (find-variable (intern name)))
 :export #'my-org-elisp-export-variable)

(org-link-set-parameters
 "elisp-face"
 :follow (lambda (name) (find-face-definition (intern name)))
 :export #'my-org-elisp-export-face))

テスト

試しに次にいろんな要素へのリンクを書いてみました。

Orgソース:

- Emacsバンドル
  - [[elisp-function:create-image]] (lisp/image.el)
  - [[elisp-function:url-retrieve]] (lisp/url/url.el ←階層あり)
  - [[elisp-function:widget-get]] (src/fns.c)
  - [[elisp-variable:truncate-lines]] (src/buffer.c)
  - [[elisp-face:font-lock-comment-face]] (lisp/font-lock.el)
- package.el
  - GitHub
    - [[elisp-function:vertico-mode][vertico-mode]]
  - org-mode
    - [[elisp-function:org-mode][org-mode]]
    - [[elisp-variable:org-link-parameters][org-link-parameters]]

注意点:再エクスポートで同じURLが生成されない問題

URLは現在実行している環境で使われているバージョンのソースコードを参照しています。文書を書いている時点のソースコードを指し示すのが最も無難だろうとの判断によるものですが、不都合なこともあるかもしれません。特に文書を書いてからしばらく経った後、Emacsやパッケージをバージョンアップした後に再度エクスポートした場合、同じURLが生成されないという問題があります。これが嫌なのであれば、大人しく通常のhttp(https)リンクを使うべきでしょう。上の仕組みを流用してそのようなhttpリンクを生成するようなコマンドも容易に作成できることでしょう。

2024-01-07

Emacs Widget Libraryについて調べる

Emacs Widget LibraryというのはEmacsのテキストバッファ内に(データ入力フォームみたいな)UIを構築するためのライブラリです。

customizeのUIなんかで使われているアレです。defcustomの:typeで指定しているのはまさにこのwidgetのtypeだったりします。他にもEmacsの様々なところで使われていますし、私のel-easydrawではプロパティ一覧編集の画面に使われていたりもします。

Emacs Lispを書いていると度々必要になるものなので、前々からこのEmacs Widget Libraryについてはちょくちょく調べています。

基本的な部分については一応マニュアルがあります。

The Emacs Widget Library

手っ取り早く動く例が欲しいのであれば、Programming Exampleがあります。この例は一つ一つのwidgetの挙動を細かく調べるには大きすぎるので、私は次のようなコードで色々試しています。

url-linkの例:

(pop-to-buffer (generate-new-buffer "*Widget Example*"))
(widget-create 'url-link
               :tag "GNUのWebサイト"
               "https://www.gnu.org/")
(widget-setup)

push-buttonの例:

(pop-to-buffer (generate-new-buffer "*Widget Example*"))
(widget-create 'push-button
               :action (lambda (widget &optional _event)
                         (message "押された value=%s" (widget-value widget)))
               :tag "押して"
               "何かの値")
(use-local-map widget-keymap) ;; これが無いと押せない。linkは押せるのに
(widget-setup)

listの例:

(pop-to-buffer (generate-new-buffer "*Widget Example*"))
(widget-create 'list
               :tag "何かの固定長固定型のリスト"
               :notify (lambda (widget &rest args)
                         (message "通知 value=%s" (widget-value widget)))
               '(const "何かの固定値")
               '(boolean :tag "何かの真偽値" :on "有効" :off "無効")
               '(text :tag "好きな複数行文字列" :value "hogehoge"))
(use-local-map widget-keymap)
(widget-setup)

widget-keymapには次のものが割り当てられています:

  • ボタンを押すために必要なコマンド(RET, down-mouse-1等)
  • 前後のwidgetへ移動するコマンド(TAB, S-TAB等)

widget-setupは(現在のバッファについて)次のことを行います:

  • 一部widgetの最終初期化処理
  • UNDO情報のクリア
  • 変更を監視するフックの追加 (変更をしかるべき所に通知するのが主な目的ですが、同時にフィールド以外の所でテキスト編集ができなくなります)

そして肝心要のwidget-createは次のことを行います:

  1. widgetオブジェクトの作成
  2. バッファへの挿入

widget-createの引数は (type &rest args) です。 type はwidgetの種類を表すシンボルです。残りの引数列 argstype ごとに定められた形の引数列です。一般的には、キーワード引数が0個以上続いた後にキーワードが付かない値が0個以上続く形になっています。

widgetの type (種類)に何があるのかは、マニュアルのBasic TypesSexp Typesに載っているほか、M-x widget-browseの補完候補で分かります。または次のコードで(現在ロードされている)一覧を得ることも出来ます。

(let ((syms))
  (mapatoms (lambda (s) (when (get s 'widget-type) (push s syms))) obarray)
  syms)
(boolean checklist widget-browse documentation-link group natnum emacs-commentary-link float visibility coding-system custom-manual tree-widget-icon regexp checkbox c-symbol-list choice other toggle variable cons integer editable-field bibtex-entry-alist tree-widget-nohandle-guide flycheck-minimum-level alist option mule-input-method-string charset plist info-link sexp c-integer-or-nil radio-button-choice character tree-widget-no-handle lazy emacs-library-link flycheck-highlighting-style custom-browse-group-tag my-attribute-list tree-widget-no-guide glyphless-char-display-method tree-widget-empty-icon custom-face-edit tree-widget-leaf-icon custom-face tree-widget-open-icon tree-widget string custom-group-visibility custom-icon link repeat list function-link hook my-attribute-plist buffer-predicate custom-browse-variable-tag variable-link custom-magic fringe-bitmap custom-comment number text directory vector documentation-string custom-group-link custom-visibility custom-browse-face-tag choice-item radio-button symbol bibtex-field-alist custom-group face restricted-sexp custom-variable custom key c-extra-types-widget tree-widget-end-guide custom-face-all function custom-browse-visibility custom-display face-link color tree-widget-close-icon tree-widget-guide item const file editable-list function-item set insert-button key-sequence radio default file-link variable-item menu-choice delete-button push-button url-link c-const-symbol tree-widget-handle)

基本的なwidgetは wid-edit.el で定義されているので、それを見るのが一番手っ取り早いでしょう。例えば url-link はwid-edit.el内で次のように定義されています。

(define-widget 'url-link 'link
  "A link to a web page."
  :action 'widget-url-link-action)

このコードによって、url-linkタイプは、linkタイプの:actionプロパティを'widget-url-link-actionに変更したものと定義されます。

これは良くあるオブジェクト指向プログラミング言語におけるクラスの定義と意味的にはほとんど同じです。linkが継承元クラスで、:actionというメソッドをオーバーライドすることに相当します。:actionはプロパティですが、その値は常に関数として(widget-applyで)呼び出されるのでメソッドのようなものです。:actionに指定された関数はwidgetが押されたときに呼び出されます。:actionに指定されているwidget-url-link-action関数の中身が (browse-url (widget-value widget)) となっているので、url-linkを押すとwidgetの現在値に設定されたURLがbrowse-url関数で開かれるわけです。

ちなみに継承元であるlinkは:

(define-widget 'link 'item
  "An embedded link."
  :button-prefix 'widget-link-prefix
  :button-suffix 'widget-link-suffix
  :follow-link 'mouse-face
  :keymap widget-link-keymap
  :help-echo "Follow the link."
  :format "%[%t%]")

さらにその継承元であるitemは:

(define-widget 'item 'default
  "Constant items for inclusion in other widgets."
  :convert-widget 'widget-value-convert-widget ;; 引数列をwidgetオブジェクトへ変換する
  :value-create 'widget-item-value-create ;; :formatの%v部分として、:valueの値をprincでバッファへ挿入する
  :value-delete 'ignore
  :value-get 'widget-value-value-get ;; :valueの値をそのまま返す
  :match 'widget-item-match
  :match-inline 'widget-item-match-inline
  :action 'widget-item-action ;; 自分自身に対して :notify を呼び出す
  :format "%t\n")

さらにさらにその継承元であるdefaultは:

(define-widget 'default nil
  "Basic widget other widgets are derived from."
  :value-to-internal (lambda (_widget value) value)
  :value-to-external (lambda (_widget value) value)
  :button-prefix 'widget-button-prefix
  :button-suffix 'widget-button-suffix
  :completions-function #'widget-default-completions
  :create 'widget-default-create ;; :format等に従ってテキストやオーバーレイなどをバッファへ挿入する。
  :indent nil
  :offset 0
  :format-handler 'widget-default-format-handler ;; :formatに知らないエスケープ文字がある場合に呼ばれる
  :button-face-get 'widget-default-button-face-get
  :mouse-face-get 'widget-default-mouse-face-get
  :sample-face-get 'widget-default-sample-face-get
  :delete 'widget-default-delete ;; バッファからwidgetの全テキストを削除する
  :copy 'identity
  :value-set 'widget-default-value-set
  :value-inline 'widget-default-value-inline
  :value-delete 'ignore ;; :value-createで挿入したものを削除する
  ;; :value-create で :format の %v 部分をバッファへ挿入する
  :default-get 'widget-default-default-get
  :menu-tag-get 'widget-default-menu-tag-get
  :validate #'ignore ;; widgetの現在値が正当かチェックする
  :active 'widget-default-active
  :activate 'widget-specify-active
  :deactivate 'widget-default-deactivate
  :mouse-down-action #'ignore
  :action 'widget-default-action
  :notify 'widget-default-notify
  :prompt-value 'widget-default-prompt-value)

と定義されており、このように継承関係を辿っていくことが出来ます。

(ちなみに、実装的にはJavaScriptのprototypeチェーンを使った継承に似ています。prototypeの代わりにシンボルの'widget-typeプロパティが使われていますが)

プロパティの一覧については、後からdefine-widget部分に載っていないプロパティが動的に追加・参照されることも多々あるのでこれだけでは完全ではありませんが、ある程度参考にはなるでしょう。

新しいwidgetタイプを作る時に使うプロパティについてはDefining New Widgetsに説明がありますが、これだけで分かる人もあまりいないと思うので wid-edit.el を見て各widget-*関数からどのようにそれらのプロパティが参照されているかを確認した方が早いでしょう。

様々なタイミングでどのような処理がされているのかいくらでも書くことが出来ますが、キリがないのでとりあえずこの辺で。

最後にwidgetタイプをクラスに見立ててクラス図を描いたのを載せておきます。

Basic Typesに書いてあるもの:

2024-01-07-classes-basic.png

Sexp Typesに書いてあるもの:

2024-01-07-classes-sexp.png

Basic Typesに書いてあるものの詳細:

2024-01-07-classes-basic-detailed.png

※(関数以外の)デフォルト値を変更しているだけのものは // を付けて残してあります。

2023-09-08 ,

el-easydrawで縦書きは表示できるか

style属性に writing-mode:vertical-rl; と指定すれば縦書きを表示できます。

edrawでテキストを縦書きにしてみた様子
図1: edrawでテキストを縦書きにしてみた様子

ただしEmacs 27.1世代の古いlibrsvgではウンともスンとも言わず全く効果はありませんでした。

私が今使っているWindows上の(MSYS2でビルドされた)Emacs 29.1においても、上スクリーンショットのように正しい位置に描画されません。他にも一部の文字の位置がずれる問題も発生しています。

text-anchorをmiddleにすることで縦方向の中心に揃えることが出来るはずですが、これも正しく機能しているとは言い難い状況です(先頭文字のmiddleになっている?)。

また、edraw自身も境界矩形を正しく認識していません。これを修正するにはstyleの値を解析する必要がありそうです。(2023-09-10追記: writing-modeプロパティを追加して境界矩形はそれを考慮するようにしました。styleの方は依然考慮していません)

実際にこのブログに描いてエクスポートすると次のようになります(埋め込みのSVGなので文字の範囲選択や検索が可能です)。

バスタ新宿中央道日野新島々駅安曇野支所前さわんどBT中の湯大正池帝国ホテル前上高地BT
図2: 実際にエクスポートされたSVG
2023-09-08 ,

el-easydrawでCSS filterは使えるのか

使えるみたいです。

各種図形のstyleプロパティにfilterを指定した様子
図1: 各種図形のstyleプロパティにfilterを指定した様子

style属性に filter:drop-shadow(3px 3px 5px black); などと指定してやると、ドロップダウンシャドウが表示されます。

(その他の書き方: filter - CSS: カスケーディングスタイルシート | MDN)

実際にエクスポートしたのが次。表示されるかはブラウザ次第です。

TEXTAAABBBCCCHEARTSPADEDIA
図2: edrawで描いてエクスポートしたSVG

ちゃんとやるならSVG本来のフィルタに対応すべきなのでしょうが、UIを作るのが面倒くさいんですよねぇ。

ちなみに、手元のEmacs 27.1バイナリで試したところEmacs内の表示には効果がありませんでした。おそらくここ数年でlibrsvgが対応したのだと思います。

filterを使うと作図エディタとしての動作がかなり重くなります。EmacsでSVGを使って色々やる場合に一番ネックになる点は、実はlibrsvgがリアルタイム向きではないという事です。Emacs Lispを使ってSVGを組み立ててそれをイベントのたびに更新するという仕組みはそれ自体かなり無駄が多いのですが、そこは今日のPCではそこまで大きな問題ではありません。一番のネックはなんといっても画像の1ピクセル毎にかかる処理時間なのです。グリッド線にブレンドモードを指定しただけでかなり重くなったりもします。この辺りは元々用途が違うものを無理矢理使っているのですから仕方が無いところかもしれません。

2023-08-26 ,

Emacsの中で動く作図ツール 最近の変更点(2023年1月~8月)

Emacsの中で動く作図ツールですが、前回(2022年末)からの変更点をまとめました。

misohena/el-easydraw: Embedded drawing tool for Emacs

ちなみにインストールはpackage-vcやらstraightやらで出来るらしいです。私は普通にGitのサブモジュールとしてcloneしてload-pathを通しているだけです。

接着機能

図形(の中の点)を他の図形にくっつける(移動に追従させる)機能を追加しました。図形の間を線で結んだり(パスツールでCtrlを押しながら図形をクリック)、テキストを矩形などの中心に配置し(テキストツールでCtrlを押しながら図形をクリック)、移動してもその状態を維持し続けられます。

接着機能の使用例(注:矢印設定は現在は複数選択で一括で出来ます)
図1: 接着機能の使用例(注:矢印設定は現在は複数選択で一括で出来ます)

仕様はかなり悩みました。今のところ条件は限定されており、また、残っている問題も多いです。内部的には点接続という図形内のアンカーポイントなどの点を別の図形内の点に関連付ける仕組みで実現しています。接続関係を表すデータは、SVG内にdata属性として記録しています。コンテキストメニュー内にも接着関連のコマンドをいくつか追加しました。

変形機能の改善
  • transform属性を図形の座標に適用
  • グループの変形に対応
  • 変形方式設定を追加
  • グループ化解除時にtransform属性を子に適用
  • GUIで変形(C-t)

最低限の変形機能は出来たと思いますがまだまだ沢山の問題が残っています。

変形と一口に言っても何をどのように変えるのかはある程度選択の幅があります。図形の種類(SVG要素の種類)によっては出来ないこともあるので、そういうときにどうするかが難しいです。

変形コマンドの使用例
図2: 変形コマンドの使用例
別フレーム対応

プロパティエディタとシェイプピッカーは別フレームで表示できるようになりました。編集中にフレームにしたりウィンドウに戻したり柔軟に変更できます。メニューボタンやコンテキストメニューから操作できます。だだ、使ってみるとそれほど便利では無いなと思いました。それほど大きな図を描くわけではありませんし、フレームが開くのに少し時間がかかるというのもあるかもしれません。そもそも私はEmacsでフレームを使うことに慣れていません。

フレーム表示例
図3: フレーム表示例
カスタムシェイプにラベルを追加

ほとんど例としてでてすが、二種類ほど追加しておきました。すでにカスタムシェイプリストを編集してしまっているとリセットしないと反映されないと思います。

シェイプピッカーも色々直したいところがあります。とりあえず折りたたみ状態は保持したいところ。

手書きツールの改善
生成する点の数を大幅に削減しました。
複製機能

選択図形を複製するコマンドを追加しました。単にコピーしてペーストしてもいいのですが、Dキー一つでできます。

また、選択ツールにおいて、M-ドラッグで複製しつつ平行移動します。

M-矢印キーまたはM-S-矢印キーで複製しつつ平行移動します。S付きは10px単位で移動します。C-u 数値のプレフィックスを付けると数値のピクセル数だけ移動します。

S-ドラッグによる移動方向制限
シフトキーを押しながらドラッグする操作に対応しました。ツールによって意味は異なりますが、45度単位で移動することが多いです。
切り抜き機能
マウスで範囲を指定してドキュメント全体を切り抜く機能を追加しました。全体を平行移動してドキュメントのサイズを変更します。範囲外を自動的に削除したりは しません 。図を描いたら端が余ってしまったということが良くあるのでそういうときに使います。実は小さくするときだけでなく大きくしたいときにも使えます。
日本語化

current-language-environmentが "Japanese" の時は日本語で表示されます。 edraw-msg-file 変数で無効化できます。環境によっては文字化け等正しく表示されない場合もあります。その場合は環境のフォント設定等を見直すか、諦めて無効化してください。

日本語でメニューが表示されている様子
図4: 日本語でメニューが表示されている様子

元々全てのメッセージをedraw-msg関数で囲っていたのはこのためでした。Emacsはメッセージが多言語化されているところがほぼありません。見つかったのはチュートリアルくらいです。それがcurrent-language-environmentによって切り替わっているので、それにならいました。そもそもEmacsのdocstringには多言語に対応する仕組みが無いのは大いに不満ですね!(最低限言語を指定するメタデータがあって、ボタン一発で翻訳するとかどうだろう)

マーカーの改善

マーカー(パスに付ける矢印や丸印)の形状をある程度カスタマイズできるようにしました。プロパティエディタから変更したり、メインメニューや変数edraw-default-marker-propertiesでデフォルトを変更できます。

将来的には形状自体を増やせるようにしたいです。そのための下ごしらえも少ししました。

パスツールのM-クリック・ドラッグ操作
Alt+クリック・ドラッグでハンドルを確実にコントロールできます。ハンドルをM-ドラッグするとそのハンドルのみを移動します(反対側のハンドルは動きません)。アンカーをM-ドラッグするとそのアンカーの二つのハンドルを再作成します(スムーズ点になります)。アンカーをM-クリックするとそのアンカーの二つのハンドルを削除します(コーナー点になります)。いわゆる切り替えツールとほぼ同じです。
点の座標指定移動
パスのアンカーやハンドルのコンテキストメニューに「座標による移動コマンド」を追加しました。精密な操作が必要な場合に有用です。
座標の表示
色々な場面で座標やサイズをメッセージ出力するようにしました。
図形に対するコンテキストメニューの「設定」によく使うプロパティの変更を追加
image要素に対するhrefとtext要素に対するfont-sizeを追加しました。
テキストツールの既存テキストクリック操作

これまでクリックは単に新しくテキストを追加するだけでしたが、既存のテキストをクリックした場合はそのテキストの文字列を(ミニバッファで)入力するようにしました。これまでプロパティエディタを開いて変更していたのですが、やっぱりその方が便利かなと思いまして。既存テキストの近くに新しいテキストを追加したい場合はC-uプレフィックスを入力してからクリックしてください。強制的に追加になります。

テキストまわりはもっと沢山の設定項目が必要です。

ツールヘルプの表示
ツールの操作は気が付きにくいものが多いので、ツール切り替え時に簡単なガイドを表示するようにしました。
選択ツールのC-ドラッグ操作
Ctrl+ドラッグで範囲と重なる図形を選択、選択解除します。
複数選択図形一括操作
複数の選択図形をプロパティエディタで変更できるようにしました。また、コンテキストメニューの「設定」でも一度にプロパティ値を変更できるようにしました。
ビューサイズの改善
表示領域自動拡大の改善
ズーム時の表示領域自動拡大の上限をウィンドウサイズに対する比率で指定出来ようにしました(edraw-editor-auto-view-enlargement-max-size変数参照)。デフォルトは幅約94%、高さ約63%に設定されています。あまり大きくすると環境によっては不安定になりそうで心配しています。
edraw-set-view-size-specの単純化
ビューのサイズ指定は、単純に高さと幅を数値で指定するだけになりました。これにより誤入力を減らせます。指定の解除はビューのリセットコマンドを使用してください。

困ったら 0 や v 0 を押してください。元に戻ります。

本当はドラッグでビューサイズを変えられると良いんですけどね。右下につまみを表示しなければなりません。

キー割り当ての追加
  • 選択図形に対する操作
    • g : グループ化
    • G : グループ化解除
    • D : 複製
    • p f : fillを変更
    • p s : strokeを変更
    • p p または M-RET: プロパティエディタを開く
    • M-矢印キー または M-S-矢印キー または C-u N M-矢印キー : 複製後移動
    • TAB : 次の図形(M-]と同じ)
    • S-TAB : 前の図形(M-[と同じ)
    • C-t : インタラクティブ変形
  • i : 画像ツール
  • dvb : svg要素のviewBox属性を変更
カスタマイズ変数の追加
edraw-editor-image-scaling-factor
大きさの微調整をします。ノートPCで少し小さいと感じたので追加しました。Emacs自体が(create-image関数が)自動スケーリング機能を持っているのですがギリギリそれが働かない解像度だったようで、それとは別に用意しました。
edraw-editor-default-tool
起動したときに選択するツールです。これまでは矩形ツールだったのですが、選択ツールの方がいいかなと思ったので変更できるようにしました。
edraw-org-link-image-max-size variable
org-mode上でインライン画像表示するときの最大サイズを設定できるようにしました。ウィンドウからはみ出すのを防止できます。
SVGファイル・データ内のコメントを可能な限り維持
SVGファイルやデータ内にあるコメントを可能な限り維持するようにしました。 <!-- -*- mode: edraw -*- --> というヘッダーコメントや任意のフッターコメントを入れることを想定しています。svg要素内にあるコメントは図形の前後関係など、動作に支障を来す可能性があります。
カラーピッカーの改善
  • 最近使った色の保存
  • 最近使った色をキーで選択(C-1, C-2, ..., C-0)
  • ドラッグ時にピッカーの外に出たときの挙動を改善(境界線上の色を指定しやすくする)
  • 色テキストを追加・置換するコマンド(カラーピッカー単独での利用)の改善
    • 子フレーム対応
    • set-transient-mapによる安定したキー操作
    • edraw-color-picker-replace-or-insert-color-at-pointコマンドを追加
    • css-modeやmhtml-modeでの設定例を追加

カラーピッカーのedraw-editor以外からの利用(応用)まではなかなか手が回らずいくつか放置されていた問題がありましたが、修正したので大分使いやすくなったと思います。私は先日書いたような設定でcss等の色が書いてある部分をいつでもカラーピッカーで変更できるようになりました。他の色形式に対応したり、元の書き方を出来るだけ変えないようにする等まだ改善点は残っています。それと子フレームは環境によっては正しく動かない可能性があるので心配しています。一応子フレームを使わないようにするカスタマイズ変数もあります。

カラーピッカー自体には、後は固定のパレットの追加と他の表色系への対応を考えています。

web-modeでカラーピッカーを使っている様子
図5: web-modeでカラーピッカーを使っている様子
edrawコマンド
edraw-mode.elにedrawコマンドを追加しました。M-x edrawで新しいバッファを作成してedraw-modeを立ち上げるだけのシンプルなものです。素早く新しい図を作成したい場合に有用です。名前を付けて保存するにはC-x C-sやC-x C-wでOKですが、その時の拡張子やauto-mode-alistの設定等によってはedraw-modeが解除されてしまうのでその際は再度M-x edraw-modeしてください。
edraw-modeの改善

単体の.edraw.svgファイル(edraw-modeバッファ)を編集する際に支障がある問題を改善しました。

  • バッファが空の場合に表示されないバグを修正
  • ファイル保存時にUTF-8を強制
  • テキストを編集できてしまうバグを修正
  • (テキスト)カーソルの非表示
  • 他のモード(xml-mode等)との確実な切り替えを確認
  • メインメニューの「保存」を単にsave-bufferコマンド(C-x C-s)へ変更
  • メインメニューにxml-modeへの切り替えを追加(単にxml-modeを呼び出すだけ)

org-modeからの利用ばかり考えていて、長らくこちらはおろそかになっていました。ちょっと試す分にはedraw-modeの方が速い気がしたので手を付けました。

README
  • org-modeの非同期エクスポートを有効にしている場合の設定方法を追加
  • org-modeの通常のファイルリンクで使う方法を追加
  • SVGファイル内のコメントやmagic-mode-alistでedraw-modeを使う方法を追加(.edraw.svgという長い拡張子を使わない方法)
バグ修正
一部の環境でエディタが表示されない
librsvgのバージョンによってセーブして再び開くとエディタが表示されない不具合がありました。svg要素のxmlnsが消えてしまうのが原因でした。新しめのlibrsvgはxmlnsを厳格に解釈するようなので、その影響かもしれません。それに伴いimage要素ではhrefではなくxlink:href属性を使用するようにしました。
画像ツールのファイル名入力を改善

Macで画像ファイル名の拡張子が入力されない不具合を修正しました。

また、画像は参照元のファイルがあるディレクトリかそのサブディレクトリにあるものしか表示できません。これはlibrsvgがセキュリティ上課している制限です。

マウスカーソルのちらつきを改善
マウスカーソルが画面が更新されるたびに一瞬だけ別の形状に変わるのを出来るだけ抑制しました。

その他沢山の細かい修正があります。