Source Programs

This repo contains programs written in Source, developed for SICP JS and other educational projects.

All programs in this repository are runnable in the Source Academy playground: copy the program into the editor, choose "Source §4", and press "Run".

Evaluators

The evaluators in this section all follow the general style of SICP JS Chapter 4.

• src/evaluators/source-0.js: evaluator for Source §0 (calculator language)
• src/evaluators/source-0-pp.js: evaluator for Source §0++ (calculator language plus conditionals, blocks and sequences)
• src/evaluators/source-2.js: evaluator for Source §2, described in SICP JS 4.1
• src/evaluators/source-2-lazy.js: lazy evaluator for Source §2, described in SICP JS 4.2
• src/evaluators/source-2-non-det.js: evaluator for Source §2 with non-determinism, described in SICP JS 4.3
• src/evaluators/typed-source.js: evaluator for Typed Source (typed version of a Source §1 sublanguage)

Steppers

The steppers in this section implement a small-step semantics, following the substitution model of SICP JS Chapter 1 and 2.

• src/steppers/source-0.js: stepper for Source §0

Type checkers

The type checkers in this section follow a rule-based static semantics available in doc/type-checking.pdf.

• src/type-checkers/source-0.js: type checker for Source §0
• src/type-checkers/typed-source.js: type checker for Typed Source, a typed version of a Source §1 sublanguage

Virtual machines

The virtual machines in this section are SECD-style and follow a description in doc/virtual-machines.pdf. Each virtual machine comes with a compiler, implemented in the same file.

• src/virtual-machines/source-0m.js: virtual machine for Source §0- (calculator language without division)
• src/virtual-machines/source-0.js: virtual machine for Source §0 (calculator language)
• src/virtual-machines/source-0p.js: virtual machine for Source §0 (calculator language with conditionals)
• 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: virtual machine for a Source §1 sublanguage with a Cheney-style stop-and-copy garbage collector
• src/virtual-machines/register-machine-gcd.js: register machine following SICP JS Section 5.2, using GCD example
• 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: 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: 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/)

• src/tool-demos/stepper.js: stepper tool (small-step semantics, based on substitution)
• src/tool-demos/box-and-pointer-diagrams.js: box-and-pointer diagram visualizer for pairs and lists (following SICP JS chapter 2)
• src/tool-demos/environment-model.js: environment model visualizer (following SICP JS chapter 3)

Module Demos

(click to run; for actual sources, go to src/module-demos/)

• src/module-demos/runes.js: the "picture language" of SICP JS 2.2.4
• src/module-demos/twist.js: some fun with the "picture language"
• src/module-demos/curves.js: a "curves" library for drawing curves with functional programming
• src/module-demos/times.js: visual times tables using the "curves" library
• src/module-demos/sounds.js: a "sounds" library for generating sounds and music, starting from their constituent sine waves
• src/module-demos/bohemian.js: Bohemian Rhapsody cover using the "sounds" library
• src/module-demos/pix-n-flix.js: a library for image and video processing, based on the constituent pixels

Test framework

• src/test/framework/main.js: 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:

parse_and_evaluate("! (1 === 1 && 2 > 3);");
// true

Before you can run the tests, you need to install js-slang by typing:

% yarn
% yarn install

Run all test cases by typing:

% 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

Line 2073: Error: memory exhausted despite garbage collection undefined

can be written in the test file:

// Line 2073: Error: memory exhausted despite garbage collection undefined

or

// 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

All JavaScript programs in this repository are licensed under the GNU General Public License Version 3.