From a568fe2c9cc324e2554e3b084ce667ff6c7f9da2 Mon Sep 17 00:00:00 2001 From: Sean McBride Date: Mon, 20 Nov 2023 17:30:26 -0500 Subject: [PATCH] Docs/wat function comments (#90) --- exercises/practice/acronym/acronym.wat | 9 + .../practice/all-your-base/all-your-base.wat | 10 +- .../armstrong-numbers/armstrong-numbers.wat | 8 +- .../practice/bank-account/bank-account.wat | 34 ++- .../practice/binary-search/binary-search.wat | 11 +- .../circular-buffer/circular-buffer.wat | 40 ++- .../collatz-conjecture/collatz-conjecture.wat | 7 + exercises/practice/darts/darts.wat | 8 + .../difference-of-squares.wat | 26 +- exercises/practice/grains/grains.wat | 18 +- exercises/practice/hamming/hamming.wat | 11 + .../practice/hello-world/hello-world.wat | 8 +- exercises/practice/leap/leap.wat | 8 +- .../nucleotide-count/nucleotide-count.wat | 11 + exercises/practice/pangram/pangram.wat | 9 +- exercises/practice/pop-count/pop-count.wat | 7 + exercises/practice/raindrops/raindrops.wat | 8 + .../resistor-color/resistor-color.wat | 20 +- .../reverse-string/reverse-string.wat | 8 + .../rna-transcription/rna-transcription.wat | 8 + .../rotational-cipher/rotational-cipher.wat | 9 + .../practice/square-root/square-root.wat | 7 + exercises/practice/triangle/triangle.wat | 27 ++ exercises/practice/two-fer/two-fer.wat | 9 + exercises/shared/.docs/help.md | 271 ++++++++++++++++++ 25 files changed, 560 insertions(+), 32 deletions(-) diff --git a/exercises/practice/acronym/acronym.wat b/exercises/practice/acronym/acronym.wat index a2d44dd..02c6707 100644 --- a/exercises/practice/acronym/acronym.wat +++ b/exercises/practice/acronym/acronym.wat @@ -1,6 +1,15 @@ (module (memory (export "mem") 1) + ;; + ;; Converts a phrase into an acronym + ;; i.e. "Ruby on Rails" -> "ROR" + ;; + ;; @param {i32} offset - offset of phrase in linear memory + ;; @param {i32} length - length of phrase in linear memory + ;; + ;; @return {(i32, i32)} - offset and length of acronym + ;; (func (export "parse") (param $offset i32) (param $length i32) (result i32 i32) (return (local.get $offset) (local.get $length)) ) diff --git a/exercises/practice/all-your-base/all-your-base.wat b/exercises/practice/all-your-base/all-your-base.wat index c790c57..2b745a1 100644 --- a/exercises/practice/all-your-base/all-your-base.wat +++ b/exercises/practice/all-your-base/all-your-base.wat @@ -9,12 +9,14 @@ ;; ;; Convert an array of digits in inputBase to an array of digits in outputBase - ;; @param {i32} arrOffset - base offset of input u32[] array - ;; @param {i32} arrLength - length of the input u32[] array in elements + ;; + ;; @param {i32} arrOffset - offset of input u32[] array + ;; @param {i32} arrLength - length of input u32[] array in elements ;; @param {i32} inputBase - base of the input array ;; @param {i32} outputBase - base of the output array - ;; @return {i32} - base offset of the output u32[] array - ;; @return {i32} - length of the output u32[] array in elements + ;; + ;; @return {i32} - offset of the output u32[] array + ;; @return {i32} - length of the output u32[] array in elements ;; @return {i32} - status code (0, -1, -2, -3) ;; (func (export "convert") (param $arrOffset i32) (param $arrLength i32) (param $inputBase i32) (param $outputBase i32) (result i32 i32 i32) diff --git a/exercises/practice/armstrong-numbers/armstrong-numbers.wat b/exercises/practice/armstrong-numbers/armstrong-numbers.wat index 860cb0d..e90fa4b 100644 --- a/exercises/practice/armstrong-numbers/armstrong-numbers.wat +++ b/exercises/practice/armstrong-numbers/armstrong-numbers.wat @@ -1,5 +1,11 @@ (module - ;; returns 1 if armstrong number, 0 otherwise + ;; + ;; Determine if a number is an Armstrong number. + ;; + ;; @param {i32} candidate - The number to check. + ;; + ;; @return {i32} 1 if the number is an Armstrong number, 0 otherwise. + ;; (func (export "isArmstrongNumber") (param $candidate i32) (result i32) (i32.const 42) ) diff --git a/exercises/practice/bank-account/bank-account.wat b/exercises/practice/bank-account/bank-account.wat index 6537e67..071b1de 100644 --- a/exercises/practice/bank-account/bank-account.wat +++ b/exercises/practice/bank-account/bank-account.wat @@ -1,25 +1,49 @@ (module - ;; returns 0 on success, -1 on failure + ;; + ;; Set the state of the bank account to open. + ;; + ;; @return {i32} 0 on success, -1 on failure + ;; (func (export "open") (result i32) (i32.const 42) ) - ;; returns 0 on success, -1 on failure + ;; + ;; Set the state of the bank account to closed. + ;; + ;; @return {i32} 0 on success, -1 on failure + ;; (func (export "close") (result i32) (i32.const 42) ) - ;; returns 0 on success, -1 if account closed, -2 if amount negative + ;; + ;; Deposit the given amount into the bank account. + ;; + ;; @param {i32} amount - The amount to deposit + ;; + ;; @return {i32} 0 on success, -1 if account closed, -2 if amount negative + ;; (func (export "deposit") (param $amount i32) (result i32) (i32.const 42) ) - ;; returns 0 on success, -1 if account closed, -2 if amount invalid + ;; + ;; Withdraw the given amount from the bank account. + ;; + ;; @param {i32} amount - The amount to withdraw + ;; + ;; @return {i32} 0 on success, -1 if account closed, -2 if amount invalid + ;; (func (export "withdraw") (param $amount i32) (result i32) (i32.const 42) ) - ;; returns balance on success, -1 if account closed + ;; + ;; Get the current balance of the bank account. + ;; + ;; @return {i32} balance on success, -1 if account closed + ;; (func (export "balance") (result i32) (i32.const 42) ) diff --git a/exercises/practice/binary-search/binary-search.wat b/exercises/practice/binary-search/binary-search.wat index e20f591..1d6ed22 100644 --- a/exercises/practice/binary-search/binary-search.wat +++ b/exercises/practice/binary-search/binary-search.wat @@ -1,7 +1,16 @@ (module (memory (export "mem") 1) - ;; Assumes size of i32 + ;; + ;; Find the first occurrence of the needle in the haystack + ;; + ;; @param {i32} base - the base address of the haystack + ;; @param {i32} nelems - the number of elements in the haystack + ;; @param {i32} needle - the value to search for + ;; + ;; @return {i32} the index of the first occurrence of the needle in the haystack + ;; or -1 if the needle is not found. + ;; (func (export "find") (param $base i32) (param $nelems i32) (param $needle i32) (result i32) (i32.const 42) ) diff --git a/exercises/practice/circular-buffer/circular-buffer.wat b/exercises/practice/circular-buffer/circular-buffer.wat index 6a3cf6d..426f93d 100644 --- a/exercises/practice/circular-buffer/circular-buffer.wat +++ b/exercises/practice/circular-buffer/circular-buffer.wat @@ -2,30 +2,54 @@ (memory 1) ;; Add globals here! - ;; newCapacity is a capacity between 0 and 1024 - ;; a WebAssembly page is 4096 bytes, so up to 1024 i32s - ;; returns 0 on success or -1 on error + ;; + ;; Initialize a circular buffer of i32s with a given capacity + ;; + ;; @param {i32} newCapacity - capacity of the circular buffer between 0 and 1024 + ;; in order to fit in a single WebAssembly page + ;; + ;; @returns {i32} 0 on success or -1 on error + ;; (func (export "init") (param $newCapacity i32) (result i32) (i32.const 42) ) + ;; + ;; Clear the circular buffer + ;; (func (export "clear") (nop) ) - ;; returns 0 on success or -1 on error + ;; + ;; Add an element to the circular buffer + ;; + ;; @param {i32} elem - element to add to the circular buffer + ;; + ;; @returns {i32} 0 on success or -1 if full + ;; (func (export "write") (param $elem i32) (result i32) (i32.const 42) ) - ;; returns 0 on success or -1 on error + ;; + ;; Add an element to the circular buffer, overwriting the oldest element + ;; if the buffer is full + ;; + ;; @param {i32} elem - element to add to the circular buffer + ;; + ;; @returns {i32} 0 on success or -1 if full (capacity of zero) + ;; (func (export "forceWrite") (param $elem i32) (result i32) (i32.const 42) ) - ;; Returns Go-style error handling tuple (i32, i32) - ;; The first element of the return tuple is the returned value or -1 on error - ;; The second element should be 0 on success or -1 on error + ;; + ;; Read the oldest element from the circular buffer, if not empty + ;; + ;; @returns {i32} element on success or -1 if empty + ;; @returns {i32} status code set to 0 on success or -1 if empty + ;; (func (export "read") (result i32 i32) (return (i32.const 42) (i32.const 42)) ) diff --git a/exercises/practice/collatz-conjecture/collatz-conjecture.wat b/exercises/practice/collatz-conjecture/collatz-conjecture.wat index ecb8fef..7df8570 100644 --- a/exercises/practice/collatz-conjecture/collatz-conjecture.wat +++ b/exercises/practice/collatz-conjecture/collatz-conjecture.wat @@ -1,4 +1,11 @@ (module + ;; + ;; Return the number of steps needed to reach 1 in the Collatz conjecture. + ;; + ;; @param {i32} number - The number to start from. + ;; + ;; @returns {i32} - The number of steps needed to reach 1. + ;; (func (export "steps") (param $number i32) (result i32) (return (i32.const 42)) ) diff --git a/exercises/practice/darts/darts.wat b/exercises/practice/darts/darts.wat index 8dd9ae9..6e77abc 100644 --- a/exercises/practice/darts/darts.wat +++ b/exercises/practice/darts/darts.wat @@ -1,4 +1,12 @@ (module + ;; + ;; Score a dart throw based on its coordinates. + ;; + ;; @param {f32} x - The x coordinate of the dart. + ;; @param {f32} y - The y coordinate of the dart. + ;; + ;; @returns {i32} - The score of the dart throw (10, 5, 1, or 0). + ;; (func (export "score") (param $x f32) (param $y f32) (result i32) (return (i32.const 42)) ) diff --git a/exercises/practice/difference-of-squares/difference-of-squares.wat b/exercises/practice/difference-of-squares/difference-of-squares.wat index 3d4b71d..4540a27 100644 --- a/exercises/practice/difference-of-squares/difference-of-squares.wat +++ b/exercises/practice/difference-of-squares/difference-of-squares.wat @@ -1,15 +1,35 @@ (module - ;; The name prefixed with $ is used to internally refer to functions via the call instruction - ;; The string in the export instruction is the name of the export made available to the - ;; embedding environment (in this case, Node.js). This is used by our test runner Jest. + ;; + ;; Calculate the square of the sum of the first N natural numbers + ;; + ;; @param {i32} max - The upper bound (inclusive) of natural numbers to consider + ;; + ;; @returns {i32} The square of the sum of the first N natural numbers + ;; (func $squareOfSum (export "squareOfSum") (param $max i32) (result i32) (i32.const 42) ) + ;; + ;; Calculate the sum of the squares of the first N natural numbers + ;; + ;; @param {i32} max - The upper bound (inclusive) of natural numbers to consider + ;; + ;; @returns {i32} The sum of the squares of the first N natural numbers + ;; (func $sumOfSquares (export "sumOfSquares") (param $max i32) (result i32) (i32.const 42) ) + ;; + ;; Calculate the difference between the square of the sum and the sum of the + ;; squares of the first N natural numbers. + ;; + ;; @param {i32} max - The upper bound (inclusive) of natural numbers to consider + ;; + ;; @returns {i32} Difference between the square of the sum and the sum of the + ;; squares of the first N natural numbers. + ;; (func (export "difference") (param $max i32) (result i32) (call $squareOfSum (i32.const 42)) ) diff --git a/exercises/practice/grains/grains.wat b/exercises/practice/grains/grains.wat index 60b8d4f..6ce6eb6 100644 --- a/exercises/practice/grains/grains.wat +++ b/exercises/practice/grains/grains.wat @@ -1,11 +1,23 @@ (module - ;; squareNum is signed - ;; Result is unsigned + ;; + ;; Calculate the number of grains of wheat on the nth square of the chessboard + ;; + ;; @param {i32} squareNum - The square of the chessboard to calculate the number of grains for + ;; + ;; @returns {i64} - The number of grains of wheat on the nth square of the + ;; chessboard or 0 if the squareNum is invalid. The result + ;; is unsigned. + ;; (func $square (export "square") (param $squareNum i32) (result i64) (i64.const 42) ) - ;; Result is unsigned + ;; + ;; Calculate the sum of grains of wheat acrosss all squares of the chessboard + ;; + ;; @returns {i64} - The number of grains of wheat on the entire chessboard. + ;; The result is unsigned. + ;; (func (export "total") (result i64) (i64.const 42) ) diff --git a/exercises/practice/hamming/hamming.wat b/exercises/practice/hamming/hamming.wat index 64d7822..3ffda7b 100644 --- a/exercises/practice/hamming/hamming.wat +++ b/exercises/practice/hamming/hamming.wat @@ -1,6 +1,17 @@ (module (memory (export "mem") 1) + ;; + ;; Calculate the hamming distance between two strings. + ;; + ;; @param {i32} firstOffset - The offset of the first string in linear memory. + ;; @param {i32} firstLength - The length of the first string in linear memory. + ;; @param {i32} secondOffset - The offset of the second string in linear memory. + ;; @param {i32} secondLength - The length of the second string in linear memory. + ;; + ;; @returns {i32} - The hamming distance between the two strings or -1 if the + ;; strings are not of equal length. + ;; (func (export "compute") (param $firstOffset i32) (param $firstLength i32) (param $secondOffset i32) (param $secondLength i32) (result i32) (i32.const 42) diff --git a/exercises/practice/hello-world/hello-world.wat b/exercises/practice/hello-world/hello-world.wat index 1708562..bd7896b 100644 --- a/exercises/practice/hello-world/hello-world.wat +++ b/exercises/practice/hello-world/hello-world.wat @@ -4,8 +4,12 @@ ;; Initializes the WebAssembly Linear Memory with a UTF-8 string of 14 characters starting at offset 64 (data (i32.const 64) "Goodbye, Mars!") - ;; Returns the base offset and length of the greeting - ;; The final number (currently “14”) must match the length of the new string. + ;; + ;; Return a greeting + ;; + ;; Note: The final number (currently “14”) must match the length of the new string! + ;; + ;; @returns {(i32, i32)} The offset and length of the greeting (func (export "hello") (result i32 i32) (i32.const 64) (i32.const 14) ) diff --git a/exercises/practice/leap/leap.wat b/exercises/practice/leap/leap.wat index 35f5051..89274a7 100644 --- a/exercises/practice/leap/leap.wat +++ b/exercises/practice/leap/leap.wat @@ -1,5 +1,11 @@ (module - ;; Returns 1 if leap year, 0 otherwise + ;; + ;; Determine if a year is a leap year + ;; + ;; @param {i32} year - The year to check + ;; + ;; @returns {i32} 1 if leap year, 0 otherwise + ;; (func (export "isLeap") (param $year i32) (result i32) (i32.const 42) ) diff --git a/exercises/practice/nucleotide-count/nucleotide-count.wat b/exercises/practice/nucleotide-count/nucleotide-count.wat index 48e0fdc..be0fa2d 100644 --- a/exercises/practice/nucleotide-count/nucleotide-count.wat +++ b/exercises/practice/nucleotide-count/nucleotide-count.wat @@ -1,6 +1,17 @@ (module (memory (export "mem") 1) + ;; + ;; Count the number of each nucleotide in a DNA string. + ;; + ;; @param {i32} offset - The offset of the DNA string in memory. + ;; @param {i32} length - The length of the DNA string. + ;; + ;; @returns {(i32,i32,i32,i32)} - The number of adenine, cytosine, guanine, + ;; and thymine nucleotides in the DNA string + ;; or (-1, -1, -1, -1) if the DNA string is + ;; invalid. + ;; (func (export "countNucleotides") (param $offset i32) (param $length i32) (result i32 i32 i32 i32) (return (i32.const -1) diff --git a/exercises/practice/pangram/pangram.wat b/exercises/practice/pangram/pangram.wat index bbcb223..ae98588 100644 --- a/exercises/practice/pangram/pangram.wat +++ b/exercises/practice/pangram/pangram.wat @@ -1,7 +1,14 @@ (module (memory (export "mem") 1) - ;; return 1 if pangram, 0 otherwise + ;; + ;; Determine if a string is a pangram. + ;; + ;; @param {i32} offset - offset of string in linear memory + ;; @param {i32} length - length of string in linear memory + ;; + ;; @returns {i32} 1 if pangram, 0 otherwise + ;; (func (export "isPangram") (param $offset i32) (param $length i32) (result i32) (return (i32.const 1)) ) diff --git a/exercises/practice/pop-count/pop-count.wat b/exercises/practice/pop-count/pop-count.wat index c1aac61..0185c82 100644 --- a/exercises/practice/pop-count/pop-count.wat +++ b/exercises/practice/pop-count/pop-count.wat @@ -1,4 +1,11 @@ (module + ;; + ;; count the number of 1 bits in the binary representation of a number + ;; + ;; @param {i32} number - the number to count the bits of + ;; + ;; @returns {i32} the number of 1 bits in the binary representation of the number + ;; (func (export "eggCount") (param $number i32) (result i32) (return (i32.const 42)) ) diff --git a/exercises/practice/raindrops/raindrops.wat b/exercises/practice/raindrops/raindrops.wat index 5f5ffac..1ee826d 100644 --- a/exercises/practice/raindrops/raindrops.wat +++ b/exercises/practice/raindrops/raindrops.wat @@ -1,6 +1,14 @@ (module (memory (export "mem") 1) + ;; + ;; Convert a number into a string of raindrop sounds + ;; + ;; @param {i32} input - The number to convert + ;; + ;; @returns {(i32,i32)} - Offset and length of raindrop sounds string + ;; in linear memory. + ;; (func (export "convert") (param $input i32) (result i32 i32) (return (i32.const 0) (i32.const 0)) ) diff --git a/exercises/practice/resistor-color/resistor-color.wat b/exercises/practice/resistor-color/resistor-color.wat index a260d2c..73f4313 100644 --- a/exercises/practice/resistor-color/resistor-color.wat +++ b/exercises/practice/resistor-color/resistor-color.wat @@ -3,18 +3,32 @@ (data (i32.const 100) "black") + ;; ;; Return buffer of comma separated colors - ;; black,brown,red,orange,yellow,green,blue,violet,grey,white + ;; "black,brown,red,orange,yellow,green,blue,violet,grey,white" + ;; + ;; @returns {(i32, i32)} - The offset and length of the buffer of comma separated colors + ;; (func (export "colors") (result i32 i32) (return (i32.const 100) (i32.const 5)) ) - ;; Called each time a module is initialized + ;; + ;; Initialization function called each time a module is initialized ;; Can be used to populate globals similar to a constructor + ;; Can be deleted if not needed + ;; (func $initialize) (start $initialize) - ;; Given a valid resistor color, returns the associated value + ;; + ;; Given a valid resistor color, returns the associated value + ;; + ;; @param {i32} offset - offset into the color buffer + ;; @param {i32} len - length of the color string + ;; + ;; @returns {i32} - the associated value + ;; (func (export "colorCode") (param $offset i32) (param $len i32) (result i32) (return (i32.const -1)) ) diff --git a/exercises/practice/reverse-string/reverse-string.wat b/exercises/practice/reverse-string/reverse-string.wat index e7fd098..afdd5d2 100644 --- a/exercises/practice/reverse-string/reverse-string.wat +++ b/exercises/practice/reverse-string/reverse-string.wat @@ -1,6 +1,14 @@ (module (memory (export "mem") 1) + ;; + ;; Reverse a string + ;; + ;; @param {i32} offset - The offset of the input string in linear memory + ;; @param {i32} length - The length of the input string in linear memory + ;; + ;; @returns {(i32,i32)} - The offset and length of the reversed string in linear memory + ;; (func (export "reverseString") (param $offset i32) (param $length i32) (result i32 i32) (return (local.get $offset) (local.get $length)) ) diff --git a/exercises/practice/rna-transcription/rna-transcription.wat b/exercises/practice/rna-transcription/rna-transcription.wat index c1982a2..be9da8e 100644 --- a/exercises/practice/rna-transcription/rna-transcription.wat +++ b/exercises/practice/rna-transcription/rna-transcription.wat @@ -1,6 +1,14 @@ (module (memory (export "mem") 1) + ;; + ;; Convert a string of DNA to RNA + ;; + ;; @param {i32} offset - The offset of the DNA string in linear memory + ;; @param {i32} length - The length of the DNA string in linear memory + ;; + ;; @returns {(i32,i32)} - The offset and length of the RNA string in linear memory + ;; (func (export "toRna") (param $offset i32) (param $length i32) (result i32 i32) (return (local.get $offset) (local.get $length)) ) diff --git a/exercises/practice/rotational-cipher/rotational-cipher.wat b/exercises/practice/rotational-cipher/rotational-cipher.wat index 937e8ba..b662080 100644 --- a/exercises/practice/rotational-cipher/rotational-cipher.wat +++ b/exercises/practice/rotational-cipher/rotational-cipher.wat @@ -1,6 +1,15 @@ (module (memory (export "mem") 1) + ;; + ;; Encrypt plaintext using the rotational cipher. + ;; + ;; @param {i32} textOffset - The offset of the plaintext input in linear memory. + ;; @param {i32} textLength - The length of the plaintext input in linear memory. + ;; @param {i32} shiftKey - The shift key to use for the rotational cipher. + ;; + ;; @returns {(i32,i32)} - The offset and length of the ciphertext output in linear memory. + ;; (func (export "rotate") (param $textOffset i32) (param $textLength i32) (param $shiftKey i32) (result i32 i32) (return (local.get $textOffset) (local.get $textLength)) ) diff --git a/exercises/practice/square-root/square-root.wat b/exercises/practice/square-root/square-root.wat index 3a72954..1a920b6 100644 --- a/exercises/practice/square-root/square-root.wat +++ b/exercises/practice/square-root/square-root.wat @@ -1,4 +1,11 @@ (module + ;; + ;; Return the square root of the given number. + ;; + ;; @param {i32} radicand + ;; + ;; @returns {i32} square root of radicand + ;; (func (export "squareRoot") (param $radicand i32) (result i32) (return (i32.const 42)) ) diff --git a/exercises/practice/triangle/triangle.wat b/exercises/practice/triangle/triangle.wat index 4e875f3..085d96c 100644 --- a/exercises/practice/triangle/triangle.wat +++ b/exercises/practice/triangle/triangle.wat @@ -1,12 +1,39 @@ (module + ;; + ;; Is the triangle equilateral? + ;; + ;; @param {i32} length of side a + ;; @param {i32} length of side b + ;; @param {i32} length of side c + ;; + ;; @returns {i32} 1 if equalateral, 0 otherwise + ;; (func (export "isEquilateral") (param f32 f32 f32) (result i32) (i32.const 42) ) + ;; + ;; Is the triangle isosceles? + ;; + ;; @param {i32} length of side a + ;; @param {i32} length of side b + ;; @param {i32} length of side c + ;; + ;; @returns {i32} 1 if isosceles, 0 otherwise + ;; (func (export "isIsosceles") (param f32 f32 f32) (result i32) (i32.const 42) ) + ;; + ;; Is the triangle scalene? + ;; + ;; @param {i32} length of side a + ;; @param {i32} length of side b + ;; @param {i32} length of side c + ;; + ;; @returns {i32} 1 if scalene, 0 otherwise + ;; (func (export "isScalene") (param f32 f32 f32) (result i32) (i32.const 42) ) diff --git a/exercises/practice/two-fer/two-fer.wat b/exercises/practice/two-fer/two-fer.wat index 126cfe3..718c8ce 100644 --- a/exercises/practice/two-fer/two-fer.wat +++ b/exercises/practice/two-fer/two-fer.wat @@ -1,6 +1,15 @@ (module (memory (export "mem") 1) + ;; + ;; Given a string X, return a string that says "One for X, one for me." + ;; If the X is empty, return the string "One for you, one for me." + ;; + ;; @param {i32} $offset - The offset of the name in linear memory. + ;; @param {i32} $length - The length of the name in linear memory. + ;; + ;; @return {(i32,i32)} - The offset and length the resulting string in linear memory. + ;; (func (export "twoFer") (param $offset i32) (param $length i32) (result i32 i32) (return (i32.const 8) (i32.const 0)) ) diff --git a/exercises/shared/.docs/help.md b/exercises/shared/.docs/help.md index 261f2ea..190adaa 100644 --- a/exercises/shared/.docs/help.md +++ b/exercises/shared/.docs/help.md @@ -4,3 +4,274 @@ To get help if you're having trouble, you can use one of the following resources - [/r/WebAssembly](https://www.reddit.com/r/WebAssembly/) is the WebAssembly subreddit. - [Github issue tracker](https://github.com/exercism/wasm/issues) is where we track our development and maintenance of Javascript exercises in exercism. But if none of the above links help you, feel free to post an issue here. + +## How to Debug + +Unlike many languages, WebAssembly code does not automatically have access to global resources such as the console. Such functionality instead must be provided as imports. + +In order to provide `console.log` like functionality and a few other niceties, the Exercism WebAssembly track exposes a standard library of functions across all exercises. + +These functions must be imported at the top of your WebAssembly module and then can be called from within your WebAssembly code. + +The `log_mem_*` functions expect to be able to access the linear memory of your WebAssembly module. By default, this is private state, so to make this accessible, you must export your linear memory under the export name `mem`. This is accomplished as follows: + +```wasm +(memory (export "mem") 1) +``` + +## Logging Locals and Globals + +We provide logging functions for each of the primitive WebAssembly types. This is useful for logging global and local variables. + +### log_i32_s - Log a 32-bit signed integer to console + +```wasm +(module + (import "console" "log_i32_s" (func $log_i32_s (param i32))) + (func $main + ;; logs -1 + (call $log_i32_s (i32.const -1)) + ) +) +``` + +### log_i32_u - Log a 32-bit unsigned integer to console + +```wasm +(module + (import "console" "log_i32_u" (func $log_i32_u (param i32))) + (func $main + ;; Logs 42 to console + (call $log_i32_u (i32.const 42)) + ) +) +``` + +### log_i64_s - Log a 64-bit signed integer to console + +```wasm +(module + (import "console" "log_i64_s" (func $log_i64_s (param i64))) + (func $main + ;; Logs -99 to console + (call $log_i32_u (i64.const -99)) + ) +) +``` + +### log_i64_u - Log a 64-bit unsigned integer to console + +```wasm +(module + (import "console" "log_i64_u" (func $log_i64_u (param i64))) + (func $main + ;; Logs 42 to console + (call $log_i64_u (i32.const 42)) + ) +) +``` + +### log_f32 - Log a 32-bit floating point number to console + +```wasm +(module + (import "console" "log_f32" (func $log_f32 (param f32))) + (func $main + ;; Logs 3.140000104904175 to console + (call $log_f32 (f32.const 3.14)) + ) +) +``` + +### log_f64 - Log a 64-bit floating point number to console + +```wasm +(module + (import "console" "log_f64" (func $log_f64 (param f64))) + (func $main + ;; Logs 3.14 to console + (call $log_f64 (f64.const 3.14)) + ) +) +``` + +## Logging from Linear Memory + +WebAssembly Linear Memory is a byte-addressable array of values. This serves as the equivalent of virtual memory for WebAssembly programs + +We provide logging functions to interpret a range of addresses within linear memory as static arrays of certain types. This acts similar to the TypedArrays of JavaScript. The length parameters are not measured in bytes. They are measured in the number of consecutive elements of the type associated with the function. + +**In order for these functions to work, your WebAssembly module must declare and export its linear memory using the named export "mem"** + +```wasm +(memory (export "mem") 1) +``` + +### log_mem_as_utf8 - Log a sequence of UTF8 characters to console + +```wasm +(module + (import "console" "log_mem_as_utf8" (func $log_mem_as_utf8 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (data (i32.const 64) "Goodbye, Mars!") + (func $main + ;; Logs "Goodbye, Mars!" to console + (call $log_mem_as_utf8 (i32.const 64) (i32.const 14)) + ) +) +``` + +### log_mem_as_i8 - Log a sequence of signed 8-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_i8" (func $log_mem_as_i8 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (memory.fill (i32.const 128) (i32.const -42) (i32.const 10)) + ;; Logs an array of 10x -42 to console + (call $log_mem_as_u8 (i32.const 128) (i32.const 10)) + ) +) +``` + +### log_mem_as_u8 - Log a sequence of unsigned 8-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_u8" (func $log_mem_as_u8 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (memory.fill (i32.const 128) (i32.const 42) (i32.const 10)) + ;; Logs an array of 10x 42 to console + (call $log_mem_as_u8 (i32.const 128) (i32.const 10)) + ) +) +``` + +### log_mem_as_i16 - Log a sequence of signed 16-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_i16" (func $log_mem_as_i16 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (i32.store16 (i32.const 128) (i32.const -10000)) + (i32.store16 (i32.const 130) (i32.const -10001)) + (i32.store16 (i32.const 132) (i32.const -10002)) + ;; Logs [-10000, -10001, -10002] to console + (call $log_mem_as_i16 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_u16 - Log a sequence of unsigned 16-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_u16" (func $log_mem_as_u16 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (i32.store16 (i32.const 128) (i32.const 10000)) + (i32.store16 (i32.const 130) (i32.const 10001)) + (i32.store16 (i32.const 132) (i32.const 10002)) + ;; Logs [10000, 10001, 10002] to console + (call $log_mem_as_u16 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_i32 - Log a sequence of signed 32-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_i32" (func $log_mem_as_i32 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (i32.store (i32.const 128) (i32.const -10000000)) + (i32.store (i32.const 132) (i32.const -10000001)) + (i32.store (i32.const 136) (i32.const -10000002)) + ;; Logs [-10000000, -10000001, -10000002] to console + (call $log_mem_as_i32 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_u32 - Log a sequence of unsigned 32-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_u32" (func $log_mem_as_u32 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (i32.store (i32.const 128) (i32.const 100000000)) + (i32.store (i32.const 132) (i32.const 100000001)) + (i32.store (i32.const 136) (i32.const 100000002)) + ;; Logs [100000000, 100000001, 100000002] to console + (call $log_mem_as_u32 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_i64 - Log a sequence of signed 64-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_i64" (func $log_mem_as_i64 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (i64.store (i32.const 128) (i64.const -10000000000)) + (i64.store (i32.const 136) (i64.const -10000000001)) + (i64.store (i32.const 144) (i64.const -10000000002)) + ;; Logs [-10000000000, -10000000001, -10000000002] to console + (call $log_mem_as_i64 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_u64 - Log a sequence of unsigned 64-bit integers to console + +```wasm +(module + (import "console" "log_mem_as_u64" (func $log_mem_as_u64 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (i64.store (i32.const 128) (i64.const 10000000000)) + (i64.store (i32.const 136) (i64.const 10000000001)) + (i64.store (i32.const 144) (i64.const 10000000002)) + ;; Logs [10000000000, 10000000001, 10000000002] to console + (call $log_mem_as_u64 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_u64 - Log a sequence of 32-bit floating point numbers to console + +```wasm +(module + (import "console" "log_mem_as_f32" (func $log_mem_as_f32 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (func $main + (f32.store (i32.const 128) (f32.const 3.14)) + (f32.store (i32.const 132) (f32.const 3.14)) + (f32.store (i32.const 136) (f32.const 3.14)) + ;; Logs [3.140000104904175, 3.140000104904175, 3.140000104904175] to console + (call $log_mem_as_u64 (i32.const 128) (i32.const 3)) + ) +) +``` + +### log_mem_as_f64 - Log a sequence of 64-bit floating point numbers to console + +```wasm +(module + (import "console" "log_mem_as_f64" (func $log_mem_as_f64 (param $byteOffset i32) (param $length i32))) + (memory (export "mem") 1) + (f64.store (i32.const 128) (f64.const 3.14)) + (f64.store (i32.const 136) (f64.const 3.14)) + (f64.store (i32.const 144) (f64.const 3.14)) + ;; Logs [3.14, 3.14, 3.14] to console + (call $log_mem_as_u64 (i32.const 128) (i32.const 3)) + ) +) +```