FORMATS/IM.txt

   1 /* Copyright (C) 2003, 2004
   2      National Institute of Advanced Industrial Science and Technology (AIST)
   3      Registration Number H15PRO112
   4    See the end for copying conditions.  */
   5
   6 /***en
   7
   8 @page mdbIM Input Method
   9
  10 @section im-description DESCRIPTION
  11
  12 The m17n library provides a driver for input methods that are
  13 dynamically loadable from the m17n database (see @ref m17nInputMethod
  14 @latexonly (P.\pageref{group__m17nInputMethod}) @endlatexonly).
  15
  16 This section describes the data format that defines those input
  17 methods.
  18
  19 @section im-format SYNTAX and SEMANTICS
  20
  21 The following data format defines an input method.  The driver loads
  22 a definition from a file, a stream, etc.  A definitions is converted
  23 into the form of plist in the driver.
  24
  25 @verbatim
  26 INPUT-METHOD ::= TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
  27
  28 TITLE ::= '(' 'title' MTEXT ')'
  29 @endverbatim
  30
  31 @c MTEXT is a text displayed on the screen when this input method is
  32 active.
  33
  34 @verbatim
  35 MAP-LIST ::= '(' 'map' MAP * ')'
  36
  37 MAP ::= '(' MAP-NAME RULE * ')'
  38
  39 MAP-NAME ::= SYMBOL
  40
  41 RULE ::= '(' KEYSEQ MAP-ACTION * ')'
  42
  43 KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'
  44 @endverbatim
  45
  46 @c SYMBOL in the definitions of @c MAP-NAME must not be @c t nor @c
  47 nil.
  48
  49 @c MTEXT in the definition of @c KEYSEQ consists of characters that
  50 can be generated by a keyboard.  Therefore @c MTEXT usually contains
  51 only ASCII characters.  However, if the input method is intended to be
  52 used, for instance, with a West European keyboard, @c MTEXT may
  53 contain Latin-1 characters.
  54
  55 @c SYMBOL in the definition of @c KEYSEQ must be the return value of
  56 the minput_event_to_key () function.
  57
  58 @c INTEGER in the definition of @c KEYSEQ must be a valid character
  59 code.
  60
  61 @verbatim
  62 MAP-ACTION ::= ACTION
  63
  64 ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK |
  65            | SHOW | HIDE | PUSHBACK | UNDO | SHIFT | CALL
  66            | SET | IF | '(' MACRO-NAME ')'
  67
  68 PREDEFINED-SYMBOL ::=
  69     '@0' | '@1' | '@2' | '@3' | '@4' |
  70     '@5' | '@6' | '@7' | '@8' | '@9' |
  71     '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
  72 @endverbatim
  73 @verbatim
  74 MACRO-LIST ::= '(' 'macro' MACRO * ')'
  75
  76 MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'
  77
  78 MACRO-NAME ::= SYMBOL
  79
  80 MACRO-ACTION ::= ACTION
  81 @endverbatim
  82 @verbatim
  83 MODULE-LIST ::= '(' 'module' MODULE * ')'
  84
  85 MODULE ::= '(' MODULE-NAME FUNCTION * ')'
  86
  87 MODULE-NAME ::= SYMBOL
  88
  89 FUNCTION ::= SYMBOL
  90 @endverbatim
  91
  92 Each @c MODULE declares the name of external module (i.e. dynamic
  93 library) and function names exported by the module.  If a @c FUNCTION has
  94 name "init", it is called with only the default arguments (see the
  95 section about @c CALL) when an input context is created for the input
  96 method.  If a @c FUNCTION has name "fini", it is called with only the
  97 default arguments when an input context is destroyed.
  98
  99 @verbatim
 100 STATE-LIST ::= '(' 'state' STATE * ')'
 101
 102 STATE ::= '(' STATE-NAME BRANCH * ')'
 103
 104 STATE-NAME ::= SYMBOL
 105
 106 BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
 107            | '(' nil BRANCH-ACTION * ')'
 108            | '(' t BRANCH-ACTION * ')'
 109 @endverbatim
 110
 111 In the first form of @c BRANCH, @c MAP-NAME must be an item that appears
 112 in @c MAP.  In this case, if a key sequence matching one of @c
 113 KEYSEQs of @c MAP-NAME is typed, @c BRANCH-ACTIONs are executed.
 114
 115 In the second form of @c BRANCH, @c BRANCH-ACTIONs are executed if a
 116 key sequence that doesn't match any of @c Branch's of the current
 117 state is typed.
 118
 119 In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed if we
 120 shift to the current state after handling all typed keys.  If the
 121 current state is the initial state, @c BRANCH-ACTIONs are executed
 122 just after an input context of the input method is created.
 123
 124 @verbatim
 125 BRANCH-ACTION ::= ACTION
 126 @endverbatim
 127
 128 An input method has the following two lists of symbols.
 129
 130 <ul>
 131 <li> marker list
 132
 133 A marker is a symbol indicating a character position in the preediting
 134 text.  The @c MARK action assigns a position to a marker.  The
 135 position of a marker is referred by the @c MOVE and the @c DELETE actions.
 136
 137 <li> variable list
 138
 139 A variable is a symbol associated with an integer value.  The value of
 140 a variable is set by the @c SET action, and is referred by the @c SET,
 141 the @c INSERT, and the @c IF actions.  All variables are implicitly
 142 initialized to zero.
 143
 144 </ul>
 145
 146 Each @c PREDEFINED-SYMBOL has a special meaning when used as a marker.
 147
 148 <ul>
 149 <li> @c @@0, @c @@1, @c @@2, @c @@3, @c @@4, @c @@5, @c @@6, @c @@7, @c @@8, @c @@9
 150
 151 The 0th, 1st, 2nd, ... 9th position respectively.
 152
 153 <li> @c @@<, @c @@=, @c @@>
 154
 155 The first, the current, and the last position.
 156
 157 <li> @c @@-, @c @@+
 158
 159 The previous and the next position.
 160
 161 <li> @c @@[, @c @@]
 162
 163 The previous and the next position where a candidate list changes.
 164 </ul>
 165
 166 Some of the @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
 167 index in the @c SELECT action.
 168
 169 <ul>
 170
 171 <li> @c @@<, @c @@=, @c @@>
 172
 173 The first, the current, and the last candidate of the current candidate group.
 174
 175 <li> @c @@-
 176
 177 The previous candidate.  If the current candidate is the first one in
 178 the current candidate group, then it means the last candidate in the
 179 previous candidate group.
 180
 181 <li> @c @@+
 182
 183 The next candidate.  If the current candidate is the last one in the
 184 current candidate group, then it means the first candidate in the next
 185 candidate group.
 186
 187 <li> @c @@[, @c @@]
 188
 189 The candidate in the previous and the next candidate group having the same
 190 candidate index as the current one.
 191 </ul>
 192
 193 The arguments and the behavior of each action are listed below.
 194
 195 @verbatim
 196 INSERT ::= '(' 'insert' MTEXT ')'
 197            | MTEXT
 198            | INTEGER
 199            | '(' 'insert' SYMBOL ')'
 200            | '(' 'insert' '(' CANDIDATES * ')' ')'
 201            | '(' CANDIDATES * ')'
 202
 203 CANDIDATES ::= MTEXT | '(' MTEXT * ')'
 204 @endverbatim
 205
 206 The first and second forms insert @c MTEXT before the current position.
 207
 208 The third form inserts the character @c INTEGER before the current
 209 position.
 210
 211 The fourth form treats @c SYMBOL as a variable, and inserts its value
 212 (if it is a valid character code) before the current position.
 213
 214 In the fifth and sixth forms, each @c CANDIDATES represents a
 215 candidate group, and each element of @c CANDIDATES represents a
 216 candidate, i.e. if @c CANDIDATES is an M-text, the candidates are the
 217 characters in the M-text; if @c CANDIDATES is a list of M-texts, the
 218 candidates are the M-texts in the list.
 219
 220 These forms insert the first candidate before the current position.
 221 The inserted string is associated with the list of candidates and
 222 the information indicating the currently selected candidate.
 223
 224 The marker positions affected by the insertion are automatically relocated.
 225
 226 @verbatim
 227 DELETE ::= '(' 'delete' SYMBOL ')'
 228            | '(' 'delete' INTEGER ')'
 229 @endverbatim
 230
 231 The first form treats @c SYMBOL as a marker, and deletes characters
 232 between the current position and the marker position.
 233
 234 The second form treats @c INTEGER as a character position, and deletes
 235 characters between the current position and the character position.
 236
 237 The marker positions affected by the deletion are automatically relocated.
 238
 239 @verbatim
 240 SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
 241            | '(' 'select' INTEGER ')'
 242 @endverbatim
 243
 244 This action first checks if the character just before the current position
 245 belongs to a string that is associated with a candidate list.  If it is,
 246 the action replaces that string with a candidate specified by the
 247 argument.
 248
 249 The first form treats @c PREDEFINED-SYMBOL as a candidate index (as
 250 described above) that specifies a new candidate in the candidate list.
 251
 252 The second form treats @c INTEGER as a candidate index that specifies a
 253 new candidate in the candidate list.
 254
 255 @verbatim
 256 SHOW ::= '(show)'
 257 @endverbatim
 258
 259 This actions instructs the input method driver to display a candidate
 260 list associated with the string before the current position.
 261
 262 @verbatim
 263 HIDE ::= '(hide)'
 264 @endverbatim
 265
 266 This action instructs the input method driver to hide the currently
 267 displayed candidate list.
 268
 269 @verbatim
 270 MOVE ::= '(' 'move' SYMBOL ')'
 271          | '(' 'move' INTEGER ')'
 272 @endverbatim
 273
 274 The first form treats @c SYMBOL as a marker, and makes the marker
 275 position be the new current position.
 276
 277 The second form treats @c INTEGER as a character position, and makes
 278 that position be the new current position.
 279
 280 @verbatim
 281 MARK ::= '(' 'mark' SYMBOL ')'
 282 @endverbatim
 283
 284 This action treats @c SYMBOL as a marker, and sets its position to the
 285 current position.  @c SYMBOL must not be a @c PREDEFINED-SYMBOL.
 286
 287
 288 @verbatim
 289 PUSHBACK :: = '(pushback INTEGER)'
 290 @endverbatim
 291
 292 This action pushes back the latest @c INTEGER number of key events to the event queue.
 293
 294 @verbatim
 295 UNDO :: = '(undo)'
 296 @endverbatim
 297
 298 This action cancels the last key event.
 299
 300 @verbatim
 301 SHIFT :: = '(' 'shift' STATE-NAME ')'
 302 @endverbatim
 303
 304 This action shifts the current state to @c STATE-NAME.  @c
 305 STATE-NAME must appear in @c STATE-LIST.
 306
 307 @verbatim
 308 CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'
 309
 310 ARG ::= INTEGER | SYMBOL | MTEXT | PLIST
 311 @endverbatim
 312
 313 This action calls the function @c FUNCTION of external module @c
 314 MODULE-NAME.  @c MODULE-NAME and @c FUNCTION must appear in @c
 315 MODULE-LIST.
 316
 317 The function is called with an argument of the type (#MPlist *).  The
 318 key of the first element is #Mt and its value is a pointer to an
 319 object of the type #MInputContext.  The key of the second element is
 320 #Msymbol and its value is the current state name.  @c ARGs are used as
 321 the value of the third and later elements.  Their keys are determined
 322 automatically; if an @c ARG is an integer, the corresponding key is
 323 #Minteger; if an @c ARG is a symbol, the corresponding key is
 324 #Msymbol, etc.
 325
 326 The function must return NULL or a value of the type (#MPlist *) that
 327 represents a list of actions to take.
 328
 329 @verbatim
 330 SET ::= '(' OPERAND SYMBOL1 [ INTEGER | SYMBOL2 ] ')'
 331
 332 OPERAND ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
 333 @endverbatim
 334
 335 This action treats @c SYMBOL1 and @c SYMBOL2 as variables and sets the
 336 value of @c SYMBOL1 as below.
 337
 338 If @c OPERAND is 'set', it sets the value of @c SYMBOL1 to @c INTEGER or the
 339 value of @c SYMBOL2.
 340
 341 If @c OPERAND is 'add', it increments the value of @c SYMBOL1 by @c INTEGER
 342 or the value of @c SYMBOL2.
 343
 344 If @c OPERAND is 'sub', it decrements the value of @c SYMBOL1 by @c INTEGER
 345 or the value of @c SYMBOL2.
 346
 347 If @c OPERAND is 'mul', it multiplies the value of @c SYMBOL1 by @c INTEGER
 348 or the value of @c SYMBOL2.
 349
 350 If @c OPERAND is 'div', it divides the value of @c SYMBOL1 by @c INTEGER or
 351 the value of @c SYMBOL2.
 352
 353 @verbatim
 354 IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 * ')'
 355
 356 CONDITION ::= OPERAND VAL1 VAL2
 357
 358 ACTION-LIST1 ::= '(' ACTION * ')'
 359
 360 ACTION-LIST2 ::= '(' ACTION * ')'
 361
 362 OPERAND ::= '=' '<' '>'
 363
 364 VAL1 ::= [ INTEGER1 | SYMBOL1 ]
 365
 366 VAL2 ::= [ INTEGER2 | SYMBOL2 ]
 367 @endverbatim
 368
 369 This action performs actions in @c ACTION-LIST1 if @c CONDITION is
 370 true, and performs @c ACTION-LIST2 (if any) otherwise.
 371
 372 @c SYMBOL1 and @c SYMBOL2 are treated as variables.
 373
 374 @ifnot FOR-MAN
 375
 376 @section im-example1 EXAMPLE 1
 377
 378 This is a very simple example for inputting Latin characters with
 379 diacritical marks (acute and cedilla).  For instance, when you type:
 380 @verbatim
 381     Comme'die-Franc,ais, chic,,
 382 @endverbatim
 383 you will get this:
 384 @if FOR-HTML
 385 @verbatim
 386     Commédie-Français, chic,
 387 @endverbatim
 388 @endif
 389 @if FOR-LATEX
 390 @latexonly
 391 \hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}ais, chic,}
 392 @endlatexonly
 393 @endif
 394
 395 The definition of the input method is very simple as below, and it is
 396 quite straight forward to extend it to cover all Latin characters.
 397
 398 @if FOR-HTML
 399 @verbatim
 400 (title "latin-postfix")
 401 (map
 402  (trans
 403   ("a'" ?á) ("e'" ?é) ("i'" ?í) ("o'" ?ó) ("u'" ?ú) ("c," ?ç)
 404   ("A'" ?Á) ("E'" ?É) ("I'" ?Í) ("O'" ?Ó) ("U'" ?Ú) ("C," ?Ç)
 405   ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")
 406   ("c,," "c,")
 407   ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")
 408   ("C,," "C,")))
 409 (state
 410  (init
 411   (trans)))
 412 @endverbatim
 413 @endif
 414 @if FOR-LATEX
 415 @latexonly
 416 \texttt{\footnotesize
 417 \hskip2mm(title "latin-postfix")\\
 418 \hskip2mm(map\\
 419 \hskip4mm (trans\\
 420 \hskip6mm  ("a'" ?\'{a}) ("e'" ?\'{e}) ("i'" ?\'{i}) ("o'" ?\'{o})
 421 ("u'" ?\'{u}) ("c," ?\c{c})\\
 422 \hskip6mm  ("A'" ?\'{A}) ("E'" ?\'{E}) ("I'" ?\'{I}) ("O'" ?\'{O})
 423 ("U'" ?\'{U}) ("C," ?\c{C})\\
 424 \hskip6mm  ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")\\
 425 \hskip6mm  ("c,," "c,")\\
 426 \hskip6mm  ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")\\
 427 \hskip6mm  ("C,," "C,")))\\
 428 \hskip2mm(state\\
 429 \hskip4mm (init\\
 430 \hskip6mm  (trans)))}
 431 @endlatexonly
 432 @endif
 433
 434 @section im-example2 EXAMPLE 2
 435
 436 This example is for inputting Unicode characters by typing C-u
 437 (Control-u) followed by four hexadecimal numbers.  For instance, when
 438 you type ("^u" means Control-u):
 439 @verbatim
 440     ^u2190^u2191^u2192^u2193
 441 @endverbatim
 442 you will get this (Unicode arrow symbols):
 443 @verbatim
 444     ←↑→↓
 445 @endverbatim
 446
 447 The definition utilizes @c SET and @c IF commands as below:
 448 @verbatim
 449 (title "UNICODE")
 450 (map
 451  (starter
 452   ((C-U) "U+"))
 453  (hex
 454   ("0" ?0) ("1" ?1) ... ("9" ?9) ("a" ?A) ("b" ?B) ... ("f" ?F)))
 455 (state
 456  (init
 457   (starter (set code 0) (set count 0) (shift unicode)))
 458  (unicode
 459   (hex (set this @-)
 460        (< this ?A
 461           ((sub this 48))
 462           ((sub this 55)))
 463        (mul code 16) (add code this)
 464        (add count 1)
 465        (= count 4
 466           ((delete @<) (insert code) (shift init))))))
 467 @endverbatim
 468
 469 @section im-example3 EXAMPLE 3
 470
 471 This example is for inputting Chinese characters by typing PinYin key
 472 sequence.
 473 @if FOR-HTML
 474 For instance, when you type:
 475 @verbatim
 476     nihaobei2jing2
 477 @endverbatim
 478 you will get:
 479 @verbatim
 480     你好北京
 481 @endverbatim
 482
 483 The definition utilizes @c CANDIDATE and @c SELECT commands as below.
 484 Note that this is just an example, and it ignores such important key
 485 as Backspace.
 486
 487 @verbatim
 488 (title "拼")
 489
 490 (map
 491  ;; The initial character of Pinyin.
 492  (starter
 493   ("a") ("b") ... ("h") ("j") ... ("t") ("w") ("x") ("y") ("z"))
 494
 495  ;; Big table of Pinyin vs the corresponding Chinese characters.
 496  (pinyin
 497   ...
 498   ("bei" ("被北备背悲辈杯倍贝碑" ...))
 499   ("hao" ("好号毫豪浩耗皓嚎昊郝" ...))
 500   ("jing" ("经京精境警竟静惊景敬" ...))
 501   ("ni" ("你呢尼泥逆倪匿拟腻妮" ...))
 502   ...)
 503  ;; Typing 1, 2, ..., 0 selects the 0th, 1st, ..., 9th candidate.
 504  (choose
 505   ("1" (select 0)) ("2" (select 1)) ... ("9" (select 8)) ("0" (select 9))))
 506
 507 (state
 508  (init
 509   ;; When an initial character of Pinyin is typed, re-handle it in
 510   ;; "main" state.  Anything else is just produced as is.
 511   (starter (show) (pushback 1) (shift main)))
 512
 513  (main
 514   ;; When a complete Pinyin sequence is typed, shift to "select" state
 515   ;; to allow users to select one from the candidates.
 516   (pinyin (shift select))
 517
 518   ;; When anything else is typed, produce the current candidate (if
 519   ;; any), and re-handle the last input in "init" state.
 520   (nil (hide) (shift init)))
 521
 522  (select
 523   ;; When a number is typed, select the corresponding canidate,
 524   ;; produce it, and shift to "init" state.
 525   (choose (hide) (shift init))
 526
 527   ;; When anything else is typed, produce the current candidate,
 528   ;; and re-handle the last input in "init" state.
 529   (nil (hide) (shift init))))
 530 @endverbatim
 531
 532 @elseif FOR-LATEX
 533 @latexonly
 534 \begin{center}
 535 \fbox{This example is readable only in the documentation of HTML version.}
 536 \end{center}
 537 @endlatexonly
 538 @endif
 539
 540 @endif
 541
 542 @section im-seealso SEE ALSO
 543
 544 @ref mim-list "Input Methods provided by the m17n database",
 545 @ref mdbGeneral "mdbGeneral(5)"
 546 */
 547
 548 /*
 549 Copyright (C) 2003, 2004
 550   National Institute of Advanced Industrial Science and Technology (AIST)
 551   Registration Number H15PRO112
 552
 553 This file is part of the m17n database; a sub-part of the m17n
 554 library.
 555
 556 The m17n library is free software; you can redistribute it and/or
 557 modify it under the terms of the GNU Lesser General Public License
 558 as published by the Free Software Foundation; either version 2.1 of
 559 the License, or (at your option) any later version.
 560
 561 The m17n library is distributed in the hope that it will be useful,
 562 but WITHOUT ANY WARRANTY; without even the implied warranty of
 563 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 564 Lesser General Public License for more details.
 565
 566 You should have received a copy of the GNU Lesser General Public
 567 License along with the m17n library; if not, write to the Free
 568 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 569 02111-1307, USA.
 570 */
 571
 572 /* Local Variables: */
 573 /* coding: utf-8 */
 574 /* End: */