[1/?] Add ability to run code examples in the playground: Move code s…

…amples to separate files (#544)


* top-level `/code-samples` directory
* flat structure within `/code-samples`
* file names within `/code-samples` having the page name, they are _primarily_ used in as a prefix
    * a few files only consist of said prefix
* file names consist of `[a-z-]`
* code samples are embedded, using the [snippet](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files) feature with the two dashes each syntax (`--8<--`)
* code samples are reused when the same code is used elsewhere or lines from it ([snippet lines](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippet-lines) syntax). Code sample reuse, that could only be achieved by the [block format](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#block-format) is not done
* code samples currently have no new line at EOF
* we currently have code samples in the following languages:
    * pony (_see below_)
    * Bash (`.sh`; 13)
    * C (9)
    * Error (`.txt`; 3)

= 313 code samples, 298 unique snippets

.gitignore

@@ -7,4 +7,7 @@
 /site
 
 # Caches and logs
-*.log
+*.log
+
+# vscode
+/.vscode

code-samples/actors-behaviors.pony

@@ -0,0 +1,9 @@
+actor Aardvark
+  let name: String
+  var _hunger_level: U64 = 0
+
+  new create(name': String) =>
+    name = name'
+
+  be eat(amount: U64) =>
+    _hunger_level = _hunger_level - amount.min(_hunger_level)

code-samples/actors-sequential.pony

@@ -0,0 +1,7 @@
+actor Main
+  new create(env: Env) =>
+    call_me_later(env)
+    env.out.print("This is printed first")
+
+  be call_me_later(env: Env) =>
+    env.out.print("This is printed last")

code-samples/aliasing-alias-types.pony

@@ -0,0 +1,2 @@
+fun test(a: A) =>
+  var b: A! = a

code-samples/aliasing-ephemeral-types.pony

@@ -0,0 +1,2 @@
+fun test(a: Wombat iso): Wombat iso^ =>
+  consume a

code-samples/aliasing-iso-to-tag.pony

@@ -0,0 +1,2 @@
+fun test(a: Wombat iso) =>
+  var b: Wombat tag = a // Allowed!

code-samples/aliasing-multiple-references-to-an-iso-object.pony

@@ -0,0 +1,2 @@
+fun test(a: Wombat iso) =>
+  var b: Wombat iso = a // Not allowed!

code-samples/aliasing-trn-to-box.pony

@@ -0,0 +1,2 @@
+fun test(a: Wombat trn) =>
+  var b: Wombat box = a // Allowed!

code-samples/appendices-annotations-empty-with-nosupertype-annotation.pony

@@ -0,0 +1,7 @@
+class \nosupertype\ Empty
+
+class Foo
+  fun foo[A: Any](a: (A | Empty val)) =>
+    match consume a
+    | let a': A => None
+    end

code-samples/appendices-annotations-empty-without-nosupertype-annotation.pony

@@ -0,0 +1,7 @@
+class Empty
+
+class Foo
+  fun foo[A: Any](a: (A | Empty val)) =>
+    match consume a
+    | let a': A => None
+    end

code-samples/appendices-annotations-likely-and-unlikely-annotations.pony

@@ -0,0 +1,16 @@
+if \likely\ cond then
+  foo
+end
+
+while \unlikely\ cond then
+  bar
+end
+
+repeat
+  baz
+until \likely\ cond end
+
+match obj
+| \likely\ expr => foo
+| \unlikely\ let capt: T => bar
+end

code-samples/appendices-annotations-nodoc-annotation.pony

@@ -0,0 +1,4 @@
+class \nodoc\Foo
+   """
+   We don't want this class and its methods to appear in generated documentation
+   """

code-samples/appendices-annotations-packed-annotation.pony

@@ -0,0 +1,3 @@
+struct \packed\ MyPackedStruct
+  var x: U8
+  var y: U32

code-samples/appendices-annotations-syntax.pony

@@ -0,0 +1 @@
+\annotation1, annotation2\

code-samples/appendices-examples-access-command-line-arguments.pony

@@ -0,0 +1,9 @@
+actor Main
+  new create(env: Env) =>
+    // The no of arguments
+    env.out.print(env.args.size().string())
+    for value in env.args.values() do
+      env.out.print(value)
+    end
+    // Access the arguments the first one will always be the application name
+    try env.out.print(env.args(0)?) end

code-samples/appendices-examples-create-arrays-with-values.pony

@@ -0,0 +1,5 @@
+let dice: Array[U32] = [1; 2; 3
+  4
+  5
+  6
+]

code-samples/appendices-examples-empty-class-functions.pony

@@ -0,0 +1,7 @@
+class Test
+  fun alpha() =>
+    """
+    """
+  fun beta() =>
+    """
+    """

code-samples/appendices-examples-enumeration-with-values-with-namespace.pony

@@ -0,0 +1,3 @@
+primitive Colours
+  fun black(): U32 => 0xFF000000
+  fun red(): U32 => 0xFFFF0000

code-samples/appendices-examples-enumeration-with-values.pony

@@ -0,0 +1,2 @@
+primitive Black fun apply(): U32 => 0xFF000000
+primitive Red   fun apply(): U32 => 0xFFFF0000

code-samples/appendices-examples-iterable-enumerations.pony

@@ -0,0 +1,13 @@
+primitive Black
+primitive Blue
+primitive Red
+primitive Yellow
+
+type Colour is (Black | Blue | Red | Yellow)
+
+primitive ColourList
+  fun tag apply(): Array[Colour] =>
+    [Black; Blue; Red; Yellow]
+
+for colour in ColourList().values() do
+end

code-samples/appendices-examples-modify-a-lexically-captured-variable-in-a-closure.pony

@@ -0,0 +1,16 @@
+actor Main
+  fun foo(n:U32): {ref(U32): U32} =>
+    var s: Array[U32] = Array[U32].init(n, 1)
+    {ref(i:U32)(s): U32 =>
+      try
+        s(0)? = s(0)? + i
+        s(0)?
+      else
+        0
+      end
+    }
+
+  new create(env:Env) =>
+    var f = foo(5)
+    env.out.print(f(10).string())
+    env.out.print(f(20).string())

code-samples/appendices-examples-operator-overloading.pony

@@ -0,0 +1,17 @@
+fun add(other: A): A
+fun sub(other: A): A
+fun mul(other: A): A
+fun div(other: A): A
+fun rem(other: A): A
+fun mod(other: A): A
+fun eq(other: A): Bool
+fun ne(other: A): Bool
+fun lt(other: A): Bool
+fun le(other: A): Bool
+fun ge(other: A): Bool
+fun gt(other: A): Bool
+fun shl(other: A): A
+fun shr(other: A): A
+fun op_and(other:A): A
+fun op_or(other: A): A
+fun op_xor(othr: A): A

code-samples/appendices-examples-pass-array-of-values-to-ffi.pony

@@ -0,0 +1,18 @@
+use @eglChooseConfig[U32](disp: Pointer[_EGLDisplayHandle], attrs: Pointer[U16] tag,
+  config: Pointer[_EGLConfigHandle], config_size: U32, num_config: Pointer[U32])
+
+primitive _EGLConfigHandle
+let a = Array[U16](8)
+a.push(0x3040)
+a.push(0x4)
+a.push(0x3033)
+a.push(0x4)
+a.push(0x3022)
+a.push(0x8)
+a.push(0x3023)
+a.push(0x8)
+a.push(0x3024)
+let config = Pointer[_EGLConfigHandle]
+if @eglChooseConfig(e_dpy, a.cpointer(), config, U32(1), Pointer[U32]) == 0 then
+    env.out.print("eglChooseConfig failed")
+end

code-samples/appendices-examples-test-helper.pony

@@ -0,0 +1,15 @@
+fun tag log(msg: String, verbose: Bool = false)
+be fail() =>
+be assert_failed(msg: String) =>
+fun tag assert_true(actual: Bool, msg: String = "") ?
+fun tag expect_true(actual: Bool, msg: String = ""): Bool
+fun tag assert_false(actual: Bool, msg: String = "") ?
+fun tag expect_false(actual: Bool, msg: String = ""): Bool
+fun tag assert_error(test: ITest, msg: String = "") ?
+fun tag expect_error(test: ITest box, msg: String = ""): Bool
+fun tag assert_is (expect: Any, actual: Any, msg: String = "") ?
+fun tag expect_is (expect: Any, actual: Any, msg: String = ""): Bool
+fun tag assert_eq[A: (Equatable[A] #read & Stringable)]
+  (expect: A, actual: A, msg: String = "") ?
+fun tag expect_eq[A: (Equatable[A] #read & Stringable)]
+  (expect: A, actual: A, msg: String = ""): Bool

code-samples/appendices-examples-use-cli-package-to-parse-command-line-arguments.pony

@@ -0,0 +1,32 @@
+use "cli"
+
+actor Main
+  new create(env: Env) =>
+    let command_spec =
+      try
+        CommandSpec.leaf(
+          "pony-embed",
+          "sample program",
+          [ OptionSpec.string("output", "output filename", 'o') ],
+          [ ArgSpec.string("input", "source of input" where default' = "-") ]
+        )? .> add_help()?
+      else
+        env.exitcode(1)
+        return
+      end
+    let command =
+      match CommandParser(command_spec).parse(env.args, env.vars)
+      | let c: Command => c
+      | let ch: CommandHelp =>
+        ch.print_help(env.out)
+        env.exitcode(0)
+        return
+      | let se: SyntaxError =>
+        env.err.print(se.string())
+        env.exitcode(1)
+        return
+      end
+    let input_source = command.arg("input").string()
+    let output_filename = command.option("output").string()
+    env.out.print("Loading data from " + input_source + ". Writing output to " + output_filename)
+    // ...

code-samples/appendices-examples-write-tests.pony

@@ -0,0 +1,17 @@
+use "pony_test"
+
+actor Main is TestList
+  new create(env: Env) => PonyTest(env, this)
+  new make() => None
+
+  fun tag tests(test: PonyTest) =>
+    test(_TestAddition)
+
+class iso _TestAddition is UnitTest
+  """
+  Adding 2 numbers
+  """
+  fun name(): String => "u32/add"
+
+  fun apply(h: TestHelper) =>
+    h.assert_eq[U32](2 + 2, 4)

code-samples/appendices-platform-dependent-code.pony

@@ -0,0 +1,2 @@
+use "foo" if linux
+use "bar" if (windows and debug)

code-samples/appendices-serialization-compare-original-object-with-deserialized-object.pony

@@ -0,0 +1,40 @@
+use "serialise"
+
+class Foo is Equatable[Foo box]
+  let _s: String
+  let _u: U32
+
+  new create(s: String, u: U32) =>
+    _s = s
+    _u = u
+
+  fun eq(foo: Foo box): Bool =>
+    (_s == foo._s) and (_u == foo._u)
+
+actor Main
+  new create(env: Env) =>
+    try
+      // get serialization authorities
+      let serialise = SerialiseAuth(env.root)
+      let output = OutputSerialisedAuth(env.root)
+      let deserialise = DeserialiseAuth(env.root)
+      let input = InputSerialisedAuth(env.root)
+
+      let foo1 = Foo("abc", 123)
+
+      // serialisation
+      let sfoo = Serialised(serialise, foo1)?
+      let bytes_foo: Array[U8] val = sfoo.output(output)
+
+      env.out.print("serialised representation is " +
+        bytes_foo.size().string() +
+        " bytes long")
+
+      // deserialisation
+      let dfoo = Serialised.input(input, bytes_foo)
+      let foo2 = dfoo(deserialise)? as Foo
+
+      env.out.print("(foo1 == foo2) is " + (foo1 == foo2).string())
+    else
+      env.err.print("there was an error")
+    end

code-samples/appendices-serialization-custom-serialization.pony

@@ -0,0 +1,42 @@
+use "serialise"
+
+use "lib:custser"
+
+use @get_string[Pointer[U8]]()
+use @serialise_space[USize](s: Pointer[U8] tag)
+use @serialise[None](bytes: Pointer[U8] tag, str: Pointer[U8] tag)
+use @deserialise[Pointer[U8] tag](bytes: Pointer[U8] tag)
+use @printf[I32](fmt: Pointer[U8] tag, ...)
+
+class CStringWrapper
+  var _cstr: Pointer[U8] tag
+
+  new create(cstr: Pointer[U8] tag) =>
+    _cstr = cstr
+
+  fun _serialise_space(): USize =>
+    @serialise_space(_cstr)
+
+  fun _serialise(bytes: Pointer[U8] tag) =>
+    @serialise(bytes, _cstr)
+
+  fun ref _deserialise(bytes: Pointer[U8] tag) =>
+    _cstr = @deserialise(bytes)
+
+  fun print() =>
+    @printf(_cstr)
+
+actor Main
+  new create(env: Env) =>
+    let csw = CStringWrapper(@get_string())
+    csw.print()
+    try
+      let serialise = SerialiseAuth(env.root)
+      let deserialise = DeserialiseAuth(env.root)
+
+      let sx = Serialised(serialise, csw)?
+      let y = sx(deserialise)? as CStringWrapper
+      y.print()
+    else
+      env.err.print("there was an error")
+    end

code-samples/appendices-whitespace-comments.pony

@@ -0,0 +1,3 @@
+// This is a line comment.
+/* This is a block comment. */
+/* This block comment /* has another block comment */ inside of it. */

code-samples/appendices-whitespace-do-a-then-do-a-unary-negation-of-b.pony

@@ -0,0 +1,2 @@
+a
+-b