Using Stores
Stores provide a facility to match a character against an array of characters. This means they can be used to reduce multiple rules down into a single rule. They can also be used to give mnemonic names to strings.
The most common use of stores is to reduce the number of rules required in a keyboard by matching multiple characters rather than a single character in a rule.
Creating stores
Stores are created with the store()
statement:
store(storeName) storeContents
Where storeName
is an identifier you give to the store, and storeContents
is the store's contents,
expressed as a string or a sequence of Unicode character constants.
All stores must be given unique identifiers, and are visible throughout the keyboard file. A store()
statement can be placed anywhere
in a keyboard source file, and its visibility is unaffected: it can even be placed after references to the store in other statements.
Apart from characters, two other elements are allowed in stores: deadkeys and virtual keys.
Stores have a maximum length of 4095 characters (note that non-character elements such as virtual keys and deadkeys take more than one character in the store).
Examples
store(vowels) 'aeiouAEIOU'
store(vowels_lower) 'ae' U+0069 U+006F U+0075
store(φωνήεντα) 'αειου'
store(vowel_keys) [K_A] [K_E] [K_I] [K_O] [K_U]
Using stores in rules
Stores are most often used with the any()
and index()
statements. The any()
statement is used in the
context or key section of the rule, and will match any character in the specified store, remembering its index.
any(storeName) + ... > ...
... + any(storeName) > ...
The index()
statement is used to look up a character in a store at the index where a specified any()
statement matched
a character. The any()
statement used to obtain the index is referenced by its character position in the context (and key) part of the rule.
In the first example line, the any()
statement is the first element (character or statement) in the rule, so the offset is 1. In
the second example line, if the three dots represent one single character or statement, the any()
is the second element of the
rule so the offset is 2. Since the context part of a rule can contain several characters or statements, the offset for the any()
could be greater than two.
index(storeName, offset)
Note that an index()
statement may reference an any()
statement which uses a
different store: the only requirement is that the stores used by each have the same length.
Examples
In the following example, the index()
statement
translates the lower case vowels to upper case vowels:
store(lowercase) "aeiou"
store(uppercase) "AEIOU"
+ any(lowercase) > index(uppercase, 1) c translate vowels to upper case
A more useful example shows how a vowel followed by a circumflex can be translated automatically into the combined character:
store(vowel) 'aeiouAEIOU'
store(vowel_circum) 'âêîôûÂÊÎÔÛ'
any(vowel) + '^' > index(vowel_circum, 1)
If we wanted to type the circumflex before the vowel, the code would be: (note the offset in the index statement is 2, not 1)
store(vowel) 'aeiouAEIOU'
store(vowel_circum) 'âêîôûÂÊÎÔÛ'
'^' + any(vowel) > index(vowel_circum, 2)
Another example of using any()
and index()
is given in the
keyboard design tutorial.
Outputting stores
The outs()
statement can be used to output the contents of a store. This can be used
in another store, or in the context or output of a rule.
outs(storeName)
Stores that contain only a single character are usually used to define named constants.
Examples
The following examples show the outs()
statement and an example of named constants:
store(vowels_lower) 'aeiou'
store(vowels_upper) 'AEIOU'
store(vowels) outs(vowels_lower) outs(vowels_upper)
store(vowel_a) 'a'
store(vowel_alpha) 'α'
+ outs(vowel_a) > outs(vowel_alpha)
+ $vowel_a > $vowel_alpha
The IPAMenu.kmn sample keyboard included with Keyman Developer gives an example of the use of stores
and outs()
to create a menu-based keyboard for entry of characters from the International Phonetic Alphabet.
System stores
System stores are stores with a name beginning with &
, which have a special purpose, usually defining properties or
behaviour of the keyboard.
Keyman 5.0 introduced the concept of system stores that replace the header statements used in earlier versions of Keyman. In Keyman 9.0
and later, system stores are also used to reflect and update system state. System stores are prefixed with an ampersand (&
).
Example
This shows the &name
store in use:
store(&name) "My First Keyboard"
IMX definition stores
Stores can be used to define an IMX interface function to be used with call()
. These stores should
not then be used for any other purpose.
Example
store(DLLFunction) "myimx.dll:KeyEvent"
+ any(key) > call(DLLFunction)
Variable stores
store(DLLFunction) "myimx.dll:KeyEvent"
+ any(key) > call(DLLFunction)
In Keyman 8.0 and later versions, variable stores are supported. These allow a keyboard to have a store which is updated dynamically while the keyboard is active, in order to track state. The store value can be persisted for use in future sessions, or can be updated just for the current session.
For Keyman 9.0, support was also added for variable system stores. Some variable system stores are read-only and some are read-write. These allow the keyboard developer to test or adjust the system configuration, including swapping touch layout layers and testing the platform the keyboard is running under.
Variable stores are sometimes called option stores, and the feature has been known in the past as "keyboard options".
store(opt_composed) '0'
store(vowel) 'aeiouAEIOU'
store(vowel_circum) 'âêîôûÂÊÎÔÛ'
+ [CTRL ALT K_1] > set(opt_composed='1')
+ [CTRL ALT K_0] > set(opt_composed='0')
if(opt_composed = '0') any(vowel) + '^' > index(vowel, 2) U+0302
if(opt_composed = '1') any(vowel) + '^' > index(vowel_circum, 2)
More information about variable stores is available in the variable stores guide.
Store statements
The following statements are used with stores:
any()
statement- Matches on an array of characters
call()
statement- Calls an Input Method Extension
if()
statement- Tests the content of a variable store
index()
statement- Outputs from an array of characters
outs()
statement- Outputs an array of characters
reset()
statement- Resets the content of a variable store to the default
save()
statement- Persists the content of a variable store
set()
statement- Updates the content of a variable store
store()
statement- Defines an array of characters
- Introduced in Keyman 3.0
- Keyman 5.0 added system stores
- Keyman 6.0 added support for deadkeys and virtual keys in stores
- Keyman 7.0 extended maximum store length to 4095 characters
- Keyman 8.0 introduced variable stores
- Keyman 9.0 introduced variable system stores