NuInput: A better INPUT for Applesoft BASIC.

by Ivan Drucker, ivan@ivanx.com
v2.0, October 2011
latest version and support: http://appleii.ivanx.com
v1.0 originally introduced at KansasFest 2010, http://www.kansasfest.org

Introduction:

Welcome to NuInput, an easy to use replacement for Applesoft INPUT
and GET. It runs on any Apple II with Applesoft in ROM, and does not
require the presence of DOS or ProDOS.

NuInput is a small (498 bytes) relocatable machine language routine
which can be loaded from a separate file or self-contained within your
Applesoft program.
 
 
 
NuInput 1.0 users: NuInput 2.0 is a complete rewrite and is much better.
However, your programs will need to be updated to be used with
NuInput 2.0. See the notes at the end for more information.



NuInput offers the following improvements over INPUT:

accepts comma, colon, and double-quote
accepts entry up to 255 characters
neat cleanup of wrapped text to right of cursor
CTRL-C breaks immediately and with cursor at any position
DELETE deletes if at end of line (backspaces otherwise)
  (works on real IIe/IIc/IIgs, but may not on all emulators)

NuInput also offers the following selectable features for each prompt:

restrict enterable keys to a specific list
provide a default entry
maximum entry length (up to 255)
specific control keys (including ESC) to submit the entry
prevent break on control-C
one-key entry (like Applesoft GET)
convert lowercase to uppercase
backspace key deletes
ESC clears typed text
return key disabled for entry
return key refuses blank entry
key list is case sensitive



Setting up NuInput is super easy:

At the start of your program, before any variables have been set, add:

10 PRINT CHR$(4);"BRUN NUINPUT.BRUN"

Or, if you don't want to have to load a separate file, you can provide
NuInput as Applesoft lines within your program. Type EXEC NUINPUT.EXEC
at an Applesoft prompt, and lines 0-19 will be added to the program in
memory (if any). Start your program from line 20 or higher.

With either method, NuInput will automatically be installed in a safe
memory location, between your program and variable space.

If you prefer to load NuInput at an address of your choosing, you can
BLOAD NUINPUT, at any address; if you don't specify, it's $8000 (32768).

Emulator users can, instead of using EXEC, copy the Applesoft lines at
http://appleii.ivanx.com and paste them in at an Applesoft prompt.

Containing machine language within regular Applesoft program lines is
provided by Slammer, available at http://appleii.ivanx.com.



Using NuInput is also super easy. To prompt the user for input:

CALL 250

This is equivalent to INPUT ST$. After the user presses return,
ST$ will contain what the user typed.

If you used BLOAD to install NuInput, CALL it at the address into which
it was loaded, instead of 250.

The line is not wrapped when return is pressed; use PRINT if needed.

For integer input (e.g. INPUT A), use VAL(ST$) after input.

You cannot use multiple-variable syntax (e.g. INPUT A$,B$) with NuInput.

The variable names ST$, KL$, KC$ and DE$ are reserved for NuInput, and
your program should avoid using them except as as explained here.
The NUINPUT.UTIL program lets you customize these names.

That's all you need to know for basic NuInput use. For finer control
over how the user enters text, read on.



You can set the following controls before calling NuInput:

KL$ = keys which can be entered, or "" for any key
DE$ = a default entry, pre-typed at the prompt
KC$ = control keys for submit, as uppercase letters, or "[" for ESC
POKE 253,XX where XX is the maximum number of enterable characters
POKE 254,YY where YY selects entry options (explained in next section)

POKE 254,0 (no options selected) is the default mode. Selecting options,
as explained shortly, lets you further manage how the user enters text.

If ST$ doesn't exist when NuInput is first called, CALL NU will
POKE 253,255 and POKE 254,0. If you want to set them yourself,
place ST$="" somewhere before the first CALL 250 in your program.

KL$ normally requires uppercase letters, and if lowercase characters are
typed, they will be recognized. If you want lowercase to be considered
separately, set the case sensitivity option, and use mixed case in KL$.

DE$ is not checked against KL$, so it's possible for the user to submit
characters in the default entry that are otherwise not typeable.

POKE 253 cannot contain 0, and if it does, NuInput will set it to 255.



The entry options to be poked into 254 are selected by adding values:

[128] prevent break on control-C
[ 64] one-key entry (like Applesoft GET)
[ 32] convert typed lowercase to uppercase
[ 16] backspace key deletes
[  8] ESC clears typed text
[  4] return key disabled for entry (if KC$ is not empty)
[  2] return key refuses blank entry
[  1] enterable key list (KL$) is case sensitive

So, to convert lowercase, have ESC clear entered text, and prohibit
blank entry, do this: POKE 254,(32+8+2)

Or, to have the backspace key delete, and prevent control-C, do this:
POKE 254,(128+16)

The default entry mode is none of the above enabled (POKE 254,0),
which is fairly similar to how INPUT behaves.

"Return key disabled for entry" is disregarded if KC$ is empty,
in order to ensure that an entry can be submitted.



Non-return submit:

The user can submit the typed text not only with return, but with
control keys that you specify, including ESC. This lets your program do
various things with the entry, depending on what key was pressed.

When submitting this way, all of what has been typed will be assigned
to ST$, even if the cursor isn't at the end of the line.

You can specify the control keys accepted in a variable called KC$. It
should contain uppercase letters, and/or "[" (left bracket) for ESC.
If KC$="", no control keys are accepted, unless one-key entry is on.

After submission, PEEK(8) contains the ASCII value of the submit control
key, from 1-26, or 27 for ESC. PEEK(9) contains the cursor position
(with zero as the first position) when the control key was pressed.

NuInput treats ctrl-C like any other control character, returning 3 in
PEEK(8), the cursor position in PEEK(9), and whatever was entered
in ST$. If the "Prevent Break on ctrl-C" option is not selected, ctrl-C
also stops the program immediately, or triggers ONERR GOTO if present.



An example:
The user is prompted for a file name based on ProDOS or DOS 3.3 rules.
A default file name is provided. Control-C catalogs the disk. ESC exits.
Blank entry is refused. In ProDOS, lowercase is converted to uppercase.

100 ST$ = "" : REM [only necessary before the first CALL 250 in program]
105 DE$ = "MY.SAVED.GAME" : REM default file name
110 KC$ = "C[" : REM enable control-C and ESC for submit
115 POKE 254,(128+32+2) : REM options:no break, lower-to-upper, no blank
120 KL$ = ".ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" : REM ok ProDOS chars
125 IF (PEEK(48896)=76) THEN CT$ = "CAT" : NL = 15 : GOTO 140 : REM PDOS
130 NL = 30 : CT$ = "CATALOG" : POKE 254,(128+2) : REM DOS 3.3
135 KL$ = KL$+CHR$(34)+"!#$%&'()*+-/:;<=>?@[\]^_`{|}~ " : REM DOS 3.3
140 POKE 253,NL : REM maximum filename length
145 PRINT "CTRL-C FOR CATALOG, ESC TO QUIT." : PRINT
150 PRINT "ENTER FILE NAME: "; : CALL 250 : REM user prompt & NuInput
155 IF (PEEK(8)=27) THEN PRINT : END : REM if ESC was typed, quit
160 DE$ = ST$ : REM set default entry to typed text in case of reprompt
165 IF (PEEK(8)<>3) THEN GOTO 175 : REM if not ctrl-C, continue
170 PRINT : PRINT : PRINT CHR$(4);CT$ : GOTO 150 : REM ctrl-C, catalog
175 IF ( ASC(LEFT$(ST$,1)) >= ASC("@") ) THEN GOTO 200 : REM is name ok?
180 HTAB 1 : GOTO 150 : REM illegal first character, prompt again
200 REM program continues here with file name in ST$



More about non-return submit:

Ctrl-H (left arrow) and ctrl-U (right arrow) can't be used for submit,
except during one-key mode (see below).

You can require control keys only (no normal keys can be typed) by
setting KL$=CHR$(0). Be sure KC$ contains something if you do this.

If the "return key disabled for entry" option is set, placing "M" in KC$
will still enable the return key, but the entire entry will be accepted,
regardless of cursor position at the time it was pressed, as with any
other control key. Keep in mind this could potentially confuse the user.

Non-lettered control keys other than "[" (ESC key) cannot be used.

If the "ESC clears typed text" option is set and "[" (ESC key) is
in KC$, then ESC will clear any text entered, or submit a blank entry if
there is no text.



One-key entry:

NuInput's one-key entry option is similar to Applesoft GET. Only one key
is accepted and no return is needed. Some things to note in this mode:

A normal key will be in ST$, and is not displayed.

A control key will be in PEEK(8), and ST$ will be "".

In one-key entry mode, If KC$ is absent or "", then all lettered control
keys, plus ESC, are accepted. To restrict which can be typed, specify
them in KC$ as usual. To disallow all control keys, use KC$=CHR$(0).

Special ctrl keys (H:left arrow, U:right arrow, M:return) are accepted.
If KC$ is specified, return is NOT accepted unless "M" is included.

DELETE can be entered, and ST$ will contain ASCII character 127.

Ctrl-C will still break unless the Prevent Break option is enabled.

DE$ (default entry), POKE 253 (maximum entry), and the options "return
key disabled for entry", "return key refuses blank entry", "ESC clears
typed text", and "backspace key deletes" are ignored for one-key entry.



Included on the NuInput 2.0 disk:

NUINPUT.HELP (Applesoft program with abbreviated and full documentation)

NUINPUT.UTIL (Applesoft program for customizing NuInput variable names)

NUINPUT (can be BLOADed and called at any location; defaults to $8000)

NUINPUT.BRUN (alternative to above; when BRUN from a program, it
  installs NuInput between program end and variable space; use CALL 250)

NUINPUT.EXEC (like NUINPUT.BRUN, but contained in Applesoft lines;
  you can EXEC this into a new or existing program)

NUINPUT.EXAMPLE (the example program listed above)

NUINPUT.README (this documentation text file)


Note that NUINPUT and NUINPUT.BRUN must be called or run from within an
Applesoft program; otherwise they will beep and do nothing.



NuInput 1.0 compatibility:

Much has changed in NuInput 2.0. Use this guide to update your program:

Changed option:                1.0         2.0
hexdec entry mode           [+128]          n/a
wrap after one-key entry [+128+64]        [PRINT after CALL 250]
prohibit break               [+32]        [+128]
ESC key submits   [+16 to prevent]        [include left bracket in KC$]
clear default entry on non-CR [+4]          n/a
backspace key deletes         [+2]        [+16]
CR refuses blank              [+1]        [+2]
ESC key clears entry   [always on]        [+8]
open-Apple-CR submit   [always on]        [n/a; use ctrl-char submit]
maximum length         POKE 239,XX        POKE 253,XX

Unchanged:
one-key entry                [+64]        [+64]
lower-to-upper               [+32]        [+32]
selectable options     POKE 254,XX        POKE 254,XX
default entry variable         DE$        DE$
typed entry variable           ST$        ST$
enterable key list variable    KL$        KL$



Changed behaviors in 2.0:
uppercase characters in KL$ are case insenstive unless [+1] is set
YZ$ (ST$ template) is no longer needed (easier and saves memory)
line never wraps to next line on submit, even on CR
submitting blank entry via ESC yields empty ST$ [instead of CHR$(27)]
POKE 253 and 254 are initialized on CALL NU if ST$ does not exist
DE$ remains in its original case even if lower-to-upper is enabled
control characters or DEL in DE$ are displayed as carets (^)
if POKE 253 contains 0, it is set to 255

New features in 2.0:
ability to submit via specifiable control characters in KC$
option to disable CR for entry
DELETE deletes if at end of entry, backspaces otherwise
PEEK(8) contains ASCII value of submit key (ctrl-key, ESC, or CR)
PEEK(9) contains cursor position when submitted
498 bytes total, down from 768 (saves over 1K when used with Slammer)
As an alternative to lines 0-19, BRUN NUINPUT.BRUN will also dynamically
  place NuInput in a safe memory location, and CALL 250 can activate it
  
NUINPUT.DEMO is not available for NuInput 2.0, though the Applesoft
programs NUINPUT.HELP and NUINPUT.DEMO are themselves usage examples.



License and general information:

You can do absolutely anything you like with NuInput, as described in
the WTFPL (http://sam.zoy.org/wtfpl/), with the following exception:

If you use NuInput in a program, or distribute a modified version of
NuInput itself, you must include the phrase "NuInput by Ivan Drucker",
or equivalent, somewhere in your program or its included documentation.
For example: 63999 REM includes NuInput by Ivan Drucker

Big thanks to Martin Haye and David Schmidt for testing and insight.

If you like NuInput, or have questions or comments, please let me know!

NuInput by Ivan Drucker, ivan@ivanx.com
v2.0, October 2011
latest version and support: http://appleii.ivanx.com
v1.0 originally introduced at KansasFest 2010, http://www.kansasfest.org
