sugarlabs / musicblocks-v4-lib

The programming framework of the new Music Blocks (v4) application.

Programming framework of musicblocks-v4

This repository contains the source code for the programming framework of the new Music Blocks (v4) application.

Architecture

Syntax Representation

• Element API represents syntax elements — the atomic constructs for building programs. There are 2 kinds of syntax elements:

  • Arguments which return values. These are of 2 types:

    • Data which return a value inherently and without operating on other provided values

    • Expression which return a value after operating on other provided values

  • Instructions which perform a task. These are of 2 types:

    • Statements perform a single task

    • Blocks encapsulate statements and generally set some states or control the flow to them

• Specification maintains a table of actual syntax elements which can be used to build programs.

• Warehouse maintains a table of instances of syntax elements registered in the specification. It can also generate statistics about the instances.

• Tree represents the syntax tree (abstract syntax tree or AST) by maintaining interconnections between syntax elements.

Execution

• Symbol Table maintains tables of dynamic variables and states which the syntax elements can use during execution.

• Parser parses the syntax tree in a postorder sequence, and maintains call frame stacks and the program counter.

• Interpreter fetches elements from the parser and executes them.

• Scheduler manages the concurrent orchestration of the execution process.

Monitor proxies information about the execution states and statictics.

There are 2 special constructs: Process and Routine. These are special block elements. Routines encapsulate instructions that can be executed by multiple processes. Processes encapsulate independent set of instructions, and multiple processes can run concurrently.

There is an additional terminology called crumbs which are sets of connected syntax elements not part of any process or routine.

Plugins

The core framework doesn't define any special syntax elements other than process and routine. All concrete syntax elements are plugins which extend the syntax element API and are registered in the syntax specification.

A set of programming specific syntax elements are bundled as a library, which use nothing beyond the set of constructs exposed by the syntax element API.

Tech Stack

This core of Music Blocks v4 uses TypeScript 4. In addition, Jest shall be used for testing.

Contributing

Programmers, please follow these general guidelines for contributions.

New Contributors

Use the discussions tab at the top of the repository to:

• Ask questions you’re wondering about.
• Share ideas.
• Engage with other community members.

Feel free. But, please don't spam :p.

Keep in Mind

1. Your contributions need not necessarily have to address any discovered issue. If you encounter any, feel free to add a fix through a PR, or create a new issue ticket.

2. Use labels on your issues and PRs.

3. Do not spam with lots of PRs with little changes.

4. If you are addressing a bulk change, divide your commits across multiple PRs, and send them one at a time. The fewer the number of files addressed per PR, the better.

5. Communicate effectively. Go straight to the point. You don't need to address anyone using 'sir'. Don't write unnecessary comments; don't be over-apologetic. There is no superiority hierarchy. Every single contribution is welcome, as long as it doesn't spam or distract the flow.

6. Write useful, brief commit messages. Add commit descriptions if necessary. PR name should speak about what it is addressing and not the issue. In case a PR fixes an issue, use fixes #ticketno or closes #ticketno in the PR's comment. Briefly explain what your PR is doing.

7. Always test your changes extensively before creating a PR. There's no sense in merging broken code. If a PR is a work in progress (WIP), convert it to draft. It'll let the maintainers know it isn't ready for merging.

8. Read and revise the concepts about programming constructs you're dealing with. You must be clear about the behavior of the language or compiler/transpiler. See JavaScript docs and TypeScript docs.

9. If you have a question, do a web search first. If you don't find any satisfactory answer, then ask it in a comment. If it is a general question about Music Blocks, please use the new discussions tab on top the the repository, or the Sugar-dev Devel <[email protected]> mailing list. Don't ask silly questions (unless you don't know it is silly ;p) before searching it on the web.

Code Quality Notes

1. Sticking to TypeScript conventions, use camelCase for filenames (PascalCase for class files), CAPITALCASE for constants, camelCase for identifiers, and PascalCase for classes. Linting has been strictly configured. A super-linter is configured to lint check the files on a pull request. In fact, the TypeScript watcher or build will throw errors/warnings if there are linting problems. This has been done to maintain code quality.

2. If a PR is addressing an issue, prefix the branch name with the issue number. For example, say a PR is addressing issue 100, a branch name could be 100-patch-foobar.

3. Meaningfully separate code across commits. Don't create arbitrary commits. In case it gets dirty, please do an interactive rebase with squash and reword to improve.

4. Follow conventional commit messages specification to help issue tracking. More often than not, take time to add meaningful commit descriptions. However, add specificity by mentioning the component; prefer mycomponent: [feat] Add button over feat: Add button, mycomponent: [fix] Use try-catch over fix: Use try-catch.

5. At any point, when new components are created or existing components are modified, unit tests (passing) reflecting the changes need to be part of the PR before being reviewed.

6. Two workflows — a Continuous Integration (CI) and a Linter (Super Linter), have been configured. Each PR must pass the checks before being reviewed.

7. For any new functions/methods or classes, add extensive TSDoc documentation.

8. Each PR needs to have supporting unit tests covering all (or as much practical) use cases to qualify for review. In case testing is done via some non-standard method, adequate description of the method/s need/s to be specified in the PR body.

Please note there is no need to ask permission to work on an issue. You should check for pull requests linked to an issue you are addressing; if there are none, then assume nobody has done anything. Begin to fix the problem, test, make your commits, push your commits, then make a pull request. Mention an issue number in the pull request, but not the commit message. These practices allow the competition of ideas (Sugar Labs is a meritocracy).

Setup Development Environment

Without Docker

This is a TypeScript project. You'll need the following installed on your development machine:

• Node.js
• Yarn
• tsc (TypeScript Compiler) to manually compile .ts files.
• ts-node (Node.js executable for TypeScript) to manually execute .ts scripts directly.

Installing Node.js will install NPM (Node.js Package Manager) by default. Use it to install Yarn using

npm install -g yarn

Once Yarn is installed, to install the above, run

yarn global add typescript
yarn global add ts-node

Note: Users on Linux and MacOS are required to add a sudo before these commands.

Check installation using

node -v && yarn -v && tsc -v && ts-node -v

Output should look like

v14.17.0
6.14.13
Version 4.3.2
v10.0.0

With Docker

This project development tools have been containerized using docker. Therefore, to use an execution sandbox, it requires docker to be installed on the development machine.

1. Setup docker.

   • For Linux, install Docker Engine. You'll also need to install Docker Compose.

   • For Windows or Mac, install Docker Desktop.

2. Open a teminal and navigate to working directory (where the source code will reside).

3. Git Clone (additional installation of Git required on Windows) this repository using

   git clone https://github.com/sugarlabs/musicblocks-v4-lib.git

4. Build docker image and launch docker network.

   Note: A built initial development image has been published to Sugar Labs GitHub Container Registry (GHCR), which can be pulled directly, so you don't have to build it again. Pull using

   docker pull ghcr.io/sugarlabs/musicblocks:initial

   Nagivate inside the project directory and launch the docker network using

   docker-compose up -d

   or (for Docker v1.28 and above)

   docker compose up -d

   If you haven't pulled the image from the GitHub Container Registry (GHCR), it'll first build the image using the Dockerfile, then launch the docker network. If an image already exists locally, it'll not be rebuilt. To force a rebuild from the Dockerfile before launching the docker network, add the --build flag.

5. In another terminal, run

   docker attach musicblocks

6. The Linux Debian 10.7 (buster) shell in the docker container named musicblocks is spawned and standard input/output is connected to the terminal.

   Node (Node.js Runtime), yarn (Node Package Manager), tsc (TypeScript Compiler), and ts-node (Node executable for TypeScript) should be installed. Check using

   node --version && yarn --version && tsc --version && ts-node --version

   Output should look like

   v14.16.1
   7.9.0
   Version 4.2.4
   v9.1.1

7. To shut down the docker network, run (in the terminal where you ran docker-compose up -d or docker compose up -d)

   docker-compose down

   or (for Docker v1.28 and above)

   docker compose down

8. To install all the dependencies (in package.json), run

   yarn install --frozen-lockfile

9. Miscellaneous commands.

   • To launch the Node.js runtime, run

     node

   • To run a JavaScript file, say file.js, run

     node file.js

   • To transpile a TypeScipt file, say file.ts, to JavaScript, run

     tsc file.ts

     This transpilation produces file.js.

   • To run a TypeScript file directly, say file.ts, run

     ts-node file.ts

10. Configured scripts.

    • For testing, run

      yarn run test

      To run a specific path

      yarn run test -- "test/path"

      To run in watch mode

      yarn run test -- "test/path" --watch

    • For generating a production build, run

      yarn run build

    • For checking linting problems

      yarn run lint

      To autofix fixable problems

      yarn run lint -- --fix

    Note: If you're running using Docker Desktop on Windows, you might experience longer execution times for these scripts. This happens due to cross-file-system communication. Duration varies across machines; duration primarily depends on hard drive read/write speed.

Editor

All code is just plain text, so it doesn't really matter what you use to edit them. However, using modern, feature-rich IDEs/text-editors like Atom, Brackets, WebStorm, Sublime Text, Visual Studio Code, etc. makes life way easier. These come with a directory-tree explorer, and an integrated terminal, at the very least, while having support for plugins/extensions to expand their functionality.

Some (non-exhaustive) benefits of using these are syntax highlighting, warning/error annotations, formatting, auto-refactoring, tons of customizable keyboard shortcuts, etc.

Visual Studio Code (VSCode) is currently the most-popular code editor for reasons like being lightweight, cleaner, large marketplace of extensions, integrated Source Control features, debugger, remote explorer support, Regular Expression (regular expression) based find/replace, etc.

In fact, a workspace configuration file for vscode.vscode/settings.json has already been added. Recommended extensions for this project are Babel JavaScript, Docker, ESLint, Git Graph, GitLens, markdownlint, Prettier, SCSS IntelliSense, and SVG.

All that, however, shouldn't necessarily stop you from using Emacs, Nano, or Vim, if that's your poison :D. Happy coding!

musicblocks-v4-lib's Issues

Syntax: Rename ElementValue to ElementData

Description

data element seems to be more suitable than value element. value element can be a concrete element that returns a stored value and doesn't do any custom property fetching.

Objectives

• Rename ElementValue and all references to ElementData

Add context and symbol table parameters to syntax element execution methods

Specification: Add snapshot function

Description

Add a function to return the snapshot of the element specification in src/syntax/specification/specification.ts. Add tests for the added function in src/syntax/specification/specification.spec.ts.

The signature is

/**
 * Returns ...
 * @returns - ...
 */
export function generateSnapshot(): {
  [key: string]: {
    ...
    // all properties of IElementSpecification except prototype (see @types/specification.d.ts)
    ...
    prototypeName: string // name of the class (.name)
  }
}

Objectives

• add function generateSnapshot() (and TSDoc documentation)
• add tests for the added function

Please keep commits separate.

Document file interdepencies

This project has a lot of inter-dependencies between its source files. This can be intriguing when trying to get a big picture. Document the interdependencies and exposed members in src/README.md.

Port musicutils prototype code from Python to TypeScript

Some prototype structures have been implemented in Python for music utilities. They are present on the musicutils branch in the src/.prototype/musicutils directory.

Port these files and the unit test file to TypeScript 4. The unit test, as ported, should be evaluated in the configured ts-jest with npm test .... The files have interdependencies, so follow the order:

• scale.py #24
• musicutils.py #28
• keysignature.py #22
• temperament.py #23
• currentpitch.py #26

If possible, split the utils_unittest.py for individual files, going one at a time according to the order above.

Sticking to TypeScript conventions, use PascalCase for filenames, CAPITALCASE for constants, camelCase for identifiers. Linting has been strictly configured. A super-linter is configured to lint check the files on a pull request. In fact, the TypeScript watcher or build will throw errors/warnings if there are linting problems. This has been done to maintain code quality.

For now, create a new directory named ts in src/.prototype/musicutils, and put your new files there. This need not be done has one large PR. But, please follow the file separation at a time. Create a draft PR to start any discussions if required. Should have the test code (pertaining to the corresponding file/s) before each PR is reviewed.

Expose API for use in musicblocks-v4

Description

An npm package is supposed to be built using the source code in this repository. The package will serve as a library responsible for handling the programming tasks in musicblocks-v4. Expose an API consisting of the functions and type definitions that shall be required by musicblocks-v4.

Add unary and binary operators to primitive element classes

File path: src/.prototype/syntaxElements/primitiveElements.ts
Unit-test file path: src/.prototype/syntaxElements/primitiveElements.test.ts

Identify (please list down in a comment) required unary and binary operators for the primitive types:

• TInt
• TFloat
• TChar
• TString
• TBoolean

Implement the identified operators as object (non-static) and class (static) methods:

• TInt (operands of type TInt)
  • add: void (unary)
  • add: TInt (binary)
  • subtract: void (unary)
  • subtract: TInt (binary)
  • multiply: void (unary)
  • multiply: TInt (binary)
  • divide: void (unary)
  • divide: TInt (binary)
  • mod: void (unary)
  • mod: TInt (binary)
  • greaterThan: TBoolean (binary)
  • lessThan: TBoolean (binary)
  • equals: TBoolean (binary)
  • increment: void (unary)
  • decrement: void (unary)
• TFloat (operands of type TInt | TFloat)
  • add: void (unary)
  • add: TFloat (binary)
  • subtract: void (unary)
  • subtract: TFloat (binary)
  • multiply: void (unary)
  • multiply: TFloat (binary)
  • divide: void (unary)
  • divide: TFloat (binary)
  • mod: void (unary)
  • mod: TFloat (binary)
  • greaterThan: TBoolean (binary)
  • lessThan: TBoolean (binary)
  • equals: TBoolean (binary)
  • increment: void (unary)
  • decrement: void (unary)
• TChar
• TString
  • length: () => TInt
  • charAt: (index: TInt) => TChar (throw index out of bounds error)
  • indexOf: (substring: TChar | TString) => TInt
  • substring: (startIndex: TInt, length?: TInt) => TChar (throw index out of bounds error, invalid length only if < 0)
  • equals: (operand: TChar | TString) => TBoolean
  • static equals: (operand_1: TChar | TString, operand_2: TChar | TString) => TBoolean
  • compareTo: (operand: TChar | TString) => TInt
  • static compare: (operand_1: TChar | TString, operand_2: TChar | TString) => TInt
• TBoolean

Write unit tests for the implemented operators:

• TInt (operands of type TInt)
  • add: void (unary)
  • add: TInt (binary)
  • subtract: void (unary)
  • subtract: TInt (binary)
  • multiply: void (unary)
  • multiply: TInt (binary)
  • divide: void (unary)
  • divide: TInt (binary)
  • mod: void (unary)
  • mod: TInt (binary)
  • greaterThan: TBoolean (binary)
  • lessThan: TBoolean (binary)
  • equals: TBoolean (binary)
  • increment: void (unary)
  • decrement: void (unary)
• TFloat (operands of type TInt | TFloat)
  • add: void (unary)
  • add: TFloat (binary)
  • subtract: void (unary)
  • subtract: TFloat (binary)
  • multiply: void (unary)
  • multiply: TFloat (binary)
  • divide: void (unary)
  • divide: TFloat (binary)
  • mod: void (unary)
  • mod: TFloat (binary)
  • greaterThan: TBoolean (binary)
  • lessThan: TBoolean (binary)
  • equals: TBoolean (binary)
  • increment: void (unary)
  • decrement: void (unary)
• TChar
• TString
  • length: () => TInt
  • charAt: (index: TInt) => TChar (throw index out of bounds error)
  • indexOf: (substring: TChar | TString) => TInt
  • substring: (startIndex: TInt, length?: TInt) => TChar (throw index out of bounds error, invalid length only if < 0)
  • equals: (operand: TChar | TString) => TBoolean
  • static equals: (operand_1: TChar | TString, operand_2: TChar | TString) => TBoolean
  • compareTo: (operand: TChar | TString) => TInt
  • static compare: (operand_1: TChar | TString, operand_2: TChar | TString) => TInt
• TBoolean

Some have already been added. Please add the rest.

Syntax Tree: Add validations

Description

generateFromSnapshot function in src/syntax/tree/syntaxTree.ts generates the syntax tree from a snapshot. However, there is no construct to validate the input snapshot.

Also, attachment checking functions and attaching functions have no connections — the idea is that the connection checks will externally be performed first before the connection is made. In this way, if a connection is known to be valid, we can skip the additional cost of reverifying. However, it would be nice to optionally check connection validity before the connections, as a direct step and not a two step process in certain use cases.

Objectives

Snapshot validation

• Add a function to validate an input snapshot
  • Validate shape of snapshot components; refer ITreeSnapshotData, ITreeSnapshotExpression, ITreeSnapshotStatement, ITreeSnapshotBlock (discuss your approach before proceeding as the interfaces listed as TypeScript specific and JavaScript doesn't have them)
  • Validate attachments — whether the snapshot describes valid instruction or argument attachments
• Call the snapshot validation function before generating the syntax tree from it, in generateFromSnapshot

Connection validation

• Add an optional flag to attachArgumentCheck to indicate whether to perform a validation
• Add an optional flag to attachInstructionBelowCheck to indicate whether to perform a validation
• Add an optional flag to attachInstructionInsideCheck to indicate whether to perform a validation

This can be done as two separate PRs.

Syntax: Build some concrete elements

Description

Building the program representation and execution components will require some concrete elements to operate on. Build a few concrete element classes for the purpose.

All concrete elements will inherit the core elements in src/syntax/elements/core: ElementData, ElementExpression, ElementStatement, and ElementBlock.

Objectives

Build the following Program collection of elements:

Values (literals)

• ElementValue which is a data element; returns a stored value

Boxes (variables)

• ElementBox which is an statement element (2 arguments); stores a value (variable)
  operates as boxName ← value
• ElementBoxIdentifier which is a data element; identifies a box (variable name)
  operates as element ← boxName

Operators

• ElementPlus which is an expression element (2 arguments); adds or concatenates
• ElementMinus which is an expression element (2 arguments); subtracts

Flow Elements

• ElementIf which is a block element (1 argument); controls program flow entry to contained instruction if true
• ElementRepeat which is a block element (1 argument); repeat contained instructions iteratively as many times as argument

Syntax: Draft the Element Specification schema

Description

Syntax Element Specification describes the relation between a syntax element name and its corresponding syntax element class. It also describes the selective interconnection configurations.

Objectives

Draft a schema to represent:

• name of the syntax element name
• class representing the syntax element
• selective connections with other syntax elements

Document components of the architecture diagram.

We have a block diagram of the project architecture; but we need a README.md file (in the docs subdirectory) that includes descriptions of each component of the diagram.

• Element API
• Specification
• Warehouse
• Tree

---

• Library Elements
• Plugin Elements

---

• Symbol Table
• Scheduler
• Parser
• Interpreter

---

• Monitor

The documentation should describe the functionality of each component and the role of the arrows in and out of each box.

Add support for scopes

Context

A group of syntax elements (related to one component in the app) may require a set of runtime states and flags, to be called context. Contexts for different groups will be independent of each other.

Symbol Table

Some syntax elements may create a dynamically named state (like a variable). They should be able to be defined, fetched, and updated by their name (identifier).

Scope

All context sets and the symbol table need to have a global set of values accessible all across the program runtime. In addition, each process and routine get to create their own copy (or use an existing one). Thereafter, as control flows into nesting, a new scope copy is created, and as control flows out, the newly created scope is destroyed. Context and symbol table keys added inside of a scope shadow same keys created outside of it. The process needs to be transparent.

Advance parser by one instruction at a time

Currently, the interpreter instructs the parser to advance control one syntax element at a time. Add support to advance by one instruction at a time.

Docker: Base image on Alpine

Description

The current image uses a slimmed build of Debian 10.7 (Buster) which is around 70MB. The aim is to get all the things installed in a smaller linux distribution — Alpine.

Objective

• Base the Dockerfile on an Alpine image.
• Install node, npm, typescript, ts-node using apk

Execution: Build the Interpreter

Description

Interpreter orchestrates the sequential execution of syntax elements using the Parser.

Objectives

• #89
• #90
• Sequentially traverse the per-program syntax element sequence using the Parser
• Execute individual syntax elements while passing parameter values, Parser, and Symbol Table references, between connected elements.

Add support for recursive control jump between processes and routines

Syntax: Build the Syntax Tree

Description

Syntax Tree handles the interconnections between the syntax elements to form the syntax of the program. It takes care of selective connections of argument elements based on the expected and return types, and the selective connections of instruction elements, using the Syntax Element Specification.

Objectives

• Draft the schema of the syntax tree
• Add connections between two syntax elements
• Remove connections between two syntax elements

Build constructs to orchestrate execution of syntax elements

Description

6 constructs: Element Specification, Element Warehouse, Syntax Tree, Program Counter, Symbol Table, and Interpreter

• Element Specification describes the relation between a syntax element name and its corresponding syntax element class. It also describes the selective interconnection configurations.

• Element Warehouse handles the logistics of instantiating syntax elements and maintaining a record of them.

• Syntax Tree handles the interconnections between the syntax elements to form the syntax of the program. It takes care of selective connections of argument elements based on the expected and return types. It also takes care of the selective connections of instruction elements.

• Parser represents the execution sequence of syntax elements as structured in the Syntax Tree and dynamically stores the current and next elements in the sequence.

• Symbol Table stores the defined variables and their values.

• Interpreter orchestrates the sequential execution of syntax elements using the Program Counter.

Notes

• Variable scopes are program-wide and not block-wide. However, global scopes are applicable across programs.

Objectives

• #73
• #74
• #75
• #76
• #77
• #78

Update the initial development Docker image

Test docker-compose on different common Operating Systems for development:

• Windows 10 (with WSL2)
• Windows 10 (with WSL)
• Mac OS 11.x (Big Sur) [Docker Preview]
• Mac OS 10.15 (Catalina)
• Ubuntu 21.04 (Hitsute Hippo)
• Ubuntu 20.10 (Groovy Gorilla)
• Ubuntu 20.04 (Focal Fossa)
• Fedora 34
• Fedora 33

Interpreter: Add proxy functions for Parser

Create basic proxy functions for Parser operations

part of #78.

Add exhaustive list of Error subclasses

Currently, there are several Error instances like TypeMismatchError, InvalidDataError, etc. which are thrown from across all units. List all and make Error subclasses for each unique behaviour.

Specification: Add validation in functions

Description

Add validation to the functions in src/syntax/specification/specification.ts. Add tests for the added validations in src/syntax/specification/specification.spec.ts.

Objectives

• registerElementSpecificationEntry: return false if element name already exists else true
• registerElementSpecificationEntry: add tests for the validation
• registerElementSpecificationEntries: add only entries for elements that don't exist; return a boolean array (see previous)
• registerElementSpecificationEntries: add tests for the validation
• removeElementSpecificationEntry: return true is successfully removed else false
• removeElementSpecificationEntry: add tests for the validation
• removeElementSpecificationEntries: return a boolean array (see previous)
• removeElementSpecificationEntries: add tests for the validation

Make changes to the return type definitions (and add TSDoc comment for @returns). Please keep commits separate.

Interpreter: Add proxy functions for Symbol Table

Create basic proxy functions for Symbol Table operations:

• declareVariable: adds a global variable to symbol table
• queryVariable: fetches a global variable from symbol table

part of #78.

Syntax: Build constructs to represent syntax elements

Description

• 2 kinds of syntax elements: Arguments and Instructions
  • Arguments return a value and are of 2 kinds: Values and Expressions
    • Values return a value without processing
    • Expressions operate on values returned by Values and other Expressions and return a value
  • Instructions perform a tasks and may or may not operate on Arguments; they are of 2 kinds: Statements and Blocks
    • Statements execute one task each
    • Blocks encapsulate Statements; they set up the state before containing Statements execute and restore the state after all containing Statements are executed
• Every syntax element has a name, class (Argument or Instruction), type (Value, Expression, Statement, or Block), and argument configuration (number and data-type of arguments it accepts with labels)

API

Syntax Element

• name field to get the element name
• class field to get the element class: Argument, Instruction
• type field to get the element type: Value, Expression, Statement, Block
• argCount field to get the number of arguments
• argLabels field to get the list of argument names
• argMap field to get a key-value pair object of argument labels and expected data-types

Argument Element

• returnType field to get the return type of the argument element

Value Element

• value field to get the value returned

Expression Element

• evaluate method to return the value after evaluation of the expression; takes the values of the arguments as parameters

Statement Element

• onVisit method to execute the statement logic; takes the values of the arguments as parameters

Block Element

• onVisit method to setup state configurations for the contained statements; takes the values of the arguments as parameters
• onInnerVisit method to setup any state configurations before every contained statement is executed
• onInnerExit method to setup any state configurations after every contained statement is executed
• onExit method to restore the state before the element was visited

Objectives

• Develop ElementSyntax abstract class
• Develop ElementArgument abstract class
• Develop ElementValue abstract class by inheriting ElementArgument
• Develop ElementExpression abstract class by inheriting ElementArgument
• Develop ElementInstruction abstract class
• Develop ElementStatement abstract class by inheriting ElementInstruction
• Develop ElementBlock abstract class by inheriting ElementInstruction
• Add tests for ElementSyntax by creating a dummy class that inherits it
• Add tests for ElementArgument by creating a dummy class that inherits it
• Add tests for ElementValue by creating a dummy class that inherits it
• Add tests for ElementExpression by creating a dummy class that inherits it

Update package dependencies

Description

The packages in the project need to be updated to the latest. However, there are interdependencies between the packages (e.g. currently configured TypeScript plugin for ESLint doesn't support TypeScript versions above 4.5.0).

Objectives

• Update Dependencies (By default versions will be preceded by ^. But, you might have to hard configure versions (without the ^). Watch out for such cases.)
• Check that all yarn scripts defined in package.json are running.

Add support for concurrent execution

Migrate to Yarn from NPM

Description

The project currently uses NPM for dependency management. However, Yarn is generally faster than NPM. Migrate the usage of NPM to Yarn.

Objectives

• Replace package-lock.json with yarn.lock
  • install yarn locally (npm i -g yarn)
  • remove node_modules folder and package-lock.json file, then run yarn install
• Update Dockerfile
  • remove NPM update step
  • replace npm install -g steps with yarn global add
• Update GitHub Actions CI workflow steps
  • replace run: npm ci with run: yarn install --frozen-lockfile
  • enable step run: yarn run build
  • replace run: npm run test --if-present with run: yarn run test
  • Update comment from Run npm scripts to Run yarn scripts
• Update README.md
  • replace npm based instructions to yarn based instructions

This may be completed through 4 separate PRs.

Add documentation for each individual component

There are currently no in-depth documentation for the components (syntax, specification, etc.). Add README.md files.

Syntax: Build the Symbol Table

Description

Symbol Table stores the defined variables and their values.

Objectives

• Maintain a map of variable ID with its type and value
• Add a new variable entry with a unique ID
• Remove a variable entry
• Fetch a variable details from ID
• Add concept of project scoping and global scoping

Docker build fails

The dockerfile doesn't build instead, shows an error upon execution of docker build command.

The dockerfile on my system:-

If I have done something wrong somewhere or I missed out on something crucial, please do tell me the same. I look forward to a fix for this issue. Thanks

Add support for instruction runtime elongation

Execution: Build the Parser

Description

Parser represents the execution sequence of syntax elements as structured in the Syntax Tree and dynamically stores the current and next elements in the sequence.

Objectives

• Generate the sequence of execution of syntax elements
• Maintain a per-program counter for the current and next element to execute
• Generate scopes of variables (for destruction at end of scope)

Symbol Table: Maintain tables by variable data type

Description

The Symbol Table component in src/syntax/symbol-table/symbolTable.ts maintains global, program-specific, and routine-specific variables only by variable name. You can only fetch variables by variable name. Add methods for each table to fetch variables by variable name and variable data type.

For example, say there is a global variable foo of data type number. Currently you can fetch it by getGlobalVariable('foo'). The objective is to optionally supply the type as well like getGlobalVariable('foo', 'number'), which returns the same. But, calling getGlobalVariable('foo', 'string') returns null.

Objectives

Refactor function signatures (make change in symbolTable.ts file and the symbolTable.spec.ts file):

• getGlobalVariable(variable: string, dataType?: TDataName): IVariable | null
• getProcessVariable(variable: string, program: string, dataType?: TDataName): IVariable | null
• getRoutineVariable(variable: string, routine: string, dataType?: TDataName): IVariable | null

Add unit tests for:

• getGlobalVariable with dataType field
• getProcessVariable with dataType field
• getRoutineVariable with dataType field

Syntax: Build the Element Warehouse

Description

Syntax Element Warehouse handles the logistics of instantiating syntax elements and maintaining a record of them.

Objectives

• Instantiate syntax element from element name as described in Syntax Element Specification
• Generate a unique ID for each instance
• Maintain a map of element ID and element instance
• Remove element entry
• Add utilities to generate metrics on the set of element instances