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. */
8 @page mdbIM Input Method
10 @section im-description DESCRIPTION
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).
16 This section describes the data format that defines those input
19 @section im-format SYNTAX and SEMANTICS
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.
26 INPUT-METHOD ::= TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
28 TITLE ::= '(' 'title' MTEXT ')'
31 @c MTEXT is a text displayed on the screen when this input method is
35 MAP-LIST ::= '(' 'map' MAP * ')'
37 MAP ::= '(' MAP-NAME RULE * ')'
41 RULE ::= '(' KEYSEQ MAP-ACTION * ')'
43 KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'
46 @c SYMBOL in the definitions of @c MAP-NAME must not be @c t nor @c
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.
55 @c SYMBOL in the definition of @c KEYSEQ must be the return value of
56 the minput_event_to_key () function.
58 @c INTEGER in the definition of @c KEYSEQ must be a valid character
64 ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK |
65 | SHOW | HIDE | PUSHBACK | UNDO | SHIFT | CALL
66 | SET | IF | '(' MACRO-NAME ')'
69 '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
72 MACRO-LIST ::= '(' 'macro' MACRO * ')'
74 MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'
78 MACRO-ACTION ::= ACTION
81 MODULE-LIST ::= '(' 'module' MODULE * ')'
83 MODULE ::= '(' MODULE-NAME FUNCTION * ')'
85 MODULE-NAME ::= SYMBOL
90 Each @c MODULE declares the name of external module (i.e. dynamic
91 library) and function names exported by the module. If a @c FUNCTION has
92 name "init", it is called with only the default arguments (see the
93 section about @c CALL) when an input context is created for the input
94 method. If a @c FUNCTION has name "fini", it is called with only the
95 default arguments when an input context is destroyed.
98 STATE-LIST ::= '(' 'state' STATE * ')'
100 STATE ::= '(' STATE-NAME BRANCH * ')'
102 STATE-NAME ::= SYMBOL
104 BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
105 | '(' nil BRANCH-ACTION * ')'
106 | '(' t BRANCH-ACTION * ')'
109 In the first form of @c BRANCH, @c MAP-NAME must be an item that appears
110 in @c MAP. In this case, if a key sequence matching one of @c
111 KEYSEQs of @c MAP-NAME is typed, @c BRANCH-ACTIONs are executed.
113 In the second form of @c BRANCH, @c BRANCH-ACTIONs are executed if a
114 key sequence that doesn't match any of @c Branch's of the current
117 In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed if we
118 shift to the current state after handling all typed keys. If the
119 current state is the initial state, @c BRANCH-ACTIONs are executed
120 just after an input context of the input method is created.
123 BRANCH-ACTION ::= ACTION
126 An input method has the following two lists of symbols.
131 A marker is a symbol indicating a character position in the preediting
132 text. The @c MARK action assigns a position to a marker. The
133 position of a marker is referred by the @c MOVE and the @c DELETE actions.
137 A variable is a symbol associated with an integer value. The value of
138 a variable is set by the @c SET action, and is referred by the @c SET,
139 the @c INSERT, and the @c IF actions. All variables are implicitly
144 Each @c PREDEFINED-SYMBOL has a special meaning when used as a marker.
147 <li> @c @@<, @c @@=, @c @@>
149 The first, the current, and the last position.
153 The previous and the next position.
157 The previous and the next position where a candidate list changes.
160 Each @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
161 index in the @c SELECT action.
164 <li> @c @@<, @c @@=, @c @@>
166 The first, the current, and the last candidate of the current candidate group.
170 The previous candidate. If the current candidate is the first one in
171 the current candidate group, then it means the last candidate in the
172 previous candidate group.
176 The next candidate. If the current candidate is the last one in the
177 current candidate group, then it means the first candidate in the next
182 The candidate in the previous and the next candidate group having the same
183 candidate index as the current one.
186 The arguments and the behavior of each action are listed below.
189 INSERT ::= '(' 'insert' MTEXT ')'
192 | '(' 'insert' SYMBOL ')'
193 | '(' 'insert' '(' CANDIDATES * ')' ')'
194 | '(' CANDIDATES * ')'
196 CANDIDATES ::= MTEXT | '(' MTEXT * ')'
199 The first and second forms insert @c MTEXT before the current position.
201 The third form inserts the character @c INTEGER before the current
204 The fourth form treats @c SYMBOL as a variable, and inserts its value
205 (if it is a valid character code) before the current position.
207 In the fifth and sixth forms, each @c CANDIDATES represents a
208 candidate group, and each element of @c CANDIDATES represents a
209 candidate, i.e. if @c CANDIDATES is an M-text, the candidates are the
210 characters in the M-text; if @c CANDIDATES is a list of M-texts, the
211 candidates are the M-texts in the list.
213 These forms insert the first candidate before the current position.
214 The inserted string is associated with the list of candidates and
215 the information indicating the currently selected candidate.
217 The marker positions affected by the insertion are automatically relocated.
220 DELETE ::= '(' 'delete' SYMBOL ')'
221 | '(' 'delete' INTEGER ')'
224 The first form treats @c SYMBOL as a marker, and deletes characters
225 between the current position and the marker position.
227 The second form treats @c INTEGER as a character position, and deletes
228 characters between the current position and the character position.
230 The marker positions affected by the deletion are automatically relocated.
233 SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
234 | '(' 'select' INTEGER ')'
237 This action first checks if the character just before the current position
238 belongs to a string that is associated with a candidate list. If it is,
239 the action replaces that string with a candidate specified by the
242 The first form treats @c PREDEFINED-SYMBOL as a candidate index (as
243 described above) that specifies a new candidate in the candidate list.
245 The second form treats @c INTEGER as a candidate index that specifies a
246 new candidate in the candidate list.
252 This actions instructs the input method driver to display a candidate
253 list associated with the string before the current position.
259 This action instructs the input method driver to hide the currently
260 displayed candidate list.
263 MOVE ::= '(' 'move' SYMBOL ')'
264 | '(' 'move' INTEGER ')'
267 The first form treats @c SYMBOL as a marker, and makes the marker
268 position be the new current position.
270 The second form treats @c INTEGER as a character position, and makes
271 that position be the new current position.
274 MARK ::= '(' 'mark' SYMBOL ')'
277 This action treats @c SYMBOL as a marker, and sets its position to the
278 current position. @c SYMBOL must not be a @c PREDEFINED-SYMBOL.
282 PUSHBACK :: = '(pushback INTEGER)'
285 This action pushes back the latest key events to the event queue.
291 This action cancels the last key event.
294 SHIFT :: = '(' 'shift' STATE-NAME ')'
297 This action shifts the current state to @c STATE-NAME. @c
298 STATE-NAME must appear in @c STATE-LIST.
301 CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'
303 ARG ::= INTEGER | SYMBOL | MTEXT | PLIST
306 This action calls the function @c FUNCTION of external module @c
307 MODULE-NAME. @c MODULE-NAME and @c FUNCTION must appear in @c
310 The function is called with an argument of the type (#MPlist *). The
311 key of the first element is #Mt and its value is a pointer to an
312 object of the type #MInputContext. The key of the second element is
313 #Msymbol and its value is the current state name. @c ARGs are used as
314 the value of the third and later elements. Their keys are determined
315 automatically; if an @c ARG is an integer, the corresponding key is
316 #Minteger; if an @c ARG is a symbol, the corresponding key is
319 The function must return NULL or a value of the type (#MPlist *) that
320 represents a list of actions to take.
323 SET ::= '(' OPERAND SYMBOL1 [ INTEGER | SYMBOL2 ] ')'
325 OPERAND ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
328 This action treats @c SYMBOL1 and @c SYMBOL2 as variables and sets the
329 value of @c SYMBOL1 as below.
331 If @c OPERAND is 'set', it sets the value of @c SYMBOL1 to @c INTEGER or the
334 If @c OPERAND is 'add', it increments the value of @c SYMBOL1 by @c INTEGER
335 or the value of @c SYMBOL2.
337 If @c OPERAND is 'sub', it decrements the value of @c SYMBOL1 by @c INTEGER
338 or the value of @c SYMBOL2.
340 If @c OPERAND is 'mul', it multiplies the value of @c SYMBOL1 by @c INTEGER
341 or the value of @c SYMBOL2.
343 If @c OPERAND is 'div', it divides the value of @c SYMBOL1 by @c INTEGER or
344 the value of @c SYMBOL2.
347 IF ::= '(' 'if' CONDITION ACTION-LIST1 ACTION-LIST2 * ')'
349 CONDITION ::= '(' OPERAND VAL1 VAL2 ')'
351 ACTION-LIST1 ::= '(' ACTION * ')'
353 ACTION-LIST2 ::= '(' ACTION * ')'
355 OPERAND ::= '=' '<' '>'
357 VAL1 ::= [ INTEGER1 | SYMBOL1 ]
359 VAL2 ::= [ INTEGER2 | SYMBOL2 ]
362 This action performs actions in @c ACTION-LIST1 if @c CONDITION is
363 true, and performs @c ACTION-LIST2 (if any) otherwise.
365 @c SYMBOL1 and @c SYMBOL2 are treated as variables.
369 @section im-example1 EXAMPLE 1
371 This is a very simple example for inputting Latin characters with
372 diacritical marks (acute and cedilla). For instance, when you type:
374 Comme'die-Franc,ais, chic,,
379 Commédie-Français, chic,
384 \hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}ais, chic,}
388 The definition of the input method is very simple as below, and it is
389 quite straight forward to extend it to cover all Latin characters.
393 (title "latin-postfix")
396 ("a'" ?á) ("e'" ?é) ("i'" ?í) ("o'" ?ó) ("u'" ?ú) ("c," ?ç)
397 ("A'" ?Á) ("E'" ?É) ("I'" ?Í) ("O'" ?Ó) ("U'" ?Ú) ("C," ?Ç)
398 ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")
400 ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")
409 \texttt{\footnotesize
410 \hskip2mm(title "latin-postfix")\\
413 \hskip6mm ("a'" ?\'{a}) ("e'" ?\'{e}) ("i'" ?\'{i}) ("o'" ?\'{o})
414 ("u'" ?\'{u}) ("c," ?\c{c})\\
415 \hskip6mm ("A'" ?\'{A}) ("E'" ?\'{E}) ("I'" ?\'{I}) ("O'" ?\'{O})
416 ("U'" ?\'{U}) ("C," ?\c{C})\\
417 \hskip6mm ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")\\
418 \hskip6mm ("c,," "c,")\\
419 \hskip6mm ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")\\
420 \hskip6mm ("C,," "C,")))\\
427 @section im-example2 EXAMPLE 2
429 This example is for inputting Unicode characters by typing C-u
430 (Control-u) followed by four hexadecimal numbers. For instance, when
431 you type ("^u" means Control-u):
433 ^u2190^u2191^u2192^u2193
435 you will get this (Unicode arrow symbols):
440 The definition utilizes @c SET and @c IF commands as below:
447 ("0" ?0) ("1" ?1) ... ("9" ?9) ("a" ?A) ("b" ?B) ... ("f" ?F)))
450 (starter (set code 0) (set count 0) (shift unicode)))
456 (mul code 16) (add code this)
459 ((delete @<) (insert code) (shift init))))))
462 @section im-example3 EXAMPLE 3
464 This example is for inputting Chinese characters by typing PinYin key
467 For instance, when you type:
476 The definition utilizes @c CANDIDATE and @c SELECT commands as below.
477 Note that this is just an example, and it ignores such important key
484 ;; The initial character of Pinyin.
486 ("a") ("b") ... ("h") ("j") ... ("t") ("w") ("x") ("y") ("z"))
488 ;; Big table of Pinyin vs the corresponding Chinese characters.
491 ("bei" ("被北备背悲辈杯倍贝碑" ...))
492 ("hao" ("好号毫豪浩耗皓嚎昊郝" ...))
493 ("jing" ("经京精境警竟静惊景敬" ...))
494 ("ni" ("你呢尼泥逆倪匿拟腻妮" ...))
496 ;; Typing 1, 2, ..., 0 selects the 0th, 1st, ..., 9th candidate.
498 ("1" (select 0)) ("2" (select 1)) ... ("9" (select 8)) ("0" (select 9))))
502 ;; When an initial character of Pinyin is typed, re-handle it in
503 ;; "main" state. Anything else is just produced as is.
504 (starter (show) (pushback 1) (shift main)))
507 ;; When a complete Pinyin sequence is typed, shift to "select" state
508 ;; to allow users to select one from the candidates.
509 (pinyin (shift select))
511 ;; When anything else is typed, produce the current candidate (if
512 ;; any), and re-handle the last input in "init" state.
513 (nil (hide) (shift init)))
516 ;; When a number is typed, select the corresponding canidate,
517 ;; produce it, and shift to "init" state.
518 (choose (hide) (shift init))
520 ;; When anything else is typed, produce the current candidate,
521 ;; and re-handle the last input in "init" state.
522 (nil (hide) (shift init))))
528 \fbox{This example is readable only in the documentation of HTML version.}
535 @section im-seealso SEE ALSO
537 @ref mim-list "Input Methods provided by the m17n database",
538 @ref mdbGeneral "mdbGeneral(5)"
542 Copyright (C) 2003, 2004
543 National Institute of Advanced Industrial Science and Technology (AIST)
544 Registration Number H15PRO112
546 This file is part of the m17n database; a sub-part of the m17n
549 The m17n library is free software; you can redistribute it and/or
550 modify it under the terms of the GNU Lesser General Public License
551 as published by the Free Software Foundation; either version 2.1 of
552 the License, or (at your option) any later version.
554 The m17n library is distributed in the hope that it will be useful,
555 but WITHOUT ANY WARRANTY; without even the implied warranty of
556 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
557 Lesser General Public License for more details.
559 You should have received a copy of the GNU Lesser General Public
560 License along with the m17n library; if not, write to the Free
561 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
565 /* Local Variables: */