@andrivet/z80-assembler 1.4.0 → 1.4.1

package/{libs/z80-assembler/src/lib/compiler/Assets.ts → lib/compiler/Assets.d.ts}

@@ -7,15 +7,10 @@
  * License:			GPLv3
  * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
  */
-
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-//@ts-nocheck
-
 import assetCharacters from '../assets/code/characters.zx81?raw';
 import assetSystemVariables from '../assets/code/system-variables.zx81?raw';
 import assetBasicLine1 from '../assets/code/basic-line1.zx81?raw';
 import assetBasicLine2 from '../assets/code/basic-line2.zx81?raw';
 import assetDisplay from '../assets/code/display.zx81?raw';
 import assetBasicEnd from '../assets/code/basic-end.zx81?raw';
-
-export {assetCharacters, assetSystemVariables, assetBasicLine1, assetBasicLine2, assetDisplay, assetBasicEnd}
+export { assetCharacters, assetSystemVariables, assetBasicLine1, assetBasicLine2, assetDisplay, assetBasicEnd };

package/lib/compiler/Ast.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Ast.ts
+ * Description: Types for building the Abstract Syntax Tree
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import { Address, bytes } from '../types/Types';
+import { ByteValue, Expression, PosInfo, WordValue } from "../grammar/z80";
+/**
+ * A function returning a number (if it is known) or null (if it is unknown).
+ */
+export type EvalFunc = (pc: Address, mustExist: boolean) => number | null;
+/**
+ * An abstract element generated by the parser.
+ */
+export interface AstBase {
+    /**
+     * The number of bytes that will be generated by this element.
+     */
+    get size(): number;
+    /**
+     * Generate actual bytes.
+     * @param instructionAddress Address of the next byte to generate,
+     */
+    generate(instructionAddress: number): bytes;
+}
+/**
+ * An AST element is either a number (the raw byte value) or derived from AstBase.
+ */
+export type AstElement = number | AstBase;
+/**
+ * Array of AST elements
+ */
+export type AstElements = AstElement[];
+/**
+ * Determine if an AST element is a raw byte or derived from AstBase (i.e. abstract)
+ * @param element The element to test.
+ * @return true if the element is concrete (a raw byte value), false if it is abstract.
+ */
+export declare function isAbstract(element: AstElement): element is AstBase;
+/**
+ * Determine the actual size in byte of an AST element.
+ * @param element The AST element.
+ * @return The number of bytes that will be generated by this element
+ */
+export declare function getByteSize(element: AstElement): number;
+/**
+ * Get the low part of a 16-bit little endian value.
+ * @param value A 16-bit little endian value.
+ */
+export declare function low(value: number): number;
+/**
+ * Get the high part of a 16-bit little endian value.
+ * @param value A 16-bit little endian value.
+ */
+export declare function high(value: number): number;
+/**
+ * An Evaluable interface, i.e. that contains an eval function that returns a number or null.
+ */
+interface Evaluable {
+    eval: EvalFunc;
+}
+/**
+ * An Inner Expression i.e. that extends an Evaluable interface.
+ */
+interface InnerExpression<E extends Evaluable> {
+    e: E;
+}
+/**
+ * A Binary operation interface, i.e. a function with two arguments and that returns a number.
+ */
+type BinaryOperation = (a: number, b: number) => number;
+/**
+ * A Unary operation interface, i.e. a function with one argument and that returns a number.
+ */
+type UnaryOperation = (a: number) => number;
+/**
+ * A Binary operation such as: 2 * 4.
+ * @param left Left side of the binary function.
+ * @param right Right side of the binary function.
+ * @param op Operation to be applied to the left and right side.
+ */
+export declare function binaryOperation<Operation extends BinaryOperation, Inner extends Evaluable, Left extends InnerExpression<Inner>, Right extends Evaluable>(left: Left | null, right: Right, op: Operation): EvalFunc;
+/**
+ * A map of strings versus binary operations. For example: '*' => operatorMul
+ */
+type BinaryOperationsMap = {
+    [key: string]: BinaryOperation;
+};
+/**
+ * A map of strings versus unary operations. For example: '-' => operatorNeg
+ */
+type UnaryOperationsMap = {
+    [key: string]: UnaryOperation;
+};
+/**
+ * An Inner Operator i.e. that extends an Inner Expression, itself extending an Evaluable.
+ */
+interface InnerOp<E extends Evaluable> extends InnerExpression<E> {
+    op: string;
+}
+/**
+ * A Binary operation such as: 2 * 4.
+ * @param left Left side of the binary function.
+ * @param right Right side of the binary function.
+ * @param map Map the operations to be applied to the left and right side.
+ */
+export declare function binaryOperations<Inner extends Evaluable, Left extends InnerOp<Inner>, Right extends Evaluable>(left: Left | null, right: Right, map: BinaryOperationsMap): EvalFunc;
+/**
+ * A Unary operation.
+ * @param e The argument.
+ * @param op The operation to be applied to the argument.
+ */
+export declare function unaryOperation<Operation extends UnaryOperation, E extends Evaluable>(e: E, op: Operation): EvalFunc;
+/**
+ * A Unary operation.
+ * @param e The argument.
+ * @param op The operation to be applied to the argument as a string.
+ * @param map Map the operations to be applied to the argument.
+ */
+export declare function unaryOperations<E extends Evaluable>(e: E, op: string, map: UnaryOperationsMap): EvalFunc;
+export declare const operatorOr: (a: number, b: number) => number;
+export declare const operatorXor: (a: number, b: number) => number;
+export declare const operatorAnd: (a: number, b: number) => number;
+export declare const operatorLeftShift: (a: number, b: number) => number;
+export declare const operatorRightShift: (a: number, b: number) => number;
+export declare const operatorAdd: (a: number, b: number) => number;
+export declare const operatorSub: (a: number, b: number) => number;
+export declare const operatorMul: (a: number, b: number) => number;
+export declare const operatorDiv: (a: number, b: number) => number;
+export declare const operatorModulo: (a: number, b: number) => number;
+export declare const operatorPlus: (a: number) => number;
+export declare const operatorNeg: (a: number) => number;
+export declare const operatorInvert: (a: number) => number;
+export declare const operatorIdentity: (a: number) => number;
+/**
+ * Returns an AST element that represents the low part of a little-endian 16-bit value.
+ * @param pos The position of the element in the source.
+ * @param e The 16-bit value.
+ */
+export declare function value16LE(pos: PosInfo, e: Expression): AstElement;
+/**
+ * Returns an AST element that represents an 8-bit unsigned value.
+ * @param pos The position of the element in the source.
+ * @param e The 8-bit unsigned value.
+ */
+export declare function value8(pos: PosInfo, e: Expression): AstElement;
+/**
+ * Returns an AST element that represents an 8-bit signed offset for IX or IY.
+ * @offset The offset for IX or IY with:
+ * pos The position of the element in the source.
+ * s The sign of the value.
+ */
+export declare function index(offset: {
+    pos: PosInfo;
+    s: string;
+    d: Expression;
+} | null): AstElement;
+/**
+ * Returns an AST element that represents an offset for a JR (jump relative) opcode.
+ * @param pos The position of the element in the source.
+ * @param e The offset value.
+ */
+export declare function jrOffset(pos: PosInfo, e: Expression): AstElement;
+/**
+ * Returns an AST element that represents an relative offset for a JR (jump relative) opcode.
+ * @param pos The position of the element in the source.
+ * @param label The label that will give the offset value
+ */
+export declare function jrRelativeOffset(pos: PosInfo, label: string): AstElement;
+/**
+ * An Inner Byte, i.e. it contains an inner field that is a Byte value.
+ */
+export interface InnerByte {
+    inner: ByteValue;
+}
+/**
+ * An Inner Word, i.e. it contains an inner field that is a Word value.
+ */
+export interface InnerWord {
+    inner: WordValue;
+}
+/**
+ * The bytes of a Byte directive.
+ * @param _ The position of the bytes in the source code.
+ * @param data0 The first byte.
+ * @param data The other bytes.
+ */
+export declare function dataBytes(_: PosInfo, data0: ByteValue, data: InnerByte[]): AstElements;
+/**
+ * The words of a Word directive.
+ * @param _ The position of the words in the source code.
+ * @param data0 The first word.
+ * @param data The other words.
+ */
+export declare function dataWords(_: PosInfo, data0: WordValue, data: InnerWord[]): AstElements;
+/**
+ * The parameters of a block of data.
+ * @param pos0 The position of the length in the source code.
+ * @param length The length (in bytes) of the block
+ * @param pos1 The position of the value in the source code.
+ * @param value The value used to initialize the block.
+ */
+export declare function dataBlock(pos0: PosInfo, length: Expression, pos1: PosInfo | undefined, value: Expression | undefined): AstElement;
+export declare function labelValue(pos: PosInfo, name: string): (pc: Address, mustExist: boolean) => number | null;
+export declare function value(nn: number): (pc: Address, mustExist: boolean) => number;
+export {};

package/lib/compiler/Compiler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Compiler.ts
+ * Description: Compiler (assembler)
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import { PosInfo } from "../grammar/z80";
+import { CompilationInfo, LinesInfo } from "../types/Types";
+/**
+ * Type of the internal data.
+ */
+interface ParseData {
+    outputName: string;
+    sldName: string;
+    deviceName: string;
+    basePath: string;
+    fileName: string;
+    getFileCode: (filename: string) => string;
+}
+/**
+ * Internal data (i.e. globals).
+ * Unfortunately, tsPEG does not allow to declare a context for the parsing.
+ * So instead, we use this ugly global.
+ */
+declare const parseData: ParseData;
+/**
+ * Set the outputs names (output directive).
+ * @param filename Filename for the binary.
+ * @param sld Filename for the SLD.
+ */
+declare function setOutputName(filename: string, sld?: string): void;
+/**
+ * Set the name of the target (device directive)
+ * @param name The name of the device
+ */
+declare function setDevice(name: string): void;
+/**
+ * Include an assembly file (include directive).
+ * @param pos Position of the include directive.
+ * @param filename The filename of the file to be included.
+ */
+declare function includeFile(pos: PosInfo, filename: string): LinesInfo;
+/**
+ * Compile an assembly source code.
+ * @param filepath The file path of the source code.
+ * @param code The assembly source code.
+ * @param getFileCode A function to get the content of included files.
+ */
+declare function compile(filepath: string, code: string, getFileCode: (filename: string) => string): CompilationInfo;
+export { parseData, compile, includeFile, setOutputName, setDevice };

package/lib/compiler/Formatter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Formatter.ts
+ * Description: Format bytes to display them easily
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+/**
+ * Represents a chunk of data to display binary.
+ */
+interface Chunk {
+    address: string;
+    bytes: string;
+}
+/**
+ * Format bytes to display them.
+ * @param bytes An array of bytes.
+ * @param perLine Number of bytes per line.
+ */
+declare function formatBytes(bytes: number[], perLine: number): Chunk[];
+export { formatBytes, Chunk };

package/lib/compiler/Generator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Generator.ts
+ * Description: Generate bytes and SLD
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import { bytes, LinesInfo } from '../types/Types';
+/**
+ * Information about a compiled program.
+ */
+interface ProgramInfo {
+    bytes: bytes;
+    outputName: string;
+    outputSldName: string;
+    address: number;
+}
+/**
+ * Compute, whenever possible, the value associated with labels.
+ * @param address The starting address.
+ * @param infos The lines (i.e. the AST)
+ * @return the address that corresponds to the code after the lines (i.e. the new starting address).
+ */
+declare function computeLabels(address: number, infos: LinesInfo[]): number;
+interface GenerationData {
+    bytes: bytes;
+    sld: string;
+    address: number;
+}
+/**
+ * Generate machine code bytes and SLD for an array of lines (i.e. an AST)
+ * @param mainfile Main file name
+ * @param address The current address.
+ * @param infos The lines (i.e. the AST) with the associated filename
+ * @return An array of bytes (numbers), debug data and the next address
+ */
+declare function generate(mainfile: string, address: number, infos: LinesInfo[]): GenerationData;
+export { computeLabels, generate, ProgramInfo };

package/lib/compiler/Labels.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Labels.ts
+ * Description: Labels associated to locations in memory
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import { Expression, PosInfo } from "../grammar/z80";
+import { Address, Position } from '../types/Types';
+/**
+ * Reset the labels.
+ */
+declare function resetLabels(): void;
+declare function resetLabelsRecursion(): void;
+/**
+ * Add a label.
+ * @param pos The position of the label in the source code.
+ * @param name The name of the label.
+ * @param value The value of the label (if known) or null (if unknown).
+ */
+declare function addLabel(pos: Position, name: string, value: number | null): void;
+/**
+ * Add a label and its associated expression.
+ * @param _ The position of the label in the source code.
+ * @param name The name of the label.
+ * @param expression The expression that gives that value of the label.
+ */
+declare function addLabelExpression(_: PosInfo, name: string, expression: Expression): void;
+/**
+ * Get the value associated with a label.
+ * @param pc Current program counter (PC).
+ * @param name The name of the label.
+ * @param pos Where this label is used.
+ * @param setUsed If set, mark the label as used.
+ * @param mustExist If set, the value of the label has to be known (not null).
+ * @return The value associated with a label or null if it is unknown.
+ */
+declare function getLabelValue(pc: Address, name: string, pos: Position, setUsed: boolean, mustExist: boolean): number | null;
+/**
+ * Is a label used in the program or only declared?
+ * @param name The name of the label.
+ * @return true if the label is used, false otherwise.
+ */
+declare function isLabelUsed(name: string): boolean | undefined;
+export { resetLabels, resetLabelsRecursion, addLabel, addLabelExpression, getLabelValue, isLabelUsed };

package/lib/grammar/LowLevel.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        LoweLevel.ts
+ * Description: Low level functions for the parser
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import { byte } from "../types/Types";
+/**
+ * Compute the binary representation of the r argument.
+ * @param r The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function r_bits(r: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the dd argument.
+ * @param dd The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function dd_bits(dd: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the qq argument.
+ * @param qq The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function qq_bits(qq: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the ss argument.
+ * @param ss The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function ss_bits(ss: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the pp argument.
+ * @param pp The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function pp_bits(pp: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the rr argument.
+ * @param rr The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function rr_bits(rr: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the cc argument.
+ * @param cc The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function cc_bits(cc: string, offset?: number): byte;
+/**
+ * Compute the binary representation of the jj argument.
+ * @param jj The argument of the opcode.
+ */
+export declare function jj_bits(jj?: string): byte;
+/**
+ * Compute the binary representation of the p argument.
+ * @param p The argument of the opcode.
+ * @param offset The number of bits to shift to the left.
+ */
+export declare function p_bits(p: number, offset?: number): byte;
+/**
+ * Compute the binary representation of the mode argument.
+ * @param mode The argument of the opcode.
+ */
+export declare function imode(mode: string): byte;

package/lib/grammar/Parse.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Z80 Assembler in Typescript
+ *
+ * File:        Parse.ts
+ * Description: Fonctions uses by the parser to convert strings
+ * Author:			Sebastien Andrivet
+ * License:			GPLv3
+ * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
+ */
+import { PosInfo } from "./z80";
+/**
+ * Parse a number.
+ * @param pos Position of the number in the source code.
+ * @param str The characters of the number.
+ * @param base The base of the number.
+ * @param nbBytes The number of bytes to represent this number (1 or 2)
+ */
+export declare function parseNumber(pos: PosInfo, str: string, base: number, nbBytes: number): number;
+/**
+ * Parse a simple escape, i.e. a backslash followed by a character.
+ * @param pos Position of the character in the source code.
+ * @param c The character after the backslash.
+ */
+export declare function parseSimpleEscape(pos: PosInfo, c: string): number[];
+/**
+ * Parse an octal value.
+ * @param pos Position of the value in the source code.
+ * @param value The characters representing the value.
+ */
+export declare function parseOctalEscape(pos: PosInfo, value: string): number[];
+/**
+ * Parse a hexadecimal value.
+ * @param pos Position of the value in the source code.
+ * @param value The characters representing the value.
+ */
+export declare function parseHexadecimalEscape(pos: PosInfo, value: string): number[];
+/**
+ * Parse a ZX81 character written in ASCII.
+ * @param pos Position of the character in the source code.
+ * @param c The ASCII character.
+ */
+export declare function parseZX81Char(pos: PosInfo, c: string): [number];
+/**
+ * Parse a ZX81 string written in ASCII.
+ * @param pos Position of the string in the source code.
+ * @param str The ASCII string.
+ */
+export declare function parseZX81String(pos: PosInfo, str: string): number[];