GNU Emacs 32.0.50 (9008bf64c3) のマニュアルを PLaMo 翻訳で機械翻訳したものです。誤訳を含むことがあります。原文: https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Properties.html ・ emacs-doc.conao3.com

33.19.2 テキストプロパティの変更

プロパティを変更するプリミティブは、バッファまたは文字列内の指定された範囲のテキストに適用されます。関数 set-text-properties(セクション末尾を参照)は、その範囲内のテキストのプロパティリスト全体を設定しますが、多くの場合、名前で指定した特定のプロパティのみを追加、変更、または削除する方が有用です。

テキストプロパティはバッファ(または文字列)の内容の一部とみなされ、画面上のバッファの表示に影響を与える可能性があるため、バッファのテキストプロパティに変更が加わると、バッファは変更済みとしてマークされます。バッファのテキストプロパティの変更は元に戻すこともできます(Undoを参照)。文字列の位置は0から始まりますが、バッファの位置は1から始まります。

関数: put-text-property start end prop value &optional object

この関数は、文字列またはバッファ object 内の start と end の間にあるテキストに対して、prop プロパティを value に設定します。object が nil の場合は、現在のバッファがデフォルトとなります。

関数: add-text-properties start end props &optional object

この関数は、文字列またはバッファ object 内の start から end までのテキストに対して、テキストプロパティを追加または上書きします。object が nil の場合は、現在のバッファがデフォルトとなります。

引数 props は、どのプロパティを追加するかを指定します。これはプロパティリスト(プロパティリストを参照)の形式である必要があります。つまり、要素としてプロパティ名と、それに続く対応する値が交互に並ぶリストです。

関数が実際に何らかのプロパティの値を変更した場合は戻り値は t となり、それ以外の場合(props が nil であるか、またはその値がテキスト内の値と一致する場合)は nil となります。

例えば、テキスト範囲の comment および face プロパティを設定する方法は以下の通りです。

(add-text-properties start end
                     '(comment t face highlight))
関数: remove-text-properties start end props &optional object

この関数は、文字列またはバッファ object 内の start から end までのテキストから、指定したテキストプロパティを削除します。object が nil の場合は、現在のバッファがデフォルトとなります。

引数 props は、どのプロパティを削除するかを指定します。これはプロパティリスト(プロパティリストを参照)の形式、つまりプロパティ名とそれに対応する値が交互に並ぶリストである必要があります。ただし、重要なのは名前のみであり、それに付随する値は無視されます。例えば、face プロパティを削除する方法は以下の通りです。

(remove-text-properties start end '(face nil))

関数が実際に何らかのプロパティの値を変更した場合は戻り値として t が、それ以外の場合(props が nil である場合、または指定されたテキスト内のどの文字もそれらのプロパティを持っていなかった場合)は nil が返されます。

特定のテキストからすべてのテキストプロパティを削除するには、set-text-properties を使用し、新しいプロパティリストとして nil を指定してください。

関数: remove-list-of-text-properties start end list-of-properties &optional object

remove-text-propertiesと同様ですが、list-of-propertiesはプロパティ名と値が交互に並ぶリストではなく、プロパティ名のみのリストとなっています。

関数: set-text-properties start end props &optional object

この関数は、文字列またはバッファ object 内の start から end までのテキストの text プロパティリストを完全に置き換えます。object が nil の場合は、現在のバッファがデフォルトとなります。

引数 props は新しいプロパティリストです。これは、プロパティ名と対応する値が交互に並ぶリストである必要があります。

set-text-properties が戻った後、指定された範囲のすべての文字は同一のプロパティを持ちます。

props が nil の場合、指定したテキスト範囲からすべてのプロパティを削除します。以下に例を示します:

(set-text-properties start end nil)

この関数の戻り値を信頼しないでください。

関数: add-face-text-property start end face &optional appendp object

この関数は start と end の間のテキストに対して作用し、face テキストプロパティにフェイス face を追加します。face は、フェイス名や匿名フェイス(フェイス を参照)など、face プロパティの有効な値(特別な意味を持つプロパティ を参照)である必要があります。

領域内のテキストに既に nil face 以外のプロパティが設定されている場合、それらの面は保持されます。この関数は、face プロパティに面のリストを設定します。その際、face が(デフォルトで)最初の要素となり、既存の面が残りの要素となります。オプション引数 appendp が nil 以外である場合は、代わりに face がリストの末尾に追加されます。なお、面のリストでは、各属性について最初に出現する値が優先される点に注意してください。

例えば、以下のコードでは、start と end の間のテキストに斜体の緑色のフェイスが割り当てられます。

(add-face-text-property start end 'italic)
(add-face-text-property start end '(:foreground "red"))
(add-face-text-property start end '(:foreground "green"))

オプション引数 object が nil 以外の場合、現在のバッファではなく、処理対象のバッファまたは文字列を指定します。object が文字列である場合、start と end はその文字列内の0始まりのインデックスとなります。

テキストプロパティを持つ文字列を作成する最も簡単な方法は、propertizeを使うことです:

関数: propertize string &rest properties

この関数は、テキストプロパティ properties が追加された string のコピーを返します。これらのプロパティは、返される文字列内のすべての文字に適用されます。以下に、face プロパティと mouse-face プロパティを持つ文字列を生成する例を示します。

(propertize "foo" 'face 'italic
            'mouse-face 'bold-italic)
     ⇒ #("foo" 0 3 (mouse-face bold-italic face italic))

文字列の各部分に異なるプロパティを設定するには、各部分を propertize で構成し、それらを concat で結合します:

(concat
 (propertize "foo" 'face 'italic
             'mouse-face 'bold-italic)
 " and "
 (propertize "bar" 'face 'italic
             'mouse-face 'bold-italic))
     ⇒ #("foo and bar"
                 0 3 (face italic mouse-face bold-italic)
                 3 8 nil
                 8 11 (face italic mouse-face bold-italic))

バッファからテキストをコピーするが、そのプロパティはコピーしない関数 buffer-substring-no-properties については、バッファ内容の確認 を参照してください。

バッファを変更済みとしてマークせずにテキストプロパティを追加または削除したい場合は、上記の呼び出しをwith-silent-modificationsマクロでラップできます。バッファの変更を参照してください。