forked from source-academy/js-slang
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* chore: update README * refactor: remove comments in grammar
- Loading branch information
1 parent
55d95a4
commit a858927
Showing
2 changed files
with
422 additions
and
141 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,201 +1,153 @@ | ||
| # js-slang | ||
|  | ||
|
|
||
| Open-source implementations of the programming language _Source_. Source is a series of small subsets of JavaScript, designed for teaching university-level programming courses for computer science majors, following Structure and Interpretation of Computer Programs, JavaScript Adaptation (<https://sourceacademy.org/sicpjs/>). | ||
| # go-slang | ||
|
|
||
| ## Table of Contents | ||
| An interpreter for a subset of the Go programming language. The interpreter is a [Explicit Control Evaluator (ECE)](https://sourceacademy.org/sicpjs/5.4) implemented in TypeScript. The Go ECE aims to help developers better reason about the behaviour of their Go programs, by making program control explicit. | ||
|
|
||
| - [Prerequisites](#prerequisites) | ||
| - [Usage](#usage) | ||
| - [Documentation](#documentation) | ||
| - [Requirements](#requirements) | ||
| - [Testing](#testing) | ||
| - [Error messages](#error-messages) | ||
| - [Using your js-slang in Source Academy](#using-your-js-slang-in-source-academy) | ||
| - [Using your js-slang in your local Source Academy](#using-your-js-slang-in-your-local-source-academy) | ||
| - [Building and publishing SICP package](#building-and-publishing-sicp-package) | ||
| - [Talks and Presentations](#talks-and-presentations) | ||
| - [License](#license) | ||
| The Go ECE currently supports commonly used sequential language constructs and widely used concurrent constructs like Channels, Mutexes and WaitGroups. _Check out the grammar below for the full list of constructs supported._ | ||
|
|
||
| ## Prerequisites | ||
| Implementation of the Go ECE is found in the [`src/go-slang`](/src/go-slang) directory. | ||
|
|
||
| - NodeJS v20 | ||
| - Python: On MacBook Pro with chip Apple M1 Pro, use python 3.10.12. Here is [the correct way to set Python 3 as default on a Mac](https://opensource.com/article/19/5/python-3-default-mac). | ||
| ## EBNF Grammar | ||
|
|
||
| ## Usage | ||
| The grammar is modified subset of the Go programming language ([go1.22 Feb 6 2024](https://go.dev/ref/spec)) specifications. | ||
|
|
||
| To build, | ||
| The parser generated using [peggy.js](https://peggyjs.org/) parser generator by converting the EBNF grammar below to Parsing Expression Grammar (PEG). | ||
|
|
||
| ```bash | ||
| $ git clone --recurse-submodules https://github.com/source-academy/js-slang.git | ||
| $ cd js-slang | ||
| $ yarn | ||
| $ yarn build | ||
| ``` | ||
| The PEG grammar can be found in the [`src/go-slang/parser/go.pegjs`](/src/go-slang/parser/go.pegjs) file. | ||
|
|
||
| This repository uses git submodules. To update existing repositories with a submodule, | ||
| ```ebnf | ||
| SourceFile = { TopLevelDeclaration } . | ||
| ```bash | ||
| # Init is only required on the very first time. | ||
| $ git submodule update --init --recursive | ||
| # Required subsequently every time you want to update the submodules. | ||
| $ git submodule update --recursive --remote | ||
| ``` | ||
| TopLevelDeclaration = Declaration | FunctionDeclaration . | ||
| Declaration = VariableDeclaration . | ||
| To add \"js-slang\" to your PATH, build it as per the above instructions, then run | ||
| FunctionDeclaration = "func" Identifier Signature Block . | ||
| Signature = "(" [ IdentifierList ] ")" . | ||
| ```bash | ||
| $ cd dist | ||
| $ npm link | ||
| ``` | ||
| Block = "{" { Statement } "}" . | ||
| If you do not wish to add \"js-slang\" to your PATH, replace \"js-slang\" with \"node dist/repl/repl.js\" in the following examples. | ||
| Statement = | ||
| Declaration | SimpleStatement | GoStatement | ReturnStatement | | ||
| BreakStatement | ContinueStatement | Block | IfStatement | | ||
| ForStatement . | ||
| To try out _Source_ in a REPL, run | ||
| SimpleStatement = | ||
| ExpressionStatement | SendStatement | IncDecStatement | | ||
| Assignment | ShortVariableDeclaration . | ||
| ```bash | ||
| $ js-slang -c [chapter] # default: 1 | ||
| ``` | ||
| VariableDeclaration = "var" VarSpec . | ||
| VarSpec = IdentifierList [ "=" ExpressionList ] . | ||
| You can set additional options: | ||
| ShortVariableDeclaration = IdentifierList ":=" ExpressionList . | ||
| ```{.} | ||
| Usage: js-slang [PROGRAM_STRING] [OPTION] | ||
| IfStatement = | ||
| "if" [ SimpleStatement ";" ] Expression Block | ||
| [ "else" (IfStatement | Block) ] . | ||
| -c, --chapter=CHAPTER set the Source chapter number (i.e., 1-4) (default: 1) | ||
| -v, --variant=VARIANT set the Source variant (i.e., default, interpreter, substituter, typed, lazy, non-det, concurrent, wasm, gpu) (default: default) | ||
| -h, --help display this help | ||
| -e, --eval don't show REPL, only display output of evaluation | ||
| ``` | ||
| ForStatement = "for" [ ForCondition | ForClause ] Block . | ||
| ForClause = [ InitStatement ] ";" [ ForCondition ] ";" [ PostStatement ] . | ||
| ForCondition = Expression . | ||
| Currently, valid CHAPTER/VARIANT combinations are: | ||
|
|
||
| - `--chapter=1 --variant=default` | ||
| - `--chapter=1 --variant=wasm` | ||
| - `--chapter=1 --variant=lazy` | ||
| - `--chapter=1 --variant=substituter` | ||
| - `--chapter=1 --variant=interpreter` | ||
| - `--chapter=1 --variant=typed` | ||
| - `--chapter=2 --variant=default` | ||
| - `--chapter=2 --variant=lazy` | ||
| - `--chapter=2 --variant=substituter` | ||
| - `--chapter=2 --variant=interpreter` | ||
| - `--chapter=2 --variant=typed` | ||
| - `--chapter=3 --variant=default` | ||
| - `--chapter=3 --variant=concurrent` | ||
| - `--chapter=3 --variant=non-det` | ||
| - `--chapter=3 --variant=interpreter` | ||
| - `--chapter=3 --variant=typed` | ||
| - `--chapter=4 --variant=default` | ||
| - `--chapter=4 --variant=gpu` | ||
| - `--chapter=4 --variant=interpreter` | ||
|
|
||
| Hint: In `bash` you can take the `PROGRAM_STRING` out of a file as follows: | ||
| Assignment = ExpressionList assign_op ExpressionList . | ||
| assign_op = [ add_op | mul_op ] "=" . | ||
| ```bash | ||
| $ js-slang -n --chapter=1 -e "$(< my_source_program.js)" | ||
| ``` | ||
| SendStatement = Expression "<-" Expression . | ||
| ## Documentation | ||
| IncDecStatememt = Expression ( "++" | "--" ) . | ||
| Source is documented here: <https://docs.sourceacademy.org/> | ||
| GoStatement = "go" Expression . | ||
| ### Requirements | ||
| Expression = UnaryExpression | Expression binary_op Expression . | ||
| ExpressionList = Expression { "," Expression } . | ||
| - `bash`: known working version: GNU bash, version 5.0.16 | ||
| - `latexmk`: Version 4.52c | ||
| - `pdflatex`: known working versions | ||
| - pdfTeX 3.14159265-2.6-1.40.18 (TeX Live 2017) | ||
| UnaryExpression = PrimaryExpression | unary_op UnaryExpression . | ||
| PrimaryExpression = | ||
| Identifier | QualifiedIdentifier | Literal | "(" Expression ")" . | ||
| To build the documentation, run | ||
| ExpressionStatement = Expression . | ||
| ```bash | ||
| $ git clone https://github.com/source-academy/js-slang.git | ||
| $ cd js-slang | ||
| $ yarn | ||
| $ yarn install | ||
| $ yarn jsdoc # to make the web pages in js-slang/docs/source | ||
| $ cd docs/specs | ||
| $ make # to make the PDF documents using LaTeX | ||
| ``` | ||
| BreakStatement = "break" . | ||
| ContinueStatement = "continue" . | ||
| ReturnStatement = "return" [ ExpressionList ] . | ||
| **Note:** The documentation may not build on Windows, depending on your bash setup, [see above](https://github.com/source-academy/js-slang#requirements). | ||
| Identifier = Letter { Letter | UnicodeDigit } . | ||
| IdentifierList = Identifier { "," Identifier } . | ||
| Documentation on the Source libraries are generated from inline documentation in the library sources, a copy of which are kept in `docs/lib/*.js`. The command `yarn jsdoc` generates the documentation and places it in the folder `docs/source`. You can test the documentation using a local server: | ||
| QualifiedIdentifier = PackageName "." Identifier . | ||
| PackageName = Identifier . | ||
| ```bash | ||
| $ cd docs/source; python -m http.server 8000 | ||
| ``` | ||
| Literal = BasicLit | FunctionLit . | ||
| BasicLit = IntegerLit | StringLit | TypeLit . | ||
| Documentation of libraries is displayed in autocomplete in the frontend. This documentation is generated by `./scripts/updateAutocompleteDocs.py` and placed in `src/editors/ace/docTooltip/*.json` files. This script is run by `yarn build`prior to`tsc`. To add a Source variant to the frontend autocomplete, edit `src/editors/ace/docTooltip/index.ts` and`./scripts/updateAutocompleteDocs.py`. | ||
| IntegerLit = HexInt | OctalInt | BinaryInt | DecimalInt . | ||
| ## Testing | ||
| TypeLit = ChannelType | WaitGroupType | MutexType . | ||
| ChannelType = "chan" . | ||
| WaitGroupType = "sync.WaitGroup" . | ||
| MutexType = "sync.Mutex" . | ||
| `js-slang` comes with an extensive test suite. To run the tests after you made your modifications, run `yarn test`. Regression tests are run automatically when you want to push changes to this repository. The regression tests are generated using `jest` and stored as snapshots in `src/\_\_tests\_\_`. After modifying `js-slang`, carefully inspect any failing regression tests reported in red in the command line. If you are convinced that the regression tests and not your changes are at fault, you can update the regression tests as follows: | ||
| FunctionLit = "func" Signature Block . | ||
| ```bash | ||
| $ yarn test -- --updateSnapshot | ||
| binary_op = "||"| "&&" | rel_op | add_op | mul_op . | ||
| rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . | ||
| add_op = "+" | "-" | "|" | "^" . | ||
| mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . | ||
| unary_op = "+" | "-" | "!" | "^" | "<-" | ||
| ``` | ||
|
|
||
| ## Error messages | ||
|
|
||
| To enable verbose messages, have the statement `"enable verbose";` as the first line of your program. This also causes the program to be run by the interpreter. | ||
| ## Usage | ||
|
|
||
| There are two main kinds of error messages: those that occur at runtime and those that occur at parse time. The first can be found in `interpreter-errors.ts`, while the second can be found in `rules/`. | ||
| There is a hosted version of the Go ECE at [dub.sh/go-slang](https://dub.sh/go-slang). The hosted version is a web-based Go playground ([fork of Source Academy Frontend](https://github.com/shenyih0ng/go-slang-frontend)) that allows you to write and run Go programs in your browser. | ||
|
|
||
| Each error subclass will have `explain()` and `elaborate()`. Displaying the error will always cause the first to be called; the second is only called when verbose mode is enabled. As such, `explain()` should be made to return a string containing the most basic information about what the error entails. Any additional details about the error message, including specifics and correction guides, should be left to `elaborate()`. | ||
| ### Local Development | ||
|
|
||
| Please remember to write test cases to reflect your added functionalities. The god of this repository is self-professed to be very particular about test cases. | ||
| **Prerequisites** | ||
|
|
||
| ## Using your js-slang in Source Academy | ||
| - NodeJS v20 | ||
| - Python: On MacBook Pro with chip Apple M1 Pro, use python 3.10.12. Here is [the correct way to set Python 3 as default on a Mac](https://opensource.com/article/19/5/python-3-default-mac). | ||
|
|
||
| js-slang is used by the [Source Academy](https://sourceacademy.org), the immersive online experiential environment for learning programming. For this, js-slang is [deployed as an NPM package](https://www.npmjs.com/package/js-slang). The frontend of the Source Academy then includes the js-slang package in its deployment bundle. | ||
| To build, | ||
|
|
||
| ## Using your js-slang in your local Source Academy | ||
| ```bash | ||
| git clone --recurse-submodules https://github.com/shenyih0ng/go-slang.git | ||
|
|
||
| A common issue when developing modifications to js-slang is how to test it using your own local frontend. Assume that you have built your own frontend locally, here is how you can make it use your own js-slang, instead of the one that the Source Academy team has deployed to npm. | ||
| cd go-slang | ||
| yarn install | ||
| yarn build | ||
| ``` | ||
|
|
||
| First, build and link your local js-slang: | ||
| Set up a link to the `go-slang` repository to be used in frontend | ||
|
|
||
| ```bash | ||
| $ cd js-slang | ||
| $ yarn build | ||
| $ yarn link | ||
| yarn link | ||
| ``` | ||
|
|
||
| Then, from your local copy of frontend: | ||
| Clone the frontend repository | ||
|
|
||
| ```bash | ||
| $ cd frontend | ||
| $ yarn link "js-slang" | ||
| cd .. # go back to the parent directory | ||
| git clone https://github.com/shenyih0ng/go-slang-frontend.git | ||
| ``` | ||
|
|
||
| Then start the frontend and the new js-slang will be used. | ||
|
|
||
| ## Building and publishing SICP package | ||
|
|
||
| To build SICP package | ||
| Link the `js-slang` library to the frontend and install the dependencies | ||
|
|
||
| ```bash | ||
| $ cd js-slang | ||
| $ yarn | ||
| $ yarn build_sicp_package | ||
| cd go-slang-frontend | ||
| yarn link js-slang | ||
| yarn install | ||
| ``` | ||
|
|
||
| To publish SICP package, update version number in `sicp_publish/package.json` | ||
| Start the development server | ||
|
|
||
| ```bash | ||
| $ cd js-slang/sicp_publish | ||
| $ npm publish | ||
| # defaults to port 8000 | ||
| yarn start | ||
| ``` | ||
|
|
||
| ## Talks and Presentations | ||
|
|
||
| - **How `js-slang` works under the hood** (17th Jan 2023 – The Gathering) ([slides](https://docs.google.com/presentation/d/1GFR39iznBZxWv948zUsmcbCSSDasm4xYs3Jc5GF7A3I/edit?usp=sharing)) | ||
|
|
||
| ## License | ||
| If there are changes made to `go-slang` during development, a simple rebuild is needed and the frontend will hot reload the updated package without having to restart the server | ||
|
|
||
| [](https://opensource.org/licenses/Apache-2.0) | ||
|
|
||
| All sources in this repository are licensed under the [Apache License Version 2][apache2]. | ||
|
|
||
| [apache2]: https://www.apache.org/licenses/LICENSE-2.0.txt | ||
| ```bash | ||
| # in the go-slang directory | ||
| yarn build:slang | ||
| ``` |
Oops, something went wrong.