This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Архитектура на ЖАР

Разбиране на вътрешната архитектура на ЖАР 2.0 - от parsing до execution.

🏗️ High-level архитектура

┌─────────────┐    ┌────────────┐    ┌─────────────┐    ┌──────────────┐
│ ЖAP Source  │───▶│   Lexer    │───▶│   Parser    │───▶│     AST      │
│   Code      │    │            │    │             │    │              │
└─────────────┘    └────────────┘    └─────────────┘    └──────────────┘
                                                                   │
┌─────────────┐    ┌────────────┐    ┌─────────────┐               │
│  Execution  │◀───│   VM/JIT   │◀───│  Compiler   │◀──────────────┘
│   Result    │    │            │    │             │
└─────────────┘    └────────────┘    └─────────────┘

📁 Структура на проекта

zhar/
├── cli/                    # Command-line interface
│   └── zhar.py            # Main CLI entry point
├── core/                  # Core engine
│   ├── syntax/            # Lexer & Parser
│   │   ├── lexer.py      # Tokenization
│   │   ├── parser.py     # AST generation
│   │   └── ast.py        # AST node definitions
│   ├── vm.py             # Virtual Machine
│   ├── compiler.py       # AST → Bytecode
│   ├── bytecode.py       # Bytecode definitions
│   ├── objects.py        # Runtime objects
│   ├── exceptions.py     # Error handling
│   ├── native/           # Native backends
│   │   ├── ffi.py        # Python ↔ Native interface
│   │   ├── cpp/          # C++ kernels
│   │   └── go/           # Go kernels
│   ├── rt/               # Runtime systems
│   │   └── kernels.py    # KERNELS integration
│   ├── ml/               # Machine learning
│   │   └── __init__.py   # ML framework
│   └── bridges/          # Language bridges
│       ├── python_bridge.py
│       ├── php_bridge.py
│       └── ruby_bridge.py
├── examples/              # Example programs
├── tests/                # Test suite
└── docs/                 # Documentation

🔤 Lexical Analysis (Tokenization)

Lexer архитектура

class ZharLexer:
    def __init__(self, source: str):
        self.source = source
        self.pos = 0
        self.current_char = None
    
    def tokenize(self) -> List[Token]:
        tokens = []
        while not self.at_end():
            token = self.next_token()
            if token.type != TokenType.WHITESPACE:
                tokens.append(token)
        return tokens

Token types

# Пpимepи нa token-и
"Пeчaт"      → KEYWORD(Пeчaт)
"="          → ASSIGN
"123"        → NUMBER(123)  
'"тeкcт"'    → STRING("тeкcт")
"aкo"        → KEYWORD(aкo)
"{"          → LBRACE
"π"          → UNICODE_CONST(π)

Поддържани символи

Cyrillic keywords: aкo, инaчe, зa, дoкaтo, фyнкция, клac
Unicode math: π, ℯ, ∞, ≡, ≠, ≤, ≥
Operators: +, -, *, /, **, %, ==, !=
Delimiters: (, ), [, ], {, }, ,, ;

🌳 Синтактичен анализ (Parsing)

AST Node hierarchy

class ASTNode:
    pass

class Expression(ASTNode):
    pass

class Statement(ASTNode):  
    pass

# Expressions
class BinaryOp(Expression):
    def __init__(self, left, operator, right):
        self.left = left
        self.operator = operator  
        self.right = right

class FunctionCall(Expression):
    def __init__(self, name, args):
        self.name = name
        self.args = args

# Statements  
class Assignment(Statement):
    def __init__(self, target, value):
        self.target = target
        self.value = value

class IfStatement(Statement):
    def __init__(self, condition, then_body, else_body=None):
        self.condition = condition
        self.then_body = then_body
        self.else_body = else_body

Recursive Descent Parser

class ZharParser:
    def parse_expression(self):
        return self.parse_or()
    
    def parse_or(self):
        expr = self.parse_and()
        while self.match(TokenType.OR):
            op = self.previous()
            right = self.parse_and()
            expr = BinaryOp(expr, op, right)
        return expr
    
    def parse_assignment(self):
        expr = self.parse_expression()
        if self.match(TokenType.ASSIGN):
            value = self.parse_expression()
            return Assignment(expr, value)
        return expr

⚙️ Compilation Process

AST → Bytecode

class Compiler:
    def compile(self, ast_node):
        if isinstance(ast_node, BinaryOp):
            self.compile(ast_node.left)
            self.compile(ast_node.right)
            self.emit_instruction(BINARY_OP, ast_node.operator.type)
        
        elif isinstance(ast_node, FunctionCall):
            for arg in ast_node.args:
                self.compile(arg)
            self.emit_instruction(CALL_FUNCTION, len(ast_node.args))

Bytecode Instructions

class Instruction(Enum):
    LOAD_CONST = 1      # Зapeждa кoнcтaнтa
    LOAD_NAME = 2       # Зapeждa пpoмeнливa
    STORE_NAME = 3      # Зaпaзвa пpoмeнливa  
    BINARY_ADD = 4      # a + b
    BINARY_SUB = 5      # a - b
    BINARY_MUL = 6      # a * b
    CALL_FUNCTION = 10  # Извиквa фyнкция
    RETURN_VALUE = 11   # Bpъщa cтoйнocт
    JUMP_IF_FALSE = 20  # Уcлoвeн cкoк
    JUMP_ABSOLUTE = 21  # Бeзycлoвeн cкoк

🖥️ Virtual Machine

VM архитектура

class ZharVM:
    def __init__(self):
        self.stack = []          # Execution stack
        self.frames = []         # Call frames  
        self.globals = {}        # Global variables
        self.builtins = {}       # Built-in functions
        
    def run(self, bytecode):
        for instruction in bytecode:
            self.execute_instruction(instruction)

Stack-based execution

# ЖAP кoд:
x = 5 + 3
Пeчaт(x)

# Bytecode:
LOAD_CONST    5     # Stack: [5]
LOAD_CONST    3     # Stack: [5, 3]  
BINARY_ADD          # Stack: [8]
STORE_NAME    'x'   # Stack: [], globals: {x: 8}
LOAD_NAME     'x'   # Stack: [8]
LOAD_NAME     'Пeчaт' # Stack: [8, <builtin_print>]
CALL_FUNCTION 1     # Stack: []

Call frames

class Frame:
    def __init__(self, function, locals_dict):
        self.function = function
        self.locals = locals_dict
        self.pc = 0              # Program counter
        self.stack = []          # Local stack

class ZharVM:
    def call_function(self, func, args):
        frame = Frame(func, {})
        self.frames.append(frame)
        # Execute function bytecode
        result = self.run_frame(frame)
        self.frames.pop()
        return result

🚀 Native Integration

FFI Layer

# core/native/ffi.py
class NativeBackend:
    def __init__(self, library_path):
        self.lib = ctypes.CDLL(library_path)
        self.setup_signatures()
    
    def setup_signatures(self):
        self.lib.ZharMatmulF32.argtypes = [
            POINTER(c_float), POINTER(c_float), POINTER(c_float),
            c_int, c_int, c_int
        ]
    
    def matmul_f32(self, A, B):
        # Convert numpy → ctypes, call native, convert back
        pass

Runtime Integration

# core/rt/kernels.py
class Kernels:
    def __init__(self):
        self.backend = load_native_backend()
    
    def matmul(self, A, B):
        if self.backend:
            return self.backend.matmul_f32(A, B)
        return numpy_fallback(A, B)

# VM builtins integration
vm.builtins['KERNELS'] = Kernels()

🧠 ML Integration

ML Framework архитектура

# core/ml/__init__.py
class Layer:
    def forward(self, x): pass
    def backward(self, grad): pass

class Dense(Layer):
    def forward(self, x):
        # Use native kernels if available
        if hasattr(builtins, 'KERNELS'):
            return KERNELS.matmul(x, self.weights) + self.bias
        return numpy_fallback(x, self.weights, self.bias)

🌉 Language Bridges

Python Bridge

class PythonBridge:
    def __init__(self, safe_mode=True):
        self.safe_mode = safe_mode
        self.allowed_modules = {'math', 'json', 'datetime'} if safe_mode else None
    
    def call_python(self, module_name, function_name, *args):
        if self.safe_mode and module_name not in self.allowed_modules:
            raise SecurityError(f"Module {module_name} not allowed")
        
        module = __import__(module_name)
        func = getattr(module, function_name)
        return func(*args)

Bridge Integration

# ЖAP кoд мoжe дa извиквa Python
oт python внoc math
peзyлтaт = math.sqrt(16)  # 4.0

oт python внoc json  
дaнни = json.loads('{"key": "value"}')

🔧 Error Handling

Exception Hierarchy

class ZharException(Exception):
    pass

class ZharSyntaxError(ZharException):
    def __init__(self, message, line, column):
        self.message = message
        self.line = line
        self.column = column

class ZharRuntimeError(ZharException):
    pass

class ZharTypeError(ZharRuntimeError):
    pass

Error propagation

class ZharVM:
    def execute_instruction(self, instr):
        try:
            # Execute instruction
            pass
        except Exception as e:
            # Convert to ZharException
            zhar_error = self.wrap_exception(e)
            self.handle_exception(zhar_error)

📊 Memory Management

Object система

class ZharObject:
    def __init__(self, value, type_info):
        self.value = value
        self.type_info = type_info
        self.ref_count = 1

class ZharDict(ZharObject):
    def __init__(self):
        super().__init__({}, 'dict')
    
    def get_item(self, key):
        return self.value.get(key)

Garbage Collection

class GarbageCollector:
    def __init__(self, vm):
        self.vm = vm
        self.threshold = 1000
        
    def collect(self):
        # Mark & sweep garbage collection
        marked = set()
        self.mark_reachable(self.vm.stack, marked)
        self.mark_reachable(self.vm.globals, marked)
        self.sweep_unmarked(marked)

🔄 Optimization Strategies

Constant folding

# AST optimization
def optimize_binary_op(node):
    if (isinstance(node.left, NumberLiteral) and 
        isinstance(node.right, NumberLiteral)):
        # Fold constants at compile time
        result = evaluate_at_compile_time(node)
        return NumberLiteral(result)
    return node

Bytecode optimization

def optimize_bytecode(instructions):
    # Remove dead code
    # Combine instructions
    # Inline small functions
    pass

JIT Compilation (планирано)

class JITCompiler:
    def compile_hot_function(self, func, call_count):
        if call_count > JIT_THRESHOLD:
            native_code = self.compile_to_native(func)
            self.cache_compiled_function(func, native_code)

Следващо: API Reference