Merge remote-tracking branch 'upstream/master'

Author: Ian Duncan

.gitignore

@@ -0,0 +1,6 @@
+node_modules
+
+*~
+
+**/output
+

LICENSE

@@ -6,12 +6,13 @@ All programs in this repository are runnable in the [Source Academy playground](
 
 ## Evaluators
 
-The evaluators in this section all follow the general style of SICP JS Section 4.1.
+The evaluators in this section all follow the general style of SICP JS Chapter 4.
 
 * [`src/evaluators/source-0.js`](https://github.com/source-academy/source-programs/blob/master/src/evaluators/source-0.js): evaluator for Source §0 (calculator language)
 * [`src/evaluators/source-0pp.js`](https://github.com/source-academy/source-programs/blob/master/src/evaluators/source-0pp.js): evaluator for Source §0++ (calculator language plus conditionals, blocks and sequences)
-* [`src/evaluators/source-1.js`](https://github.com/source-academy/source-programs/blob/master/src/evaluators/source-1.js): evaluator for Source §1
+* [`src/evaluators/source-4-1.js`](https://github.com/source-academy/source-programs/blob/master/src/evaluators/source-4-1.js): evaluator for Source §1, described in SICP JS 4.1
 * [`src/evaluators/typed-source.js`](https://github.com/source-academy/source-programs/blob/master/src/evaluators/typed-source.js): evaluator for Typed Source (typed version of a Source §1 sublanguage)
+* [`src/evaluators/source-4-3.js`](https://github.com/source-academy/source-programs/blob/master/src/evaluators/source-4-3.js): meta-circular evaluator for Source §4.3 (non-deterministic programming)
 
 ## Steppers
 
@@ -36,14 +37,21 @@ The virtual machines in this section are SECD-style and follow a description in
 * [`src/virtual-machines/source-1.js`](https://github.com/source-academy/source-programs/blob/master/src/virtual-machines/source-1.js): virtual machine for a Source §1 sublanguage (without memory management)
 * [`src/virtual-machines/source-1-with-copying-gc.js`](https://github.com/source-academy/source-programs/blob/master/src/virtual-machines/source-1-with-copying-gc.js): virtual machine for a Source §1 sublanguage with a Cheney-style stop-and-copy garbage collector
 * [`src/virtual-machines/register-machine-gcd.js`](https://github.com/source-academy/source-programs/blob/master/src/virtual-machines/register-machine-gcd.js): register machine following SICP JS Section 5.2, using GCD example
+* [`src/virtual-machines/source-2.js`](https://github.com/source-academy/source-programs/blob/master/src/virtual-machines/source-2.js): virtual machine for a Source §2 sublanguage (without memory management)
+* [`src/virtual-machines/source-2-with-copying-gc.js`](https://github.com/source-academy/source-programs/blob/master/src/virtual-machines/source-2-with-copying-gc.js): virtual machine for a Source §2 sublanguage with a Cheney-style stop-and-copy garbage collector
+* [`src/virtual-machines/source-2-with-ms-gc.js`](https://github.com/source-academy/source-programs/blob/master/src/virtual-machines/source-2-with-ms-gc.js): virtual machine for a Source §2 sublanguage with a Mark-and-Sweep-style garbage collector
 
 ## Tool Demos
 
+(click to run; for actual sources, go to [`src/tool-demos/`](https://github.com/source-academy/source-programs/blob/master/src/tool-demos/))
+
 * [`src/tool-demos/stepper.js`](https://tinyurl.com/SICPJS-stepper): stepper tool (small-step semantics, based on substitution)
 * [`src/tool-demos/box-and-pointer-diagrams.js`](https://tinyurl.com/SICPJS-box-and-pointer): box-and-pointer diagram visualizer for pairs and lists (following SICP JS chapter 2)
 * [`src/tool-demos/environment-model.js`](https://tinyurl.com/SICPJS-env-diagram): environment model visualizer (following SICP JS chapter 3)
 
-## Library Demos
+## Module Demos
+
+(click to run; for actual sources, go to [`src/module-demos/`](https://github.com/source-academy/source-programs/blob/master/src/module-demos/))
 
 * [`src/module-demos/runes.js`](https://tinyurl.com/SICPJS-hearts): the "picture language" of SICP JS 2.2.4
 * [`src/module-demos/twist.js`](https://tinyurl.com/SICPJS-twist): some fun with the "picture language"
@@ -53,4 +61,68 @@ The virtual machines in this section are SECD-style and follow a description in
 * [`src/module-demos/bohemian.js`](https://tinyurl.com/SICPJS-rhapsody): Bohemian Rhapsody cover using the "sounds" library 
 * [`src/module-demos/pix-n-flix.js`](https://tinyurl.com/SICP-distortion): a library for image and video processing, based on the constituent pixels
 
+## Test framework
+* [`src/test/framework/main.js`](https://github.com/source-academy/source-programs/blob/master/src/test/framework/): test framework for Source programs, written in Source §4
+
+# Testing
+
+[requires bash (any version) and awk (BSD awk 20070501); does not work with gawk]
+
+For testing your Source programs, you need `node` and `yarn`.
+
+Write your test cases in a folder `__tests__` in each `src` subfolder. The name of the file specifies the targeted Source of your test case. For example, if `src/steppers/source-0.js` is the Source, a test case might be `src/steppers/__tests__/source-0.test1.js`.
+
+Only the tests written will be run.
+
+Each test case is appended to your Source, and then run with `js-slang` (using Source §4). The last line of the test case is a `//` comment that must contain the expected result. For example, a stepper test case may be:
+
+``` js
+parse_and_evaluate("! (1 === 1 && 2 > 3);");
+// true
+```
+
+Before you can run the tests, you need to install `js-slang` by typing:
+
+``` sh
+% yarn
+% yarn install
+```
+
+Run all test cases by typing:
+
+``` sh
+% yarn test
+```
+
+For failure cases (where you program is to throw error, e.g. memory exhausted error for virtual machines), you can include the error message as per normal. The lastest JS-Slang already throws the error message explicitly, without letting the underlying TypeScript handling it. Hence, an error message
+
+``` sh
+Line 2073: Error: memory exhausted despite garbage collection undefined
+```
+
+can be written in the test file:
+
+``` js
+// Line 2073: Error: memory exhausted despite garbage collection undefined
+```
+
+or
+
+``` js
+// Error: memory exhausted despite garbage collection undefined
+```
+
+where only the part that starts from `Error:` will be compared. Line number is be ignored as it varies. If line number is needed for a particular reason, it can be appended to the back.
+
+>**Note**: for virtual machine tests, you will have to make a function that outputs a single line output without the help of any `displays()`, as the test currently only supports 1 line comparison. Help to make this generic is appreciated.
+
+>Integration of the `test` script with `src/test/framework/` is pending a fix to the `--variant` parameter; any help appreciated.
+
+# License
+
+[![GPL 3][gpl3-image]][gpl3]
+All JavaScript programs in this repository are licensed under the 
+[GNU General Public License Version 3][gpl3].
 
+[gpl3]: https://www.gnu.org/licenses/gpl-3.0.en.html
+[gpl3-image]: https://upload.wikimedia.org/wikipedia/commons/thumb/7/79/License_icon-gpl.svg/50px-License_icon-gpl.svg.png

README.md

@@ -0,0 +1,25 @@
+{
+  "name": "source-programs",
+  "version": "0.4.21",
+  "description": "Javascript-based implementations of Source, written in Typescript",
+  "author": {
+    "name": "Source Academy",
+    "url": "https://github.com/source-academy/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "./scripts/test.sh"
+  },
+  "dependencies": {
+    "js-slang": "^0.4.33",
+    "lodash": "^4.17.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/source-academy/source-programs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/source-academy/source-programs/issues"
+  },
+  "homepage": "https://github.com/source-academy/source-programs"
+}

package.json

@@ -0,0 +1,103 @@
+#! /usr/bin/env bash
+
+JS_SLANG="node node_modules/js-slang/dist/repl/repl.js"
+
+# must use BSD awk
+AWK="awk"
+
+SOURCEFILES=src/*/*.js
+SOURCE_TEST="src/test/framework/main.js"
+
+DEFAULT_CHAPTER=4
+DEFAULT_VARIANT="default"
+
+red=`tput setaf 1`
+green=`tput setaf 2`
+normal=`tput setaf 7`
+
+passed=0
+failed=0
+
+# $1 is the source file to be tested
+# $2 is the test file
+# $3 is the chapter
+# $4 is the variant
+
+test_source() {
+
+    # if program throws error, ignore the output and compare the error message only
+    # NOTE: error output line is striped of line number as it is machine dependent
+    ERROR=$( { $JS_SLANG -e --chapter=$3 "$(cat $1 $2)">$DIR/__tests__/output; } 2>&1 )
+    if [ ! -z "$ERROR" ]
+    then
+        DIFF=$(diff <(echo $ERROR | grep -o 'Error:.*') <(cat $2 | tail -1 | grep -o 'Error:.*'))
+    else 
+        DIFF=$(diff <(cat $DIR/__tests__/output) \
+            <(cat $2 | tail -1 | cut -c4-))
+    fi
+    
+    if [ "$DIFF" = "" ]
+    then passed=$(($passed+1)); echo "${green}PASS $2"
+    else failed=$(($failed+1)); echo "${red}FAIL $2:
+$DIFF"
+    fi
+    # clean up temp file
+    rm $DIR/__tests__/output
+    
+}
+
+test_source_framework() {
+
+    # run concatenation of source-test framework, source and test files
+    RESULTS=$($JS_SLANG -e --chapter=$3 --variant=$4 "$(cat $SOURCE_TEST $1 $2)")
+    
+    # retrieve names for tests that passed
+    while read test_name
+    do 
+        passed=$(($passed+1))
+        echo "${green}PASS $2 $test_name"
+    done < <(echo ${RESULTS} | grep -o '\w* PASSED' | $AWK -F 'PASSED' '{ print $1 }')
+    
+    # retrieve names and error messages for tests that failed
+    while read test_info 
+    do 
+        failed=$(($failed+1))
+        echo $test_info | $AWK -F 'FAILED:' '{ print $1 ":" $2 }' | $AWK -F '"' '{ print $1 $2 }' | 
+            while read test_name test_error 
+            do echo "${red}FAIL $2 $test_name $test_error"; 
+            done
+    done < <(echo ${RESULTS} | grep -o '\w* FAILED:[^"]*')
+}
+
+main() {
+    for s in ${SOURCEFILES}
+    do
+        DIR=$(dirname ${s})
+	# if __tests__ directory exists
+	if [ -d "$DIR/__tests__" ]
+	then
+	    # call test_source on each test case in __tests__
+	    for i in "$DIR/__tests__/$(basename ${s} .js)".*
+	    do
+        if [ -f "$i" ]; then
+            # check if first line of test file contains 'chapter=' and retrieve its value. Set to the default chapter if it does not
+            chapter=$($AWK -F 'chapter=' 'FNR==1{ if ($0~"chapter=") { print $2 } else { print '$DEFAULT_CHAPTER' } }' $i | $AWK -F ' ' '{ print $1 }')
+        
+            # check if first line of test file contains 'variant=' and retrieve its value. Set to the default variant if it does not
+            variant=$($AWK -F 'variant=' 'FNR==1{ if ($0~"variant=") { print $2 } else { print '$DEFAULT_VARIANT' } }' $i | $AWK -F ' ' '{ print $1 }')
+            
+            # check if first line of test file contains 'framework'
+            use_source_test=$($AWK 'FNR==1{ if ($0~"framework") print "yes" }' $i)
+            if [[ $use_source_test == "yes" ]]
+            then chapter=4 ; test_source_framework $s $i $chapter $variant
+            else test_source $s $i $chapter $variant
+            fi
+        fi
+        done
+	fi
+    done
+}
+
+main
+echo "${normal}test cases completed; $passed passed, $failed failed"
+exit 0

scripts/test.sh

@@ -0,0 +1,2 @@
+// permutations
+

src/classics/permutations.js

@@ -0,0 +1,98 @@
+// The following sorting algorithms work on numbers and
+// strings: they use the comparison operator <=.
+// For other data types, replace this operator
+// appropriately.
+
+// Merge sort
+
+function merge_sort(xs) {
+    if ( is_null(xs) || is_null(tail(xs))) {
+        return xs;
+    } else {
+        const mid = middle(length(xs)) ;
+        return merge(merge_sort(take(xs, mid)),
+                     merge_sort(drop(xs, mid)));
+    }
+}
+
+function middle(n) {
+    return math_floor(n / 2) ;
+}
+
+function merge(xs , ys) {
+    if ( is_null(xs)) {
+        return ys;
+    } else if (is_null(ys)) {
+        return xs;
+    } else {
+        const x = head(xs) ;
+        const y = head(ys) ;
+        if (x <= y) {
+            return pair(x, merge(tail(xs), ys));
+        } else {
+            return pair(y, merge(xs, tail(ys)));
+        }
+    }
+}
+
+function take(xs , n) {
+    return (n === 0) 
+        ? null
+        : pair(head(xs), take(tail(xs), n - 1));
+}
+
+function drop(xs, n) {
+    return n === 0
+        ? xs
+        : drop(tail(xs), n - 1);
+}
+
+// selection sort
+
+function selection_sort(xs) {
+    if (is_null(xs)) {
+        return xs;
+    } else {
+	const s = smallest(xs) ;
+	return pair(s, selection_sort(remove(s, xs)));
+    }
+}
+
+// iterative smallest
+function smallest (xs) {
+    function sm(x, ys) {
+	return is_null(ys)
+	    ? x 
+            : x <= head(ys)
+	      ? sm(x, tail(ys))
+              : sm(head(ys), tail(ys));
+    }
+    return sm(head(xs), tail(xs));
+}
+
+// insertion sort
+
+function insertion_sort (xs) {
+    return is_null(xs)
+        ? xs
+        : insert(head(xs), insertion_sort(tail(xs)));
+}
+
+function insert(x, xs) {
+    return is_null(xs)
+        ? list(x)
+        : x <= head(xs)
+          ? pair(x, xs)
+          : pair(head(xs), insert(x, tail(xs)));
+}
+
+// quicksort (not given here, because it's a homework exercise
+//            in CS1101S at NUS; no spoilers please)
+
+function quicksort(xs) {
+    // uses partition
+}
+
+function partition (xs, p) {
+    // ...
+}

src/classics/sorting_lists.js

@@ -0,0 +1,2 @@
+// subsets
+