Provided by: m17n-docs_1.5.0-1_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 ? DESCRIPTION ? VARIABLE-LIST ? COMMAND-LIST ?
           TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST

       IM-DECLARATION ::= ’(’ ’input-method’ LANGUAGE NAME [ ’(version’
       VERSION ’)’] ’)’ DESCRIPTION ::= ’(’ ’description’ [ MTEXT-OR-GETTEXT |
       nil] ’)’ VARIABLE-LIST ::= ’(’ ’variable’ VARIABLE-DECLARATION * ’)’
       COMMAND-LIST ::= ’(’ ’command’ COMMAND-DECLARATION * ’)’ TITLE ::= ’(’
       ’title’ TITLE-TEXT ’)’

       VARIABLE-DECLARATION ::=
           ’(’ VAR-NAME [ MTEXT-OR-GETTEXT | nil ] VALUE VALUE-CANDIDATE * ’)’

       COMMAND-DECLARATION ::=
           ’(’ CMD-NAME [ MTEXT-OR-GETTEXT | nil ] KEYSEQ * ’)’

       MTEXT-OR-GETTEXT ::=
           [ MTEXT | ’(’ ’_’ MTEXT ’)’]

       LANGUAGE ::= SYMBOL NAME ::= SYMBOL VERSION ::= MTEXT IM-DESCRIPTION
       ::= MTEXT VAR-NAME ::= SYMBOL VAR-DESCRIPTION ::= MTEXT VALUE ::= MTEXT
       | SYMBOL | INTEGER VALUE-CANDIDATE ::= VALUE | ’(’ RANGE-FROM RANGE-TO
       ’)’ RANGE-FROM ::= INTEGER RANGE-TO ::= INTEGER CMD-NAME ::= SYMBOL
       CMD-DESCRIPTION ::= MTEXT TITLE-TEXT ::= MTEXT

       IM-DECLARATION specifies the language and name of this 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 specifies the description text of this input method by
       MTEXT-OR-GETTEXT. It it takes the second form, the text is translated
       according to the current locale by ’gettext’ (if the translation is
       provided).

       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.

       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.

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

       MAP-LIST ::= ’(’ ’map’ MAP * ’)’

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

       MAP-NAME ::= SYMBOL

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

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

       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 oreder. 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-ACTION ::= ACTION

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

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

       MACRO-LIST ::= ’(’ ’macro’ MACRO * ’)’

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

       MACRO-NAME ::= SYMBOL

       MACRO-ACTION ::= ACTION

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

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

       MODULE-NAME ::= SYMBOL

       FUNCTION ::= SYMBOL

       Each MODULE declares the name of 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.

       STATE-LIST ::= ’(’ ’state’ STATE * ’)’

       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 * ’)’

       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.

       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 value. The
              value of a variable is set by the SET action, and is referred by
              the SET, the INSERT, and the IF actions. All variables are
              implicitly initialized to 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
                  | ’(’ ’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 form treats SYMBOL as a variable, and inserts its value (if
       it is a valid character code) before the current position.
       In the fifth and sixth 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 ’)’
       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.

       SHOW ::= ’(show)’
       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.

       UNHANDLE :: = ’(unhandle)’
       This action commit the current preedit and return the last key as
       unhandled.

       SHIFT :: = ’(’ ’shift’ STATE-NAME ’)’
       This action shifts the current state to STATE-NAME. 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 | ’(’ OPERAND EXPRESSION * ’)’

       OPERAND ::= ’+’ | ’-’ | ’*’ | ’/’ | ’|’ | ’&’ | ’!’
                   | ’=’ | ’<’ | ’>’ | ’<=’ | ’>=’

       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.
       SYMBOL1 and SYMBOL2 are treated as variables.

       COND ::= ’(’ ’cond’ [ ’(’ EXPRESSION ACTION * ’) ] * ’)’
       This action performs the first action ACTION whose corresponding
       EXPRESSION has nonzero value.
       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)

                                  28 Dec 2007                         mdbIM(5)