lisp/composite.el

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