@ (c) 2020 Aaron Taylor <ataylor at subgeniuskitty dot com>
@ See LICENSE.txt file for copyright and license details.

#ifndef VVS_STDLIB_DEBUG
#define VVS_STDLIB_DEBUG

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Some of the subroutines in this file duplicate other stdlib subroutines.
@ This is to avoid outside dependencies and allow debugging of stdlib code.
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   dumpheap (111000)
@ Description:
@   Dumps the heap from 'startaddr' to 'endaddr'.
@   This subroutine stomps on heap[1] after printing the first heap location.
@     If you dump starting from heap[0], then heap[1] will print inaccurately.
@     Starting the dump from any other location will work without error.
@     TODO: Should I use heap[0] and DIE rather than RTS?
@           At the moment, the ability to continue is too useful to me.
@           If it's useful to me, it's probably useful to other people.
@           For now, leave dumpheap as-is.
@ Call Stack: 
@   endaddr
@   startaddr  <-- TOS
@ Return Stack:
@   <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTSSSN              | Mark: 111000 (debug:dumpheap)

@ Prepare a numeric address and value on the stack
SNS                      | DUP
SNS                      | DUP
TTT                      | LOAD
SNT                      | SWAP

@ Print output line for this memory location
NSTTTTSTTN               | JSR > 111011 (debug:printmagnitude)
SSSTSSTN                 | PUSH ASCII '\t'
SSSTTTSTSN               | PUSH ASCII ':'
TNSS                     | PUTC
TNSS                     | PUTC
SNS                      | DUP
NSTTTTSTSN               | JSR > 111010 (debug:printsign)
NSTTTTSTTN               | JSR > 111011 (debug:printmagnitude)
SSSTSTSN                 | PUSH ASCII '\n'
TNSS                     | PUTC

@ Figure out if the loop is complete.
SSSTN                    | PUSH 1 (ptr)
SNT                      | SWAP
TTS                      | STORE
SNS                      | DUP
SSSTN                    | PUSH 1 (ptr)
TTT                      | LOAD
TSST                     | SUBTRACT
NTSSSTTTSSSSSSSSSSSN     | BRZ > 00111000 00000000
SSSTN                    | PUSH 1 (ptr)
TTT                      | LOAD
SSSTN                    | PUSH 1
TSSS                     | ADD
NSNTTTSSSN               | JMP > 111000 (dump heap)

@ Clean up and return
NSSVSSTTTSSSSSSSSSSSN    | Mark: 00111000 00000000
SNN                      | DROP
NTN                      | RTS

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   dumpstack (111001)
@ Description:
@   Dumps 'count' entries from the stack.
@ Call Stack:
@   count <-- TOS
@ Return Stack:
@   <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTSSTN              | Mark: 111001 (debug:dumpstack)

@ Orient the user
SSSSSSSSSN               | PUSH ASCII '\0'
SSSSSSTSTSN              | PUSH ASCII '\n'
SSSSTTTSTSN              | PUSH ASCII ':'
SSSTSTSSTTN              | PUSH ASCII 'S'
SSSTSSTTTTN              | PUSH ASCII 'O'
SSSTSTSTSSN              | PUSH ASCII 'T'
NSTTTTTSSN               | JSR > 111100 (debug:printstring)

@ Print output line for the current TOS.
NSSVSSTTTSSTSSSSSSSTN    | Mark: 00111001 00000001
SNS                      | DUP
NSTTTTSTTN               | JSR > 111011 (debug:printmagnitude)
SSSTSSTN                 | PUSH ASCII '\t'
SSSTTTSTSN               | PUSH ASCII ':'
TNSS                     | PUTC
TNSS                     | PUTC
SNT                      | SWAP
SNS                      | DUP
NSTTTTSTSN               | JSR > 111010 (debug:printsign)
NSTTTTSTTN               | JSR > 111011 (debug:printmagnitude)
SSSTSTSN                 | PUSH ASCII '\n'
TNSS                     | PUTC

@ Figure out if the loop is complete.
SSSTN                    | PUSH 1
TSST                     | SUBTRACT
SNS                      | DUP
NTSSSTTTSSTSSSSSSSSN     | BRZ > 00111001 00000000
NSNSSTTTSSTSSSSSSSTN     | JMP > 00111001 00000001

@ Clean up and return
NSSVSSTTTSSTSSSSSSSSN    | Mark: 00111001 00000000
SNN                      | DROP
NTN                      | RTS

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   printsign (111010)
@ Description:
@   Prints the sign of 'number'.
@ Call Stack:
@   number <-- TOS
@ Return Stack:
@   <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTSTSN             | Mark: 111010 (debug:printsign)
NTTSSTTTSTSSSSSSSSTN    | BMI > 00111010 00000001
SSSTSTSTTN              | PUSH ASCII '+'
NSNSSTTTSTSSSSSSSTSN    | JMP > 00111010 00000010
NSSVSSTTTSTSSSSSSSSTN   | Mark: 00111010 00000001
SSSTSTTSTN              | PUSH ASCII '-'
NSSVSSTTTSTSSSSSSSTSN   | Mark: 00111010 00000010
TNSS                    | PUTC
NTN                     | RTS

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   printmagnitude (111011)
@ Description:
@   Prints the magnitude of 'number'.
@ Call Stack:
@   number <-- TOS
@ Return Stack:
@   <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTSTTN             | Mark: 111011 (debug:printmagnitude)

@ Extract the magnitude of the number.
SNS                     | DUP
NTTSSTTTSTTSSSSSSSSN    | BMI > 00111011 00000000
NSNSSTTTSTTSSSSSSSTN    | JMP > 00111011 00000001
NSSVSSTTTSTTSSSSSSSSN   | Mark: 00111011 00000000
SSTTN                   | PUSH -1
TSSN                    | MULTIPLY
NSSVSSTTTSTTSSSSSSSTN   | Mark: 00111011 00000001

@ Prepare for building a string on the stack.
SSSSN                   | PUSH ASCII '\0'
SNT                     | SWAP

@ Pick off one digit on each pass through this loop.
NSSVSSTTTSTTSSSSSSTSN   | Mark: 00111011 00000010
SNS                     | DUP

@ Mod-off a digit, convert to ASCII, store on stack as part of the string.
SSSTSTSN                | PUSH +10
TSTT                    | MODULO
SSSTTSSSSN              | PUSH ASCII '0'
TSSS                    | ADD
SNT                     | SWAP

@ Divide down to next digit and keep looping if number != 0 yet.
SSSTSTSN                | PUSH +10
TSTS                    | DIVIDE
SNS                     | DUP
NTSSSTTTSTTSSSSSSTTN    | BRZ > 00111011 00000011
NSNSSTTTSTTSSSSSSTSN    | JMP > 00111011 00000010

@ Print the string we have built on the stack.
NSSVSSTTTSTTSSSSSSTTN   | Mark: 00111011 00000011
SNN                     | DROP
NSTTTTTSSN              | JSR > 111100 (debug:printstring)
NTN                     | RTS

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   printstring (111100)
@ Description:
@   Prints a null-terminated string from the stack.
@ Call Stack:
@   null-terminator (ASCII '\0')
@   char n
@   ...
@   char 2
@   char 1 <-- TOS
@ Return Stack:
@   <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTTSSN             | Mark: 111100 (debug:printstring)
SNS                     | DUP
NTSSSTTTTSSSSSSSSSTN    | BRZ > 00111100 00000001
TNSS                    | Print character
NSNTTTTSSN              | JMP > 111100
NSSVSSTTTTSSSSSSSSSTN   | Mark: 00111100 00000001
SNN                     | DROP
NTN                     | RTS

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   printsignednumber (111101)
@ Description:
@   Prints 'number' from the stack in sign-magnitude format.
@   Leading zeros are suppressed.
@ Call Stack:
@   number  <-- TOS
@ Return Stack:
@   <empty>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTTSTN             | Mark: 111101 (debug:printsignednumber)
SNS                     | DUP
NSTTTTSTSN              | JSR > 111010 (debug:printsign)
NSTTTTSTTN              | JSR > 111011 (debug:printmagnitude)
NTN                     | RTS

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ Name:
@   stdlib_version (111110)
@ Description:
@   Returns the version of the stdlib.
@   The version number should be a monotonically increasing integer.
@ Call Stack:
@   <empty>   <-- TOS
@ Return Stack:
@   version_number  <-- TOS
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NSSVTTTTTSN             | Mark: 111110 (debug:printsignednumber)
SSSTN                   | PUSH 1 (version)
NTN                     | RTS

#endif