Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
mdbIM(5)			 Version 1.5.5			      mdbIM(5)

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.

       o 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.
       o 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.
       o @0, @1, @2, @3, @4, @5, @6, @7, @8, @9
       The 0th,	1st, 2nd, ... 9th position respectively.
       o @<, @=, @>
       The first, the current, and the last position.
       o @-, @+
       The previous and	the next position.
       o @[, @]
       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.
       o @<, @=, @>
       The first, the current, and the last candidate of the current candidate
       group.
       o @-
       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.
       o @+
       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.
       o @[, @]
       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.
       o @@
       Number of handled keys at that moment.
       These are for supporting	surround text handling.
       o @-0
       -1 if surrounding text is supported, -2 if not.
       o @-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.
       o @+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-2009 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>.

				  15 Oct 2009			      mdbIM(5)

NAME | DESCRIPTION | SYNTAX and SEMANTICS | EXAMPLE 1 | EXAMPLE 2 | EXAMPLE 3 | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mdbIM&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help