Provided by: m17n-docs_1.6.2-2_all bug

NAME

       mdbIM - Input Method

DESCRIPTION

       The m17n library provides a driver for input methods that are dynamically loadable from
       the m17n database (see m17nInputMethod ).

       This section describes the data format that defines those input methods.

SYNTAX and SEMANTICS

       The following data format defines an input method. The driver loads a definition from a
       file, a stream, etc. The definition is converted into the form of plist in the driver.

       INPUT-METHOD ::=
           IM-DECLARATION ? IM-DESCRIPTION ? TITLE ?
            VARIABLE-LIST ? COMMAND-LIST ?  MODULE-LIST ?
            MACRO-LIST ? MAP-LIST ? STATE-LIST ?

       IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME EXTRA-ID ? VERSION ? ')'
       LANGUAGE ::= SYMBOL
       NAME ::= SYMBOL
       EXTRA-ID ::= SYMBOL
       VERSION ::= '(' 'version' VERSION-NUMBER ')'

       IM-DESCRIPTION ::= '(' 'description' DESCRIPTION ')'
       DESCRIPTION ::= MTEXT-OR-GETTEXT | 'nil'
       MTEXT-OR-GETTEXT ::=  [ MTEXT | '(' '_' MTEXT ')']

       TITLE ::= '(' 'title' TITLE-TEXT ')'
       TITLE-TEXT ::= MTEXT

       VARIABLE-LIST ::= '(' 'variable' VARIABLE-DECLARATION * ')'
       VARIABLE-DECLARATION ::=  '(' VAR-NAME [ DESCRIPTION VALUE VALUE-CANDIDATE * ]')'
       VAR-NAME ::= SYMBOL
       VALUE ::= MTEXT | SYMBOL | INTEGER
       VALUE-CANDIDATE ::= VALUE | '(' RANGE-FROM RANGE-TO ')'
       RANGE-FROM ::= INTEGER
       RANGE-TO ::= INTEGER

       COMMAND-LIST ::= '(' 'command' COMMAND-DECLARATION * ')'
       COMMAND-DECLARATION ::=  '(' CMD-NAME [ DESCRIPTION KEYSEQ * ] ')'
       CMD-NAME ::= SYMBOL

       IM-DECLARATION specifies the language and name of this input method.

       When LANGUAGE is t, the use of the input method is not limited to one language.

       When NAME is nil, the input method is not standalone, but is expected to be used in other
       input methods. In such cases, EXTRA-ID is required to identify the input method.

       VERSION specifies the required minimum version number of the m17n library. The format is
       'XX.YY.ZZ' where XX is a major version number, YY is a minor version number, and ZZ is a
       patch level.

       DESCRIPTION, if not nil, specifies the description text of an input method, a variable or
       a command. If MTEXT-OR-GETTEXT takes the second form, the text is translated according to
       the current locale by 'gettext' (if the translation is provided).

       TITLE-TEXT is a text displayed on the screen when this input method is active.

       There is one special input method file 'global.mim' that declares common variables and
       commands. The input method driver always loads this file and other input methods can
       inherit the variables and the commands.

       VARIABLE-DECLARATION declares a variable used in this input method. If a variable must be
       initialized to the default value, or is to be customized by a user, it must be declared
       here. The declaration can be used in two ways. One is to introduce a new variable. In that
       case, VALUE must not be omitted. Another is to inherit the variable from what declared in
       'global.mim', and to give the different default value and/or to make the variable
       customizable specially for the current input method. In the latter case, VALUE can be
       omitted.

       COMMAND-DECLARATION declares a command used in this input method. If a command must be
       bound to the default key sequence, or is to be customized by a user, it must be declared
       here. Like VARIABLE-DECLARATION, the declaration can be used in two ways. One is to
       introduce a new command. In that case, KEYSEQ must not be omitted. Another is to inherit
       the command from what declared in 'global.mim', and to give the different key binding
       and/or to make the command customizable specially for the current input method. In the
       latter case, KEYSEQ can be omitted.

       MODULE-LIST ::= '(' 'module' MODULE * ')'

       MODULE ::= '(' MODULE-NAME FUNCTION * ')'

       MODULE-NAME ::= SYMBOL

       FUNCTION ::= SYMBOL

       Each MODULE declares the name of an external module (i.e. dynamic library) and function
       names exported by the module. If a FUNCTION has name 'init', it is called with only the
       default arguments (see the section about CALL) when an input context is created for the
       input method. If a FUNCTION has name 'fini', it is called with only the default arguments
       when an input context is destroyed.

       MACRO-LIST ::=  MACRO-INCLUSION ? '(' 'macro' MACRO * ')' MACRO-INCLUSION ?

       MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'

       MACRO-NAME ::= SYMBOL

       MACRO-ACTION ::= ACTION

       TAGS ::= `(` LANGUAGE NAME EXTRA-ID ? `)`

       MACRO-INCLUSION ::= '(' 'include' TAGS 'macro' MACRO-NAME ? ')'

       MACRO-INCLUSION includes macros from another input method specified by TAGS. When
       MACRO-NAME is not given, all macros from the input method are included.

       MAP-LIST ::= MAP-INCLUSION ? '(' 'map' MAP * ')'
       MAP-INCLUSION ?

       MAP ::= '(' MAP-NAME RULE * ')'

       MAP-NAME ::= SYMBOL

       RULE ::= '(' KEYSEQ MAP-ACTION * ')'

       KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'

       MAP-INCLUSION ::= '(' 'include' TAGS 'map' MAP-NAME ? ')'

       When an input method is never standalone and always included in another method, MAP-LIST
       can be omitted.

       SYMBOL in the definitions of MAP-NAME must not be t nor nil.

       MTEXT in the definition of KEYSEQ consists of characters that can be generated by a
       keyboard. Therefore MTEXT usually contains only ASCII characters. However, if the input
       method is intended to be used, for instance, with a West European keyboard, MTEXT may
       contain Latin-1 characters.

       SYMBOL in the definition of KEYSEQ must be the return value of the minput_event_to_key()
       function. Under the X window system, you can quickly check the value using the xev
       command. For example, the return key, the backspace key, and the 0 key on the keypad are
       represented as (Return) , (BackSpace) , and (KP_0) respectively. If the shift, control,
       meta, alt, super, and hyper modifiers are used, they are represented by the S- , C- , M- ,
       A- , s- , and H- prefixes respectively in this order. Thus, 'return with shift with meta
       with hyper' is (S-M-H-Return) . Note that 'a with shift' .. 'z with shift' are represented
       simply as A .. Z . Thus 'a with shift with meta with hyper' is (M-H-A) .

       INTEGER in the definition of KEYSEQ must be a valid character code.

       MAP-INCLUSION includes maps from another input method specified by TAGS. When MAP-NAME is
       not given, all maps from the input method are included.

       MAP-ACTION ::= ACTION

       ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK
                  | SHOW | HIDE | PUSHBACK | POP | UNDO
               | COMMIT | UNHANDLE | SHIFT | CALL
               | SET | IF | COND | '(' MACRO-NAME ')'

       PREDEFINED-SYMBOL ::=
           '@0' | '@1' | '@2' | '@3' | '@4'
           | '@5' | '@6' | '@7' | '@8' | '@9'
           | '@<' | '@=' | '@>' | '@-' | '@+' | '@[' | '@]'
           | '@@'
           | '@-0' | '@-N' | '@+N'

       STATE-LIST ::= STATE-INCUSION ? '(' 'state' STATE * ')'  STATE-INCUSION ?

       STATE ::= '(' STATE-NAME [ STATE-TITLE-TEXT ] BRANCH * ')'

       STATE-NAME ::= SYMBOL

       STATE-TITLE-TEXT ::= MTEXT

       BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
               | '(' 'nil' BRANCH-ACTION * ')'
               | '(' 't' BRANCH-ACTION * ')'

       STATE-INCLUSION ::= '(' 'include' TAGS 'state' STATE-NAME ? ')'

       When an input system is never standalone and always included in another system, STATE-LIST
       can be omitted.

       STATE-INCLUSION includes states from another input method specified by TAGS. When
       STATE-NAME is not given, all states from the input method are included.

       The optional STATE-TITLE-TEXT specifies a title text displayed on the screen when the
       input method is in this state. If STATE-TITLE-TEXT is omitted, TITLE-TEXT is used.

       In the first form of BRANCH, MAP-NAME must be an item that appears in MAP. In this case,
       if a key sequence matching one of KEYSEQs of MAP-NAME is typed, BRANCH-ACTIONs are
       executed.

       In the second form of BRANCH, BRANCH-ACTIONs are executed if a key sequence that doesn't
       match any of Branch's of the current state is typed.

       If there is no BRANCH beginning with nil and the typed key sequence does not match any of
       the current BRANCHs, the input method transits to the initial state.

       In the third form of BRANCH, BRANCH-ACTIONs are executed when shifted to the current
       state. If the current state is the initial state, BRANCH-ACTIONs are executed also when an
       input context of the input method is created.

       BRANCH-ACTION ::= ACTION

       An input method has the following two lists of symbols.

       • marker list
       A marker is a symbol indicating a character position in the preediting text. The MARK
       action assigns a position to a marker. The position of a marker is referred by the MOVE
       and the DELETE actions.
       • variable list
       A variable is a symbol associated with an integer, a symbol, or an M-text value. The
       integer value of a variable can be set and referred by the SET action. It can be referred
       by the SET, the INSERT, the SELECT, the UNDO, the IF, the COND actions. The M-text value
       of a variable can be referred by the INSERT action. The symbol value of a variable can not
       be referred directly, is used the library implicitly (e.g. candidates-charset). All
       variables are implicitly initialized to the integer value zero.
       Each PREDEFINED-SYMBOL has a special meaning when used as a marker.
       • @0, @1, @2, @3, @4, @5, @6, @7, @8, @9
       The 0th, 1st, 2nd, ... 9th position respectively.
       • @<, @=, @>
       The first, the current, and the last position.
       • @-, @+
       The previous and the next position.
       • @[, @]
       The previous and the next position where a candidate list changes.
       Some of the PREDEFINED-SYMBOL has a special meaning when used as a candidate index in the
       SELECT action.
       • @<, @=, @>
       The first, the current, and the last candidate of the current candidate group.
       • @-
       The previous candidate. If the current candidate is the first one in the current candidate
       group, then it means the last candidate in the previous candidate group.
       • @+
       The next candidate. If the current candidate is the last one in the current candidate
       group, then it means the first candidate in the next candidate group.
       • @[, @]
       The candidate in the previous and the next candidate group having the same candidate index
       as the current one.
       And, this also has a special meaning.
       • @@
       Number of handled keys at that moment.
       These are for supporting surround text handling.
       • @-0
       -1 if surrounding text is supported, -2 if not.
       • @-N
       Here, N is a positive integer. The value is the Nth previous character in the preedit
       buffer. If there are only M (M<N) previous characters in it, the value is the (N-M)th
       previous character from the inputting spot. When this is used as the argument of delete
       action, it specifies the number of characters to be deleted.
       • @+N
       Here, N is a positive integer. The value is the Nth following character in the preedit
       buffer. If there are only M (M<N) following characters in it, the value is the (N-M)th
       following character from the inputting spot. When this is used as the argument of delete
       action, it specifies the number of characters to be deleted.
       The arguments and the behavior of each action are listed below.
       INSERT ::= '(' 'insert' MTEXT ')'
                  | MTEXT
               | INTEGER
               | SYMBOL
                  | '(' 'insert' SYMBOL ')'
                  | '(' 'insert' '(' CANDIDATES * ')' ')'
                  | '(' CANDIDATES * ')'

       CANDIDATES ::= MTEXT | '(' MTEXT * ')'
       The first and second forms insert MTEXT before the current position.
       The third form inserts the character INTEGER before the current position.
       The fourth and fith form treats SYMBOL as a variable, and inserts its value (if it is a
       valid character code) before the current position.
       In the sixth and seventh forms, each CANDIDATES represents a candidate group, and each
       element of CANDIDATES represents a candidate, i.e. if CANDIDATES is an M-text, the
       candidates are the characters in the M-text; if CANDIDATES is a list of M-texts, the
       candidates are the M-texts in the list.
       These forms insert the first candidate before the current position. The inserted string is
       associated with the list of candidates and the information indicating the currently
       selected candidate.
       The marker positions affected by the insertion are automatically relocated.
       DELETE ::= '(' 'delete' SYMBOL ')'
                  | '(' 'delete' INTEGER ')'
       The first form treats SYMBOL as a marker, and deletes characters between the current
       position and the marker position.
       The second form treats INTEGER as a character position, and deletes characters between the
       current position and the character position.
       The marker positions affected by the deletion are automatically relocated.
       SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
                  | '(' 'select' INTEGER ')'
               | '(' 'select' SYMBOL ')'
       This action first checks if the character just before the current position belongs to a
       string that is associated with a candidate list. If it is, the action replaces that string
       with a candidate specified by the argument.
       The first form treats PREDEFINED-SYMBOL as a candidate index (as described above) that
       specifies a new candidate in the candidate list.
       The second form treats INTEGER as a candidate index that specifies a new candidate in the
       candidate list.
       In the third form, SYMBOL must have a integer value, and it is treated as a candidate
       index.
       SHOW ::= '(show)' .fi
       This actions instructs the input method driver to display a candidate list associated with the string before the current position.
       HIDE ::= '(hide)'
       This action instructs the input method driver to hide the currently displayed candidate
       list.
       MOVE ::= '(' 'move' SYMBOL ')'
                | '(' 'move' INTEGER ')'
       The first form treats SYMBOL as a marker, and makes the marker position be the new current
       position.
       The second form treats INTEGER as a character position, and makes that position be the new
       current position.
       MARK ::= '(' 'mark' SYMBOL ')'
       This action treats SYMBOL as a marker, and sets its position to the current position.
       SYMBOL must not be a PREDEFINED-SYMBOL.
       PUSHBACK :: = '(' 'pushback' INTEGER ')'
                     | '(' 'pushback' KEYSEQ ')'
       The first form pushes back the latest INTEGER number of key events to the event queue if
       INTEGER is positive, and pushes back all key events if INTEGER is zero.
       The second form pushes back keys in KEYSEQ to the event queue.
       POP ::= '(' 'pop' ')'
       This action pops the first key event that is not yet handled from the event queue.
       UNDO :: = '(' 'undo' [ INTEGER | SYMBOL ] ')'
       If there's no argument, this action cancels the last two key events (i.e. the one that
       invoked this command, and the previous one).
       If there's an integer argument NUM, it must be positive or negative (not zero). If
       positive, from the NUMth to the last events are canceled. If negative, the last (- NUM)
       events are canceled.
       If there's a symbol argument, it must be resolved to an integer number and the number is
       treated as the actual argument as above.
       COMMIT :: = '(commit)'
       This action commits the current preedit.
       UNHANDLE :: = '(unhandle)'
       This action commits the current preedit and returns the last key as unhandled.
       SHIFT :: = '(' 'shift' STATE-NAME ')'
       If STATE-NAME is t, this action shifts the current state to the previous one, otherwise it
       shifts to STATE-NAME. In the latter case, STATE-NAME must appear in STATE-LIST.
       CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'

       ARG ::= INTEGER | SYMBOL | MTEXT | PLIST
       This action calls the function FUNCTION of external module MODULE-NAME. MODULE-NAME and
       FUNCTION must appear in MODULE-LIST.
       The function is called with an argument of the type (MPlist *). The key of the first
       element is Mt and its value is a pointer to an object of the type MInputContext. The key
       of the second element is Msymbol and its value is the current state name. ARGs are used as
       the value of the third and later elements. Their keys are determined automatically; if an
       ARG is an integer, the corresponding key is Minteger; if an ARG is a symbol, the
       corresponding key is Msymbol, etc.
       The function must return NULL or a value of the type (MPlist *) that represents a list of
       actions to take.
       SET ::= '(' CMD SYMBOL1 EXPRESSION ')'

       CMD ::= 'set' | 'add' | 'sub' | 'mul' | 'div'

       EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERATOR EXPRESSION * ')'

       OPERATOR ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
                   | '=' | '<' | '>' | '<=' | '>='

       This action treats SYMBOL1 and SYMBOL2 as variables and sets the value of SYMBOL1 as
       below.
       If CMD is 'set', it sets the value of SYMBOL1 to the value of EXPRESSION.
       If CMD is 'add', it increments the value of SYMBOL1 by the value of EXPRESSION.
       If CMD is 'sub', it decrements the value of SYMBOL1 by the value of EXPRESSION.
       If CMD is 'mul', it multiplies the value of SYMBOL1 by the value of EXPRESSION.
       If CMD is 'div', it divides the value of SYMBOL1 by the value of EXPRESSION.
       IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ? ')'

       CONDITION ::= [ '=' | '<' | '>' | '<=' | '>=' ] EXPRESSION1 EXPRESSION2

       ACTION-LIST1 ::= '(' ACTION * ')'

       ACTION-LIST2 ::= '(' ACTION * ')'
       This action performs actions in ACTION-LIST1 if CONDITION is true, and performs
       ACTION-LIST2 (if any) otherwise.
       COND ::= '(' 'cond' [ '(' EXPRESSION ACTION * ') ] * ')'
       This action performs the first action ACTION whose corresponding EXPRESSION has nonzero
       value.

EXAMPLE 1

       This is a very simple example for inputting Latin characters with diacritical marks (acute
       and cedilla). For instance, when you type:
           Comme'die-Franc,aise, chic,,

       you will get this:
       The definition of the input method is very simple as below, and it is quite straight
       forward to extend it to cover all Latin characters.

EXAMPLE 2

       This example is for inputting Unicode characters by typing C-u (Control-u) followed by
       four hexadecimal digits. For instance, when you type ('^u' means Control-u):
           ^u2190^u2191^u2192^u2193

       you will get this (Unicode arrow symbols):
       The definition utilizes SET and IF commands as below:
       (title "UNICODE")
       (map
        (starter
         ((C-U) "U+"))
        (hex
         ("0" ?0) ("1" ?1) ... ("9" ?9) ("a" ?A) ("b" ?B) ... ("f" ?F)))
       (state
        (init
         (starter (set code 0) (set count 0) (shift unicode)))
        (unicode
         (hex (set this @-)
              (< this ?A
              ((sub this 48))
              ((sub this 55)))
              (mul code 16) (add code this)
              (add count 1)
              (= count 4
              ((delete @<) (insert code) (shift init))))))

EXAMPLE 3

       This example is for inputting Chinese characters by typing PinYin key sequence.

SEE ALSO

       Input Methods provided by the m17n database, mdbGeneral(5)

COPYRIGHT

       Copyright (C) 2001 Information-technology Promotion Agency (IPA)
       Copyright (C) 2001-2011 National Institute of Advanced Industrial Science and Technology
       (AIST)
       Permission is granted to copy, distribute and/or modify this document under the terms of
       the GNU Free Documentation License <http://www.gnu.org/licenses/fdl.html>.