refactor(code-samples): 📝 Revert non-pony code samples

Co-authored-by: Joe Eli McIlvain <[email protected]>

As requested in ponylang#544 (comment)

From db1eb11

docs/appendices/compiler-args.md

@@ -3,7 +3,7 @@
 `ponyc`, the compiler, is usually called in the project directory, where it finds the `.pony` files and its dependencies automatically. There it will create the binary based on the directory name. You can override this and tune the compilation with several options as described via `ponyc --help` and you can pass a separate source directory as an argument.
 
 ```bash
---8<-- "appendices-compiler-args-ponyc.sh"
+ponyc [OPTIONS] <package directory>
 ```
 
 The most useful options are `--debug`, `--path` or just `-p`, `--output` or just `-o` and `--docs` or `-g`.

docs/appendices/error-messages.md

@@ -19,7 +19,14 @@ Suppose you wrote:
 The error message would be:
 
 ```error
---8<-- "error-messages-left-side-must-be-something-that-can-be-assigned-to-error-message.txt"
+Error:
+main.pony:4:5: can't assign to a let or embed definition more than once
+    x = 12
+    ^
+Error:
+main.pony:4:7: left side must be something that can be assigned to
+    x = 12
+      ^
 ```
 
 What happened is that you declared `x` as a constant, by writing `let x`, and then tried to assign a new value to it, 12. To fix the error, replace `let` with `var` or reconsider what value you want `x` to have.
@@ -37,7 +44,10 @@ Suppose you create a class with a mutable field and added a method to change the
 The error message would be:
 
 ```error
---8<-- "error-messages-left-side-is-immutable-error-message.txt"
+Error:
+main.pony:4:11: left side is immutable
+    color = new_color
+          ^
 ```
 
 To understand this error message, you have to have some background. The field `color` is mutable since it is declared with `var`, but the method `dye` does not have an explicit receiver reference capability. The default receiver reference capability is `box`, which allows `dye` to be called on any mutable or immutable `Wombat`; the `box` reference capability says that the method may read from but not write to the receiver. As a result, it is illegal to attempt to modify the receiver in the method.
@@ -57,7 +67,23 @@ In this example, rather than trying to change the value of a field, the code cal
 The problem is very similar to that of the last section, but the error message is significantly more complicated:
 
 ```error
---8<-- "error-messages-receiver-type-is-not-a-subtype-of-target-type-error-message.txt"
+Error:
+main.pony:4:16: receiver type is not a subtype of target type
+    colors.push(color)
+               ^
+    Info:
+    main.pony:4:5: receiver type: this->Array[String val] ref (which becomes 'Array[String val] box' in this context)
+        colors.push(color)
+        ^
+    /root/.local/share/ponyup/ponyc-release-0.58.0-x86_64-linux-musl/packages/builtin/array.pony:623:3: target type: Array[String val] ref^
+      fun ref push(value: A) =>
+      ^
+    main.pony:2:15: Array[String val] box is not a subtype of Array[String val] ref^: box is not a subcap of ref^
+      let colors: Array[String] = Array[String]
+                  ^
+    main.pony:3:3: you are trying to change state in a box function; this would be possible in a ref function
+      fun add_stripe(color: String) =>
+      ^
 ```
 
 Once again, Pony is trying to be helpful. The first few lines describe the error, in general terms that only a programming language maven would like: an incompatibility between the receiver type and the target type. However, Pony provides more information: the lines immediately after "Info:" tell you what it believes the receiver type to be and the next few lines describe what it believes the target type to be. Finally, the last few lines describe in detail what the problem is.

docs/appendices/ponypath.md

@@ -11,7 +11,7 @@ Assuming you just placed new Pony code under a directory called `pony` in your h
 Edit/add the `rc` file corresponding to your chosen shell (`echo $SHELL` will tell you what shell you are running). For example, if using bash, add the following to your `~/.bashrc`:
 
 ```bash
---8<-- "ponypath-unix-mac.sh"
+export PONYPATH=$PONYPATH:$HOME/pony
 ```
 
 (Then run `source ~/.bashrc` to add this variable to a running session. New terminal session will automatically source `~/.bashrc`.)
@@ -30,5 +30,5 @@ Edit/add the `rc` file corresponding to your chosen shell (`echo $SHELL` will te
 You can also add to `PONYPATH` from the command prompt via:
 
 ```bash
---8<-- "ponypath-windows.sh"
+setx PONYPATH %PONYPATH%;%USERPROFILE%\pony
 ```

docs/appendices/serialisation.md

@@ -62,5 +62,43 @@ Assume we have a Pony class with a field that is a pointer to a C string. We wou
 ```
 
 ```c
---8<-- "appendices-serialization-custom-serialization.c"
+// custser.c
+
+#include <stdlib.h>
+#include <string.h>
+
+extern char *get_string()
+{
+  return "hello world\n";
+}
+
+extern size_t serialise_space(char *s)
+{
+  // space for the size and the string (without the null)
+  return 4 + strlen(s);
+}
+
+extern void serialise(char *buff, char *s)
+{
+  size_t sz = strlen(s);
+  unsigned char *ubuff = (unsigned char *) buff;
+  // write the size as a 32-bit big-endian integer
+  ubuff[0] = (sz >> 24) & 0xFF;
+  ubuff[1] = (sz >> 16) & 0xFF;
+  ubuff[2] = (sz >> 8) & 0xFF;
+  ubuff[3] = sz & 0xFF;
+
+  // copy the string
+  strncpy(buff + 4, s, sz);
+}
+
+extern char *deserialise(char *buff)
+{
+  unsigned char *ubuff = (unsigned char *) buff;
+  size_t sz = (ubuff[0] << 24) + (ubuff[1] << 16) + (ubuff[2] << 8) + ubuff[3];
+  char *s = malloc(sizeof(char) * sz + 1);
+  memcpy(s, buff + 4, sz);
+  s[sz] = '\0';
+  return s;
+}
 ```

docs/c-ffi/c-abi.md

@@ -15,21 +15,47 @@ Let's look at a complete example of a C function we may wish to provide to Pony.
 Let's say we wish to compare the pure Pony performance to an existing C function with the following header:
 
 ```c
---8<-- "c-abi-jump-consistent-hashing-header.c"
+#ifndef __JCH_H_
+#define __JCH_H_
+
+extern "C"
+{
+  int32_t jch_chash(uint64_t key, uint32_t num_buckets);
+}
+
+#endif
 ```
 
 Note the use of `extern "C"`. If the library is built as C++ then we need to tell the compiler not to mangle the function name, otherwise, Pony won't be able to find it. For libraries built as C, this is not needed, of course.
 
 The implementation of the previous header would be something like:
 
 ```c
---8<-- "c-abi-jump-consistent-hashing-implementation.c"
+#include <stdint.h>
+
+// A fast, minimal memory, consistent hash algorithm
+// https://arxiv.org/abs/1406.2294
+int32_t jch_chash(uint64_t key, uint32_t num_buckets)
+{
+  int b = -1;
+  uint64_t j = 0;
+
+  do {
+    b = j;
+    key = key * 2862933555777941757ULL + 1;
+    j = (b + 1) * ((double)(1LL << 31) / ((double)(key >> 33) + 1));
+  } while(j < num_buckets);
+
+  return (int32_t)b;
+}
 ```
 
 We need to compile the native code to a shared library. This example is for MacOS. The exact details may vary on other platforms.
 
 ```bash
---8<-- "c-abi-compile-jump-consistent-hashing-for-macos.sh"
+clang -fPIC -Wall -Wextra -O3 -g -MM jch.c >jch.d
+clang -fPIC -Wall -Wextra -O3 -g  -c -o jch.o jch.c
+clang -shared -lm -o libjch.dylib jch.o
 ```
 
 The Pony code to use this new C library is just like the code we've already seen for using C libraries.

docs/c-ffi/callbacks.md

@@ -39,7 +39,10 @@ Bare lambdas can also be used to define structures containing function pointers.
 This Pony structure is equivalent to the following C structure:
 
 ```c
---8<-- "c-ffi-callbacks-struct-with-function-pointers.c"
+struct S
+{
+  void(*fun_ptr)();
+};
 ```
 
 In the same vein as bare functions, bare lambdas cannot specify captures, cannot use `this` neither as an identifier nor as a type, and cannot specify a receiver capability. In addition, a bare lambda object always has a `val` capability.
@@ -51,7 +54,22 @@ Classic lambda types and bare lambda types can never be subtypes of each other.
 Consider SQLite, mentioned earlier. When the client code calls `sqlite3_exec`, an SQL query is executed against a database, and the callback function is called for each row returned by the SQL statement. Here's the signature for `sqlite3_exec`:
 
 ```c
---8<-- "c-ffi-callbacks-sqlite3-callback.c"
+typedef int (*sqlite3_callback)(void*,int,char**, char**);
+
+...
+
+SQLITE_API int SQLITE_STDCALL sqlite3_exec(
+sqlite3 *db,                /* The database on which the SQL executes */
+const char *zSql,           /* The SQL to be executed */
+sqlite3_callback xCallback, /* Invoke this callback routine */
+void *pArg,                 /* First argument to xCallback() */
+char **pzErrMsg             /* Write error messages here */
+)
+{
+  ...
+  xCallback(pArg, nCol, azVals, azCols)
+  ...
+}
 ```
 
 `sqlite3_callback` is the type of the callback function that will be called by `sqlite3_exec` for each row returned by the `sql` statement. The first argument to the callback function is the pointer `pArg` that was passed to `sqlite3_exec`, the second argument is the number of columns in the row being processed, the third argument is data for each column, and the fourth argument is the name of each column.