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