Merge pull request #125 from sugarlabs/develop

Release v1.0.1

CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## 1.0.1 [2022-02-09]
+
+- ([#122](https://github.com/sugarlabs/musicblocks-v4-lib/pull/122))
+Added provision to provide initialisation values in snapshot of data elements.
+- ([#119](https://github.com/sugarlabs/musicblocks-v4-lib/pull/119))
+Added function to **specification** snapshot.
+- ([#121](https://github.com/sugarlabs/musicblocks-v4-lib/pull/121))
+Removed custom type reliance for element name (`TElementName`).
+- ([#120](https://github.com/sugarlabs/musicblocks-v4-lib/pull/120))
+Updated package dependencies.
+- ([#118](https://github.com/sugarlabs/musicblocks-v4-lib/pull/118))
+Added validations in **specification** functions for registering and unregistering _syntax elements_.
+
+## 1.0.0 [2022-01-26]
+
+- Added 3 categories of components: **Syntax Representation**, **Execution Engine**, **Library**
+
+  - **Syntax Representation**
+
+    - Added **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
+
+    - Added **Specification** component: maintains a table of concrete **syntax elements** which can
+    be used to build programs.
+    - Added **Warehouse** component: maintains a table of instances of **syntax elements** registered
+    in the **specification**. It can also generate statistics about the instances.
+    - Added **Syntax Tree** component: represents the _abstract syntax tree_ or _AST_ by maintaining
+    interconnections between **syntax elements**.
+
+  - **Execution Engine**
+
+    - Added **Symbol Table** component: maintains tables of dynamic global variables and states which
+    the **syntax elements** can use during execution.
+    - Added **Parser** component: parses the **syntax tree** in a postorder sequence, and maintains
+    _call frame stacks_ and the _program counter_.
+    - Added **Interpreter** component: fetches elements from the **parser** and executes them.
+
+    - 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_.
+
+  - **Library**
+
+    - Added basic **Concrete Syntax Elements**
+      - **Values**
+        - Represent stored values
+        - Supports `boolean`, `number`, `string` data-types
+      - **Boxes**
+        - Represents variable values
+        - Support `boolean`, `number`, `string`, `generic` data-types
+      - **Box Identifiers**
+        - Represents variable identifiers
+        - Supports `boolean`, `number`, `string`, `generic` **boxes**
+      - **Math Operators**
+        - `plus`, `minus`, `times`, `divide`, `modulus` operators
+      - **Conditionals**: `if`
+      - **Loops**: generic `repeat`
+      - **Program**: `process` and `routine`
+      - **Miscellaneous**: `print`
+    - Added a _specification_ of the above **syntax elements**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sugarlabs/musicblocks-v4-lib",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "The core of the new Music Blocks (v4) application",
   "repository": {
     "type": "git",
@@ -17,21 +17,21 @@
   "main": "index.js",
   "types": ".",
   "devDependencies": {
-    "@types/jest": "^26.0.19",
-    "@types/uuid": "^8.3.1",
-    "@typescript-eslint/eslint-plugin": "^4.11.1",
-    "@typescript-eslint/parser": "^4.11.1",
-    "eslint": "^7.17.0",
-    "eslint-config-prettier": "^7.1.0",
+    "@types/jest": "^27.4.0",
+    "@types/uuid": "^8.3.4",
+    "@typescript-eslint/eslint-plugin": "^5.10.2",
+    "@typescript-eslint/parser": "^5.10.2",
+    "eslint": "^8.8.0",
+    "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-json": "^3.1.0",
-    "jest": "^26.6.3",
-    "prettier": "^2.4.1",
+    "jest": "^27.4.7",
+    "prettier": "^2.5.1",
     "textlint": "^12.1.0",
     "textlint-rule-no-dead-link": "^4.8.0",
     "textlint-rule-no-empty-section": "^1.1.0",
     "textlint-rule-terminology": "^2.1.5",
-    "ts-jest": "^26.4.4",
-    "typescript": "4.1.3"
+    "ts-jest": "^27.1.3",
+    "typescript": "4.5.5"
   },
   "dependencies": {
     "uuid": "^8.3.2"

src/@types/elements.d.ts

@@ -1,12 +1,12 @@
 import { TData, TDataName } from './data';
-import { TElementName, TElementKind, TElementType } from './specification';
+import { TElementKind, TElementType } from './specification';
 
 // -------------------------------------------------------------------------------------------------
 
 /** Interface for the class that implements a syntax element. */
 export interface IElementSyntax {
     /** Name of the syntax element. */
-    name: TElementName;
+    name: string;
     /** Display name of the syntax element. */
     label: string;
     /** Kind (`Argument`, `Instruction`) of the syntax element. */

src/@types/specification.d.ts

@@ -1,4 +1,4 @@
-import { TData } from './data';
+import { TData, TDataName } from './data';
 import {
     IElementData,
     IElementExpression,
@@ -14,54 +14,17 @@ export type TElementKind = 'Argument' | 'Instruction';
 /** Type (`Data`, `Expression`, `Statement`, `Block`) of the syntax element. */
 export type TElementType = 'Data' | 'Expression' | 'Statement' | 'Block';
 
-/** Names of factory list of data elements. */
-export type TElementNameData =
-    // value elements
-    | 'value-boolean'
-    | 'value-number'
-    | 'value-string'
-    // box identifier elements
-    | 'boxidentifier-generic'
-    | 'boxidentifier-boolean'
-    | 'boxidentifier-number'
-    | 'boxidentifier-string';
-
-/** Names of factory list of expression elements. */
-export type TElementNameExpression =
-    // math operator elements
-    | 'operator-math-plus'
-    | 'operator-math-minus'
-    | 'operator-math-times'
-    | 'operator-math-divide'
-    | 'operator-math-modulus';
-
-/** Names of factory list of statement elements. */
-export type TElementNameStatement =
-    // box elements
-    | 'box-generic'
-    | 'box-boolean'
-    | 'box-number'
-    | 'box-string'
-    // print element
-    | 'print';
-
-/** Names of factory list of block elements. */
-export type TElementNameBlock = 'process' | 'routine' | 'repeat' | 'if';
-
-/** Names of factory list of syntax elements. */
-export type TElementName =
-    | 'dummy'
-    | TElementNameData
-    | TElementNameExpression
-    | TElementNameStatement
-    | TElementNameBlock;
-
 /** Type for the specification object for data elements. */
 export interface IElementSpecificationData {
     label: string;
     type: 'Data';
     category: string;
-    prototype: (name: TElementNameData, label: string) => IElementData<TData>;
+    prototype: (name: string, label: string) => IElementData<TData>;
+    values?:
+        | string[]
+        | {
+              types: TDataName[];
+          };
 }
 
 /** Type for the specification entry object for data elements. */
@@ -77,7 +40,7 @@ export interface IElementSpecificationExpression {
     label: string;
     type: 'Expression';
     category: string;
-    prototype: (name: TElementNameExpression, label: string) => IElementExpression<TData>;
+    prototype: (name: string, label: string) => IElementExpression<TData>;
 }
 
 /** Type for the specification object for expression elements. */
@@ -90,21 +53,21 @@ export interface IElementSpecificationEntryExpression extends IElementSpecificat
 
 /** Type for the specification object for instruction elements. */
 interface IElementSpecificationInstruction {
-    allowAbove?: TElementName[] | boolean;
-    allowBelow?: TElementName[] | boolean;
-    forbidAbove?: TElementName[];
-    forbidBelow?: TElementName[];
+    allowAbove?: string[] | boolean;
+    allowBelow?: string[] | boolean;
+    forbidAbove?: string[];
+    forbidBelow?: string[];
     allowedNestLevel?: number[] | 'any';
-    allowedNestInside?: TElementNameBlock[] | boolean;
-    forbiddenNestInside?: TElementNameBlock[];
+    allowedNestInside?: string[] | boolean;
+    forbiddenNestInside?: string[];
 }
 
 /** Type for the specification object for statement elements. */
 export type IElementSpecificationStatement = IElementSpecificationInstruction & {
     label: string;
     type: 'Statement';
     category: string;
-    prototype: (name: TElementNameStatement, label: string) => IElementStatement;
+    prototype: (name: string, label: string) => IElementStatement;
 };
 
 /** Type for the specification object for statement elements. */
@@ -120,9 +83,9 @@ export type IElementSpecificationBlock = IElementSpecificationInstruction & {
     label: string;
     type: 'Block';
     category: string;
-    prototype: (name: TElementNameBlock, label: string) => IElementBlock;
-    allowNestInside?: (TElementNameStatement | TElementNameBlock)[] | boolean;
-    forbidNestInside?: (TElementNameStatement | TElementNameBlock)[];
+    prototype: (name: string, label: string) => IElementBlock;
+    allowNestInside?: string[] | boolean;
+    forbidNestInside?: string[];
 };
 
 /** Type for the specification entry object for block elements. */
@@ -131,22 +94,33 @@ export type IElementSpecificationEntryBlock = IElementSpecificationInstruction &
     type: 'Block';
     category: string;
     prototype: typeof IElementBlock;
-    allowNestInside?: (TElementNameStatement | TElementNameBlock)[] | boolean;
-    forbidNestInside?: (TElementNameStatement | TElementNameBlock)[];
+    allowNestInside?: string[] | boolean;
+    forbidNestInside?: string[];
 };
 
+/** Type for the specification object for an element. */
 export interface IElementSpecification {
     label: string;
     type: TElementType;
     category: string;
-    prototype: new (name: TElementName, label: string) => IElementSyntax;
-    allowAbove?: TElementName[] | boolean;
-    allowBelow?: TElementName[] | boolean;
-    forbidAbove?: TElementName[];
-    forbidBelow?: TElementName[];
+    prototype: new (name: string, label: string) => IElementSyntax;
+    allowAbove?: string[] | boolean;
+    allowBelow?: string[] | boolean;
+    forbidAbove?: string[];
+    forbidBelow?: string[];
     allowedNestLevel?: number[] | 'any';
-    allowedNestInside?: TElementNameBlock[] | boolean;
-    forbiddenNestInside?: TElementNameBlock[];
-    allowNestInside?: (TElementNameStatement | TElementNameBlock)[] | boolean;
-    forbidNestInside?: (TElementNameStatement | TElementNameBlock)[] | boolean;
+    allowedNestInside?: string[] | boolean;
+    forbiddenNestInside?: string[];
+    allowNestInside?: string[] | boolean;
+    forbidNestInside?: string[] | boolean;
+    values?:
+        | string[]
+        | {
+              types: TDataName[];
+          };
+}
+
+/** Type for the snapshot of an element's specification. */
+export interface IElementSpecificationSnapshot extends Omit<IElementSpecification, 'prototype'> {
+    prototypeName: string;
 }

src/@types/syntaxTree.d.ts

@@ -1,17 +1,11 @@
-import {
-    TElementNameData,
-    TElementNameExpression,
-    TElementNameStatement,
-    TElementNameBlock,
-    TElementName,
-} from './specification';
-
 // -- snapshots ------------------------------------------------------------------------------------
 
 /** Type definition for the snapshot input of a data element. */
 export interface ITreeSnapshotDataInput {
     /** Name of the data element. */
     elementName: string;
+    /** Value to initialize data element with. */
+    value?: string;
 }
 
 /** Type definition for the snapshot of a data element. */
@@ -105,7 +99,7 @@ export interface ITreeSnapshot {
 /** Type definition for the class that implements a generic syntax tree node. */
 interface ITreeNode {
     /** Name of the syntax element. */
-    elementName: TElementName;
+    elementName: string;
     /** Node ID of the syntax tree node instance. */
     nodeID: string;
     /** Warehouse ID of the syntax element instance. */
@@ -121,15 +115,15 @@ export interface ITreeNodeArgument extends ITreeNode {
 /** Type definition for the class that implements a syntax tree data node. */
 export interface ITreeNodeData extends ITreeNodeArgument {
     /** Name of the data element. */
-    elementName: TElementNameData;
+    elementName: string;
     /** Returns a snapshot of the syntax tree data node. */
     snapshot: ITreeSnapshotData;
 }
 
 /** Type definition for the class that implements a syntax tree expression node. */
 export interface ITreeNodeExpression extends ITreeNodeArgument {
     /** Name of the expression element. */
-    elementName: TElementNameExpression;
+    elementName: string;
     /** Returns a snapshot of the syntax tree expression node. */
     snapshot: ITreeSnapshotExpression;
     /** Object with key-value pairs of argument names and corresponding argument nodes. */
@@ -175,15 +169,15 @@ export interface ITreeNodeInstruction extends ITreeNode {
 /** Type definition for the class that implements a syntax tree statement node. */
 export interface ITreeNodeStatement extends ITreeNodeInstruction {
     /** Name of the statement element. */
-    elementName: TElementNameStatement;
+    elementName: string;
     /** Returns a snapshot of the syntax tree statement node. */
     snapshot: ITreeSnapshotStatement;
 }
 
 /** Type definition for the class that implements a syntax tree block node. */
 export interface ITreeNodeBlock extends ITreeNodeInstruction {
     /** Name of the block element. */
-    elementName: TElementNameBlock;
+    elementName: string;
     /** Returns a snapshot of the syntax tree block node. */
     snapshot: ITreeSnapshotBlock;
     /** Syntax tree node reference of the first nested instruction element. */