-/* Copyright (C) 2003, 2004
+/* Copyright (C) 2003, 2004, 2005
National Institute of Advanced Industrial Science and Technology (AIST)
Registration Number H15PRO112
See the end for copying conditions. */
@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 ::= TITLE MAP-LIST MACRO-LIST ? MODULE-LIST ? STATE-LIST
+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
-TITLE ::= '(' 'title' MTEXT ')'
@endverbatim
-@c MTEXT is a text displayed on the screen when this input method is
-active.
+@c IM-DECLARATION specifies the language and name of this input
+method.
+
+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 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. 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.
+
+
+@verbatim
+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
-MAP-LIST ::= '(' 'map' MAP * ')'
+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 | SHIFT | CALL
- | SET | IF | '(' MACRO-NAME ')'
+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'
@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 * ')'
+When an input system is never standalone and always included in
+another system, @c STATE-LIST can be omitted.
-STATE ::= '(' STATE-NAME BRANCH * ')'
+@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.
-STATE-NAME ::= SYMBOL
+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.
-BRANCH ::= '(' MAP-NAME BRANCH-ACTION * ')'
- | '(' nil BRANCH-ACTION * ')'
- | '(' t BRANCH-ACTION * ')'
-@endverbatim
-
-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 if we
-shift to the current state after handling all typed keys. If the
-current state is the initial state, @c BRANCH-ACTIONs are executed
-just after an input context of the input method is created.
+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.
@verbatim
BRANCH-ACTION ::= ACTION
<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>
Each @c PREDEFINED-SYMBOL has a special meaning when used as a marker.
<ul>
+<li> @c @@0, @c @@1, @c @@2, @c @@3, @c @@4, @c @@5, @c @@6, @c @@7, @c @@8, @c @@9
+
+The 0th, 1st, 2nd, ... 9th position respectively.
+
<li> @c @@<, @c @@=, @c @@>
The first, the current, and the last position.
The previous and the next position where a candidate list changes.
</ul>
-Each @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
+Some of the @c PREDEFINED-SYMBOL has a special meaning when used as a candidate
index in the @c SELECT action.
<ul>
+
<li> @c @@<, @c @@=, @c @@>
The first, the current, and the last candidate of the current candidate group.
candidate index as the current one.
</ul>
+And, this also has a special meaning.
+
+<ul>
+<li> @c @@@
+
+Number of handled keys at that moment.
+
+</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.
@verbatim
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 ')'
+@endverbatim
+
+The first form pushes back the latest @c INTEGER number of key events
+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 @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 ] ')'
+@endverbatim
+
+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.
@verbatim
-PUSHBACK :: = '(pushback INTEGER)'
+COMMIT :: = '(commit)'
@endverbatim
-This action pushes back the latest key events to the event queue.
+This action commits the current preedit.
@verbatim
-UNDO :: = '(undo)'
+UNHANDLE :: = '(unhandle)'
@endverbatim
-This action cancels the last key event.
+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 * ')'
represents a list of actions to take.
@verbatim
-SET ::= '(' OPERAND SYMBOL1 [ INTEGER | SYMBOL2 ] ')'
+SET ::= '(' CMD SYMBOL1 EXPRESSION ')'
+
+CMD ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
+
+EXPRESSION ::= INTEGER | SYMBOL2 | '(' OPERATOR EXPRESSION * ')'
+
+OPERATOR ::= '+' | '-' | '*' | '/' | '|' | '&' | '!'
+ | '=' | '<' | '>' | '<=' | '>='
-OPERAND ::= 'set' | 'add' | 'sub' | 'mul' | 'div'
@endverbatim
This action treats @c SYMBOL1 and @c SYMBOL2 as variables and sets the
value of @c SYMBOL1 as below.
-If @c OPERAND is 'set', it sets the value of @c SYMBOL1 to @c INTEGER or the
-value of @c SYMBOL2.
+If @c CMD is 'set', it sets the value of @c SYMBOL1 to the value of @c
+EXPRESSION.
-If @c OPERAND is 'add', it increments the value of @c SYMBOL1 by @c INTEGER
-or the value of @c SYMBOL2.
+If @c CMD is 'add', it increments the value of @c SYMBOL1 by the value
+of @c EXPRESSION.
-If @c OPERAND is 'sub', it decrements the value of @c SYMBOL1 by @c INTEGER
-or the value of @c SYMBOL2.
+If @c CMD is 'sub', it decrements the value of @c SYMBOL1 by the value
+of @c EXPRESSION.
-If @c OPERAND is 'mul', it multiplies the value of @c SYMBOL1 by @c INTEGER
-or the value of @c SYMBOL2.
+If @c CMD is 'mul', it multiplies the value of @c SYMBOL1 by the value
+of @c EXPRESSION.
-If @c OPERAND is 'div', it divides the value of @c SYMBOL1 by @c INTEGER or
-the value of @c SYMBOL2.
+If @c CMD is 'div', it divides the value of @c SYMBOL1 by the value of
+@c EXPRESSION.
@verbatim
-IF ::= '(' 'if' CONDITION ACTION-LIST1 ACTION-LIST2 * ')'
+IF ::= '(' CONDITION ACTION-LIST1 ACTION-LIST2 ? ')'
-CONDITION ::= '(' OPERAND VAL1 VAL2 ')'
+CONDITION ::= [ '=' | '<' | '>' | '<=' | '>=' ] EXPRESSION1 EXPRESSION2
ACTION-LIST1 ::= '(' ACTION * ')'
ACTION-LIST2 ::= '(' ACTION * ')'
-
-OPERAND ::= '=' '<' '>'
-
-VAL1 ::= [ INTEGER1 | SYMBOL1 ]
-
-VAL2 ::= [ INTEGER2 | SYMBOL2 ]
@endverbatim
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 action @c ACTION whose corresponding
+@c EXPRESSION has nonzero value.
@ifnot FOR-MAN
This is a very simple example for inputting Latin characters with
diacritical marks (acute and cedilla). For instance, when you type:
@verbatim
- Comme'die-Franc,ais, chic,,
+ Comme'die-Franc,aise, chic,,
@endverbatim
you will get this:
@if FOR-HTML
@verbatim
- Commédie-Français, chic,
+ Commédie-Française, chic,
@endverbatim
@endif
@if FOR-LATEX
@latexonly
-\hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}ais, chic,}
+\hskip5mm\texttt{\footnotesize Comm\'{e}die-Fran\c{c}aise, chic,}
@endlatexonly
@endif
@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
*/
/*
-Copyright (C) 2003, 2004
+Copyright (C) 2003, 2004, 2005
National Institute of Advanced Industrial Science and Technology (AIST)
Registration Number H15PRO112
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