@andrivet/z80-assembler 1.3.2 → 1.4.0

package/.editorconfig

@@ -0,0 +1,13 @@
+# Editor configuration, see http://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+libs/z80-assembler/src/lib/grammar/z80.ts
+libs/z80-assembler/src/lib/**/*.test.ts

package/.eslintrc.json

@@ -0,0 +1,35 @@
+{
+  "root": true,
+  "ignorePatterns": ["**/*"],
+  "plugins": ["@nx"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {
+        "@nx/enforce-module-boundaries": [
+          "error",
+          {
+            "enforceBuildableLibDependency": true,
+            "allow": [],
+            "depConstraints": [
+              {
+                "sourceTag": "*",
+                "onlyDependOnLibsWithTags": ["*"]
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "extends": ["plugin:@nx/typescript"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "extends": ["plugin:@nx/javascript"],
+      "rules": {}
+    }
+  ]
+}

package/.github/workflows/node.js.yml

@@ -0,0 +1,47 @@
+name: CD
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - name: Install dependencies
+      run: npm ci --legacy-peer-deps
+    - name: Build
+      run: npx nx build z80-assembler-app --prod --baseHref=/z80-assembler/
+    - name: Run tests
+      run: npx nx test z80-assembler
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: dist/apps/z80-assembler-app
+
+  deploy:
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

package/.prettierignore

@@ -0,0 +1,3 @@
+# Add files here to ignore them from prettier formatting
+/dist
+/coverage

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "singleQuote": true
+}

package/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "nrwl.angular-console",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint"
+  ]
+}

package/README.md

@@ -1,53 +1,79 @@
 # z80-assembler
 
-A Z80 assembler library entirely written in Typescript and derived from a PEG grammar.
-It optimized for the old ZX81 computer but can also be used with any other Z80 targets.
+![Z80](assets/images/logo.png)
 
-## Demo application
+A Z80 assembler entirely written in Typescript and derived from a PEG grammar.
 
-A demo application is available: https://andrivet.github.io/z80-assembler/.
+## Components
 
-## Quick guide to use the library
+* The first component is the library itself, `z80-assembler` that can be used like any npm library.
+* The second component is an application, `z80-assembler-app` that uses this library.
+  It can be used by itself or as an example of how to use the library. It is written in Typescript with React.
 
-To install the library:
+![z80-assembler-app](assets/images/z80-assembler-app.png)
+
+This assembler is also used in the [ZX81 Debugger](https://github.com/andrivet/ZX81-Debugger).
+
+## How to build from source
 
 ```
-$ npm install @andrivet/z80-assembler
+npm --legacy-peer-deps install
+./node_modules/.bin/nx run z80-assembler-app:build:production
 ```
 
-The main function is simply called `compile`. It takes three arguments:
+Notes: 
 
-* the name of the source file
-* the Z80 source code to compile
-* a function used to return the content of included files
+* For the moment, you have to use `--legacy-peer-deps` because react-daisyui is not yet updated for DaisyUI 3.
+Once it is the case, this flag will no more be necessary.
 
-It returns an object of type `CompilationInfo` with the following fields:
+* If you have installed NX globally, you do not need to specify its path.
 
-* `outputName`: The name of the output as set by the `output` directive.
-* `bytes`: A array of numbers. Each element represents a byte of the generated machine code.
-* `sld`: The Source Level Debugging data as a string. This is used in order to debug the code.
-* `errs`: An array of errors
-
-A typical way to use the function is:
+## How to run the application
 
 ```
-const info = compile(filepath, code, handleGetFileCode);
-if(info.errs.length > 0)
-  displayErrors(info.errs);
-else
-  saveOutput(info.outputName, info.bytes);
+nx run z80-assembler-app:dev:production
 ```
 
-You can find a complete example in the [demo application](https://github.com/andrivet/z80-assembler/), in particular in the `app.tsx` file.
+Open a navigator at the URL http://localhost:4200/
+
+
+## Quick guide to use the application
+
+Under the **File** menu, you find the following commands:
+
+![Z80](assets/images/menu.png)
+
+* **Open Code**: Open a Z80 source file.
+* **Open Code Directory**: Open a directory with Z80 source files. This is especially useful if your source files contain includes.
+* **Save Code**: Save the current code file.
+* **Save Binary**: Save the compiled binary.
+* **Save SLD File**: Save the Source Level Debugging data in text format.
+* **Close Code**: Close the current code.
+* **Close All**: Close all the open codes.
+
+![Z80](assets/images/open-dir.png)
+
+Once one or more files are open, click on Compile to compile the code.
+The binary are displayed on the right side:
+
+![Z80](assets/images/compile.png)
+
+While writing your Z80 assembly code, you can display the list of Z80 opcodes by clicking on **Z80 Opcodes**:
+
+![Z80](assets/images/opcodes.png)
+
+Click on a category to see the corresponding opcodes:
+
+![Z80](assets/images/opcodes-load8.png)
 
+## Z80 assembly
 
-## Source code
+The format of assembly source file is described in [Z80 Assembly Source Code Format](./docs/assembly.md).
 
-The source code is published on GitHub: https://github.com/andrivet/z80-assembler/.
 
 ## Licence
 
-This library and associated application are released under GPLv3.
+This library and application are released under GPLv3.
 
 ## Copyrights
 

package/apps/z80-assembler-app/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["plugin:@nx/react", "../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

package/apps/z80-assembler-app/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Z80 Assembler in Typescript</title>
+    <base href="/" />
+
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="stylesheet" href="/src/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/apps/z80-assembler-app/postcss.config.js

@@ -0,0 +1,24 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        postcss.config.js
+ * Description: Configuration for PostCSS
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+const { join } = require('path');
+
+// Note: If you use library-specific PostCSS/Tailwind configuration then you should remove the `postcssConfig` build
+// option from your application's configuration (i.e. project.json).
+//
+// See: https://nx.dev/guides/using-tailwind-css-in-react#step-4:-applying-configuration-to-libraries
+
+module.exports = {
+  plugins: {
+    tailwindcss: {
+      config: join(__dirname, 'tailwind.config.js'),
+    },
+    autoprefixer: {},
+  },
+};

package/apps/z80-assembler-app/project.json

@@ -0,0 +1,70 @@
+{
+  "name": "z80-assembler-app",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/z80-assembler-app/src",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "@nx/vite:build",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "outputPath": "dist/apps/z80-assembler-app"
+      },
+      "configurations": {
+        "development": {
+          "mode": "development"
+        },
+        "production": {
+          "mode": "production"
+        }
+      }
+    },
+    "dev": {
+      "executor": "@nx/vite:dev-server",
+      "defaultConfiguration": "development",
+      "options": {
+        "buildTarget": "z80-assembler-app:build"
+      },
+      "configurations": {
+        "development": {
+          "buildTarget": "z80-assembler-app:build:development",
+          "hmr": true
+        },
+        "production": {
+          "buildTarget": "z80-assembler-app:build:production",
+          "hmr": false
+        }
+      }
+    },
+    "preview": {
+      "executor": "@nx/vite:preview-server",
+      "defaultConfiguration": "development",
+      "options": {
+        "buildTarget": "z80-assembler-app:build"
+      },
+      "configurations": {
+        "development": {
+          "buildTarget": "z80-assembler-app:build:development"
+        },
+        "production": {
+          "buildTarget": "z80-assembler-app:build:production"
+        }
+      }
+    },
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["apps/z80-assembler-app/**/*.{ts,tsx,js,jsx}"]
+      }
+    },
+    "serve-static": {
+      "executor": "@nx/web:file-server",
+      "options": {
+        "buildTarget": "z80-assembler-app:build"
+      }
+    }
+  },
+  "tags": []
+}

package/apps/z80-assembler-app/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "React App",
+  "name": "Create React App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

package/apps/z80-assembler-app/public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

package/apps/z80-assembler-app/src/app/app.tsx

@@ -0,0 +1,122 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        app.tsx
+ * Description: Application view
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import styles from './app.module.css';
+
+import React, {useRef, useState} from 'react';
+import {AppOpcodes} from "./opcodes";
+import {Chunk, CompilationError, compile, formatBytes} from "@andrivet/z80-assembler";
+import AppFooter from "./footer";
+import AppHeader from "./header";
+import AppBinary from "./binary";
+import AppEditor, {AppEditorHandlers} from "./editor";
+import Errors from "./errors";
+import {closeDropdown} from "./misc";
+import {fileSave} from "browser-fs-access";
+
+interface BinaryOrOpCodesProps {
+  showOpCodes: boolean,
+  chunks: Chunk[] | undefined;
+}
+
+function BinaryOrOpCodes({showOpCodes, chunks}: BinaryOrOpCodesProps) {
+  return showOpCodes ? <AppOpcodes /> : <AppBinary chunks={chunks} />;
+}
+
+export function App() {
+  const [code, setCode] = useState<string>('');
+  const [filepath, setFilepath] = useState<string>('');
+  const [errors, setErrors] = useState<CompilationError[] | undefined>();
+  const [bytes, setBytes] = useState<number[] | undefined>();
+  const [sld, setSld] = useState<string>('');
+  const [chunks, setChunks] = useState<Chunk[] | undefined>();
+  const [showOpCodes, setShowOpCodes] = useState<boolean>(false);
+  const [outputName, setOutputName] = useState<string | undefined>(undefined);
+  const ref = useRef<AppEditorHandlers>(null);
+
+  function handleGetFileCode(filename: string): string {
+    if(ref.current == null) throw new Error(`Invalid reference to the editor`);
+    return ref.current.getCode(filename);
+  }
+
+  function handleCompile() {
+    const info = compile(filepath, code, handleGetFileCode);
+    if(info.errs.length > 0) {
+      setBytes([]);
+      setSld('');
+      setChunks([]);
+      setErrors(info.errs);
+    }
+    else {
+      setShowOpCodes(false);
+      setOutputName(info.outputName);
+      setBytes(info.bytes);
+      setSld(info.sld);
+      setChunks(formatBytes(info.bytes, 16));
+      setErrors([]);
+    }
+  }
+
+  async function handleSaveBinary() {
+    closeDropdown();
+    if (!bytes || !outputName) return;
+    const data = Uint8Array.from(bytes);
+    const blob = new Blob([data]);
+    await fileSave(blob, {
+      fileName: outputName,
+      extensions: ['.P']
+    });
+  }
+
+  async function handleSaveSld() {
+    closeDropdown();
+    if (sld.length <= 0 || !outputName) return;
+    const blob = new Blob([sld]);
+    await fileSave(blob, {
+      fileName: outputName.replace(/\.P$/, ''),
+      extensions: ['.sld']
+    });
+  }
+
+  return (
+    <div className="flex flex-col h-screen bg-neutral-600">
+      <AppHeader
+        onOpenCode={() => ref.current?.openCode()}
+        onOpenCodeDirectory={() => ref.current?.openCodeDirectory()}
+        onSaveCode={() => ref.current?.saveCode()}
+        onSaveBinary={handleSaveBinary}
+        onSaveSld={handleSaveSld}
+        onClose={() => ref.current?.closeCode()}
+        onCloseAll={() => ref.current?.closeAll()}
+        onCompile={handleCompile}
+        onShowOpCodes={() => setShowOpCodes(true)}
+      />
+      <div className="flex-1 flex m-4 gap-4">
+        <div className="flex flex-col w-2/3">
+          <AppEditor
+            ref={ref}
+            code={code}
+            setFilePath={setFilepath}
+            setCode={setCode}
+            errors={errors}
+            setErrors={setErrors} />
+        </div>
+        <div className="flex flex-col w-1/3 z-0">
+          <BinaryOrOpCodes showOpCodes={showOpCodes} chunks={chunks}/>
+        </div>
+      </div>
+      <Errors errors={errors} />
+      <AppFooter />
+    </div>
+  );
+}
+
+export default App;

package/apps/z80-assembler-app/src/app/binary.tsx

@@ -0,0 +1,39 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        binary,tsx
+ * Description: Binary view
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import React from "react";
+import {Table} from "react-daisyui";
+import {Chunk} from "@andrivet/z80-assembler";
+
+interface AppBinaryProps {
+  chunks: Chunk[] | undefined;
+}
+
+export default function AppBinary({chunks}: AppBinaryProps) {
+  return (chunks == null || chunks.length <= 0) ? null : (
+    <>
+      <h1 className="font-bold mb-2 text-orange-400">Machine Code</h1>
+      <div className="flex flex-auto h-full relative mt-0">
+        <div className="absolute top-0 bottom-0 left-0 right-0 overflow-auto">
+          <Table zebra={true}>
+            <Table.Head>{['Address', 'Bytes']}</Table.Head>
+            <Table.Body>
+              {chunks?.map((data, index) => (
+                <Table.Row key={data.address}  className="font-mono">{[
+                  <strong key={`addr-${data.address}`} className="text-orange-400">{data.address}</strong>,
+                  <span key={`data-${data.address}`} >{data.bytes}</span>
+                ]}</Table.Row>
+              ))}
+            </Table.Body>
+          </Table>
+        </div>
+      </div>
+    </>
+  );
+}