Fix: label strict syntax declaration control. Added documentation.

Author: jugubell

.gitignore

@@ -1,7 +1,11 @@
 ### IntelliJ IDEA ###
 out/
+release/
 !**/src/main/**/out/
 !**/src/test/**/out/
+.idea/
+src/main/resources/META-INF/
+bproc-cli.iml
 
 ### Eclipse ###
 .apt_generated
@@ -25,9 +29,5 @@ bin/
 ### VS Code ###
 .vscode/
 
-### IDEA ###
-.idea/
-src/main/resources/META-INF/
-doc/
 ### Mac OS ###
 .DS_Store

README.md

@@ -1,35 +1,54 @@
-# BProC CLI - Basic Processors Compiler Command Line Interface #
-## Description ##
-BProC is a compiler for basic processor designs, it uses assembly code written in `.baspm` 
+![](./src/main/resources/img/bproc_logo_h128.png)
+# BProC CLI - Basic Processors Compiler Command Line Interface
+
+## Table of contents
+* [Table of contents](#table-of-contents)
+* [Description](#description)
+* [Installation](#installation)
+  * [Package install](#package-install)
+  * [JAR run](#jar-run)
+    * [Prerequisites](#prerequisites)
+    * [Run the .jar file](#run-the-jar-file)
+* [Usage](#usage)
+  * [Arguments](#arguments)
+  * [Actions](#actions)
+  * [Options](#options)
+  * [Other arguments](#other-arguments)
+* [Supported instruction set](#supported-instruction-set)
+* [Keywords](#keywords)
+* [TODO](#todo)
+* [Credit](#credit)
+
+## Description
+BProC is a compiler for basic processor designs, it uses assembly code written in `.bpasm` 
 files. BProC-CLI is a simple command line interface for compiling assembler files `.bpasm` 
 for basic processors intended for education use. The vision of the project is to provide 
 simple way to generate RAM programs while designing basic processors.
 The project, as it is, provide a rigid instruction set, but the goal is to provide a 
 configurable instruction set.
 
-## Installation ##
+## Installation
 Choose one of the options available:
-- Pakage install
-- JAR run
-### Package install ###
-1. Download one of the packages suitable for your device in the release 
-section : <a href="https://github.com/jugubell/bproc-cli/releases">Release section</a>
+- [Package install](#package-install)
+- [JAR run](#jar-run)
+### Package install
+1. Download one of the packages suitable for your device in the Release Section
 2. Install the package with dnf/apt or execute installer on Windows.
    - Supported packages: rpm, deb, exe.
-   - Supported architectures: x86_64, aarch64
+   - Supported architectures: x86_64, aarch64/amd64
 
-### JAR run ###
-#### Prerequisites ####
+### JAR run
+#### Prerequisites
 Java 8 or later runtime is needed to run the compiler. To verify, 
 in the terminal run `java -version` or `java --version`. 
-Otherwise, install the JRE for your device from <a href="https://adoptium.net/en-GB/temurin/releases?version=21">here</a>.
+Otherwise, install the JRE for your device from *Eclipse Adoptium* [here](https://adoptium.net/en-GB/temurin/releases?version=21).
 
-#### Run the .jar file ####
+#### Run the .jar file
 The `.jar` file provided can be used to compile `.bpasm` assembly files in a terminal:
-1. Download the `.jar` file from the <a href="https://github.com/jugubell/bproc-cli/releases">Release section</a> 
+1. Download the `.jar` file from the Release section.
 2. Run with: `java -jar bproc-cli.jar <argument(s)>`
 
-## Usage ##
+## Usage
 Here is how to use the BProC-CLI:
 ```
 bproc [-action <inputFile (*.bpasm)>] [optional -output <outputFileName/outputDirectory>] [optional --option <compileType>]
@@ -38,30 +57,30 @@ If you're using the JAR file:
 ```
 java -jar bproc-cli.jar [-action <inputFile (*.bpasm)>] [optional -output <outputFileName/outputDirectory>] [optional --option <compileType>]
 ```
-#### Arguments ####
-- inputFile (*.bpasm): A valid assembler file absolute or relative path with `.bpasm` extension.
-- outputFileName/outputDirectory: A valid output directory, if the name file 
+#### Arguments
+- **inputFile (*.bpasm)**: A valid assembler file absolute or relative path with `.bpasm` extension.
+- **outputFileName/outputDirectory**: A valid output directory, if the name file 
 is not provided, it will be generated.
-- compileType [binary|hexv3]: Type of compilation : default 'binary'
+- **compileType**: Type of compilation : default 'binary'
 
-#### Actions ####
+#### Actions
 - `-s` : verify syntax.
 - `-g` : verify syntax, compile then generate the compiled code.
 - `-o` : verify syntax, compile and save the compiled code to a file
 
-#### Options ####
-- `--bin` : compiles to binary [value by default]
+#### Options
+- `--bin` : compiles to binary (value by default)
 - `--hex` : compiles to hexadecimal
 - `--hexv3` : compiles to hexadecimal version 3 format (compatible for Logisim RAM)
 - `--vhdl` : compiles to a portion of VHDL RAM initialization signal
 - `--vrlg` : compiles to a portion of Verilog RAM initial bloc
 
-#### Other arguments ####
+#### Other arguments
 - `--help`, `-h`, `help`       : shows the help.
 - `--version`, `-v`, `version` : shows the version.
 - `--instruction-set`, `--is`  : shows the supported instruction set.
 
-## Supported Instruction Set ##
+## Supported Instruction Set
 This table recapitulate the current supported instruction set.
 
 | Instruction | Op code | Type     | Needs an operand | Description                                                                  |
@@ -89,19 +108,21 @@ This table recapitulate the current supported instruction set.
 | ***WOR***   | 0xF400  | Hardware | No               | Write output register (GPIO out)                                             |
 | ***SFI***   | 0xF200  | Hardware | No               | Skip the next instr. if flag FGI = 1 (Input reading flag)                    |
 | ***SFO***   | 0xF100  | Hardware | No               | Skip the next instr. if flag FGO = 0 (Output writing flag)                   |
-| ***LDD***   | 0xF080  | Software | No               | Load data in immediate mode                                                  |
+| ***LDD***\* | 0x0000  | Software | Yes              | Load data in immediate mode                                                  |
 | ***JMP***   | 0x0000  | Software | No               | Jump to label in assembly code                                               |
+\* Not yet supported (instead, use .data declaration combined with LDA)
 
-## Keywords ##
+## Keywords
 There are 2 keywords :
   - `.data`     : for data declaration in RAM
   - `start:`    : label to indicate the program start. This label is put after data declaration
   - `0x` prefix or `h` suffix : for addresses and values in hexadecimal
 
-## TODO ##
-1. Integrate an SQLite database to manage a custom instruction set and configurations.
-2. Extend RAM use to custom RAM capacity.
-3. Enable software instruction from one or more hardware instruction.
+## TODO
+1. Add LDD instruction support for immediate addressing
+2. Integrate an SQLite database to manage a custom instruction set and configurations.
+3. Extend RAM use to custom RAM capacity.
+4. Enable software instruction from one or more hardware instruction.
 
-## Credit ##
+## Credit
 Default instruction set mostly inspired from PhD lab work at University of Blida.

bproc-cli.iml

@@ -12,13 +12,13 @@
 ;.data 011h 5D3Ch  ; delay: 1000 ms
 
 start:
-INP
+RIR
 STA 012h
 CLA
 CLE
 LDA 010h
 ADD 012h
-OUT
+WOR
 CLE
 LDA 011h
 

examples/bpAddInOut.bpasm

@@ -0,0 +1,19 @@
+; Basic processor
+; This program adds value of addresses
+; 010h and 011h and stores the result
+; in address 012h
+; ./examples/bpAdd.bpasm
+
+; verify syntax with -s argument, correct and uncomment error by error indicated in comments by <<<>>>
+
+.data 10h FFFFh ; <<<address should be explicitly 16bits>>>
+;.data 011h 014h ; <<<data should be explicitly 12bits>>>
+
+;start: <<<uncomment, start: should be present when .data is declared>>>
+;LDAWRONG 010h   ; <<<correct instruction  LDA. Load address 010h to AC>>>
+ADD 011h   ; Add AC and address 011h
+STA [012h] ; Store ALU result (AC) to address 012h
+
+;2haltProc: ; <<<label syntax not allowed>>>
+HLT        ; Halt the processor
+; end of program

examples/bpAdd_wrong_syntax.bpasm

@@ -11,5 +11,5 @@
 
 start:
 LDA 020h
-OUT
+WOR
 HLT

examples/bpOut.bpasm

@@ -13,7 +13,7 @@
 
 start:
 LDA 020h ; load address 010h to AC
-OUT      ; put AC value in GPIO_OUT
+WOR      ; put AC value in GPIO_OUT
 
 CLE
 LDA 021h
@@ -24,8 +24,8 @@ SZA
 JMP delay1
 
 LDA 020h
-CIL      ; shift left AC value
-OUT      ; put AC value in GPIO_OUT
+SLA      ; shift left AC value
+WOR      ; put AC value in GPIO_OUT
 
 CLE
 LDA 021h

examples/bpShiftOut.bpasm

@@ -24,13 +24,13 @@ LDA 033h ; init toggle state
 STA 034h
 
 LDA 035h ; load OUT ref
-OUT
+WOR
 JMP delay
 
 toggle:
 LDA 035h ; load OUT ref
-CIL
-OUT
+SLA
+WOR
 
 delay:
 LDA 031h ; init counter

examples/bpShiftOut500ms.bpasm

@@ -27,6 +27,8 @@
 import com.jugubell.bproccli.utils.*;
 
 import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 /**
  * The class handling the syntax verification of the code.
@@ -215,12 +217,20 @@ public boolean isSyntaxCorrect() {
      */
     public LineType isLabel(String[] label) {
         String labelStr = String.join(" ", label);
-        int indexOfColumn = label[0].indexOf(":");
-        if(!labelStr.isEmpty() && indexOfColumn != -1) {
-            if(!String.join(" ", label).isEmpty() && !this.instSet.containsKey(label[0].replace(":", "")) && labelStr.substring(indexOfColumn+1).trim().isEmpty()) {
+//        int indexOfColumn = label[0].indexOf(":");
+
+        if(!labelStr.isEmpty()) {
+//            if(!String.join(" ", label).isEmpty() && !this.instSet.containsKey(label[0].replace(":", "")) && labelStr.substring(indexOfColumn+1).trim().isEmpty()) {
+//                return LineType.LABEL;
+//            } else {
+//                return LineType.SYNTAX_ERROR;
+//            }
+            Pattern labelPattern = Pattern.compile("^[A-Za-z_][A-Za-z0-9_]*:$");
+            Matcher labelMatcher = labelPattern.matcher(labelStr);
+            if(labelMatcher.find()) {
                 return LineType.LABEL;
             } else {
-                return LineType.SYNTAX_ERROR;
+                return LineType.START;
             }
         } else {
             return LineType.SYNTAX_ERROR;

src/main/java/com/jugubell/bproccli/compiler/VerifySyntax.java

@@ -66,20 +66,12 @@ public static void help() {
         System.out.println("*****************************************************");
         System.out.println("**************** Help for BProC CLI *****************");
         System.out.println("*****************************************************");
-        System.out.println("*                                                   *");
-        System.out.println("*  ;;;;      /                                      *");
-        System.out.println("*  ;;;;     /_____  ______  _____  ______  ______   *");
-        System.out.println("*          /     / /     / /      /     / /         *");
-        System.out.println("*  ;;;;   /_____/ /_____/ /      /_____/ /______    *");
-        System.out.println("*   ;;;          /                                  *");
-        System.out.println("*  ;;           /                                   *");
-        System.out.println("*****************************************************");
         System.out.println();
         System.out.println("Description:");
         System.out.println("    BProC is a simple command line interface for compiling assembler files '.bpasm'");
         System.out.println("    for basic processors intended for education use.");
-        System.out.println("    Please find the supported instruction set in: https://github.com/jugubell/bproc-cli");
-        System.out.println("    This project is free and open source, it is licensed under the GPLv2 license.");
+        System.out.println("    Please find related info about the project on: https://github.com/jugubell/bproc-cli");
+        System.out.println("    This project is free and open source, and it is licensed under the GPLv2 license.");
         System.out.println();
         System.out.println("Usage:");
         System.out.println("    bproc [-action <inputFile (*.bpasm)>] [optional -output <outputFileName/outputDirectory>] [optional --option <compileType>]");
@@ -115,7 +107,7 @@ public static void version() {
     }
 
     public static void instructionSet() {
-        Globals glb = new Globals();
+//        Globals glb = new Globals();  // for future dynamic instruction set fetch
         System.out.println("BProC compiler supported instruction set:");
         System.out.println("-------------------------------------------------------------------------------------------------------------------");
         System.out.println("| Instr. | Op code | Type     | Needs an oprd. | Description                                                      |");
@@ -129,8 +121,8 @@ public static void instructionSet() {
         System.out.println("| ISZ    | 0x6000  | Hardware | Yes            | Increment value of addr. and skip next instr. if result=0        |");
         System.out.println("| CLA    | 0x7800  | Hardware | No             | Clear accumulator A                                              |");
         System.out.println("| CLE    | 0x7400  | Hardware | No             | Clear flag E (carry out)                                         |");
-        System.out.println("| CMA    | 0x7200  | Hardware | No             | Logic `NOT` of accumulator A (A = Ā)                             |");
-        System.out.println("| CME    | 0x7100  | Hardware | No             | Logic `NOT` of flag E (E = Ē)                                    |");
+        System.out.println("| LNA    | 0x7200  | Hardware | No             | Logic `NOT` of accumulator A (A = Ā)                             |");
+        System.out.println("| LNE    | 0x7100  | Hardware | No             | Logic `NOT` of flag E (E = Ē)                                    |");
         System.out.println("| SRA    | 0x7080  | Hardware | No             | Shift right of the accumulator A through the flag E              |");
         System.out.println("| SLA    | 0x7040  | Hardware | No             | Shift left of the accumulator A through the flag E               |");
         System.out.println("| INC    | 0x7020  | Hardware | No             | Increment accumulator A                                          |");
@@ -143,9 +135,10 @@ public static void instructionSet() {
         System.out.println("| WOR    | 0xF400  | Hardware | No             | Write output register (GPIO out)                                 |");
         System.out.println("| SFI    | 0xF200  | Hardware | No             | Skip the next instr. if flag FGI = 1 (Input reading flag)        |");
         System.out.println("| SFO    | 0xF100  | Hardware | No             | Skip the next instr. if flag FGO = 0 (Output writing flag)       |");
-        System.out.println("| LDI    | 0xF080  | Hardware | Yes            | Load data in immediate mode                                      |");
+        System.out.println("| LDD*   | 0xF080  | Hardware | Yes            | Load data in immediate addressing mode                           |");
         System.out.println("| JMP    | 0x0000  | Software | No             | Jump to label in assembly code                                   |");
         System.out.println("-------------------------------------------------------------------------------------------------------------------");
+        System.out.println("* Not yet supported (instead, use .data declaration combined with LDA)");
         System.out.println();
         System.out.println("Keywords:");
         System.out.println("------------------------------------------------------------------------------------------------------------------");