*
*-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=*
*                              *
* STDIO.MAC                    *
*                              *
* AUTHOR:  NATHAN RIGGS        *
* CONTACT: NATHAN.RIGGS@       *
*          OUTLOOK.COM         *
*                              *
* VERSION: 0.1.2               *
* DATE:    30-OCT-2018         *
* ASSEMBLER: MERLIN 8 PRO      *
*                              *
****   SEE CHANGELOG FOR    ****
****  HISTORY OF CHANGES    ****
*                              *
* LICENSE: MIT LICENSE, WHERE  *
*  APPLICABLE. CODE INSPIRED   *
*  BY THE WORKS OF OTHERS MAY  *
*  FALL UNDER A DIFFERENT      *
*  LICENSE (NOTED IN ROUTINE). *
*                              *
*------------------------------*
*                              *
* THIS IS A MACRO LIBRARY FOR  *
* STDIO.LIB, AND CAN BE USED   *
* REGARDLESS OF WHETHER A      *
* SPECIFIC FUNCTION IS         *
* INCLUDED AS A PUT IN THE     *
* MAIN SOURCE. IT IS INTENDED  *
* TO SERVE AS A USEFUL SHORT-  *
* CUT FOR CALLING THE VARIOUS  *
* ROUTINES. SO, YOU KNOW. LIKE *
* A MACRO LIBRARY.             *
*                              *
*------------------------------*
*                              *
* LIST OF MACROS               *
*                              *
* _TPG1 : SET TEXT PAGE 1      *
* _TPG2 : SET TEXT PAGE 2      *
* _PRN  : FLEXIBLE PRINT       *
* _PCR  : PRINT CARRIAGE RET   *
* _PLN  : PRINT LINE           *
* _INP  : SPECIAL INPUT        *
* _GKEY : GET SINGLE KEY       *
* _WKEY : WAIT FOR KEY         *
* _CXY  : SET CURS POS AT X,Y  *
* _CX   : SET CURSOR X         *
* _CY   : SET CURSOR Y         *
* _CURF : CURSOR FORWARD       *
* _CURB : CURSOR BACKWARD      *
* _CURU : CURSOR UP            *
* _CURD : CURSOR DOWN          *
* _RCXY : READ CURSOR POSITION *
* _PDL  : READ PADDLE STATE    *
* _PBX  : READ PDL BTN X       *
* _TVLN : TEXT VERTICAL LINE   *
* _THLN : TEXT HORIZ LINE      *
* _TFIL : TEXT FILL AREA       *
*                              *
*-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=*
*
*``````````````````````````````*
* _TPG1 : SET TEXT PAGE 1      *
*                              *
* SIMPLY SETS TEXT PAGE 1.     *
* BARELY WORTH BEING A MACRO,  *
* BUT KEEPING FOR NOW.         *
*-                            -*
* PARAMETERS: NONE             *
*-                            -*
* SAMPLE USAGE: _TPG1          *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_TPG1    MAC              ;SET P1
         LDA   PAGE1
         <<<
*
*``````````````````````````````*
* _TPG2 : SET TEXT PAGE 2      *
*                              *
* SIMPLY SETS TEXT PAGE 2.     *
* BARELY WORTH BEING A MACRO,  *
* BUT KEEPING FOR NOW.         *
*-                            -*
* PARAMETERS: NONE             *
*-                            -*
* SAMPLE USAGE: _TPG2          *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_TPG2    MAC              ;SET P2
         LDA   PAGE2
         <<<
*
*``````````````````````````````*
* _PRN :: PRINT (NO <CR> )     *
*-                            -*
* EITHER PRINTS A STRING OF    *
* TEXT PROVIDED, OR PRINTS THE *
* DATA FOUND AT THE SPECIFIED  *
* MEMORY LOCATION.             *
*-                            -*
* PARAMETERS                   *
*                              *
* IF FIRST LETTER OF VAR1 IS   *
* A QUOTATION MARK, THEN PASS  *
* CONTROL TO XPRINT.           *
*                              *
* IF FIRST LETTER OF VAR1 IS   *
* A DOLLAR SIGN, THEN IT IS A  *
* MEMORY LOCATION, SO PASS TO  *
* DPRINT.                      *
*                              *
* IF FIRST LETTER OF VAR1 IS   *
* AN 'S', THEN A STRING PRINT  *
* IS BEING INDICATED. VAR2     *
* (]2) HOLDS THE ADDRESS TO    *
* THE STRING; TRANSFER CONTROL *
* TO SPRINT.                   *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _PRN "HELLO!"         *
*        _PRN $300             *
*        _PRN S;$310           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_PRN     MAC
*
         IF    ",]1   ; --- IF PARAM=STRING
*
         JSR   XPRINT     ; SPECIAL PRINT
         ASC   ]1         ; PUT STRING HERE
         HEX   00         ; STRING TERMINATE
*
         ELSE             ; ELSE, PARAM IS
                          ; MEMORY LOCATION
*
         LDA   #>]1       ; PUSH HIGH BYTE
         PHA              ; TO STACK
         LDA   #<]1       ; PUSH LOW BYTE
         PHA
         JSR   DPRINT
*
         FIN
         <<<
*
*``````````````````````````````*
* _PCR: PRINT CARRAIGE RETURN  *
*                              *
* SIMPLY SENDS A CR AND LINE   *
* FEED TO COUT (OR THE         *
* EQUIVALENT, ANYHOW).         *
*-                            -*
* PARAMETERS: NONE             *
*-                            -*
* SAMPLE USAGE: _PCR           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_PCR     MAC
         LDA   #$8D
         JSR   COUT1
         LDA   #$00
         JSR   COUT1
         <<<
*
*``````````````````````````````*
* _PLN: PRINT LINE             *
*                              *
* PRINTS A STRING OF TEXT FROM *
* PARAMETER, PRINTS IT AND     *
* THEN PRINTS A NEWLINE.       *
* CURRENTLY, THIS WILL ONLY    *
* SUPPORT DIRECT PRINTS, NOT   *
* MEMORY CALLS OR STRINGS.     *
*-                            -*
* PARAMETERS                   *
*                              *
* VAR1 SHOULD CONTAIN THE      *
* STRING OF CHARACTERS TO BE   *
* PRINTED (]1).                *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _PLN "HELLO!"         *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_PLN     MAC
         JSR   XPRINT
         ASC   ]1
         HEX   8D00
         <<<
*
*``````````````````````````````*
* _INP: INPUT MACRO            *
*                              *
* INPUTS A STRING FROM KEYBRD  *
* AND STORES IT AT SPECIFIED   *
* LOCATION.                    *
*-                            -*
* PARAMETERS                   *
*                              *
* VAR1 (]1) SHOULD CONTAIN THE *
* ADDRESS WHERE THE INPUTTED   *
* STRING WILL BE STORED.       *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _INP $6A00            *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_INP     MAC
         LDA   #>]1       ; HIGH ORDER
         PHA
         LDA   #<]1       ; LOW ORDER
         PHA
         JSR   SINPUT
         <<<
*
*``````````````````````````````*
* _GKEY [LOC] : GETKEY         *
*                              *
* WAITS FOR USER TO PRESS A    *
* KEY, THEN STORES THAT IN     *
* THE SPECIFIED LOCATION.      *
*-                            -*
* PARAMETERS                   *
*                              *
* THE FIRST PARAMETER SHOULD   *
* HOLD THE ADDRESS WHERE THE   *
* CHARACTER IS TO BE STORED.   *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _GKEY $6A00           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_GKEY    MAC
         LDA   #<]1
         LDX   #>]1
         STX   ADDR1+1
         STA   ADDR1
         JSR   GETKEY
         LDY   #$00
         STA   (ADDR1),Y
         LDA   #$00
         STA   STROBE
         <<<
*
*``````````````````````````````*
* WKEY : WAIT FOR KEYPRESS     *
*                              *
* SIMPLY LOOPS UNTIL A KEY IS  *
* PRESSED. KEY VALUE STORED    *
* IN ACCUMULATOR.              *
*-                            -*
* PARAMETERS: NONE             *
*-                            -*
* SAMPLE USAGE: _WKEY          *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_WKEY    MAC
_LOOP    LDA   KYBD
         CMP   #$80
         BCC   _LOOP
         STA   STROBE
         <<<
*
*``````````````````````````````*
*  _CXY: POSITION CURSOR X,Y   *
*-                            -*
* SETS THE CURSOR POSITION.    *
*-                            -*
* PARAMETERS                   *
*                              *
* THE FIRST PARAMETER SHOULD   *
* HOLD THE X POSITION; THE     *
* SECOND SHOULD HOLD Y.        *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _CXY  #10;#10         *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CXY     MAC
         LDX   ]1
         LDY   ]2
         STX   CURSH
         STY   CURSV
         JSR   VTAB
         <<<
*
*``````````````````````````````*
*- _CX: POSITION CURSOR HORIZ -*
*-                            -*
* SETS THE HORIZONTAL POSITION *
* OF THE TEXT CURSOR.          *
* NUMBER Y TO MOVE UPWARD.     *
*-                            -*
* PARAMETERS                   *
*                              *
* FIRST PARAMETER HOLDS X.     *
*-                            -*
* SAMPLE USAGE: _CX  #10       *
*                              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CX      MAC
         LDX   ]1
         STX   CURSH
         JSR   VTAB
         <<<
*
*``````````````````````````````*
*  _CY: POSITION CURSOR VERT   *
*-                            -*
* SET CURSOR VERTICAL POSITION *
*-                            -*
* PARAMETERS                   *
*                              *
* FIRST PARAMETER HOLDS Y.     *
*-                            -*
* SAMPLE USAGE: _CY  #10       *
*                              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CY      MAC
         LDY   ]1
         STY   CURSV
         JSR   VTAB
         <<<
*
*``````````````````````````````*
*  _CURF : TEXT CURSOR FORWRD  *
*-                            -*
* MOVES THE CURSOR FORWARD BY  *
* SPECIFIED AMOUNT.            *
*-                            -*
* PARAMETERS                   *
*                              *
* FIRST PARAMETER SHOULD HOLD  *
* NUMBER X TO MOVE FORWARD.    *
*-                            -*
* SAMPLE USAGE: _CURF  #10     *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CURF    MAC
         LDA   ]1
         JSR   CURSFOR
         <<<
*
*``````````````````````````````*
*  _CURB : TEXT CURSOR BACKWD  *
*-                            -*
* MOVES THE CURSOR BACKWARD BY *
* SPECIFIED AMOUNT.            *
*-                            -*
* PARAMETERS                   *
*                              *
* FIRST PARAMETER SHOULD HOLD  *
* NUMBER X TO MOVE BACKWARD.   *
*-                            -*
* SAMPLE USAGE: _CURB  #10     *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CURB    MAC
         LDA   ]1
         JSR   CURSBAK
         <<<
*
*``````````````````````````````*
*  _CURU : TEXT CURSOR UP      *
*-                            -*
* MOVES THE CURSOR UP BY       *
* SPECIFIED AMOUNT.            *
*-                            -*
* PARAMETERS                   *
*                              *
* FIRST PARAMETER SHOULD HOLD  *
* NUMBER Y TO MOVE UPWARD.     *
*-                            -*
* SAMPLE USAGE: _CURU #10      *
*                              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CURU    MAC
         LDA   ]1
         JSR   CURSUP
         <<<
*
*``````````````````````````````*
*  _CURD : TEXT CURSOR DOWN    *
*-                            -*
* MOVES THE CURSOR DOWN BY     *
* SPECIFIED AMOUNT.            *
*-                            -*
* PARAMETERS                   *
*                              *
* FIRST PARAMETER SHOULD HOLD  *
* THE AMOUNT TO MOVE DOWN IN Y *
*-                            -*
* SAMPLE USAGE: #10            *
*                              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_CURD    MAC
         LDA   ]1
         JSR   CURSDN
         <<<
*
*``````````````````````````````*
* _RCXY : READ SCREEN AT XY    *
*-                            -*
* READ THE CHARACTER AT POS    *
* X,Y AND LOADS INTO ACCUM     *
*-                            -*
* PARAMETERS                   *
*                              *
* PARAMETER 1 SHOULD HOLD THE  *
* X POSITION ON SCREEN TO BE   *
* READ, PARAMETER 2 HOLDS Y.   *
*-                            -*
* SAMPLE USAGE: _RCXY #3;#9    *
*                              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_RCXY    MAC
         LDA   ]1         ; ROW
         LDY   ]2         ; COLUMN
         JSR   $F847      ; NOT SURE ABOUT THIS MAGIC NUM
         LDA   ($26),Y    ; LOAD CHAR INTO ACCUM
*
* THANKS GO TO ERIC JACOBS
* IN THE APPLE II ENTHUSIASTS
* FACEBOOK GROUP FOR THIS
*
         <<<
*
*``````````````````````````````*
* PADDLE / MOUSE INPUT         *
*-                            -*
* SIMPLY READS STATE OF PADDLE *
* NUMBER [NUM] AND STORES IT   *
* IN THE Y REGISTER.           *
*-                            -*
* PARAMETERS                   *
*                              *
* PARAMETER 1 SHOULD HOLD THE  *
* NUMBER THAT CORRESPONDS TO   *
* THE PADDLE TO READ.          *
*-                            -*
* SAMPLE USAGE: _PDL #0        *
*                              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_PDL     MAC              ; GET PADDLE VALUE
         LDX   #]1        ; READ PADDLE # ]1 (USUALLY 0)
         JSR   PREAD      ; PADDLE READING STORED IN Y
         <<<
*
*``````````````````````````````*
* _PBX : PADDLE BUTTON X       *
*                              *
* STORE 1 IN ACCUMULATOR IF    *
* PADDLE BUTTON X IS PRESSED,  *
* OTHERWISE STORE 0 IN ACCUM.  *
*-                            -*
* PARAMETERS                   *
*                              *
* PARAMETER1 SHOULD HOLD THE   *
* ADDRESS OF THE PADDLE BUTTON *
* READ. THEY ARE AS FOLLOWS:   *
*                              *
* PB0: $C061       PB1: $C062  *
* PB2: $C063       PB4: $C060  *
*-                            -*
* SAMPLE USAGE: _PBX  $C061    *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_PBX     MAC
         LDA   #>]1
         PHA
         LDA   #<]1
         PHA
         JSR   GPBX
         <<<
*
*``````````````````````````````*
* _TVLN : TEXT VERTICAL LINE   *
*-                            -*
* CREATES A VERTICAL LINE OF   *
* TEXT AT THE CURRENT CURSOR   *
* COLUMN CONSISTING OF THE     *
* SPECIFIED CHARACTER.         *
*-                            -*
* PARAMETERS                   *
*                              *
* PARAM1 = START OF VLINE,     *
* PARAM2 = END POS OF VLINE,   *
* PARAM3 = X POSITION OF LINE, *
* PARAM4 = FILL CHARACTER.     *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _TVLN #0;#10;#3;#$18  *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_TVLN    MAC
         LDA   ]1         ; Y START
         PHA
         LDA   ]2         ; Y END
         PHA
         LDA   ]3         ; X POSITION
         PHA
         LDA   ]4         ; CHARACTER
         PHA
         JSR   TVLIN
         <<<
*
*``````````````````````````````*
* _THLN : TEXT HORIZONTAL LINE *
*                              *
* CREATES A HORIZONTAL LINE OF *
* TEXT FROM X1,Y TO X2,Y WITH  *
* THE SPECIFIED CHARACTER.     *
*-                            -*
* PARAMETERS                   *
*                              *
* PARAM1 = START OF HLINE,     *
* PARAM2 = END POS OF HLINE,   *
* PARAM3 = Y POSITION OF LINE, *
* PARAM4 = FILL CHARACTER.     *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _THLN #0;#10;#12;#$18 *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_THLN    MAC
         LDA   ]1         ; X START
         PHA
         LDA   ]2         ; X END
         PHA
         LDA   ]3         ; Y POS
         PHA
         LDA   ]4         ; FILL CHAR
         PHA
         JSR   THLIN
         <<<
*
*``````````````````````````````*
* _TFIL : TEXT FILL (A)       -*
*-                            -*
* FILL X1,Y1 TO X2,Y2 WITH     *
* SPECIFIED CHARACTER.         *
*-                            -*
* PARAMETERS                   *
*                              *
* PARAM1 = LEFT BOUNDARY       *
* PARAM2 = RIGHT BOUNDARY      *
* PARAM3 = TOP BOUNDARY        *
* PARAM4 = BOTTOM BOUNDARY     *
*-                            -*
* SAMPLE USAGE:                *
*                              *
*        _TFIL #0;#10;#0;#10   *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_TFIL    MAC
         LDA   ]1         ; LEFT BOUNDARY
         PHA
         LDA   ]2         ; RIGHT BOUNDARY
         PHA
         LDA   ]3         ; TOP BOUNDARY
         PHA
         LDA   ]4         ; BOTTOM BOUNDARY
         PHA
         LDA   ]5         ; FILL CHAR
         PHA
         JSR   TFILLA
         <<<
*