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. */
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 a
22 definition from a file, a stream, etc. The definition is converted
23 into the form of plist in the driver.
27 IM-DECLARATION ? DESCRIPTION ? TITLE ?
28 VARIABLE-LIST ? COMMAND-LIST ? MODULE-LIST ?
29 MACRO-LIST ? MAP-LIST ? STATE-LIST ?
31 IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME EXTRA-ID ? VERSION ? ')'
32 VERSION ::= '(' 'version' VERSION-NUMBER ')'
33 DESCRIPTION ::= '(' 'description' [ MTEXT-OR-GETTEXT | nil] ')'
34 VARIABLE-LIST ::= '(' 'variable' VARIABLE-DECLARATION * ')'
35 COMMAND-LIST ::= '(' 'command' COMMAND-DECLARATION * ')'
36 TITLE ::= '(' 'title' TITLE-TEXT ')'
38 VARIABLE-DECLARATION ::=
39 '(' VAR-NAME [ [ MTEXT-OR-GETTEXT | nil ] VALUE VALUE-CANDIDATE * ]')'
41 COMMAND-DECLARATION ::=
42 '(' CMD-NAME [ [ MTEXT-OR-GETTEXT | nil ] KEYSEQ * ] ')'
45 [ MTEXT | '(' '_' MTEXT ')']
51 IM-DESCRIPTION ::= MTEXT
53 VAR-DESCRIPTION ::= MTEXT
54 VALUE ::= MTEXT | SYMBOL | INTEGER
55 VALUE-CANDIDATE ::= VALUE | '(' RANGE-FROM RANGE-TO ')'
56 RANGE-FROM ::= INTEGER
59 CMD-DESCRIPTION ::= MTEXT
63 @c IM-DECLARATION specifies the language and name of this input
66 When @c LANGUAGE is @c t, the use of the input method is not limited
69 When @c NAME is @c nil, the input method is not standalone, but
70 is expected to be used in other input methods. In such cases,
71 @EXTRA-ID is required to identify the input method.
73 @c VERSION specifies the required minimum version number of the m17n
74 library. The format is "XX.YY.ZZ" where XX is a major version
75 number, YY is a minor version number, and ZZ is a patch level.
77 @c DESCRIPTION specifies the description text of this input method by
78 MTEXT-OR-GETTEXT. It it takes the second form, the text is translated
79 according to the current locale by "gettext" (if the translation is
82 @c TITLE-TEXT is a text displayed on the screen when this input method
85 @c VARIABLE-DECLARATION declares a variable used in this input method.
86 If a variable must be initialized to the default value, or is to be
87 customized by a user, it must be declared here. The declaration can
88 be used in two ways. One is to introduce a new variable. In that
89 case, VALUE must not be omitted. Another is to inherit the variable
90 from what declared in the special MIM file "global.mim", and to give
91 the different default value and/or to make the variable customizable
92 specially for the current input method. In the last case, VALUE can
96 @c COMMAND-DECLARATION declares a command used in this input method.
97 If a command must be bound to the default key sequence, or is to be
98 customized by a user, it must be declared here. As well as
99 VARIABLE-DECLARATION, the declaration can be used in two ways. One is
100 to introduce a new command. In that case, KEYSEQ must not be omitted.
101 Another is to inherit the command from what declared in the special
102 MIM file "global.mim", and to give the different key binding and/or to
103 make the command customizable specially for the current input method.
104 In the last case, KEYSEQ can be omitted.
107 MODULE-LIST ::= '(' 'module' MODULE * ')'
109 MODULE ::= '(' MODULE-NAME FUNCTION * ')'
111 MODULE-NAME ::= SYMBOL
116 Each @c MODULE declares the name of external module (i.e. dynamic
117 library) and function names exported by the module. If a @c FUNCTION has
118 name "init", it is called with only the default arguments (see the
119 section about @c CALL) when an input context is created for the input
120 method. If a @c FUNCTION has name "fini", it is called with only the
121 default arguments when an input context is destroyed.
124 MACRO-LIST ::= MACRO-INCLUSION ? '(' 'macro' MACRO * ')' MACRO-INCLUSION ?
126 MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'
128 MACRO-NAME ::= SYMBOL
130 MACRO-ACTION ::= ACTION
132 TAGS ::= `(` LANGUAGE NAME EXTRA-ID ? `)`
134 MACRO-INCLUSION ::= '(' 'include' TAGS 'macro' MACRO-NAME ? ')'
138 @c MACRO-INCLUSION includes macros from another input method specified by @c TAGS.
139 When @c MACRO-NAME is not given, all macros from the input method are included.
142 MAP-LIST ::= MAP-INCLUSION ? '(' 'map' MAP * ')' MAP-INCLUSION ?
144 MAP ::= '(' MAP-NAME RULE * ')'
148 RULE ::= '(' KEYSEQ MAP-ACTION * ')'
150 KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'
152 MAP-INCLUSION ::= '(' 'include' TAGS 'map' MAP-NAME ? ')'
156 When an input system is never standalone and always included in
157 another system, @c MAP-LIST can be omitted.
159 @c SYMBOL in the definitions of @c MAP-NAME must not be @c t nor @c
162 @c MTEXT in the definition of @c KEYSEQ consists of characters that
163 can be generated by a keyboard. Therefore @c MTEXT usually contains
164 only ASCII characters. However, if the input method is intended to be
165 used, for instance, with a West European keyboard, @c MTEXT may
166 contain Latin-1 characters.
168 @c SYMBOL in the definition of @c KEYSEQ must be the return value of
169 the minput_event_to_key () function. Under the X window system, you
170 can quickly check the value using the @c xev command. For example,
171 the return key, the backspace key, and the 0 key on the keypad are
172 represented as @c (Return) , @c (BackSpace) , and @c (KP_0)
173 respectively. If the shift, control, meta, alt, super, and hyper
174 modifiers are used, they are represented by the S- , C- , M- , A- , s-
175 , and H- prefixes respectively in this oreder. Thus, "return with
176 shift with meta with hyper" is @c (S-M-H-Return) . Note that "a with
177 shift" .. "z with shift" are represented simply as A .. Z . Thus "a
178 with shift with meta with hyper" is @c (M-H-A) .
180 @c INTEGER in the definition of @c KEYSEQ must be a valid character
183 @c MAP-INCLUSION includes maps from another input method specified by @c TAGS.
184 When @c MAP-NAME is not given, all maps from the input method are included.
187 MAP-ACTION ::= ACTION
189 ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK
190 | SHOW | HIDE | PUSHBACK | POP | UNDO
191 | COMMIT | UNHANDLE | SHIFT | CALL
192 | SET | IF | COND | '(' MACRO-NAME ')'
194 PREDEFINED-SYMBOL ::=
195 '@0' | '@1' | '@2' | '@3' | '@4'
196 | '@5' | '@6' | '@7' | '@8' | '@9'
197 | '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
199 | '@-0' | '@-N' | '@+N'
203 STATE-LIST ::= STATE-INCUSION ? '(' 'state' STATE * ')' STATE-INCUSION ?
205 STATE ::= '(' STATE-NAME [ STATE-TITLE-TEXT ] BRANCH * ')'
207 STATE-NAME ::= SYMBOL
209 STATE-TITLE-TEXT ::= MTEXT
211 BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
212 | '(' nil BRANCH-ACTION * ')'
213 | '(' t BRANCH-ACTION * ')'
215 STATE-INCLUSION ::= '(' 'include' TAGS 'state' STATE-NAME ? ')'
219 When an input system is never standalone and always included in
220 another system, @c STATE-LIST can be omitted.
222 @c STATE-INCLUSION includes states from another input method specified by @c TAGS.
223 When @c STATE-NAME is not given, all states from the input method are included.
225 The optional @c STATE-TITLE-TEXT specifies a title text displayed on
226 the screen when the input method is in this state. If @c
227 STATE-TITLE-TEXT is omitted, @c TITLE-TEXT is used.
229 In the first form of @c BRANCH, @c MAP-NAME must be an item that
230 appears in @c MAP. In this case, if a key sequence matching one of @c
231 KEYSEQs of @c MAP-NAME is typed, @c BRANCH-ACTIONs are executed.
233 In the second form of @c BRANCH, @c BRANCH-ACTIONs are executed if a
234 key sequence that doesn't match any of @c Branch's of the current
237 If there is no @c BRANCH beginning with @c nil and the typed key
238 sequence does not match any of the current @c BRANCHs, the input
239 method transits to the initial state.
241 In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed when
242 shifted to the current state. If the current state is the initial
243 state, @c BRANCH-ACTIONs are executed also when an input context of
244 the input method is created.
247 BRANCH-ACTION ::= ACTION
250 An input method has the following two lists of symbols.
255 A marker is a symbol indicating a character position in the preediting
256 text. The @c MARK action assigns a position to a marker. The
257 position of a marker is referred by the @c MOVE and the @c DELETE actions.
261 A variable is a symbol associated with an integer value. The value of
262 a variable is set by the @c SET action, and is referred by the @c SET,
263 the @c INSERT, and the @c IF actions. All variables are implicitly
268 Each @c PREDEFINED-SYMBOL has a special meaning when used as a marker.
271 <li> @c @@0, @c @@1, @c @@2, @c @@3, @c @@4, @c @@5, @c @@6, @c @@7, @c @@8, @c @@9
273 The 0th, 1st, 2nd, ... 9th position respectively.
275 <li> @c @@<, @c @@=, @c @@>
277 The first, the current, and the last position.
281 The previous and the next position.
285 The previous and the next position where a candidate list changes.
288 Some of the @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
289 index in the @c SELECT action.
293 <li> @c @@<, @c @@=, @c @@>
295 The first, the current, and the last candidate of the current candidate group.
299 The previous candidate. If the current candidate is the first one in
300 the current candidate group, then it means the last candidate in the
301 previous candidate group.
305 The next candidate. If the current candidate is the last one in the
306 current candidate group, then it means the first candidate in the next
311 The candidate in the previous and the next candidate group having the same
312 candidate index as the current one.
315 And, this also has a special meaning.
320 Number of handled keys at that moment.
324 These are for supporting surround text handling.
329 -1 if surrounding text is supported, -2 if not.
333 Here, @c N is a positive integer. The value is the Nth previous
334 character in the preedit buffer. If there are only M (M<N) previous
335 characters in it, the value is the (N-M)th previous character from the
336 inputting spot. When this is used as the argument of @c delete
337 action, it specifies the number of characters to be deleted.
341 Here, @c N is a positive integer. The value is the Nth following
342 character in the preedit buffer. If there are only M (M<N) following
343 characters in it, the value is the (N-M)th following character from
344 the inputting spot. When this is used as the argument of @c delete
345 action, it specifies the number of characters to be deleted.
348 The arguments and the behavior of each action are listed below.
351 INSERT ::= '(' 'insert' MTEXT ')'
354 | '(' 'insert' SYMBOL ')'
355 | '(' 'insert' '(' CANDIDATES * ')' ')'
356 | '(' CANDIDATES * ')'
358 CANDIDATES ::= MTEXT | '(' MTEXT * ')'
361 The first and second forms insert @c MTEXT before the current position.
363 The third form inserts the character @c INTEGER before the current
366 The fourth form treats @c SYMBOL as a variable, and inserts its value
367 (if it is a valid character code) before the current position.
369 In the fifth and sixth forms, each @c CANDIDATES represents a
370 candidate group, and each element of @c CANDIDATES represents a
371 candidate, i.e. if @c CANDIDATES is an M-text, the candidates are the
372 characters in the M-text; if @c CANDIDATES is a list of M-texts, the
373 candidates are the M-texts in the list.
375 These forms insert the first candidate before the current position.
376 The inserted string is associated with the list of candidates and
377 the information indicating the currently selected candidate.
379 The marker positions affected by the insertion are automatically relocated.
382 DELETE ::= '(' 'delete' SYMBOL ')'
383 | '(' 'delete' INTEGER ')'
386 The first form treats @c SYMBOL as a marker, and deletes characters
387 between the current position and the marker position.
389 The second form treats @c INTEGER as a character position, and deletes
390 characters between the current position and the character position.
392 The marker positions affected by the deletion are automatically relocated.
395 SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
396 | '(' 'select' INTEGER ')'
397 | '(' 'select' SYMBOL ')'
400 This action first checks if the character just before the current position
401 belongs to a string that is associated with a candidate list. If it is,
402 the action replaces that string with a candidate specified by the
405 The first form treats @c PREDEFINED-SYMBOL as a candidate index (as
406 described above) that specifies a new candidate in the candidate list.
408 The second form treats @c INTEGER as a candidate index that specifies a
409 new candidate in the candidate list.
411 In the third form, @c SYMBOL must have a integer value, and it is treated
412 as a candidate index.
414 @verbatim SHOW ::= '(show)' @endverbatim
416 This actions instructs the input method driver to display a candidate
417 list associated with the string before the current position.
423 This action instructs the input method driver to hide the currently
424 displayed candidate list.
427 MOVE ::= '(' 'move' SYMBOL ')'
428 | '(' 'move' INTEGER ')'
431 The first form treats @c SYMBOL as a marker, and makes the marker
432 position be the new current position.
434 The second form treats @c INTEGER as a character position, and makes
435 that position be the new current position.
438 MARK ::= '(' 'mark' SYMBOL ')'
441 This action treats @c SYMBOL as a marker, and sets its position to the
442 current position. @c SYMBOL must not be a @c PREDEFINED-SYMBOL.
445 PUSHBACK :: = '(' 'pushback' INTEGER ')'
446 | '(' 'pushback' KEYSEQ ')'
449 The first form pushes back the latest @c INTEGER number of key events
450 to the event queue if @c INTEGER is positive, and pushes back all key
451 events if @c INTEGER is zero.
453 The second form pushes back keys in @c KEYSEQ to the event queue.
456 POP ::= '(' 'pop' ')'
459 This action pops the first key event that is not yet handled from the
463 UNDO :: = '(' 'undo' [ INTEGER | SYMBOL ] ')'
466 If there's no argument, this action cancels the last two key events
467 (i.e. the one that invoked this command, and the previous one).
469 If there's an integer argument NUM, it must be positive or negative
470 (not zero). If positive, from the NUMth to the last events are
471 canceled. If negative the last (- NUM) events are canceled.
473 If there's a symbol argument, it must be resolved to an integer number
474 and the number is treated as the actual argument as above.
477 COMMIT :: = '(commit)'
480 This action commits the current preedit.
483 UNHANDLE :: = '(unhandle)'
486 This action commits the current preedit and return the last key as
490 SHIFT :: = '(' 'shift' STATE-NAME ')'
493 This action shifts the current state to @c STATE-NAME. @c
494 STATE-NAME must appear in @c STATE-LIST.
497 CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'
499 ARG ::= INTEGER | SYMBOL | MTEXT | PLIST
502 This action calls the function @c FUNCTION of external module @c
503 MODULE-NAME. @c MODULE-NAME and @c FUNCTION must appear in @c
506 The function is called with an argument of the type (#MPlist *). The
507 key of the first element is #Mt and its value is a pointer to an
508 object of the type #MInputContext. The key of the second element is
509 #Msymbol and its value is the current state name. @c ARGs are used as
510 the value of the third and later elements. Their keys are determined
511 automatically; if an @c ARG is an integer, the corresponding key is
512 #Minteger; if an @c ARG is a symbol, the corresponding key is
515 The function must return NULL or a value of the type (#MPlist *) that
516 represents a list of actions to take.
519 SET ::= '(' CMD SYMBOL1 EXPRESSION ')'
521 CMD ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
523 EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERATOR EXPRESSION * ')'
525 OPERATOR ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
526 | '=' | '<' | '>' | '<=' | '>='
530 This action treats @c SYMBOL1 and @c SYMBOL2 as variables and sets the
531 value of @c SYMBOL1 as below.
533 If @c CMD is 'set', it sets the value of @c SYMBOL1 to the value of @c
536 If @c CMD is 'add', it increments the value of @c SYMBOL1 by the value
539 If @c CMD is 'sub', it decrements the value of @c SYMBOL1 by the value
542 If @c CMD is 'mul', it multiplies the value of @c SYMBOL1 by the value
545 If @c CMD is 'div', it divides the value of @c SYMBOL1 by the value of
549 IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ')'
551 CONDITION ::= [ '=' | '<' | '>' | '<=' | '>=' ] EXPRESSION1 EXPRESSION2
553 ACTION-LIST1 ::= '(' ACTION * ')'
555 ACTION-LIST2 ::= '(' ACTION * ')'
558 This action performs actions in @c ACTION-LIST1 if @c CONDITION is
559 true, and performs @c ACTION-LIST2 (if any) otherwise.
561 @c SYMBOL1 and @c SYMBOL2 are treated as variables.
564 COND ::= '(' 'cond' [ '(' EXPRESSION ACTION * ') ] * ')'
567 This action performs the first action @c ACTION whose corresponding
568 @c EXPRESSION has nonzero value.
572 @section im-example1 EXAMPLE 1
574 This is a very simple example for inputting Latin characters with
575 diacritical marks (acute and cedilla). For instance, when you type:
577 Comme'die-Franc,aise, chic,,
582 Commédie-Française, chic,
587 \hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}aise, chic,}
591 The definition of the input method is very simple as below, and it is
592 quite straight forward to extend it to cover all Latin characters.
596 (title "latin-postfix")
599 ("a'" ?á) ("e'" ?é) ("i'" ?í) ("o'" ?ó) ("u'" ?ú) ("c," ?ç)
600 ("A'" ?Á) ("E'" ?É) ("I'" ?Í) ("O'" ?Ó) ("U'" ?Ú) ("C," ?Ç)
601 ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")
603 ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")
612 \texttt{\footnotesize
613 \hskip2mm(title "latin-postfix")\\
616 \hskip6mm ("a'" ?\'{a}) ("e'" ?\'{e}) ("i'" ?\'{i}) ("o'" ?\'{o})
617 ("u'" ?\'{u}) ("c," ?\c{c})\\
618 \hskip6mm ("A'" ?\'{A}) ("E'" ?\'{E}) ("I'" ?\'{I}) ("O'" ?\'{O})
619 ("U'" ?\'{U}) ("C," ?\c{C})\\
620 \hskip6mm ("a''" "a'") ("e''" "e'") ("i''" "i'") ("o''" "o'") ("u''" "u'")\\
621 \hskip6mm ("c,," "c,")\\
622 \hskip6mm ("A''" "A'") ("E''" "E'") ("I''" "I'") ("O''" "O'") ("U''" "U'")\\
623 \hskip6mm ("C,," "C,")))\\
630 @section im-example2 EXAMPLE 2
632 This example is for inputting Unicode characters by typing C-u
633 (Control-u) followed by four hexadecimal digits. For instance, when
634 you type ("^u" means Control-u):
636 ^u2190^u2191^u2192^u2193
638 you will get this (Unicode arrow symbols):
641 $\leftarrow \uparrow \rightarrow \downarrow
650 The definition utilizes @c SET and @c IF commands as below:
657 ("0" ?0) ("1" ?1) ... ("9" ?9) ("a" ?A) ("b" ?B) ... ("f" ?F)))
660 (starter (set code 0) (set count 0) (shift unicode)))
666 (mul code 16) (add code this)
669 ((delete @<) (insert code) (shift init))))))
672 @section im-example3 EXAMPLE 3
674 This example is for inputting Chinese characters by typing PinYin key
677 For instance, when you type:
686 The definition utilizes @c CANDIDATE and @c SELECT commands as below.
687 Note that this is just an example, and it ignores such important key
694 ;; The initial character of Pinyin.
696 ("a") ("b") ... ("h") ("j") ... ("t") ("w") ("x") ("y") ("z"))
698 ;; Big table of Pinyin vs the corresponding Chinese characters.
701 ("bei" ("被北备背悲辈杯倍贝碑" ...))
702 ("hao" ("好号毫豪浩耗皓嚎昊郝" ...))
703 ("jing" ("经京精境警竟静惊景敬" ...))
704 ("ni" ("你呢尼泥逆倪匿拟腻妮" ...))
706 ;; Typing 1, 2, ..., 0 selects the 0th, 1st, ..., 9th candidate.
708 ("1" (select 0)) ("2" (select 1)) ... ("9" (select 8)) ("0" (select 9))))
712 ;; When an initial character of Pinyin is typed, re-handle it in
713 ;; "main" state. Anything else is just produced as is.
714 (starter (show) (pushback 1) (shift main)))
717 ;; When a complete Pinyin sequence is typed, shift to "select" state
718 ;; to allow users to select one from the candidates.
719 (pinyin (shift select))
721 ;; When anything else is typed, produce the current candidate (if
722 ;; any), and re-handle the last input in "init" state.
723 (nil (hide) (shift init)))
726 ;; When a number is typed, select the corresponding canidate,
727 ;; produce it, and shift to "init" state.
728 (choose (hide) (shift init))
730 ;; When anything else is typed, produce the current candidate,
731 ;; and re-handle the last input in "init" state.
732 (nil (hide) (shift init))))
738 \fbox{This example is readable only in the documentation of HTML version.}
745 @section im-seealso SEE ALSO
747 @ref mim-list "Input Methods provided by the m17n database",
748 @ref mdbGeneral "mdbGeneral(5)"
752 Copyright (C) 2003, 2004, 2005
753 National Institute of Advanced Industrial Science and Technology (AIST)
754 Registration Number H15PRO112
756 This file is part of the m17n database; a sub-part of the m17n
759 The m17n library is free software; you can redistribute it and/or
760 modify it under the terms of the GNU Lesser General Public License
761 as published by the Free Software Foundation; either version 2.1 of
762 the License, or (at your option) any later version.
764 The m17n library is distributed in the hope that it will be useful,
765 but WITHOUT ANY WARRANTY; without even the implied warranty of
766 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
767 Lesser General Public License for more details.
769 You should have received a copy of the GNU Lesser General Public
770 License along with the m17n library; if not, write to the Free
771 Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
772 Boston, MA 02110-1301, USA.
775 /* Local Variables: */