PySHDL 0.1.3__tar.gz → 0.1.4__tar.gz

{pyshdl-0.1.3 → pyshdl-0.1.4}/.gitignore

@@ -1,4 +1,5 @@
 .gitignore
+
 # Python-generated files
 __pycache__/
 *.py[oc]
@@ -13,4 +14,5 @@ wheels/
 
 *.c
 *.so
-.python-version
+.python-version
+.DS_Store

{pyshdl-0.1.3 → pyshdl-0.1.4}/DOCS.md

@@ -191,6 +191,72 @@ A[1]    # LSB of A
 A[8]    # MSB of 8-bit A
 ```
 
+### Constants
+
+Constants allow you to define named values that can be used throughout your component definition. This makes your code more maintainable and easier to parameterize.
+
+**Syntax:**
+
+```shdl
+CONSTANT_NAME = value;
+```
+
+Where `value` can be:
+- Decimal: `WIDTH = 16;`
+- Binary: `MASK = 0b1111;`
+- Hexadecimal: `FLAGS = 0xFF;`
+
+**Rules:**
+- Constant names must be all uppercase with underscores (e.g., `WIDTH`, `BUS_SIZE`, `NUM_GATES`)
+- Any uppercase identifier followed by `= number;` is treated as a constant
+- Constants must be declared inside the component body, before their use
+- Constant values must be non-negative integers
+- Constants are substituted before generator expansion
+
+**Usage:**
+
+Constants can be used in two ways:
+
+1. **As scalar values** in connections (for constants 0 or 1):
+```shdl
+TRUE = 1;
+FALSE = 0;
+A -> gate1.A;
+TRUE -> gate1.B;  # Ties input B to constant 1
+```
+
+2. **As bit-indexed vectors** in connections:
+```shdl
+COMP = 7;  # 0b111 in binary
+COMP[1] -> gate1.A;  # Bit 1 (LSB) of COMP
+COMP[2] -> gate2.A;  # Bit 2 of COMP
+COMP[3] -> gate3.A;  # Bit 3 (MSB) of COMP
+```
+
+**Example:**
+
+```shdl
+component ParamAdder(A[16], B[16], Cin) -> (Sum[16], Cout) {
+    WIDTH = 16;
+    LAST_BIT = 16;
+    
+    # Create WIDTH full adders
+    >i[WIDTH]{
+        fa{i}: FullAdder;
+    }
+    
+    connect {
+        # ... connections using WIDTH and LAST_BIT ...
+    }
+}
+```
+
+**Use Cases:**
+- Defining bus widths: `BUS_WIDTH = 32;`
+- Setting array sizes: `>i[BUS_WIDTH]{ ... }`
+- Parameterizing generator ranges: `>i[1, WIDTH]{ ... }`
+- Making components more maintainable and reusable
+
 ---
 
 ## Imports and Modules

{pyshdl-0.1.3 → pyshdl-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PySHDL
-Version: 0.1.3
+Version: 0.1.4
 Summary: SHDL (Simple Hardware Description Language) is a minimal HDL designed for creating digital circuits and easily simulating them. It compiles directly to C for maximum performance and portability. PySHDL is the Python interface for SHDL.
 Project-URL: Homepage, https://github.com/rafa-rrayes/SHDL
 Project-URL: Repository, https://github.com/rafa-rrayes/SHDL
@@ -20,6 +20,7 @@ A lightweight hardware description language and Python driver for digital circui
 - ⚡ **C Backend** - Compiles to optimized C code for fast simulation and portability
 - 🔧 **Command Line Tools** - Built-in compiler and utilities
 - 📦 **Component Reuse** - Import and compose reusable circuit components
+- 🔢 **Constants Support** - Use named constants for parameterizable designs
 
 ## Installation
 
@@ -128,7 +129,7 @@ See the `examples/` directory for more complete examples:
 
 ## Documentation
 Github repository: [rafa-rrayes/SHDL](https://github.com/rafa-rrayes/SHDL)
-For more detailed documentation, see [DOCS.md](DOCS.md).
+For more detailed documentation, see [DOCS.md](https://github.com/rafa-rrayes/SHDL/blob/master/DOCS.md)
 
 ## Requirements
 

{pyshdl-0.1.3 → pyshdl-0.1.4}/README.md

@@ -9,6 +9,7 @@ A lightweight hardware description language and Python driver for digital circui
 - ⚡ **C Backend** - Compiles to optimized C code for fast simulation and portability
 - 🔧 **Command Line Tools** - Built-in compiler and utilities
 - 📦 **Component Reuse** - Import and compose reusable circuit components
+- 🔢 **Constants Support** - Use named constants for parameterizable designs
 
 ## Installation
 
@@ -117,7 +118,7 @@ See the `examples/` directory for more complete examples:
 
 ## Documentation
 Github repository: [rafa-rrayes/SHDL](https://github.com/rafa-rrayes/SHDL)
-For more detailed documentation, see [DOCS.md](DOCS.md).
+For more detailed documentation, see [DOCS.md](https://github.com/rafa-rrayes/SHDL/blob/master/DOCS.md)
 
 ## Requirements
 

pyshdl-0.1.4/examples/SHDL_components/compare7.shdl

@@ -0,0 +1,23 @@
+use stdgates::{AND};
+
+component Comp7(A[3]) -> (True) {
+    COMP = 7;  # 0b111
+    
+    >i[3]{
+        and{i}: AND;
+    }
+    and_out1: AND;
+    and_out2: AND;
+    
+    connect {
+        >i[3]{
+            A[{i}] -> and{i}.A;
+            COMP[{i}] -> and{i}.B;
+        }
+        and1.O -> and_out1.A;
+        and2.O -> and_out1.B;
+        and_out1.O -> and_out2.A;
+        and3.O -> and_out2.B;
+        and_out2.O -> True;
+    }
+}

{pyshdl-0.1.3 → pyshdl-0.1.4}/examples/interacting.py

@@ -1,5 +1,14 @@
 from PySHDL import Circuit
 
+def test_comp7():
+    circuit = Circuit("examples/SHDL_components/compare7.shdl")
+
+    for val in range(8):
+        circuit.poke("A", val)
+        circuit.step(10)
+        result = circuit.peek("True")
+        print(f"Compare7 input: {val}, output: {result}")
+
 def test_register16():
     circuit = Circuit("examples/SHDL_components/reg16.shdl")
 
@@ -37,4 +46,5 @@ if __name__ == "__main__":
     result = circuit.peek("Sum")
 
     print(f"{A} + {B} + {Cin} = {result}, expected {A + B + Cin}")
-    test_register16()
+    test_register16()
+    test_comp7()

{pyshdl-0.1.3 → pyshdl-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "PySHDL"
-version = "0.1.3"
+version = "0.1.4"
 description = "SHDL (Simple Hardware Description Language) is a minimal HDL designed for creating digital circuits and easily simulating them. It compiles directly to C for maximum performance and portability. PySHDL is the Python interface for SHDL."
 readme = "README.md"
 authors = [

{pyshdl-0.1.3 → pyshdl-0.1.4}/src/PySHDL/__init__.py

@@ -1,4 +1,4 @@
-"""PySHDL library."""
+"""shdl library."""
 
 from importlib import import_module
 from importlib.metadata import PackageNotFoundError, version
@@ -16,6 +16,6 @@ __all__ = [
     "__version__",
 ]
 try:
-    __version__ = version("PySHDL")
+    __version__ = version("shdl")
 except PackageNotFoundError:
     __version__ = "0.0.0"

{pyshdl-0.1.3 → pyshdl-0.1.4}/src/PySHDL/shdlc.py

@@ -59,6 +59,7 @@ class Component:
     instances: List[Instance] = field(default_factory=list)
     connections: List[Tuple[str, str]] = field(default_factory=list)  # (from, to)
     imports: Dict[str, List[str]] = field(default_factory=dict)  # module -> [components]
+    constants: Dict[str, int] = field(default_factory=dict)  # constant_name -> value
 
 
 class SHDLParser:
@@ -142,6 +143,9 @@ class SHDLParser:
         # Parse outputs
         comp.outputs = self._parse_ports(outputs_str, is_input=False)
         
+        # Parse constants
+        comp.constants = self._parse_constants(body)
+        
         # Parse body (instances and connections)
         self._parse_body(comp, body)
         
@@ -171,11 +175,81 @@ class SHDLParser:
         
         return ports
     
+    def _parse_constants(self, body: str) -> Dict[str, int]:
+        """
+        Parse constant declarations from component body.
+        Syntax: NAME = value;
+        Example: WIDTH = 16; or COMP = 0b111; or MASK = 0xFF;
+        Constants are identified by uppercase names.
+        Supports decimal, binary (0b), and hexadecimal (0x) literals.
+        """
+        constants = {}
+        
+        # Match: UPPERCASE_NAME = value;
+        # Constants must be all uppercase with optional underscores
+        # Value can be: decimal (123), binary (0b1010), or hex (0xAF)
+        pattern = r'([A-Z_][A-Z0-9_]*)\s*=\s*(0[bB][01]+|0[xX][0-9a-fA-F]+|\d+)\s*;'
+        
+        for match in re.finditer(pattern, body):
+            name = match.group(1)
+            value_str = match.group(2)
+            
+            # Parse the value based on prefix
+            if value_str.startswith(('0b', '0B')):
+                value = int(value_str[2:], 2)  # Binary
+            elif value_str.startswith(('0x', '0X')):
+                value = int(value_str[2:], 16)  # Hexadecimal
+            else:
+                value = int(value_str)  # Decimal
+            
+            constants[name] = value
+        
+        return constants
+    
+    def _add_constant_drivers(self, comp: Component, body: str):
+        """
+        Build a mapping of constant bit signals to their values (VCC/GND).
+        This will be used to resolve references during connection parsing.
+        """
+        # Find all synthetic constant bit signals in the body
+        const_bit_pattern = r'__const_([A-Z_][A-Z0-9_]*)_bit_(\d+)'
+        matches = re.findall(const_bit_pattern, body)
+        
+        # Build mapping: signal_name -> '__VCC' or '__GND'
+        const_bit_map = {}
+        
+        for const_name, bit_str in matches:
+            bit_index = int(bit_str)
+            
+            # Get the constant value
+            if const_name not in comp.constants:
+                continue
+            
+            const_value = comp.constants[const_name]
+            
+            # Extract the bit value (1-indexed, LSB is bit 1)
+            bit_value = (const_value >> (bit_index - 1)) & 1
+            
+            # Create a signal name for this constant bit
+            signal_name = f'__const_{const_name}_bit_{bit_index}'
+            
+            # Map to VCC or GND
+            const_bit_map[signal_name] = '__VCC' if bit_value == 1 else '__GND'
+        
+        # Store the mapping in the component for use during connection parsing
+        comp.constants_bit_map = const_bit_map
+    
     def _parse_body(self, comp: Component, body: str):
         """Parse component body (instances and connections)."""
-        # Expand generators first
+        # Substitute constants first
+        body = self._substitute_constants(body, comp.constants)
+        
+        # Expand generators
         body = self._expand_generators(body)
         
+        # Add constant bit drivers AFTER generator expansion
+        self._add_constant_drivers(comp, body)
+        
         # Split into instances and connections
         connect_match = re.search(r'connect\s*\{(.*)\}', body, re.DOTALL)
         
@@ -192,6 +266,44 @@ class SHDLParser:
         # Parse connections
         self._parse_connections(comp, connections_part)
     
+    def _substitute_constants(self, body: str, constants: Dict[str, int]) -> str:
+        """
+        Substitute constant names with their values in the body.
+        Constants can be used:
+        1. As scalar values in connections: TRUE -> a1.B;  (becomes __VCC or __GND)
+        2. As bit-indexed vectors: COMP[{i}] -> gate.A;  (becomes __const_COMP_bit_N)
+        """
+        # Remove constant declarations from the body
+        body = re.sub(r'[A-Z_][A-Z0-9_]*\s*=\s*(?:0[bB][01]+|0[xX][0-9a-fA-F]+|\d+)\s*;', '', body)
+        
+        # For each constant, we need to handle two cases:
+        # 1. Direct usage: CONSTANT_NAME (not followed by [)
+        # 2. Bit-indexed usage: CONSTANT_NAME[index]
+        
+        for const_name, const_value in constants.items():
+            # Case 1: Bit-indexed usage CONST[N] - convert to synthetic signal name
+            # CONST[1] becomes __const_CONST_bit_1, CONST[2] becomes __const_CONST_bit_2, etc.
+            def replace_bit_index(match):
+                bit_index = match.group(1)
+                return f'__const_{const_name}_bit_{bit_index}'
+            
+            # Replace CONST[...] with synthetic signal name
+            body = re.sub(rf'\b{const_name}\[([^\]]+)\]', replace_bit_index, body)
+            
+            # Case 2: Direct scalar usage - replace with __VCC or __GND for 0/1, 
+            # or leave as numeric value for other constants
+            # Use word boundaries to avoid partial matches
+            if const_value == 0:
+                body = re.sub(r'\b' + const_name + r'\b', '__GND', body)
+            elif const_value == 1:
+                body = re.sub(r'\b' + const_name + r'\b', '__VCC', body)
+            else:
+                # For other values, replace with the numeric value
+                # This is useful for parameterization in generators
+                body = re.sub(r'\b' + const_name + r'\b', str(const_value), body)
+        
+        return body
+    
     def _expand_generators(self, body: str) -> str:
         """
         Expand generator syntax:
@@ -269,9 +381,19 @@ class SHDLParser:
         # Match: signal -> port;
         pattern = r'([^\s;]+)\s*->\s*([^\s;]+)\s*;'
         
+        # Get the constant bit mapping if it exists
+        const_bit_map = getattr(comp, 'constants_bit_map', {})
+        
         for match in re.finditer(pattern, connections_str):
             from_sig = match.group(1).strip()
             to_sig = match.group(2).strip()
+            
+            # Resolve constant bit signals to VCC/GND
+            if from_sig in const_bit_map:
+                from_sig = const_bit_map[from_sig]
+            if to_sig in const_bit_map:
+                to_sig = const_bit_map[to_sig]
+            
             comp.connections.append((from_sig, to_sig))
     
     def _load_imports(self, comp: Component, base_path: Path):
@@ -666,6 +788,17 @@ def generate_c_code(component: Component) -> str:
         # constant zero for unconnected pins?
         if src == CONST_ZERO:
             return '0u'
+        # VCC (constant 1)?
+        if src == '__VCC':
+            return '1u'
+        # GND (constant 0)?
+        if src == '__GND':
+            return '0u'
+        # Synthetic constant bit signal?
+        if src.startswith('__const_'):
+            # These should have been resolved to __VCC or __GND via connections
+            # but if we see them here directly, treat as error
+            raise ValueError(f'Unresolved constant signal: {src}')
         # input bit?
         if is_bit(src):
             base, idx = parse_bit(src)

{pyshdl-0.1.3 → pyshdl-0.1.4}/uv.lock

@@ -1,8 +1,8 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.9"
 
 [[package]]
 name = "pyshdl"
-version = "0.1.2"
+version = "0.1.3"
 source = { editable = "." }