From: Aaron Taylor Date: Mon, 30 Mar 2020 05:20:10 +0000 (-0700) Subject: Moving `examples/hello_world` -> `examples/hello-world` to match other examples. X-Git-Url: http://git.subgeniuskitty.com/vvhitespace/.git/commitdiff_plain/31f53e886387b23ccaa5777bf4f4692da50c3e4d?hp=07331ceeb01f6045ddf02e0aba05752ef1ea8838 Moving `examples/hello_world` -> `examples/hello-world` to match other examples. --- diff --git a/examples/hello-world/Makefile b/examples/hello-world/Makefile new file mode 100644 index 0000000..94fca51 --- /dev/null +++ b/examples/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/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`. diff --git a/examples/hello-world/hello.pvvs b/examples/hello-world/hello.pvvs new file mode 100644 index 0000000..507437e --- /dev/null +++ b/examples/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 diff --git a/examples/hello_world/Makefile b/examples/hello_world/Makefile deleted file mode 100644 index 94fca51..0000000 --- a/examples/hello_world/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# (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/hello_world/README.md b/examples/hello_world/README.md deleted file mode 100644 index b49b706..0000000 --- a/examples/hello_world/README.md +++ /dev/null @@ -1,138 +0,0 @@ -# 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/hello_world/hello.pvvs b/examples/hello_world/hello.pvvs deleted file mode 100644 index 507437e..0000000 --- a/examples/hello_world/hello.pvvs +++ /dev/null @@ -1,8 +0,0 @@ -@@ 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