From: Aaron Taylor Date: Mon, 30 Mar 2020 03:36:13 +0000 (-0700) Subject: Added a 'Hello, World!" tutorial that links Whitespace example to VVhitespace+stdlib. X-Git-Url: http://git.subgeniuskitty.com/vvhitespace/.git/commitdiff_plain/048de9cca66e794792a0961ac9019833803389b1 Added a 'Hello, World!" tutorial that links Whitespace example to VVhitespace+stdlib. --- diff --git a/examples/tutorial_1_hello_world/Makefile b/examples/tutorial_1_hello_world/Makefile new file mode 100644 index 0000000..94fca51 --- /dev/null +++ b/examples/tutorial_1_hello_world/Makefile @@ -0,0 +1,17 @@ +# (c) 2019 Aaron Taylor +# See LICENSE.txt file for copyright and license details. + +include ../config.mk + +all: hello + +hello: + @$(CPP) $(CPP_FLAGS) -o temp.pvvs hello.pvvs + @$(VVS_COMPILER) -i temp.pvvs -o hello.vvs + @rm -f temp.pvvs + +run: hello + @$(VVS_INTERPRETER) -i hello.vvs + +clean: + @rm -f hello.vvs temp.pvvs diff --git a/examples/tutorial_1_hello_world/README.md b/examples/tutorial_1_hello_world/README.md new file mode 100644 index 0000000..b49b706 --- /dev/null +++ b/examples/tutorial_1_hello_world/README.md @@ -0,0 +1,138 @@ +# Overview # + +This example starts with the `Hello, world!` example from Wikipedia's +Whitespace page, gradually rewriting it to use the ASCII string feature of the +VVhitespace compiler and the `printf` subroutine from the stdlib. + +# "Hello, World!" in VVhitespace # + +Wikipedia's `Hello, World!` example is reproduced below. It follows a simple +form, pushing an integer corresponding to an ASCII character onto the stack and +then printing it with an IO instruction, repeating this two part process for +each character before terminating with the final instruction. + + SSSTSSTSSSN | Push +72 (ASCII H) + TNSS | Output character + SSSTTSSTSTN | Push +101 (ASCII e) + TNSS | Output character + SSSTTSTTSSN | Push +108 (ASCII l) + TNSS | Output character + SSSTTSTTSSN | Push +108 (ASCII l) + TNSS | Output character + SSSTTSTTTTN | Push +111 (ASCII o) + TNSS | Output character + SSSTSTTSSN | Push +44 (ASCII ,) + TNSS | Output character + SSSTSSSSSN | Push +32 (ASCII space) + TNSS | Output character + SSSTTTSTTTN | Push +119 (ASCII w) + TNSS | Output character + SSSTTSTTTTN | Push +111 (ASCII o) + TNSS | Output character + SSSTTTSSTSN | Push +114 (ASCII r) + TNSS | Output character + SSSTTSTTSSN | Push +108 (ASCII l) + TNSS | Output character + SSSTTSSTSSN | Push +100 (ASCII d) + TNSS | Output character + SSSTSSSSTN | Push +33 (ASCII !) + TNSS | Output character + SSSTSTSN | Push +10 (ASCII '\n') + TNSS | Output character + NNN | Terminate program + +If we push the string onto the stack in reverse order we can rearrange the +code as shown below. Now we're first pushing all the ASCII characters onto the +stack, then printing them all at once. + + SSSTSTSN | Push +10 (ASCII '\n') + SSSTSSSSTN | Push +33 (ASCII !) + SSSTTSSTSSN | Push +100 (ASCII d) + SSSTTSTTSSN | Push +108 (ASCII l) + SSSTTTSSTSN | Push +114 (ASCII r) + SSSTTSTTTTN | Push +111 (ASCII o) + SSSTTTSTTTN | Push +119 (ASCII w) + SSSTSSSSSN | Push +32 (ASCII space) + SSSTSTTSSN | Push +44 (ASCII ,) + SSSTTSTTTTN | Push +111 (ASCII o) + SSSTTSTTSSN | Push +108 (ASCII l) + SSSTTSTTSSN | Push +108 (ASCII l) + SSSTTSSTSTN | Push +101 (ASCII e) + SSSTSSTSSSN | Push +72 (ASCII H) + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + NNN | Terminate program + +As a convenience, the VVhitespace compiler will accept `A""` syntax, generating +a sequence of `PUSH` instructions, just like the prior examples, that places a +null-terminated ASCII string on the stack. This allows us to shorten the +program. Like before, the start of the string is closest to the top of the +stack. Unlike before, there is now a null terminator at the end of the string. +For now, we'll just leave that on the stack when the program terminates. + + A"Hello, world!\n" + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + TNSS | Output character + NNN | Terminate program + +Finally, we will use `printf` from the stdlib to shorten that mass of IO +instructions. Every stdlib subroutine includes a text description as well as +diagrams of the call and return stack. From `stdio.pvvs` we see the call stack +for `printf` reproduced below. + + Call Stack: + ACSII '\0' + string word n + ... + string word 1 + substitution n + ... + substitution 1 + number of substitutions <-- TOS + +The text description for `printf` also informs us that, if we are printing a +static string (i.e. no substitutions like '%d'), the `number of substitutions` +should be `0` and it should be immediately followed by `string word 1`. Looking +at the call stack, that makes sense since we have no substitutions to place +between those two things. + +Note the ASCII `\0` on the call stack. That corresponds to the null terminator +at the end of our string that was automatically placed by the `A""` syntax. + +Don't forget to `#include` the relevant stdlib files. This is done at the +bottom of the file since VVhitespace files are executed from top to bottom. You +wouldn't want to accidentally start executing random library code! + +Putting all that together, we discover a greatly simplified program. + + A"Hello, world!\n" + SSSSN | PUSH 0 (number of substitutions) + NSTTSSSN | JSR > 1000 (stdlib:printf) + NNN | Terminate program + #include + +This is already saved in `hello.pvvs` which you can execute with `make run`. diff --git a/examples/tutorial_1_hello_world/hello.pvvs b/examples/tutorial_1_hello_world/hello.pvvs new file mode 100644 index 0000000..507437e --- /dev/null +++ b/examples/tutorial_1_hello_world/hello.pvvs @@ -0,0 +1,8 @@ +@@ This program outputs "Hello, world!" + +A"Hello, world!\n" +SSSSN | ST: PUSH 0 +NSTTSSSN | FC: JSR>1000 (printf; see stdlib) +NNN | FC: Terminate program + +#include