NuInput: A better INPUT for Applesoft BASIC. by Ivan Drucker, ivan@ivanx.com v2.1, December 2011 latest version and support: http://appleii.ivanx.com v1.0 originally introduced at KansasFest 2010, http://www.kansasfest.org 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 (492 bytes) relocatable machine language routine which can be loaded from a separate file or self-contained within your Applesoft program. NuInput 2.0 users: In, NuInput 2.1, when using one-key mode, KC$="" now means accept no control characters, rather than all. Update accordingly. NuInput 1.0 users: NuInput 2.1 is a complete rewrite and is much better. However, your programs will need to be updated to be used with NuInput 2.1. 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 250 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. 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. A very simple usage example, which asks the user for a name: 10 PRINT CHR$(4);"BRUN NUINPUT.BRUN" : REM load NuInput 100 PRINT "WHAT'S YOUR NAME?"; 110 CALL 250 120 REM ST$ now contains the name Another typical usage example: The user is prompted for a phone number. ESC exits. Left arrow deletes. Blank entry is refused. 10 PRINT CHR$(4);"BRUN NUINPUT.BRUN" : REM load NuInput 20 ST$ = "" : REM [only necessary before the first CALL 250 in program] 100 PRINT "WHAT'S YOUR PHONE NUMBER?"; : REM user prompt 110 KL$="+-()1234567890" : KC$="[" : REM set allowed chars & ESC submit 120 POKE 253,14 : POKE 254,(16+2) : REM set max length & select options 130 DE$="" : CALL 250 : PRINT : REM no default entry; call NuInput 140 IF PEEK(8)=27 THEN END : REM if ESC was pressed, quit 150 REM ST$ is now the phone number A more complex example appears further down. 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 "". Special ctrl keys (H:left arrow, U:right arrow, M:RETURN) are accepted if specified in KC$, and are not accepted otherwise. If you want ESC, RETURN, and the four arrow keys to be accepted at a "Press Any Key" prompt, set KC$="[MHJKU". 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. A more complex 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 CHR$(4);CT$ : PRINT : 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$ Included on the NuInput 2.1 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 more complex 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.1. Use this guide to update your program: Changed option: 1.0 2.1 hexdec entry mode [+128] n/a wrap after one-key entry [+128+64] [PRINT after CALL 250] prohibit break [+16] [+128] ESC key submits [+8 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.1 (compared with 1.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 250 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.1 (compared with 1.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 492 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.1, 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.1, December 2011 latest version and support: http://appleii.ivanx.com/nuinput v1.0 originally introduced at KansasFest 2010, http://www.kansasfest.org