@section im-format SYNTAX and SEMANTICS
-The following data format defines an input method. The driver loads
-a definition from a file, a stream, etc. A definitions is converted
+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.
@verbatim
INPUT-METHOD ::=
- IM-DECLARATION ? DESCRIPTION ? VARIABLE-LIST ? COMMAND-LIST ?
- TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
+ IM-DECLARATION ? IM-DESCRIPTION ? TITLE ?
+ VARIABLE-LIST ? COMMAND-LIST ? MODULE-LIST ?
+ MACRO-LIST ? MAP-LIST ? STATE-LIST ?
-IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME ')'
-DESCRIPTION ::= '(' 'description' MTEXT ')'
-VARIABLE-LIST ::= '(' 'variable' VARIABLE-DECLARATION * ')'
-COMMAND-LIST ::= '(' 'command' COMMAND-DECLARATION * ')'
-TITLE ::= '(' 'title' TITLE-TEXT ')'
+IM-DECLARATION ::= '(' 'input-method' LANGUAGE NAME EXTRA-ID ? VERSION ? ')'
+LANGUAGE ::= SYMBOL
+NAME ::= SYMBOL
+EXTRA-ID ::= SYMBOL
+VERSION ::= '(' 'version' VERSION-NUMBER ')'
-VARIABLE-DECLARATION ::=
- '(' VAR-NAME [ VAR-DESCRIPTION | nil ] VALUE VALUE-CANDIDATE * ')'
+IM-DESCRIPTION ::= '(' 'description' DESCRIPTION ')'
+DESCRIPTION ::= MTEXT-OR-GETTEXT | 'nil'
+MTEXT-OR-GETTEXT ::= [ MTEXT | '(' '_' MTEXT ')']
-COMMAND-DECLARATION ::=
- '(' CMD-NAME [ CMD-DESCRIPTION | nil ] KEYSEQ * ')'
+TITLE ::= '(' 'title' TITLE-TEXT ')'
+TITLE-TEXT ::= MTEXT
-LANGUAGE ::= SYMBOL
-NAME ::= SYMBOL
-IM-DESCRIPTION ::= MTEXT
+VARIABLE-LIST ::= '(' 'variable' VARIABLE-DECLARATION * ')'
+VARIABLE-DECLARATION ::= '(' VAR-NAME [ DESCRIPTION VALUE VALUE-CANDIDATE * ]')'
VAR-NAME ::= SYMBOL
-VAR-DESCRIPTION ::= MTEXT
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
-CMD-DESCRIPTION ::= MTEXT
-TITLE-TEXT ::= MTEXT
+
@endverbatim
@c IM-DECLARATION specifies the language and name of this input
-method.
+method.
-@c DESCRIPTION specifies the description text of this input method by
-MTEXT.
+When @c LANGUAGE is @c t, the use of the input method is not limited
+to one language.
+
+When @c NAME is @c nil, the input method is not standalone, but
+is expected to be used in other input methods. In such cases,
+@c EXTRA-ID is required to identify the input method.
+
+@c 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.
+
+@c DESCRIPTION, if not nil, specifies the description text of an input
+method, a variable or a command. If @c MTEXT-OR-GETTEXT takes the
+second form, the text is translated according to the current locale by
+"gettext" (if the translation is provided).
+
+@c 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.
@c VARIABLE-DECLARATION declares a variable used in this input method.
-If a variable must be initialized from the default value, or is to be
-customized by a user, it must be declared here.
+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, @c 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, @c VALUE can be omitted.
@c 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.
+customized by a user, it must be declared here. Like @c
+VARIABLE-DECLARATION, the declaration can be used in two ways. One is
+to introduce a new command. In that case, @c 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, @c KEYSEQ can be omitted.
-@c TITLE-TEXT is a text displayed on the screen when this input method
-is active.
@verbatim
-MAP-LIST ::= '(' 'map' MAP * ')'
+MODULE-LIST ::= '(' 'module' MODULE * ')'
+
+MODULE ::= '(' MODULE-NAME FUNCTION * ')'
+
+MODULE-NAME ::= SYMBOL
+
+FUNCTION ::= SYMBOL
+@endverbatim
+
+Each @c MODULE declares the name of an external module (i.e. dynamic
+library) and function names exported by the module. If a @c FUNCTION has
+name "init", it is called with only the default arguments (see the
+section about @c CALL) when an input context is created for the input
+method. If a @c FUNCTION has name "fini", it is called with only the
+default arguments when an input context is destroyed.
+
+@verbatim
+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 ? ')'
+
+@endverbatim
+
+@c MACRO-INCLUSION includes macros from another input method specified
+by @c TAGS. When @c MACRO-NAME is not given, all macros from the
+input method are included.
+
+@verbatim MAP-LIST ::= MAP-INCLUSION ? '(' 'map' MAP * ')'
+MAP-INCLUSION ?
MAP ::= '(' MAP-NAME RULE * ')'
RULE ::= '(' KEYSEQ MAP-ACTION * ')'
KEYSEQ ::= MTEXT | '(' [ SYMBOL | INTEGER ] * ')'
+
+MAP-INCLUSION ::= '(' 'include' TAGS 'map' MAP-NAME ? ')'
+
@endverbatim
+When an input method is never standalone and always included in
+another method, @c MAP-LIST can be omitted.
+
@c SYMBOL in the definitions of @c MAP-NAME must not be @c t nor @c
nil.
contain Latin-1 characters.
@c SYMBOL in the definition of @c KEYSEQ must be the return value of
-the minput_event_to_key () function.
+the minput_event_to_key () function. Under the X window system, you
+can quickly check the value using the @c xev command. For example,
+the return key, the backspace key, and the 0 key on the keypad are
+represented as @c (Return) , @c (BackSpace) , and @c (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 @c (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 @c (M-H-A) .
@c INTEGER in the definition of @c KEYSEQ must be a valid character
code.
+@c MAP-INCLUSION includes maps from another input method specified by
+@c TAGS. When @c MAP-NAME is not given, all maps from the input method
+are included.
+
+
@verbatim
MAP-ACTION ::= ACTION
ACTION ::= INSERT | DELETE | SELECT | MOVE | MARK
- | SHOW | HIDE | PUSHBACK | UNDO | UNHANDLE | SHIFT | CALL
+ | 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'
@endverbatim
+
@verbatim
-MACRO-LIST ::= '(' 'macro' MACRO * ')'
+STATE-LIST ::= STATE-INCUSION ? '(' 'state' STATE * ')' STATE-INCUSION ?
-MACRO ::= '(' MACRO-NAME MACRO-ACTION * ')'
+STATE ::= '(' STATE-NAME [ STATE-TITLE-TEXT ] BRANCH * ')'
-MACRO-NAME ::= SYMBOL
+STATE-NAME ::= SYMBOL
-MACRO-ACTION ::= ACTION
-@endverbatim
-@verbatim
-MODULE-LIST ::= '(' 'module' MODULE * ')'
+STATE-TITLE-TEXT ::= MTEXT
-MODULE ::= '(' MODULE-NAME FUNCTION * ')'
+BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
+ | '(' 'nil' BRANCH-ACTION * ')'
+ | '(' 't' BRANCH-ACTION * ')'
-MODULE-NAME ::= SYMBOL
+STATE-INCLUSION ::= '(' 'include' TAGS 'state' STATE-NAME ? ')'
-FUNCTION ::= SYMBOL
@endverbatim
-Each @c MODULE declares the name of external module (i.e. dynamic
-library) and function names exported by the module. If a @c FUNCTION has
-name "init", it is called with only the default arguments (see the
-section about @c CALL) when an input context is created for the input
-method. If a @c FUNCTION has name "fini", it is called with only the
-default arguments when an input context is destroyed.
-
-@verbatim
-STATE-LIST ::= '(' 'state' STATE * ')'
-
-STATE ::= '(' STATE-NAME BRANCH * ')'
+When an input system is never standalone and always included in
+another system, @c STATE-LIST can be omitted.
-STATE-NAME ::= SYMBOL
+@c STATE-INCLUSION includes states from another input method specified
+by @c TAGS. When @c STATE-NAME is not given, all states from the input
+method are included.
-BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
- | '(' nil BRANCH-ACTION * ')'
- | '(' t BRANCH-ACTION * ')'
-@endverbatim
+The optional @c STATE-TITLE-TEXT specifies a title text displayed on
+the screen when the input method is in this state. If @c
+STATE-TITLE-TEXT is omitted, @c TITLE-TEXT is used.
-In the first form of @c BRANCH, @c MAP-NAME must be an item that appears
-in @c MAP. In this case, if a key sequence matching one of @c
+In the first form of @c BRANCH, @c MAP-NAME must be an item that
+appears in @c MAP. In this case, if a key sequence matching one of @c
KEYSEQs of @c MAP-NAME is typed, @c BRANCH-ACTIONs are executed.
In the second form of @c BRANCH, @c BRANCH-ACTIONs are executed if a
key sequence that doesn't match any of @c Branch's of the current
state is typed.
-In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed when we
-shift to the current state. If the current state is the initial
+If there is no @c BRANCH beginning with @c nil and the typed key
+sequence does not match any of the current @c BRANCHs, the input
+method transits to the initial state.
+
+In the third form of @c BRANCH, @c BRANCH-ACTIONs are executed when
+shifted to the current state. If the current state is the initial
state, @c BRANCH-ACTIONs are executed also when an input context of
the input method is created.
<li> variable list
-A variable is a symbol associated with an integer value. The value of
-a variable is set by the @c SET action, and is referred by the @c SET,
-the @c INSERT, and the @c IF actions. All variables are implicitly
-initialized to zero.
+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 @c SET action. It can be referred by the @c SET, the @c
+INSERT, the @c SELECT, the @c UNDO, the @c IF, the @c COND actions.
+The M-text value of a variable can be referred by the @c 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.
</ul>
Number of handled keys at that moment.
-</ulL
+</ul>
+
+These are for supporting surround text handling.
+
+<ul>
+<li> @c @@-0
+
+-1 if surrounding text is supported, -2 if not.
+
+<li> @c @@-N
+
+Here, @c 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 @c delete
+action, it specifies the number of characters to be deleted.
+
+<li> @c @@+N
+
+Here, @c 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 @c delete
+action, it specifies the number of characters to be deleted.
+</ul>
The arguments and the behavior of each action are listed below.
INSERT ::= '(' 'insert' MTEXT ')'
| MTEXT
| INTEGER
+ | SYMBOL
| '(' 'insert' SYMBOL ')'
| '(' 'insert' '(' CANDIDATES * ')' ')'
| '(' CANDIDATES * ')'
The third form inserts the character @c INTEGER before the current
position.
-The fourth form treats @c SYMBOL as a variable, and inserts its value
-(if it is a valid character code) before the current position.
+The fourth and fith form treats @c 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 @c CANDIDATES represents a
+In the sixth and seventh forms, each @c CANDIDATES represents a
candidate group, and each element of @c CANDIDATES represents a
candidate, i.e. if @c CANDIDATES is an M-text, the candidates are the
characters in the M-text; if @c CANDIDATES is a list of M-texts, the
@verbatim
SELECT ::= '(' 'select' PREDEFINED-SYMBOL ')'
| '(' 'select' INTEGER ')'
+ | '(' 'select' SYMBOL ')'
@endverbatim
This action first checks if the character just before the current position
The second form treats @c INTEGER as a candidate index that specifies a
new candidate in the candidate list.
-@verbatim
-SHOW ::= '(show)'
-@endverbatim
+In the third form, @c SYMBOL must have a integer value, and it is treated
+as a candidate index.
+
+@verbatim SHOW ::= '(show)' @endverbatim
This actions instructs the input method driver to display a candidate
list associated with the string before the current position.
This action treats @c SYMBOL as a marker, and sets its position to the
current position. @c SYMBOL must not be a @c PREDEFINED-SYMBOL.
-
@verbatim
PUSHBACK :: = '(' 'pushback' INTEGER ')'
| '(' 'pushback' KEYSEQ ')'
to the event queue if @c INTEGER is positive, and pushes back all key
events if @c INTEGER is zero.
-The second form pushes back keys in KEYSEQ to the event queue.
+The second form pushes back keys in @c KEYSEQ to the event queue.
+
+@verbatim
+POP ::= '(' 'pop' ')'
+@endverbatim
+
+This action pops the first key event that is not yet handled from the
+event queue.
@verbatim
UNDO :: = '(' 'undo' [ INTEGER | SYMBOL ] ')'
(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, the NUMth event to the last one are
-cancelled. If negative the last (- NUM) events are cancelled.
+(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.
@verbatim
+COMMIT :: = '(commit)'
+@endverbatim
+
+This action commits the current preedit.
+
+@verbatim
UNHANDLE :: = '(unhandle)'
@endverbatim
-This action commit the current preedit and return the last key as
+This action commits the current preedit and returns the last key as
unhandled.
@verbatim
SHIFT :: = '(' 'shift' STATE-NAME ')'
@endverbatim
-This action shifts the current state to @c STATE-NAME. @c
-STATE-NAME must appear in @c STATE-LIST.
+If @c STATE-NAME is @c t, this action shifts the current state to the
+previous one, otherwise it shifts to @c STATE-NAME. In the latter
+case, @c STATE-NAME must appear in @c STATE-LIST.
@verbatim
CALL ::= '(' 'call' MODULE-NAME FUNCTION ARG * ')'
CMD ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
-EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERAND EXPRESSION * ')'
+EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERATOR EXPRESSION * ')'
-OPERAND ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
+OPERATOR ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
| '=' | '<' | '>' | '<=' | '>='
@endverbatim
@c EXPRESSION.
@verbatim
-IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ')'
+IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ? ')'
CONDITION ::= [ '=' | '<' | '>' | '<=' | '>=' ] EXPRESSION1 EXPRESSION2
This action performs actions in @c ACTION-LIST1 if @c CONDITION is
true, and performs @c ACTION-LIST2 (if any) otherwise.
-@c SYMBOL1 and @c SYMBOL2 are treated as variables.
-
@verbatim
COND ::= '(' 'cond' [ '(' EXPRESSION ACTION * ') ] * ')'
@endverbatim
-This action performs the first actions @c ACTION whose corresponding
+This action performs the first action @c ACTION whose corresponding
@c EXPRESSION has nonzero value.
@ifnot FOR-MAN
@section im-example2 EXAMPLE 2
This example is for inputting Unicode characters by typing C-u
-(Control-u) followed by four hexadecimal numbers. For instance, when
+(Control-u) followed by four hexadecimal digits. For instance, when
you type ("^u" means Control-u):
@verbatim
^u2190^u2191^u2192^u2193
@endverbatim
you will get this (Unicode arrow symbols):
+@if FOR-LATEX
+@verbatim
+ $\leftarrow \uparrow \rightarrow \downarrow
+@endverbatim
+@endif
+@if FOR-HTML
@verbatim
←↑→↓
@endverbatim
+@endif
The definition utilizes @c SET and @c IF commands as below:
@verbatim
You should have received a copy of the GNU Lesser General Public
License along with the m17n library; if not, write to the Free
-Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307, USA.
+Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+Boston, MA 02110-1301, USA.
*/
/* Local Variables: */
projects / m17n / m17n-db.git / blobdiff