v0.3.3: Add stg parse function to print the list of modules, and sort it through in-degree and submodule counts.

.github/workflows/documentation.yml

@@ -1,6 +1,10 @@
 name: documentation
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
 
 permissions:
   contents: write

.gitignore

@@ -71,3 +71,5 @@ obj_dir/
 # Built documentation
 /target/doc/
 
+# Environment variables
+.env

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "stg"
-version = "0.3.2"
+version = "0.3.3"
 edition = "2024"
 authors = ["En-Ming Huang (samuel21119)"]
 description = "Structured Testbench Generation - Automated SystemVerilog testbench generator"

USAGE.md

@@ -32,9 +32,28 @@ STG supports two main testbench generation modes SV and CC/SC mode:
 
 In SV mode, both your DUT and golden reference are Verilog/SystemVerilog modules.
 
+**Note:** Verilog files can be specified as positional arguments or with `--verilog` flag. Both styles are equivalent:
+```bash
+# Using positional arguments (shorter)
+stg generate path/to/dut.v --golden path/to/golden.v --type <design_type> --out testbench.sv
+
+# Using --verilog flag (explicit)
+stg generate --verilog path/to/dut.v --golden path/to/golden.v --type <design_type> --out testbench.sv
+```
+
 #### Generate Testbench Only
 
 ```bash
+# Using positional arguments
+stg generate \
+  path/to/dut.v \
+  --module dut_module_name \
+  --golden path/to/golden.v \
+  --golden-module golden_module_name \
+  --type <design_type> \
+  --out testbench.sv
+
+# Or using --verilog flag
 stg generate \
   --verilog path/to/dut.v \
   --module dut_module_name \
@@ -313,7 +332,7 @@ Generate a testbench and optionally compile it.
 
 | Argument | Description | Example |
 |----------|-------------|---------|
-| `--verilog <FILE>` | Path to DUT Verilog file(s) - supports multiple DUTs | `--verilog dut.v` or `--verilog dut1.v --verilog dut2.v` |
+| `<VERILOG_FILES>...` or `--verilog <FILE>` | Path to DUT Verilog file(s) - can be positional args or with flag | `dut.v` or `--verilog dut.v` or `dut1.v dut2.v` |
 | `--type <TYPE>` | Design type | `--type combinational` |
 | `--out <FILE>` | Output testbench path | `--out tb.sv` or `--out tb.cpp` |
 
@@ -383,6 +402,14 @@ Generate a testbench and optionally compile it.
 Identify and classify signals in a Verilog module.
 
 ```bash
+# Using positional argument
+stg identify \
+  path/to/module.v \
+  --module module_name \
+  --type <design_type> \
+  --out signals.yaml
+
+# Or using --verilog flag
 stg identify \
   --verilog path/to/module.v \
   --module module_name \
@@ -401,20 +428,103 @@ outputs: [result, valid]
 reset_active_high: false
 ```
 
+### `stg parse`
+
+Parse Verilog/SystemVerilog files and generate a module priority list. This command analyzes the module instantiation hierarchy and outputs modules sorted by priority (least dependencies first, then by submodule complexity).
+
+**Note:** Multiple Verilog files can be specified and will be automatically concatenated before parsing.
+
+```bash
+# Single file (using positional argument)
+stg parse \
+  path/to/module.v \
+  --out modules.yaml
+
+# Multiple files (positional arguments - will be concatenated)
+stg parse \
+  file1.v file2.v file3.v \
+  --out modules.yaml
+
+# Or using --verilog flag
+stg parse \
+  --verilog path/to/module.v \
+  --out modules.yaml
+
+# Multiple files with flag
+stg parse \
+  --verilog file1.v,file2.v,file3.v \
+  --out modules.yaml
+```
+
+**What this does:**
+- Parses all modules in the Verilog file
+- Analyzes the module instantiation graph
+- Calculates the total number of submodules for each module (including nested submodules)
+- Sorts modules by priority: modules with fewer dependencies come first, followed by those with more submodules
+- Outputs detailed module information in YAML format
+
+**Output format (YAML):**
+```yaml
+- name: submodule_a
+  submodule_count: 0
+  ports:
+    - name: in
+      direction: input
+      width: 8
+    - name: out
+      direction: output
+      width: 8
+- name: top_module
+  submodule_count: 5
+  ports:
+    - name: clk
+      direction: input
+      width: 1
+    - name: data_in
+      direction: input
+      width: 32
+    - name: data_out
+      direction: output
+      width: 32
+```
+
+**Use cases:**
+- Understanding the module hierarchy in complex Verilog files
+- Identifying the top-level module when `--module` is not specified
+- Analyzing module complexity based on submodule count
+- Debugging module dependencies
+
 ### `stg compile`
 
 Compile user-provided testbench with DUT and golden model.
 
 **SystemVerilog:**
 ```bash
+# Using positional arguments
+stg compile \
+  dut.v \
+  --golden golden.v \
+  --testbench tb.sv \
+  --out-exe tb_exe \
+  [--verilator]
+
+# Or using --verilog flag
 stg compile \
   --verilog dut.v \
   --golden golden.v \
   --testbench tb.sv \
   --out-exe tb_exe \
   [--verilator]
 
-# Multi-DUT SystemVerilog
+# Multi-DUT with positional arguments
+stg compile \
+  dut1.v dut2.v \
+  --golden golden.v \
+  --testbench tb.sv \
+  --out-exe tb_exe \
+  [--verilator]
+
+# Multi-DUT with flag
 stg compile \
   --verilog dut1.v --verilog dut2.v \
   --golden golden.v \
@@ -426,7 +536,7 @@ stg compile \
 **C++/SystemC:**
 ```bash
 stg compile \
-  --verilog dut.v \
+  dut.v \
   --module dut_module \
   --golden golden_model.h \
   --testbench tb.cpp \

docs/source/cli_reference.md

@@ -14,12 +14,17 @@ These options can be used with any `stg` command.
 The `generate` command is used to create a new testbench.
 
 ```bash
-stg generate [OPTIONS] --verilog <VERILOG> --out <OUT> --type <TYPE>
+stg generate [OPTIONS] [VERILOG_FILES...] --out <OUT> --type <TYPE>
 ```
 
+**Note:** Verilog files can be specified either as positional arguments or using the `--verilog` flag. Both approaches are equivalent.
+
 ### File and Module Options
 
--   `--verilog <VERILOG>`: (Required) Path to the DUT (Design Under Test) Verilog/SystemVerilog file. You can specify this option multiple times for multi-DUT testing.
+-   `[VERILOG_FILES...]` or `--verilog <VERILOG>`: (Required) Path to the DUT (Design Under Test) Verilog/SystemVerilog file(s).
+    - Positional: `stg generate dut.v --type combinational --out tb.sv`
+    - With flag: `stg generate --verilog dut.v --type combinational --out tb.sv`
+    - Multiple files: `stg generate dut1.v dut2.v ...` or `--verilog dut1.v --verilog dut2.v`
 -   `--module <MODULE>`: The name of the DUT (Device Under Test) module to be tested. This is strongly recommended if the Verilog file contains more than one module. If no `--module` is specified, we use a smart algorithm to decide the best module by parsing the module instantiation graph and selecting the one with the least in-degree. For multi-DUT testing, you can provide a comma-separated list (e.g., `--module dut0,dut1`) or use the option multiple times (e.g., `--module dut0 --module dut1`). If there are multiple DUTs but only one `--module` is specified, STG will reference all DUTs using the same module name.  
 **Note**: in SystemVerilog-mode, `--emplace-module` should be given so that there is no naming conflicts if the modules are having same name. However, in C++/System-C mode, this renaming mechanism is handled by Verilator automatically.
 -   `--golden <GOLDEN>`: Path to the golden reference model. This can be a Verilog/SystemVerilog file or a C++/SystemC header file (when using `--cc` or `--sc`).
@@ -74,26 +79,74 @@ stg generate [OPTIONS] --verilog <VERILOG> --out <OUT> --type <TYPE>
 The `identify` command classifies the signals of a module.
 
 ```bash
-stg identify [OPTIONS] --verilog <VERILOG> --type <TYPE> --out <OUT>
+stg identify [OPTIONS] [VERILOG_FILE] --type <TYPE> --out <OUT>
 ```
 
--   `--verilog <VERILOG>`: (Required) Path to the Verilog/SystemVerilog file.
+-   `[VERILOG_FILE]` or `--verilog <VERILOG>`: (Required) Path to the Verilog/SystemVerilog file.
+    - Positional: `stg identify module.v --type combinational --out signals.yaml`
+    - With flag: `stg identify --verilog module.v --type combinational --out signals.yaml`
 -   `--module <MODULE>`: The name of the module to identify signals from.
 -   `--type <TYPE>`: (Required) The design type (`combinational`, `seq_clocked`, `seq_done`).
 -   `--out <OUT>`: (Required) The output path for the signal list in YAML format.
 -   `--config <CONFIG>`: Path to a YAML configuration file.
 -   `--control-signals [<CONTROL_SIGNALS>...]`: Explicitly define control signals.
 -   `--data-signals [<DATA_SIGNALS>...]`: Explicitly define data signals.
 
+## `stg parse`
+
+The `parse` command parses Verilog/SystemVerilog files and generates a module priority list.
+
+```bash
+stg parse [VERILOG_FILES...] --out <OUT>
+```
+
+-   `[VERILOG_FILES...]` or `--verilog <VERILOG>`: (Required) Path to the Verilog/SystemVerilog file(s) to parse.
+    - Single file: `stg parse module.v --out modules.yaml`
+    - Multiple files (concatenated): `stg parse file1.v file2.v file3.v --out modules.yaml`
+    - With flag: `stg parse --verilog module.v --out modules.yaml`
+-   `--out <OUT>`: (Required) Output path for the module priority list in YAML format.
+
+**Description:**
+
+The `parse` command analyzes Verilog/SystemVerilog files to extract module information and their dependencies. When multiple files are provided, they are automatically concatenated before parsing. It performs the following:
+
+1. Parses all modules in the specified file
+2. Builds a module instantiation graph to understand dependencies
+3. Calculates the total submodule count for each module (including nested submodules)
+4. Sorts modules by priority using a smart algorithm:
+   - Modules with fewer dependencies (lower in-degree) come first
+   - Among modules with the same in-degree, those with more submodules come first
+5. Outputs detailed information in YAML format, including module names, submodule counts, and port information
+
+**Output Format:**
+
+```yaml
+- name: module_name
+  submodule_count: <number>
+  ports:
+    - name: port_name
+      direction: input/output
+      width: <bit_width>
+```
+
+**Use Cases:**
+- Understanding module hierarchy in complex designs
+- Identifying the top-level module when `--module` is not specified in other commands
+- Analyzing design complexity based on submodule counts
+- Debugging module dependencies and instantiation relationships
+
 ## `stg compile`
 
 The `compile` command compiles a user-provided testbench.
 
 ```bash
-stg compile [OPTIONS] --verilog <VERILOG> --golden <GOLDEN> --testbench <TESTBENCH> --out-exe <OUT_EXE>
+stg compile [OPTIONS] [VERILOG_FILES...] --golden <GOLDEN> --testbench <TESTBENCH> --out-exe <OUT_EXE>
 ```
 
--   `--verilog <VERILOG>`: (Required) Path to the DUT Verilog/SystemVerilog file(s).
+-   `[VERILOG_FILES...]` or `--verilog <VERILOG>`: (Required) Path to the DUT Verilog/SystemVerilog file(s).
+    - Single file: `stg compile dut.v --golden golden.v --testbench tb.sv --out-exe exe`
+    - Multiple files: `stg compile dut1.v dut2.v --golden golden.v --testbench tb.sv --out-exe exe`
+    - With flag: `stg compile --verilog dut.v --golden golden.v --testbench tb.sv --out-exe exe`
 -   `--module <MODULE>`: The name of the DUT module.
 -   `--golden <GOLDEN>`: (Required) Path to the golden reference file.
 -   `--testbench <TESTBENCH>`: (Required) Path to the testbench file (`.sv` or `.cpp`).

docs/source/usage.md

@@ -32,9 +32,28 @@ STG supports two main testbench generation modes SV and CC/SC mode:
 
 In SV mode, both your DUT and golden reference are Verilog/SystemVerilog modules.
 
+**Note:** Verilog files can be specified as positional arguments or with `--verilog` flag. Both styles are equivalent:
+```bash
+# Using positional arguments (shorter)
+stg generate path/to/dut.v --golden path/to/golden.v --type <design_type> --out testbench.sv
+
+# Using --verilog flag (explicit)
+stg generate --verilog path/to/dut.v --golden path/to/golden.v --type <design_type> --out testbench.sv
+```
+
 #### Generate Testbench Only
 
 ```bash
+# Using positional arguments
+stg generate \
+  path/to/dut.v \
+  --module dut_module_name \
+  --golden path/to/golden.v \
+  --golden-module golden_module_name \
+  --type <design_type> \
+  --out testbench.sv
+
+# Or using --verilog flag
 stg generate \
   --verilog path/to/dut.v \
   --module dut_module_name \
@@ -401,6 +420,54 @@ outputs: [result, valid]
 reset_active_high: false
 ```
 
+### `stg parse`
+
+Parse Verilog/SystemVerilog files and generate a module priority list. This command analyzes the module instantiation hierarchy and outputs modules sorted by priority (least dependencies first, then by submodule complexity).
+
+```bash
+stg parse \
+  --verilog path/to/module.v \
+  --out modules.yaml
+```
+
+**What this does:**
+- Parses all modules in the Verilog file
+- Analyzes the module instantiation graph
+- Calculates the total number of submodules for each module (including nested submodules)
+- Sorts modules by priority: modules with fewer dependencies come first, followed by those with more submodules
+- Outputs detailed module information in YAML format
+
+**Output format (YAML):**
+```yaml
+- name: submodule_a
+  submodule_count: 0
+  ports:
+    - name: in
+      direction: input
+      width: 8
+    - name: out
+      direction: output
+      width: 8
+- name: top_module
+  submodule_count: 5
+  ports:
+    - name: clk
+      direction: input
+      width: 1
+    - name: data_in
+      direction: input
+      width: 32
+    - name: data_out
+      direction: output
+      width: 32
+```
+
+**Use cases:**
+- Understanding the module hierarchy in complex Verilog files
+- Identifying the top-level module when `--module` is not specified
+- Analyzing module complexity based on submodule count
+- Debugging module dependencies
+
 ### `stg compile`
 
 Compile user-provided testbench with DUT and golden model.