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