lisp/composite.el

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