Message-ID: <49D211D2.5000203@bcs.org.uk> Date: Tue, 31 Mar 2009 13:51:30 +0100 From: Peter Knaggs Newsgroups: comp.lang.forth Subject: RfD: KEY/EKEY 20090331 Original Text Problem ======= The document currently refers to a character. According to the definition (3.1.2), a character may vary in size. This leads to confusion a modern environment where a character may consist of several keyboard events. This relates particular to the relationship between KEY and EKEY. The rationale for EKEY allows for the word to return an "event record" but defines the signature of ( -- u ). This should be changed to ( -- x ) in order to allow EKEY to return the address of the "event record". The rationale for EKEY currently allows this, but the document does not. Solution ======== Redefine a character (3.1.2) to insist that a character is of a fixed with, and unsigned. This will resolve a number of issues within the document. Especially with the FILE and FACILITY word sets. Correct the stack signature of EKEY, and thus EKEY>CHAR and EKEY>FKEY to refer to an x rather than a u. Proposal ======== 1. Replace the current text of 3.1.2: Characters shall be at least one address unit wide, contain at least eight bits, and have a size less than or equal to cell size. The characters provided by a system shall include the graphic characters {32 ... 126}, which represent graphic forms as shown in table 3.2. with the new text: Characters shall have the following properties: - at least one address unit wide; - contain at least eight bits; - be of fixed width; - have a size less than or equal to cell size; - be unsigned. The characters provided by a system shall include the graphic characters {32 ... 126}, which represent graphic forms as shown in table 3.2. This adds two additional restrictions on a character, that it should be of a fixed with, and be unsigned. 2. Add an additional section: 3.1.2.3 Primitive Character A primitive character (pchar) is a character with no restrictions on its contents. Unless otherwise stated, a "character" refers to a primitive character. This allows us to rework the rationale for KEY/EKEY. 3. Add a rationale for KEY (which does not currently have a rational): A.6.1.1750 KEY Use of KEY indicates that the application is processing primitive characters. Some input devices, e.g. keyboards, may provide more information than can be represented as a primitive character and such an event may be received as an implementation-specific sequence of primitive characters. See A.10.6.1.1306 EKEY 4. Replace the existing (three page) rationale for EKEY with the following: A.10.6.1.1306 EKEY For some input devices, e.g. keyboards, more information is available than can be returned by a single execution of KEY. EKEY provides a standard word to access a system-dependent set of events. EKEY and EKEY? are implementation specific; no assumption can be made regarding the interaction between the pairs EKEY/EKEY? and KEY/KEY?. This standard does not define a timing relationship between KEY? and EKEY?. Undefined results may be avoided by using only one pairing of KEY/KEY? or EKEY/EKEY? in a program for each input stream. EKEY assumes no particular numerical correspondence between particular event code values and the values representing standard characters. On some systems, this may allow two separate keys that correspond to the same standard character to be distinguished from one another. A standard program may only interpret the results of EKEY via the translation words provided for that purpose (EKEY>CHAR and EKEY>FKEY). In systems that combine both keyboard and mouse events into a single "event stream", the value returned by EKEY may be inadequate to represent the full range of input possibilities. In such systems, a single "event record" may include a time stamp, the (x,y) coordinates of the mouse position, the keyboard state, and the state of the mouse buttons; EKEY could return the address of an "event record" from which this information can be extracted. See: A.6.1.1750 KEY, 10.6.2.1306 EKEY>CHAR and 10.6.2.xxxx EKEY>FKEY. 5. Replace the rationale for EKEY? with a simple reference to the rationale for EKEY. In order to allow the "event record" discussed in this rational we need to replace the reference to a u with an x in the description definition of the following words: 6. Replace u with x in the definition of 10.6.1.1306 EKEY. ( -- u ) becomes ( -- x ) 7. Replace the u with x in the definition of 10.6.2.1306 EKEY>CHAR. 8. Change the definition of 10.6.2.xxxx EKEY>FKEY as follows: a. The stack description changes from ( u1 -- u2 f ) to ( x -- u flag ). b. The u1 becomes x, allowing an address to be passed into the word. c. The u2 becomes u, indicating a value which can be compared with an K-... value. d. The stack symbol f is not defined in 2.2.2 (Stack notation) and should be replaced with flag which is. Credits ======= Peter Knaggs, pjk@bcs.org.uk School of Engineering, Computing and Mathematics, University of Exeter, Exeter, Devon EX4 7QF, England tel: +44 (0)13 9226 4014 web: http://www.rigwit.co.uk