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.

SYNTAXandSEMANTICS

The following data format defines an input method. The driver loads a
definition from a file, a stream, etc. A definitions is converted into
the form of plist in the driver.
INPUT-METHOD ::= TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
TITLE ::= ’(’ ’title’ MTEXT ’)’
MTEXT 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.
INTEGER in the definition of KEYSEQ must be a valid character code.
MAP-ACTION ::= ACTION
ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK |
| SHOW | HIDE | PUSHBACK | UNDO | SHIFT | CALL | SET
| IF | ’(’ MACRO-NAME ’)’
PREDEFINED-SYMBOL ::=
’@0’ | ’@1’ | ’@2’ | ’@3’ | ’@4’ |
’@5’ | ’@6’ | ’@7’ | ’@8’ | ’@9’ |
’@<’ | ’@=’ | ’@>’ | ’@-’ | ’@+’ | ’@[’ | ’@]’
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 BRANCH * ’)’
STATE-NAME ::= SYMBOL
BRANCH ::= ’(’ MAP-NAME BRANCH-ACTION * ’)’ | ’(’ nil BRANCH-
ACTION * ’)’ | ’(’ t BRANCH-ACTION * ’)’
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 if we shift to
the current state after handling all typed keys. If the current state
is the initial state, BRANCH-ACTIONs are executed just after 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.
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)’
This action pushes back the latest INTEGER number of key events to the
event queue.
UNDO :: = ’(undo)’
This action cancels the last key event.
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 ::= ’(’ OPERAND SYMBOL1 [ INTEGER | SYMBOL2 ] ’)’
OPERAND ::= ’set’ | ’add’ | ’sub’ | ’mul’ | ’div’
This action treats SYMBOL1 and SYMBOL2 as variables and sets the value
of SYMBOL1 as below.
If OPERAND is ’set’, it sets the value of SYMBOL1 to INTEGER or the
value of SYMBOL2.
If OPERAND is ’add’, it increments the value of SYMBOL1 by INTEGER or
the value of SYMBOL2.
If OPERAND is ’sub’, it decrements the value of SYMBOL1 by INTEGER or
the value of SYMBOL2.
If OPERAND is ’mul’, it multiplies the value of SYMBOL1 by INTEGER or
the value of SYMBOL2.
If OPERAND is ’div’, it divides the value of SYMBOL1 by INTEGER or the
value of SYMBOL2.
IF ::= ’(’ CONDITION ACTION-LIST1 ACTION-LIST2 * ’)’
CONDITION ::= OPERAND VAL1 VAL2
ACTION-LIST1 ::= ’(’ ACTION * ’)’
ACTION-LIST2 ::= ’(’ ACTION * ’)’
OPERAND ::= ’=’ ’<’ ’>’
VAL1 ::= [ INTEGER1 | SYMBOL1 ]
VAL2 ::= [ INTEGER2 | SYMBOL2 ]
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.