lisp/composite.el

   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 3, 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.
  44 A glyph reference point symbol is to be used to specify a composition
  45 rule in COMPONENTS argument to such functions as `compose-region' and
  46 `make-composition'.
  47
  48 Meanings 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
  60 Glyph reference point symbols are to be used to specify composition
  61 rule of the form \(GLOBAL-REF-POINT . NEW-REF-POINT), where
  62 GLOBAL-REF-POINT is a reference point in the overall glyphs already
  63 composed, and NEW-REF-POINT is a reference point in the new glyph to
  64 be added.
  65
  66 For instance, if GLOBAL-REF-POINT is `br' (bottom-right) and
  67 NEW-REF-POINT is `tc' (top-center), the overall glyph is updated as
  68 follows (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.
  85 RULE 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
 166 Characters are composed relatively, i.e. composed by overstricking or
 167 stacking depending on ascent, descent and other properties.
 168
 169 When called from a program, expects these four arguments.
 170
 171 First two arguments START and END are positions (integers or markers)
 172 specifying the region.
 173
 174 Optional 3rd argument COMPONENTS, if non-nil, is a character or a
 175 sequence (vector, list, or string) of integers.  In this case,
 176 characters are composed not relatively but according to COMPONENTS.
 177
 178 If it is a character, it is an alternate character to display instead
 179 of the text in the region.
 180
 181 If it is a string, the elements are alternate characters.
 182
 183 If it is a vector or list, it is a sequence of alternate characters and
 184 composition rules, where (2N)th elements are characters and (2N+1)th
 185 elements are composition rules to specify how to compose (2N+2)th
 186 elements with previously composed N glyphs.
 187
 188 A composition rule is a cons of global and new glyph reference point
 189 symbols.  See the documentation of `reference-point-alist' for more
 190 detail.
 191
 192 Optional 4th argument MODIFICATION-FUNC is a function to call to
 193 adjust the composition when it gets invalid because of a change of
 194 text in the composition."
 195   (interactive "r")
 196   (let ((modified-p (buffer-modified-p))
 197         (inhibit-read-only t))
 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
 207 When called from a program, expects two arguments,
 208 positions (integers or markers) specifying the region."
 209   (interactive "r")
 210   (let ((modified-p (buffer-modified-p))
 211         (inhibit-read-only t))
 212     (remove-text-properties start end '(composition nil))
 213     (restore-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
 219 The return value is STRING where `composition' property is put on all
 220 the characters in it.
 221
 222 Optional 2nd and 3rd arguments START and END specify the range of
 223 STRING to be composed.  They default to the beginning and the end of
 224 STRING respectively.
 225
 226 Optional 4th argument COMPONENTS, if non-nil, is a character or a
 227 sequence (vector, list, or string) of integers.  See the function
 228 `compose-region' for more detail.
 229
 230 Optional 5th argument MODIFICATION-FUNC is a function to call to
 231 adjust the composition when it gets invalid because of a change of
 232 text 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.
 249 For relative composition, arguments are characters.
 250 For rule-based composition, Mth \(where M is odd) arguments are
 251 characters, and Nth \(where N is even) arguments are composition rules.
 252 A 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
 274 If the character at POS has `composition' property, the value is a list
 275 of FROM, TO, and VALID-P.
 276
 277 FROM and TO specify the range of text that has the same `composition'
 278 property, VALID-P is non-nil if and only if this composition is valid.
 279
 280 If there's no composition at POS, and the optional 2nd argument LIMIT
 281 is non-nil, search for a composition toward LIMIT.
 282
 283 If no composition is found, return nil.
 284
 285 Optional 3rd argument STRING, if non-nil, is a string to look for a
 286 composition in; nil means the current buffer.
 287
 288 If a valid composition is found and the optional 4th argument DETAIL-P
 289 is non-nil, the return value is a list of FROM, TO, COMPONENTS,
 290 RELATIVE-P, MOD-FUNC, and WIDTH.
 291
 292 COMPONENTS is a vector of integers, the meaning depends on RELATIVE-P.
 293
 294 RELATIVE-P is t if the composition method is relative, else nil.
 295
 296 If RELATIVE-P is t, COMPONENTS is a vector of characters to be
 297 composed.  If RELATIVE-P is nil, COMPONENTS is a vector of characters
 298 and composition rules as described in `compose-region'.
 299
 300 MOD-FUNC is a modification function of the composition.
 301
 302 WIDTH 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 \f
 310 ;;;###autoload
 311 (defun compose-chars-after (pos &optional limit object)
 312   "Compose characters in current buffer after position POS.
 313
 314 It looks up the char-table `composition-function-table' (which see) by
 315 a character after POS.  If non-nil value is found, the format of the
 316 value should be an alist of PATTERNs vs FUNCs, where PATTERNs are
 317 regular expressions and FUNCs are functions.  If the text after POS
 318 matches one of PATTERNs, call the corresponding FUNC with three
 319 arguments POS, TO, and PATTERN, where TO is the end position of text
 320 matching PATTERN, and return what FUNC returns.  Otherwise, return
 321 nil.
 322
 323 FUNC is responsible for composing the text properly.  The return value
 324 is:
 325   nil -- if no characters were composed.
 326   CHARS (integer) -- if CHARS characters were composed.
 327
 328 Optional 2nd arg LIMIT, if non-nil, limits the matching of text.
 329
 330 Optional 3rd arg OBJECT, if non-nil, is a string that contains the
 331 text to compose.  In that case, POS and LIMIT index to the string.
 332
 333 This 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.
 354 The argument is a parameterized event of the form
 355         \(compose-last-chars N COMPONENTS),
 356 where N is the number of characters before point to compose,
 357 COMPONENTS, if non-nil, is the same as the argument to `compose-region'
 358 \(which see).  If it is nil, `compose-chars-after' is called,
 359 and that function finds a proper rule to compose the target characters.
 360 This function is intended to be used from input methods.
 361 The global keymap binds special event `compose-last-chars' to this
 362 function.  Input method may generate an event (compose-last-chars N COMPONENTS)
 363 after 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 \f
 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
 382 If 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
 384 vector of CHAR respectively.
 385 Optional 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 \f
 394
 395 ;; arch-tag: ee703d77-1723-45d4-a31f-e9f0f867aa33
 396 ;;; composite.el ends here