Regenerated.
[emacs.git] / lisp / composite.el
blob1f279cd6a178793bdc8d35561f5730e4441893f9
1 ;;; composite.el --- support character composition
3 ;; Copyright (C) 1999 Electrotechnical Laboratory, JAPAN.
4 ;; Licensed to the Free Software Foundation.
6 ;; Keywords: mule, multilingual, character composition
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
13 ;; any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
25 ;;; Commentary:
27 ;;; Code:
29 ;;;###autoload
30 (defconst reference-point-alist
31 '((tl . 0) (tc . 1) (tr . 2)
32 (Bl . 3) (Bc . 4) (Br . 5)
33 (bl . 6) (bc . 7) (br . 8)
34 (cl . 9) (cc . 10) (cr . 11)
35 (top-left . 0) (top-center . 1) (top-right . 2)
36 (base-left . 3) (base-center . 4) (base-right . 5)
37 (bottom-left . 6) (bottom-center . 7) (bottom-right . 8)
38 (center-left . 9) (center-center . 10) (center-right . 11)
39 ;; For backward compatibility...
40 (ml . 3) (mc . 10) (mr . 5)
41 (mid-left . 3) (mid-center . 10) (mid-right . 5))
42 "Alist of symbols vs integer codes of glyph reference points.
43 A glyph reference point symbol is to be used to specify a composition
44 rule in COMPONENTS argument to such functions as `compose-region' and
45 `make-composition'.
47 Meanings of glyph reference point codes are as follows:
49 0----1----2 <---- ascent 0:tl or top-left
50 | | 1:tc or top-center
51 | | 2:tr or top-right
52 | | 3:Bl or base-left 9:cl or center-left
53 9 10 11 <---- center 4:Bc or base-center 10:cc or center-center
54 | | 5:Br or base-right 11:cr or center-right
55 --3----4----5-- <-- baseline 6:bl or bottom-left
56 | | 7:bc or bottom-center
57 6----7----8 <---- descent 8:br or bottom-right
59 Glyph reference point symbols are to be used to specify composition
60 rule of the form \(GLOBAL-REF-POINT . NEW-REF-POINT), where
61 GLOBAL-REF-POINT is a reference point in the overall glyphs already
62 composed, and NEW-REF-POINT is a reference point in the new glyph to
63 be added.
65 For instance, if GLOBAL-REF-POINT is `br' (bottom-right) and
66 NEW-REF-POINT is `tc' (top-center), the overall glyph is updated as
67 follows (the point `*' corresponds to both reference points):
69 +-------+--+ <--- new ascent
70 | | |
71 | global| |
72 | glyph | |
73 -- | | |-- <--- baseline \(doesn't change)
74 +----+--*--+
75 | | new |
76 | |glyph|
77 +----+-----+ <--- new descent
80 ;; Encode composition rule RULE into an integer value. RULE is a cons
81 ;; of global and new reference point symbols.
82 ;; This must be compatible with C macro COMPOSITION_ENCODE_RULE
83 ;; defined in composite.h.
85 (defun encode-composition-rule (rule)
86 (if (and (integerp rule) (< rule 144))
87 ;; Already encoded.
88 rule
89 (or (consp rule)
90 (error "Invalid composition rule: %S" rule))
91 (let ((gref (car rule))
92 (nref (cdr rule)))
93 (or (integerp gref)
94 (setq gref (cdr (assq gref reference-point-alist))))
95 (or (integerp nref)
96 (setq nref (cdr (assq nref reference-point-alist))))
97 (or (and (>= gref 0) (< gref 12) (>= nref 0) (< nref 12))
98 (error "Invalid composition rule: %S" rule))
99 (+ (* gref 12) nref))))
101 ;; Decode encoded composition rule RULE-CODE. The value is a cons of
102 ;; global and new reference point symbols.
103 ;; This must be compatible with C macro COMPOSITION_DECODE_RULE
104 ;; defined in composite.h.
106 (defun decode-composition-rule (rule-code)
107 (or (and (natnump rule-code) (< rule-code 144))
108 (error "Invalid encoded composition rule: %S" rule-code))
109 (let ((gref (car (rassq (/ rule-code 12) reference-point-alist)))
110 (nref (car (rassq (% rule-code 12) reference-point-alist))))
111 (or (and gref (symbolp gref) nref (symbolp nref))
112 (error "Invalid composition rule code: %S" rule-code))
113 (cons gref nref)))
115 ;; Encode composition rules in composition components COMPONENTS. The
116 ;; value is a copy of COMPONENTS, where composition rules (cons of
117 ;; global and new glyph reference point symbols) are replaced with
118 ;; encoded composition rules. Optional 2nd argument NOCOPY non-nil
119 ;; means don't make a copy but modify COMPONENTS directly.
121 (defun encode-composition-components (components &optional nocopy)
122 (or nocopy
123 (setq components (copy-sequence components)))
124 (if (vectorp components)
125 (let ((len (length components))
126 (i 1))
127 (while (< i len)
128 (aset components i
129 (encode-composition-rule (aref components i)))
130 (setq i (+ i 2))))
131 (let ((tail (cdr components)))
132 (while tail
133 (setcar tail
134 (encode-composition-rule (car tail)))
135 (setq tail (nthcdr 2 tail)))))
136 components)
138 ;; Decode composition rule codes in composition components COMPONENTS.
139 ;; The value is a copy of COMPONENTS, where composition rule codes are
140 ;; replaced with composition rules (cons of global and new glyph
141 ;; reference point symbols). Optional 2nd argument NOCOPY non-nil
142 ;; means don't make a copy but modify COMPONENTS directly.
143 ;; It is assumed that COMPONENTS is a vector and is for rule-base
144 ;; composition, thus (2N+1)th elements are rule codes.
146 (defun decode-composition-components (components &optional nocopy)
147 (or nocopy
148 (setq components (copy-sequence components)))
149 (let ((len (length components))
150 (i 1))
151 (while (< i len)
152 (aset components i
153 (decode-composition-rule (aref components i)))
154 (setq i (+ i 2))))
155 components)
157 ;;;###autoload
158 (defun compose-region (start end &optional components modification-func)
159 "Compose characters in the current region.
161 Characters are composed relatively, i.e. composed by overstricking or
162 stacking depending on ascent, descent and other properties.
164 When called from a program, expects these four arguments.
166 First two arguments START and END are positions (integers or markers)
167 specifying the region.
169 Optional 3rd argument COMPONENTS, if non-nil, is a character or a
170 sequence (vector, list, or string) of integers. In this case,
171 characters are composed not relatively but according to COMPONENTS.
173 If it is a character, it is an alternate character to display instead
174 of the text in the region.
176 If it is a string, the elements are alternate characters.
178 If it is a vector or list, it is a sequence of alternate characters and
179 composition rules, where (2N)th elements are characters and (2N+1)th
180 elements are composition rules to specify how to compose (2N+2)th
181 elements with previously composed N glyphs.
183 A composition rule is a cons of global and new glyph reference point
184 symbols. See the documentation of `reference-point-alist' for more
185 detail.
187 Optional 4th argument MODIFICATION-FUNC is a function to call to
188 adjust the composition when it gets invalid because of a change of
189 text in the composition."
190 (interactive "r")
191 (let ((modified-p (buffer-modified-p))
192 (buffer-read-only nil))
193 (if (or (vectorp components) (listp components))
194 (setq components (encode-composition-components components)))
195 (compose-region-internal start end components modification-func)
196 (set-buffer-modified-p modified-p)))
198 ;;;###autoload
199 (defun decompose-region (start end)
200 "Decompose text in the current region.
202 When called from a program, expects two arguments,
203 positions (integers or markers) specifying the region."
204 (interactive "r")
205 (let ((modified-p (buffer-modified-p))
206 (buffer-read-only nil))
207 (remove-text-properties start end '(composition nil))
208 (set-buffer-modified-p modified-p)))
210 ;;;###autoload
211 (defun compose-string (string &optional start end components modification-func)
212 "Compose characters in string STRING.
214 The return value is STRING where `composition' property is put on all
215 the characters in it.
217 Optional 2nd and 3rd arguments START and END specify the range of
218 STRING to be composed. They defaults to the beginning and the end of
219 STRING respectively.
221 Optional 4th argument COMPONENTS, if non-nil, is a character or a
222 sequence (vector, list, or string) of integers. See the function
223 `compose-region' for more detail.
225 Optional 5th argument MODIFICATION-FUNC is a function to call to
226 adjust the composition when it gets invalid because of a change of
227 text in the composition."
228 (if (or (vectorp components) (listp components))
229 (setq components (encode-composition-components components)))
230 (or start (setq start 0))
231 (or end (setq end (length string)))
232 (compose-string-internal string start end components modification-func)
233 string)
235 ;;;###autoload
236 (defun decompose-string (string)
237 "Return STRING where `composition' property is removed."
238 (remove-text-properties 0 (length string) '(composition nil) string)
239 string)
241 ;;;###autoload
242 (defun compose-chars (&rest args)
243 "Return a string from arguments in which all characters are composed.
244 For relative composition, arguments are characters.
245 For rule-based composition, Mth \(where M is odd) arguments are
246 characters, and Nth \(where N is even) arguments are composition rules.
247 A composition rule is a cons of glyph reference points of the form
248 \(GLOBAL-REF-POINT . NEW-REF-POINT). See the documentation of
249 `reference-point-alist' for more detail."
250 (let (str components)
251 (if (consp (car (cdr args)))
252 ;; Rule-base composition.
253 (let ((len (length args))
254 (tail (encode-composition-components args 'nocopy)))
256 (while tail
257 (setq str (cons (car tail) str))
258 (setq tail (nthcdr 2 tail)))
259 (setq str (concat (nreverse str))
260 components args))
261 ;; Relative composition.
262 (setq str (concat args)))
263 (compose-string-internal str 0 (length str) components)))
265 ;;;###autoload
266 (defun find-composition (pos &optional limit string detail-p)
267 "Return information about a composition at or nearest to buffer position POS.
269 If the character at POS has `composition' property, the value is a list
270 of FROM, TO, and VALID-P.
272 FROM and TO specify the range of text that has the same `composition'
273 property, VALID-P is non-nil if and only if this composition is valid.
275 If there's no composition at POS, and the optional 2nd argument LIMIT
276 is non-nil, search for a composition toward LIMIT.
278 If no composition is found, return nil.
280 Optional 3rd argument STRING, if non-nil, is a string to look for a
281 composition in; nil means the current buffer.
283 If a valid composition is found and the optional 4th argument DETAIL-P
284 is non-nil, the return value is a list of FROM, TO, COMPONENTS,
285 RELATIVE-P, MOD-FUNC, and WIDTH.
287 COMPONENTS is a vector of integers, the meaning depends on RELATIVE-P.
289 RELATIVE-P is t if the composition method is relative, else nil.
291 If RELATIVE-P is t, COMPONENTS is a vector of characters to be
292 composed. If RELATIVE-P is nil, COMPONENTS is a vector of characters
293 and composition rules as described in `compose-region'.
295 MOD-FUNC is a modification function of the composition.
297 WIDTH is a number of columns the composition occupies on the screen."
298 (let ((result (find-composition-internal pos limit string detail-p)))
299 (if (and detail-p result (nth 2 result) (not (nth 3 result)))
300 ;; This is a valid rule-base composition.
301 (decode-composition-components (nth 2 result) 'nocopy))
302 result))
305 ;;;###autoload
306 (defun compose-chars-after (pos &optional limit object)
307 "Compose characters in current buffer after position POS.
309 It looks up the char-table `composition-function-table' (which see) by
310 a character after POS. If non-nil value is found, the format of the
311 value should be an alist of PATTERNs vs FUNCs, where PATTERNs are
312 regular expressions and FUNCs are functions. If the text after POS
313 matches one of PATTERNs, call the corresponding FUNC with three
314 arguments POS, TO, and PATTERN, where TO is the end position of text
315 matching PATTERN, and return what FUNC returns. Otherwise, return
316 nil.
318 FUNC is responsible for composing the text properly. The return value
320 nil -- if no characters were composed.
321 CHARS (integer) -- if CHARS characters were composed.
323 Optional 2nd arg LIMIT, if non-nil, limits the matching of text.
325 Optional 3rd arg OBJECT, if non-nil, is a string that contains the
326 text to compose. In that case, POS and LIMIT index to the string.
328 This function is the default value of `compose-chars-after-function'."
329 (let ((tail (aref composition-function-table (char-after pos)))
330 pattern func result)
331 (when tail
332 (save-match-data
333 (save-excursion
334 (while (and tail (not func))
335 (setq pattern (car (car tail))
336 func (cdr (car tail)))
337 (goto-char pos)
338 (if (if limit
339 (and (re-search-forward pattern limit t)
340 (= (match-beginning 0) pos))
341 (looking-at pattern))
342 (setq result (funcall func pos (match-end 0) pattern nil))
343 (setq func nil tail (cdr tail)))))))
344 result))
346 ;;;###autoload
347 (defun compose-last-chars (args)
348 "Compose last characters.
349 The argument is a parameterized event of the form
350 \(compose-last-chars N COMPONENTS),
351 where N is the number of characters before point to compose,
352 COMPONENTS, if non-nil, is the same as the argument to `compose-region'
353 \(which see). If it is nil, `compose-chars-after' is called,
354 and that function find a proper rule to compose the target characters.
355 This function is intended to be used from input methods.
356 The global keymap binds special event `compose-last-chars' to this
357 function. Input method may generate an event (compose-last-chars N COMPONENTS)
358 after a sequence character events."
359 (interactive "e")
360 (let ((chars (nth 1 args)))
361 (if (and (numberp chars)
362 (>= (- (point) (point-min)) chars))
363 (if (nth 2 args)
364 (compose-region (- (point) chars) (point) (nth 2 args))
365 (compose-chars-after (- (point) chars) (point))))))
367 ;;;###autoload(global-set-key [compose-last-chars] 'compose-last-chars)
370 ;;; The following codes are only for backward compatibility with Emacs
371 ;;; 20.4 and earlier.
373 ;;;###autoload
374 (defun decompose-composite-char (char &optional type with-composition-rule)
375 "Convert CHAR to string.
377 If optional 2nd arg TYPE is non-nil, it is `string', `list', or
378 `vector'. In this case, CHAR is converted to string, list of CHAR, or
379 vector of CHAR respectively.
380 Optional 3rd arg WITH-COMPOSITION-RULE is ignored."
381 (cond ((or (null type) (eq type 'string)) (char-to-string char))
382 ((eq type 'list) (list char))
383 (t (vector char))))
385 ;;;###autoload
386 (make-obsolete 'decompose-composite-char 'char-to-string "21.1")
389 ;;; composite.el ends here