@andrivet/z80-assembler 1.1.0 → 1.3.0

package/lib/compiler/Ast.d.ts

@@ -16,19 +16,29 @@
  * License:			GPLv3
  * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
  */
-import { bytes } from '../types/Types';
+import { Address, bytes } from '../types/Types';
 import { ByteValue, Expression, PosInfo, WordValue } from "../grammar/z80";
 /**
- * A function taking no argument and returning a number (if it is known) or null (if it is unknown).
+ * A function returning a number (if it is known) or null (if it is unknown).
  * Une function qui ne prend pas d'argument et qui retourne un nombre (s'il est connu) ou null (s'il est inconnu).
  */
-export type EvalFunc = () => number | null;
+export type EvalFunc = (pc: Address, mustExist: boolean) => number | null;
 /**
  * An abstract element generated by the parser.
  * Un élément abstrait générà par l'analyseur.
  */
 export interface AstBase {
+    /**
+     * The number of bytes that will be generated by this element.
+     * Le nombre d'octets générés par cet élément.
+     */
     get size(): number;
+    /**
+     * Generate actual bytes.
+     * Génération des octets
+     * @param instructionAddress Address of the next byte to generate,
+     *                           Adresse du prochain octet à générer.
+     */
     generate(instructionAddress: number): bytes;
 }
 /**
@@ -91,7 +101,7 @@ type UnaryOperation = (a: number) => number;
  * @param op Operation to be applied to the left and right side.
  *           L'opération à appliquer aux opérandes
  */
-export declare function binaryOperation<Operation extends BinaryOperation, Inner extends Evaluable, Left extends InnerExpression<Inner>, Right extends Evaluable>(left: Left | undefined, right: Right, op: Operation): EvalFunc;
+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
  */
@@ -120,7 +130,7 @@ interface InnerOp<E extends Evaluable> extends InnerExpression<E> {
  * @param map Map the operations to be applied to the left and right side.
  *            Une correspondance pour les opérations à appliquer aux opérandes.
  */
-export declare function binaryOperations<Inner extends Evaluable, Left extends InnerOp<Inner>, Right extends Evaluable>(left: Left, right: Right, map: BinaryOperationsMap): EvalFunc;
+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.
@@ -167,15 +177,20 @@ export declare function value16LE(pos: PosInfo, e: Expression): AstElement;
  */
 export declare function value8(pos: PosInfo, e: Expression): AstElement;
 /**
- * Returns an AST element that represents an 8-bit signed value.
- * Retourne un élément de l'AST qui représente une valeur 8 bits signée.
- * @param pos The position of the element in the source.
- *            La position de l'élément dans le code source.
- * @param s The sign of the value.
- * @param e The 8-bit signed value
- *          La valeur 8-bit signée.
+ * Returns an AST element that represents an 8-bit signed offset for IX or IY.
+ * Retourne un élément de l'AST qui représente un décalage 8 bits signé pour IX ou IY.
+ * @offset The offset for IX or IY with:
+ * pos The position of the element in the source.
+ *     La position de l'élément dans le code source.
+ * s The sign of the value.
+ * e The 8-bit signed décalage
+ *   Le décalage 8-bit signée.
  */
-export declare function svalue8(pos: PosInfo, s: string, e: Expression): AstElement;
+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.
  * Retourne un élément de l'AST qui représente un décalage pour un saut relatif JR.
@@ -243,4 +258,6 @@ export declare function dataWords(_: PosInfo, data0: WordValue, data: InnerWord[
  *              La valeur utilisée pour initialiser le bloc.
  */
 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

@@ -45,7 +45,7 @@ declare const parseData: ParseDate;
  * @param filename Filename for the binary.
  *                 Nom de fichier pour le binaire.
  * @param sld Filename for the SLD.
- *            Nom de fihcier pour le SLD.
+ *            Nom de fichier pour le SLD.
  */
 declare function setOutputName(filename: string, sld?: string): void;
 /**

package/lib/compiler/Formatter.d.ts

@@ -26,7 +26,7 @@ interface Chunk {
 }
 /**
  * Format bytes to display them.
- * Formatte des octets pour les afficher.
+ * Formate des octets pour les afficher.
  * @param bytes An array of bytes.
  *              Un tableau d'octets.
  * @param perLine Number of bytes per line.

package/lib/compiler/Labels.d.ts

@@ -17,39 +17,55 @@
  * Copyrights: 	Copyright (C) 2023 Sebastien Andrivet
  */
 import { Expression, PosInfo } from "../grammar/z80";
+import { Address, Position } from '../types/Types';
 /**
  * Reset the labels.
+ * Supprime toutes les étiquettes.
  */
 declare function resetLabels(): void;
+declare function resetLabelsRecursion(): void;
 /**
  * Add a label.
+ * Ajoute une étiquette.
  * @param pos The position of the label in the source code.
+ *            La position de l'étiquette dans le code source.
  * @param name The name of the label.
- * @param value The value of the label (if known) or null (if unknown)
+ *             Le nom de l'étiquette.
+ * @param value The value of the label (if known) or null (if unknown).
+ *              La valeur de l'étiquette (si connue) ou null (si inconnue).
  */
-declare function addLabel(pos: PosInfo, name: string, value: number | null): void;
+declare function addLabel(pos: Position, name: string, value: number | null): void;
 /**
  * Add a label and its associated expression.
+ * Ajoute une étiquette et son expression associée.
  * @param _ The position of the label in the source code.
+ *          La position de l'étiquette dans le code source.
  * @param name The name of the label.
+ *             Le nom de l'étiquette.
  * @param expression The expression that gives that value of the label.
+ *                   L'expression qui donne la valeur de l'étiquette.
  */
 declare function addLabelExpression(_: PosInfo, name: string, expression: Expression): void;
 /**
  * Get the value associated with a label.
+ * Obtient la valeur associée avec une étiquette.
+ * @param pc: Current program counter (PC).
  * @param name The name of the label.
- * @param setUsed Set the used flag or not.
+ *             Le nom de l'étiquette.
+ * @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.
+ *         La valeur associée avec l'étiquette ou null si elle est inconnue.
  */
-declare function getLabelValue(name: string, setUsed?: boolean): number | null;
+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?
+ * Est-ce qu'une étiquette a été utilisée ou seulement déclarée ?
  * @param name The name of the label.
- * @return true if the label is used, false if it is unused or undeclared.
+ *             Le nom de l'étiquette.
+ * @return true if the label is used, false otherwise.
+ *         true si l'étiquette a été utilisée, false sinon.
  */
 declare function isLabelUsed(name: string): boolean | undefined;
-/**
- * Get the list of labels with an unknown value.
- */
-declare function getUnknownLabels(): string[];
-export { resetLabels, addLabel, addLabelExpression, getLabelValue, isLabelUsed, getUnknownLabels };
+export { resetLabels, resetLabelsRecursion, addLabel, addLabelExpression, getLabelValue, isLabelUsed };

package/lib/grammar/LowLevel.d.ts

@@ -19,59 +19,87 @@
 import { byte } from "../types/Types";
 /**
  * Compute the binary representation of the r argument.
- * @param r The argument of the opcode
+ * Calcule la représentation binaire de l'argument r.
+ * @param r The argument of the opcode.
+ *          L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument dd.
+ * @param dd The argument of the opcode.
+ *           L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument qq.
+ * @param qq The argument of the opcode.
+ *           L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument ss.
+ * @param ss The argument of the opcode.
+ *           L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument pp.
+ * @param pp The argument of the opcode.
+ *           L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument rr.
+ * @param rr The argument of the opcode.
+ *           L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument cc.
+ * @param cc The argument of the opcode.
+ *           L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument jj.
+ * @param jj The argument of the opcode.
+ *           L'argument du code assembleur.
  */
 export declare function jj_bits(jj?: string): byte;
 /**
  * Compute the binary representation of the p argument.
- * @param p The argument of the opcode
+ * Calcule la représentation binaire de l'argument p.
+ * @param p The argument of the opcode.
+ *          L'argument du code assembleur.
  * @param offset The number of bits to shift to the left.
+ *               Le nombre de bits à décaler vers la gauche.
  */
 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
+ * Calcule la représentation binaire de l'argument mode.
+ * @param mode The argument of the opcode.
+ *             L'argument du code assembleur.
  */
 export declare function imode(mode: string): byte;

package/lib/grammar/Parse.d.ts

@@ -19,39 +19,59 @@
 import { PosInfo } from "./z80";
 /**
  * Parse a number.
+ * Analyse un nombre.
  * @param pos Position of the number in the source code.
+ *            Position du nombre dans le code source.
  * @param str The characters of the number.
+ *            Les caractères du nombre.
  * @param base The base of the number.
+ *             La base du nombre.
  * @param nbBytes The number of bytes to represent this number (1 or 2)
+ *                Le nombre d'octets pour représenter ce nombre (1 ou 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.
+ * Analyse un échappement simple, c.-à-d. une barre oblique inversée suivie d'un caractère.
  * @param pos Position of the character in the source code.
+ *            Position du caractère dans le code source.
  * @param c The character after the backslash.
+ *          Le caractère après la barre oblique inversée.
  */
 export declare function parseSimpleEscape(pos: PosInfo, c: string): number[];
 /**
  * Parse an octal value.
+ * Analyse une valeur octale.
  * @param pos Position of the value in the source code.
+ *            Position de la valeur dans le code source.
  * @param value The characters representing the value.
+ *              Les caractères représentant la valeur.
  */
 export declare function parseOctalEscape(pos: PosInfo, value: string): number[];
 /**
  * Parse a hexadecimal value.
+ * Analyse une valeur hexadécimale.
  * @param pos Position of the value in the source code.
+ *            Position de la valeur dans le code source.
  * @param value The characters representing the value.
+ *              Les caractères représentant la valeur.
  */
 export declare function parseHexadecimalEscape(pos: PosInfo, value: string): number[];
 /**
  * Parse a ZX81 character written in ASCII.
+ * Analyse un caractère ZX81 écrit en ASCII.
  * @param pos Position of the character in the source code.
+ *            Position du caractère dans le code source.
  * @param c The ASCII character.
+ *          Le caractère ASCII.
  */
-export declare function parseZX81Char(pos: PosInfo, c: string): number;
+export declare function parseZX81Char(pos: PosInfo, c: string): [number];
 /**
  * Parse a ZX81 string written in ASCII.
+ * Analyse un chaine ZX81 écrit en ASCII.
  * @param pos Position of the string in the source code.
+ *            Position de la chaine dans le code source.
  * @param str The ASCII string.
+ *            La chaine ASCII.
  */
 export declare function parseZX81String(pos: PosInfo, str: string): number[];