X-Git-Url: http://git.subgeniuskitty.com/vvhitespace/.git/blobdiff_plain/00ec7afcb1111d36f334292f8575660af92d3432..e3dfa9e4d24186cdb143ca6e05d54448049a564f:/examples/hello_world/README.md diff --git a/examples/hello_world/README.md b/examples/hello_world/README.md new file mode 100644 index 0000000..b49b706 --- /dev/null +++ b/examples/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`.