TextInput.mesa
Copyright (C) 1984, 1985, 1986 by Xerox Corporation. All rights reserved.
Last revised by McManis on: 29-Apr-85 16:03:12
Tim Diebert: October 23, 1986 11:21:42 am PDT
Ruseli Binsol: December 8, 1986 9:20:40 am PST
TextInput performs standardized TTY input processing. It handles all aspects of editing user input, prompting for parameters, processing special characters (e.g., "?"), etc., in a "standard" way. >>
DIRECTORY
BasicTime USING [GMT, nullGMT],
CHNameP2V0 USING [Name],
NSString USING [nullString, String],
Process USING [Seconds],
Rope USING [ROPE],
TTY USING [Handle],
XMessage USING [StringArray],
XNS USING [Host, Net, unknownHost, unknownNet];
TextInput:
CEDAR
DEFINITIONS =
BEGIN
OPEN CHName: CHNameP2V0;
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
TYPES
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
ROPE: TYPE ~ Rope.ROPE;
ChoiceIndex: TYPE = [0..maxChoices];
Choices:
TYPE = XMessage.StringArray;
The names of choices passed to GetChoice*. Must have have at least one element.
Chosen:
TYPE =
PACKED
ARRAY ChoiceIndex
OF
BOOLEAN;
elements in the are will be TRUE if the corresponding number choice was chosen by the user.
HelpProc: TYPE = PROCEDURE [tty: TTY.Handle];
YesOrNo: TYPE = {yes, no, uncertain};
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
CONSTANTS
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
maxChoices: CARDINAL = 63; -- limited by the number of choices which can simultaneously be displayed on the tty screen values for specifying that no default exists, and for returning nil values.
nilChoice: ChoiceIndex = maxChoices;
nilDate: BasicTime.GMT = BasicTime.nullGMT;
nilDecimal: INTEGER = FIRST[INTEGER]; -- (-32,768)
nilLongDecimal: LONG INTEGER = FIRST[LONG INTEGER]; -- (-2,147,483,648);
nilString: NSString.String = NSString.nullString;
nilYesNo: YesOrNo = uncertain; --used only to specify that no default
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
ERRORS :
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
<< Although no signals or errors are defined in this interface, the user is expected to catch the signals and errors generated by calls on TTY.Handle. Specifically, the user should be prepared for TTY.Handle.Rubout and ABORTED.>>
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
OPERATIONS :
-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- --
<< PARAMETER INPUT;
The following procedures all prompt the user with the "prompt" string and then process the parameter input, performing whatever validation they can. This sequence of operations is repeated until valid input is received or the TTY.Handle.Rubout or ABORTED is raised. When a default value is specified, it is displayed after the ':' in the prompt, and is overwritten with the user's input unless the user immediately enters a carriage return (accepting the default) or an editing command (Backspace, Backword). >>
Confirm:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String, default: YesOrNo ← nilYesNo,
helpProc: HelpProc ←
NIL]
RETURNS [
BOOLEAN] =
INLINE
{RETURN[GetYesNo[tty, prompt, default, helpProc] = yes]};
GetChoice:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String, choices:
REF Choices,
default: ChoiceIndex ← nilChoice, nilOK:
BOOLEAN ←
FALSE,
helpProc: HelpProc ←
NIL]
RETURNS [ChoiceIndex];
<< Gives the user a numbered list of choices, and returns the index of the choice selected. The user selects a choice in the range [1..LENGTH[choices]], while the routine returns a choice in the range [0..LENGTH[choices]). default is given to the user as a default choice. nilChoice may be returned only if nilOK = TRUE. >>
GetChoices:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String, choices:
REF Choices,
default: ChoiceIndex ← nilChoice, nilOK:
BOOLEAN ←
FALSE,
helpProc: HelpProc ←
NIL]
RETURNS [Chosen];
<< choices are numbered 1 to LENGTH[Choices] and displayed to the user. The user selects choices in the range [1..LENGTH[choices]]. For each choice selected, chosen[selected] ← TRUE. nilChoice may be returned only if nilOK = TRUE. >>
GetDate:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
default: BasicTime.
GMT ← nilDate, nilOK:
BOOLEAN ←
FALSE, helpProc: HelpProc ←
NIL]
RETURNS [BasicTime.
GMT];
Gets a date parameter. nilDate may be returned only if nilOK = TRUE.
GetDateAndTime:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
default: BasicTime.
GMT ← nilDate, nilOK:
BOOLEAN ←
FALSE, helpProc: HelpProc ←
NIL]
RETURNS [BasicTime.
GMT];
Gets a date and time parameter. nilDate may be returned only if nilOK = TRUE.
GetDecimal:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
min:
INTEGER ←
FIRST[
INTEGER], max:
INTEGER ←
LAST[
INTEGER],
default:
INTEGER ← nilDecimal, nilOK:
BOOLEAN ←
FALSE, helpProc: HelpProc ←
NIL]
RETURNS [
INTEGER];
Gets a decimal number in the range [min..max]. -32767 <= min <= max <= 32767. nilDecimal may be returned only if nilOK = TRUE.
GetHostNumber:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
default:
XNS.Host ←
XNS.unknownHost, helpProc: HelpProc ←
NIL]
RETURNS [
XNS.Host];
Users enter numbers as a string of digits, with each block of three digits separated by a hyphen.
GetLongDecimal:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
min:
LONG
INTEGER ←
FIRST[
LONG
INTEGER],
max:
LONG
INTEGER ←
LAST[
LONG
INTEGER],
default:
LONG
INTEGER ← nilLongDecimal, nilOK:
BOOLEAN ←
FALSE,
helpProc: HelpProc ←
NIL]
RETURNS [
LONG
INTEGER];
Gets a decimal number in the range [min..max]. -2147483647 <= min <= max <= 2147483647. nilLongDecimal may be returned only if nilOK = TRUE.
GetNetworkNumber:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
default:
XNS.Net ←
XNS.unknownNet, helpProc: HelpProc ←
NIL]
RETURNS [
XNS.Net];
Users enter numbers as a string of digits, with each block of three digits separated by a hyphen.
GetNSName:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String, name: CHName.Name,
defaultName: CHName.Name ← [
NIL,
NIL,
NIL],
defaultFields: CHName.Name ← [
NIL,
NIL,
NIL],
promptFullyQualifiedDefault:
BOOLEAN ←
FALSE, helpProc: HelpProc ←
NIL];
<< Obtains an NSName from the user, putting the result in "name", which must have been preallocated by the client. If "defaultName" is non-NIL, it is output and treated as the default input value. defaultFields is used for defaulting domain and org on input and/or output. If promptFullyQualifiedDefault is TRUE, domain and organization fields are never omitted when outputting default.>>
GetPathName: PROCEDURE [tty: TTY.Handle, prompt: NSString.String, path: REF TEXT,
defaultPath: NSString.String ← NSString.nullString,
defaultFields: CHName.Name ← [NIL, NIL, NIL], promptFullyQualified,
nilOK: BOOLEAN ← FALSE, helpProc: HelpProc ← NIL]
RETURNS [newPath: REF TEXT];
GetText:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String, text: NSString.String,
minLength:
CARDINAL ← 1, maxLength:
CARDINAL, echoStars:
BOOLEAN ←
FALSE,
default:
REF
TEXT ←
NIL, helpProc: HelpProc ←
NIL]
RETURNS [newText: NSString.String];
<< Inputs a text parameter, insuring that it is between minLength and maxLength characters long. echoStars is used to have asterisks echoed, as when entering passwords. It is safe to pass the same string as text and default in order to use the previous value of the string as the default. The returned string replaces the "text" parameter, which should no longer be used. If minLength = 0 and the user gives no input, the returned string will have a length of zero. >>
GetTime:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
default: BasicTime.
GMT ← nilDate, nilOK:
BOOLEAN ←
FALSE, helpProc: HelpProc ←
NIL]
RETURNS [BasicTime.
GMT];
Gets a time parameter. nilDate may be returned only if nilOK = TRUE.
GetTimedYesNo:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
timeAllotted: Process.Seconds, valueIfTimedOut: YesOrNo, helpProc: HelpProc ←
NIL]
RETURNS [YesOrNo];
Returns Yes or No if user keys in before timeAllotted seconds, and valueIfTimedOut otherwise. 'uncertain' is never returned.
GetYesNo:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String, default: YesOrNo ← nilYesNo,
helpProc: HelpProc ←
NIL]
RETURNS [YesOrNo];
Gets a Yes/No parameter; 'uncertain' is never returned.
TimedConfirm:
PROCEDURE [tty:
TTY.Handle, prompt: NSString.String,
timeAllotted: Process.Seconds,
valueIfTimedOut: YesOrNo, helpProc: HelpProc ←
NIL]
RETURNS [
BOOLEAN] =
INLINE {
RETURN[GetTimedYesNo[tty, prompt, timeAllotted, valueIfTimedOut, helpProc] = yes]};
END. -- of TextInput.mesa
LOG [Time - Person - Action]
26-Sep-83 9:48:45 - Alfvin - Created file from old NSCommand.
28-Oct-83 0:06:00 - McManis - Fixed up some comments.
7-Nov-83 23:11:30 - McManis - Allowed GetText to have minLength characters = 0. Added GetTime.
3-Jan-84 18:43:42 - Saund - Added NSName
29-Apr-85 16:03:17 - McManis - Added Confirm, GetPathName, and TimedConfirm.