@andrivet/z80-assembler 1.3.1 → 1.4.0

package/libs/z80-assembler/src/lib/compiler/Ast.ts

@@ -0,0 +1,545 @@
+/**
+ * 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, byte, bytes, Position} from '../types/Types';
+import {CompilationError} from "../types/Error";
+import {ByteValue, Expression, PosInfo, WordValue} from "../grammar/z80";
+import {getLabelValue} from "./Labels";
+import {parseData} from "../compiler/Compiler";
+
+/**
+ * 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 that represents a block of bytes.
+ */
+class ByteBlock implements AstBase {
+  private readonly position0: Position;
+  private readonly position1?: Position;
+
+  /**
+   * Constructor.
+   * @param pos0 Position of the length of the block.
+   * @param length Length of the block.
+   * @param pos1 Position of the value.
+   * @param value Value to use to fill the block.
+   */
+  constructor(
+    pos0: PosInfo,
+    private length: Expression,
+    pos1: PosInfo | undefined,
+    private value: Expression | undefined) {
+    this.position0 = {filename: parseData.fileName, pos: pos0};
+    if(pos1) this.position1 = {filename: parseData.fileName, pos: pos1};
+  }
+
+  /**
+   * The number of bytes that will be generated by this element.
+   */
+  get size(): number {
+    // Evaluate the size
+    // Evalue la taille.
+    const size = this.length.eval(0, true);
+    // Is it valid?
+    // Est-elle valide ?
+    if(size == null) throw new CompilationError(this.position0, "Unknown size for the data block");
+    if(size < 0) throw new CompilationError(this.position0, `Invalid size size for the data block: ${size}`);
+    return size;
+  }
+
+  /**
+   * Evaluate the expression for the value used to fill the block.
+   * @private
+   */
+  private getValue(pc: Address) {
+    // Be sure we have valid data.
+    // On s'assure d'avoir des données valides.
+    if(this.value == null || this.position1 == null) return 0;
+    // Evaluate the expression for the value.
+    // On évalue l'expression pour la valeur.
+    let v =  this.value.eval(pc, true);
+    // If the value is null (unknown), we have a compilation error.
+    // Si la valeur est nulle (inconnue), nous avons une erreur de compilation.
+    if(v == null) throw new CompilationError(this.position1, `Not able to determine a value`);
+    // If the value does not fit into 8-bit, we have a compilation error.
+    // Si la valeur ne peux pas être représentée sur 8-bit, nous avons une erreur de compilation.
+    if(v < -256 || v > 255) throw new CompilationError(this.position1, `Invalid 8-bits value: ${v}`);
+    // If the value is negative, take its 2-complement.
+    // Si la valeur est négative, on prend son complément à 2.
+    if(v < 0) v = 256 + v;
+    return v;
+  }
+
+  /**
+   * Generate actual bytes.
+   */
+  generate(pc: Address): bytes {
+    // Prepare an array of the right size and fill it.
+    // On prépare un tableau de la bonne taille et on le remplit.
+    const array = new Array<byte>(this.size);
+    array.fill(this.getValue(pc));
+    return array;
+  }
+}
+
+/**
+ * An AST element that represents a 16-byte value.
+ */
+class Value16 implements AstBase {
+  private readonly position: Position;
+
+  /**
+   * Constructor.
+   * @param pos Position of the expression for the value.
+   * @param expression Expression for the value.
+   */
+  constructor(pos: PosInfo, private expression: Expression) {
+    this.position = {filename: parseData.fileName, pos: pos}
+  }
+
+  /**
+   * The number of bytes that will be generated by this element.
+   */
+  get size(): number { return 2; }
+
+  /**
+   * Generate actual bytes.
+   */
+  generate(pc: Address): bytes {
+    // Evaluate the expression for the value.
+    let v = this.expression.eval(pc, true);
+    // If the value is null (unknown), we have a compilation error.
+    if(v == null) throw new CompilationError(this.position, `Not able to determine the 16-bits value`);
+    // If the value does not fit into 16-bit, we have a compilation error.
+    if(v < -65536 || v > 65535) throw new CompilationError(this.position, `Invalid 16-bits value: ${v}`);
+    // If the value is negative, take its 2-complement.
+    if(v < 0) v = 65536 + v;
+    // Return two bytes. The first one is the low part, the second is the high part (little endian).
+    return [v & 0x00FF, (v & 0xFF00) >> 8];
+  }
+}
+
+/**
+ * An AST element that represents a 8-byte value.
+ */
+class Value8 implements AstBase {
+  private readonly position: Position;
+
+  constructor(pos: PosInfo, private expression: Expression) {
+    this.position = {filename: parseData.fileName, pos: pos}
+  }
+
+  /**
+   * The number of bytes that will be generated by this element.
+   */
+  get size(): number { return 1; }
+
+  /**
+   * Generate actual bytes.
+   */
+  generate(pc: Address): bytes {
+    // Evaluate the expression for the value.
+    let v = this.expression.eval(pc, true);
+    // If the value is null (unknown), we have a compilation error.
+    if(v == null) throw new CompilationError(this.position, `Not able to determine the 8-bits value`);
+    // If the value does not fit into 8-bit, we have a compilation error.
+    if(v < -256 || v > 255) throw new CompilationError(this.position, `Invalid 8-bits value: ${v}`);
+    // If the value is negative, take its 2-complement.
+    if(v < 0) v = 256 + v;
+    return [v];
+  }
+}
+
+/**
+ * An AST element that represents a negative 8-byte value.
+ */
+class ValueNeg8 implements AstBase {
+  private readonly position: Position;
+
+  constructor(pos: PosInfo, private expression: Expression) {
+    this.position = {filename: parseData.fileName, pos: pos}
+  }
+
+  /**
+   * The number of bytes that will be generated by this element.
+   */
+  get size(): number { return 1; }
+
+  /**
+   * Generate actual bytes.
+   */
+  generate(pc: Address): bytes {
+    // Evaluate the expression for the value.
+    let v = this.expression.eval(pc, true);
+    // If the value is null (unknown), we have a compilation error.
+    if(v == null) throw new CompilationError(this.position, `Not able to determine the 8-bits value`);
+    // Take the opposite.
+    v = -v;
+    // If the value does not fit into 8-bit, we have a compilation error.
+    if(v < -256 || v > 255) throw new CompilationError(this.position, `Invalid 8-bits value: ${v}`);
+    // If the value is negative, take its 2-complement.
+    if(v < 0) v = 256 + v;
+    return [v];
+  }
+}
+
+/**
+ * An AST element that represents an absolute offset for a relative jump.
+ */
+class Jr implements AstBase {
+  private readonly position: Position;
+
+  constructor(pos: PosInfo, private expression: Expression) {
+    this.position = {filename: parseData.fileName, pos: pos}
+  }
+  /**
+   * The number of bytes that will be generated by this element.
+   */
+  get size(): number { return 1; }
+
+  /**
+   * Generate actual bytes.
+   */
+  generate(pc: Address): bytes {
+    // Evaluate the expression for the offset.
+    let offset = this.expression.eval(pc, true);
+    // If the offset is null (unknown), we have a compilation error.
+    if(offset == null) throw new CompilationError(this.position, `Not able to determine the offset value`);
+    // The offset has to be between -126 and 129.
+    if(offset < -126 || offset > 129) throw new CompilationError(this.position, `Invalid offset for JR instruction: ${offset}`);
+    // The actual representation is the offset minus 2.
+    offset -= 2;
+    // If the value is offset, take its 2-complement.
+    if(offset < 0) offset = 256 + offset;
+    return [offset];
+  }
+}
+
+/**
+ * An AST element that represents a relative offsez for a relative jump.
+ */
+class JrRelative implements AstBase {
+  private readonly position: Position;
+
+  constructor(pos: PosInfo, private label: string) {
+    this.position = {filename: parseData.fileName, pos: pos};
+  }
+
+  /**
+   * The number of bytes that will be generated by this element.
+   */
+  get size(): number { return 1; }
+
+  /**
+   * Generate actual bytes.
+   * @param pc Address of the next byte to generate,
+   */
+  generate(pc: Address): bytes {
+    if(pc == null) throw new CompilationError(this.position, `Not able to determine PC value`);
+    // Get the value of the label.
+    const targetAddress = getLabelValue(pc, this.label, this.position, true, true);
+    // If the value is null (unknown), we have a compilation error.
+    if(targetAddress == null) throw new CompilationError(this.position, `Not able to determine the value of label '${this.label}'`);
+    // The offset is between the address hold by the label and the address of the current instruction.
+    let offset = targetAddress - pc;
+    // The offset has to be between -126 and 129.
+    if(offset < -126 || offset > 129) throw new CompilationError(this.position, `Label ${this.label} is to far from JR instruction: ${offset} bytes`);
+    // The actual representation is the offset minus 2.
+    offset -= 2;
+    // If the value is offset, take its 2-complement.
+    if(offset < 0) offset = 256 + offset;
+    return [offset];
+  }
+}
+
+/**
+ * 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 function isAbstract(element: AstElement): element is AstBase {
+  return (element as AstBase).generate !== undefined;
+}
+
+/**
+ * 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 function getByteSize(element: AstElement): number {
+  return isAbstract(element) ? element.size : 1;
+}
+
+/**
+ * Get the low part of a 16-bit little endian value.
+ * @param value A 16-bit little endian value.
+ */
+export function low(value: number) {
+  return value & 0x00FF;
+}
+
+/**
+ * Get the high part of a 16-bit little endian value.
+ * @param value A 16-bit little endian value.
+ */
+export function high(value: number) {
+  return (value & 0xFF00) >> 8;
+}
+
+/**
+ * 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 function binaryOperation<
+  Operation extends BinaryOperation,
+  Inner extends Evaluable,
+  Left extends InnerExpression<Inner>,
+  Right extends Evaluable>(left: Left | null, right: Right, op: Operation): EvalFunc {
+  return (pc: Address, mustExist: boolean) => {
+    // Evaluate the right side
+    const rightValue = right.eval(pc, mustExist);
+    // If the left side is empty, we return the right side
+    if(!left) return rightValue;
+    // Evaluate the left side
+    const leftValue = left.e.eval(pc, mustExist);
+    // If one of the values is null, the result is null. Otherwise, apply the operation.
+    return leftValue == null || rightValue == null ? null : op(leftValue, rightValue);
+  }
+}
+
+/**
+ * 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 function binaryOperations<
+  Inner extends Evaluable,
+  Left extends InnerOp<Inner>,
+  Right extends Evaluable>(left: Left | null, right: Right, map: BinaryOperationsMap): EvalFunc {
+  return (pc: Address, mustExist: boolean) => {
+    // Evaluate the right side
+    const rightValue = right.eval(pc, mustExist);
+    // If the left side is empty, we return the right side value.
+    if(!left) return rightValue;
+    // Evaluate the left side
+    const leftValue = left.e.eval(pc, mustExist);
+    // If one of the values is null, the result is null. Otherwise, apply the operation.
+    return leftValue == null || rightValue == null ? null : map[left.op](leftValue, rightValue);
+  }
+}
+
+/**
+ * A Unary operation.
+ * @param e The argument.
+ * @param op The operation to be applied to the argument.
+ */
+export function unaryOperation<
+  Operation extends UnaryOperation,
+  E extends Evaluable>(e: E, op: Operation): EvalFunc {
+  // Evaluate the argument. If the value is null, the result is null. Otherwise, apply the operation.
+  return (pc: Address, mustExist: boolean) => {
+    const value = e.eval(pc, mustExist);
+    return (value == null) ? null : op(value);
+  }
+}
+
+/**
+ * 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 function unaryOperations<
+  E extends Evaluable>(e: E, op: string, map: UnaryOperationsMap): EvalFunc {
+  return (pc: Address, mustExist: boolean) => {
+    const value = e.eval(pc, mustExist);
+    return (value == null) ? null : map[op](value);
+  }
+}
+
+// Note: As far as I know, it is not possible to manipulate in Javascript and Typescript builtin operators.
+// So we define a set of functions for this purpose.
+
+export const operatorOr = (a: number, b: number) => a | b;
+export const operatorXor = (a: number, b: number) => a ^ b;
+export const operatorAnd = (a: number, b: number) => a & b;
+export const operatorLeftShift = (a: number, b: number) => a << b;
+export const operatorRightShift = (a: number, b: number) => a >> b;
+export const operatorAdd = (a: number, b: number) => a + b;
+export const operatorSub = (a: number, b: number) => a - b;
+export const operatorMul = (a: number, b: number) => a * b;
+export const operatorDiv = (a: number, b: number) => Math.trunc(a / b);
+export const operatorModulo = (a: number, b: number) => a % b;
+export const operatorPlus = (a: number) => +a;
+export const operatorNeg = (a: number) => -a;
+export const operatorInvert = (a: number) => ~a;
+export const operatorIdentity = (a: number) => a;
+
+/**
+ * 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 function value16LE(pos: PosInfo, e: Expression): AstElement {
+  return new Value16(pos, e);
+}
+
+/**
+ * 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 function value8(pos: PosInfo, e: Expression): AstElement {
+  return new Value8(pos, e);
+}
+
+/**
+ * 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 function index(offset: {pos: PosInfo, s: string, d: Expression} | null): AstElement {
+  return !offset ? 0 : offset.s === '-' ? new ValueNeg8(offset.pos, offset.d) : new Value8(offset.pos, offset.d);
+}
+
+/**
+ * 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 function jrOffset(pos: PosInfo, e: Expression): AstElement {
+  return new Jr(pos, e);
+}
+
+/**
+ * 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 function jrRelativeOffset(pos: PosInfo, label: string): AstElement {
+  return new JrRelative(pos, label);
+}
+
+/**
+ * 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 function dataBytes(_: PosInfo, data0: ByteValue, data: InnerByte[]): AstElements {
+  return data.reduce((r, c) => r.concat(c.inner.elements), data0.elements);
+}
+
+/**
+ * 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 function dataWords(_: PosInfo, data0: WordValue, data: InnerWord[]): AstElements {
+  return data.reduce((r, c) => r.concat(c.inner.elements), data0.elements);
+}
+
+/**
+ * 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 function dataBlock(pos0: PosInfo, length: Expression, pos1: PosInfo | undefined, value: Expression | undefined): AstElement {
+  return new ByteBlock(pos0, length, pos1, value);
+}
+
+export function labelValue(pos: PosInfo, name: string) {
+  return (pc: Address, mustExist: boolean) =>
+    getLabelValue(pc, name, {filename: parseData.fileName, pos: pos}, true, mustExist);
+}
+
+export function value(nn: number) {
+  return (pc: Address, mustExist: boolean) => nn;
+}