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