AlphaWiki/Commands/The [regPrefixChar] command

This file documents the new [regPrefixChar] command as of version 8.2a1d5 of AlphaX.

Introduction

The [regPrefixChar] command lets you define composite bindings involving an infix. For instance, the Embrace package implements complex bindings like ctrl-B 3 S: here B is the prefix, 3 is the infix and S is the suffix (or key combo). Such a binding means that the user has to press the ctrl-B key combo, then press 3 and then press S. The result of this action, as implemented by the the Embrace package, is that the 3 preceding words are enclosed in a pair of square brackets.

The new [regPrefixChar] command lets you specify a regular expression defining the permitted values for the infix.

Synopsis

The syntax of the [regPrefixChar] command is

 
     regPrefixChar -regexp expr ?-prompt str?

The arguments have the following meaning:

the -regexp argument is required. It specifies, by the means of a regular expression expr, the values among which the infix can be chosen. For instance, if we wanted to allow any digit between 0 and 5 and the letters a, b, c, the value of the option would be

 
[0-5abc]

the -prompt argument is optional. It specifies the text of the prompt string written in the status bar as a label for the input field. If it is not specified, the prefix combo (for instance ctrl-B in the preceding example) is used as a default.

Concerning the infix, the following rules apply: in the case digits are allowed by the regular expression, it is possible to enter several digits in a row, that is to say to compose numbers, before the key combo. Otherwise the infix is a single character. For instance, in the example above, the infix could be either a number composed of digits between 0 and 5 (like 1, 20, 54321, etc.) or one of the letters a, b, or c.

Howto

Here is an example to demonstrate how the command works. Say we want to define a complex binding like

 
     ctrl-B infix S

where infix is iether a number or the letter r.

Note that this example makes use of the new [binding] command introduced in version 8.2a1d1 of AlphaX. See the BindingCommand page for more details about it.

The action triggered by the combo is a Tcl proc or a Tcl script. The composite binding is defined with the [binding] command and takes the Tcl script as its last argument. For instance:

 
     binding create -prefix {z 'B'} {"" 'S'} {embrace::toggle "\[" "\]"}]

The ctrl-B prefix combo must be bound to the [regPrefixChar] command (instead of the simple [prefixChar] command used to create composite bindings without an infix):

 
     binding create {z 'B'} {regPrefixChar -regex {[0-9r]}}

The regular expression [0-9r] specifies that the infix can be either a number or the letter r. It could also be written as (\d|r).

Now, when the user presses ctrl-B, AlphaX will be expecting the infix followed by the key combo (the letter S in this example). As soon as the S is entered, AlphaX invokes the proc associated with the binding after appending the infix to the list of arguments. For instance, if the user entered ctrl-B 15 S, the proc would be invoked as

 
     embrace::toggle "\[" "\]" 15

with the result that the 15 preceding words will be enclosed in a pair of brackets.

If the user did not enter any number or character recognized as an infix and pressed ctrl-B S directly then the argument appended to the proc would be empty.

(add your comments here...)