diff options
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | README_ES.md | 1415 | ||||
| -rw-r--r-- | README_ZH_CN.md | 1415 | ||||
| -rw-r--r-- | README_ZH_TW.md | 1415 |
4 files changed, 4251 insertions, 0 deletions
@@ -1,6 +1,12 @@ <div align="center"> +[English](README.md) • [简体中文](README_ZH_CN.md) • [繁體中文](README_ZH_TW.md) • [Español](README_ES.md) + +</div> + +<div align="center"> + # Zen C **Modern Ergonomics. Zero Overhead. Pure C.** diff --git a/README_ES.md b/README_ES.md new file mode 100644 index 0000000..2735497 --- /dev/null +++ b/README_ES.md @@ -0,0 +1,1415 @@ + +<div align="center"> + +[English](README.md) • [简体中文](README_ZH_CN.md) • [繁體中文](README_ZH_TW.md) • [Español](README_ES.md) + +</div> + +<div align="center"> + +# Zen C + +**Ergonomía Moderna. Cero Sobrecarga. C Puro.** + +[]() +[]() +[]() +[]() + +*Escribe como un lenguaje de alto nivel, ejecuta como C.* + +</div> + +--- + +## Descripción General + +**Zen C** es un lenguaje de programación de sistemas moderno que se compila a `GNU C`/`C11` legible por humanos. Proporciona un conjunto rico de características que incluyen inferencia de tipos, coincidencia de patrones (pattern matching), genéricos, traits, async/await y gestión manual de memoria con capacidades RAII, todo manteniendo una compatibilidad total con el ABI de C. + +## Comunidad + +¡Únete a la discusión, comparte demos, haz preguntas o reporta errores en el servidor oficial de Discord de Zen C! + +- Discord: [Únete aquí](https://discord.com/invite/q6wEsCmkJP) + +--- + +## Índice + +- [Descripción General](#descripción-general) +- [Comunidad](#comunidad) +- [Inicio Rápido](#inicio-rápido) + - [Instalación](#instalación) + - [Uso](#uso) + - [Variables de Entorno](#variables-de-entorno) +- [Referencia del Lenguaje](#referencia-del-lenguaje) + - [1. Variables y Constantes](#1-variables-y-constantes) + - [2. Tipos Primitivos](#2-tipos-primitivos) + - [3. Tipos Agregados](#3-tipos-agregados) + - [Arrays](#arrays) + - [Tuplas](#tuplas) + - [Structs](#structs) + - [Structs Opacos](#structs-opacos) + - [Enums](#enums) + - [Uniones](#uniones) + - [Alias de Tipos](#alias-de-tipos) + - [Alias de Tipos Opacos](#alias-de-tipos-opacos) + - [4. Funciones y Lambdas](#4-funciones-y-lambdas) + - [Funciones](#funciones) + - [Argumentos Const](#argumentos-const) + - [Argumentos por Defecto](#argumentos-por-defecto) + - [Lambdas (Clausuras)](#lambdas-clausuras) + - [Punteros a Funciones Crudos](#punteros-a-funciones-crudos) + - [Funciones Variádicas](#funciones-variádicas) + - [5. Flujo de Control](#5-flujo-de-control) + - [Condicionales](#condicionales) + - [Coincidencia de Patrones](#coincidencia-de-patrones) + - [Bucles](#bucles) + - [Control Avanzado](#control-avanzado) + - [6. Operadores](#6-operadores) + - [Operadores Sobrecargables](#operadores-sobrecargables) + - [Azúcar Sintáctico](#azúcar-sintáctico) + - [7. Impresión e Interpolación de Cadenas](#7-impresión-e-interpolación-de-cadenas) + - [Palabras Clave](#palabras-clave) + - [Abreviaturas](#abreviaturas) + - [Interpolación de Cadenas (F-strings)](#interpolación-de-cadenas-f-strings) + - [Prompts de Entrada (`?`)](#prompts-de-entrada-) + - [8. Gestión de Memoria](#8-gestión-de-memoria) + - [Defer](#defer) + - [Autofree](#autofree) + - [Semántica de Recursos (Movimiento por Defecto)](#semántica-de-recursos-movimiento-por-defecto) + - [RAII / Drop Trait](#raii--drop-trait) + - [9. Programación Orientada a Objetos](#9-programación-orientada-a-objetos) + - [Métodos](#métodos) + - [Traits](#traits) + - [Traits Estándar](#traits-estándar) + - [Composición](#composición) + - [10. Genéricos](#10-genéricos) + - [11. Concurrencia (Async/Await)](#11-concurrencia-asyncawait) + - [12. Metaprogramación](#12-metaprogramación) + - [Comptime](#comptime) + - [Embed](#embed) + - [Plugins](#plugins) + - [Macros de C Genéricas](#macros-de-c-genéricas) + - [13. Atributos](#13-atributos) + - [Atributos Personalizados](#atributos-personalizados) + - [Derivaciones Inteligentes](#derivaciones-inteligentes) + - [14. Ensamblador Inline](#14-ensamblador-inline) + - [Uso Básico](#uso-básico) + - [Volatile](#volatile) + - [Restricciones con Nombre](#restricciones-con-nombre) + - [15. Directivas de Construcción](#15-directivas-de-construcción) + - [16. Palabras Clave](#16-palabras-clave) +- [Biblioteca Estándar](#biblioteca-estándar) +- [Herramientas](#herramientas) + - [Servidor de Lenguaje (LSP)](#servidor-de-lenguaje-lsp) + - [REPL](#repl) +- [Soporte del Compilador y Compatibilidad](#soporte-del-compilador-y-compatibilidad) + - [Estado de la Suite de Pruebas](#estado-de-la-suite-de-pruebas) + - [Construyendo con Zig](#construyendo-con-zig) + - [Interop con C++](#interop-con-c) + - [Interop con CUDA](#interop-con-cuda) + - [Interop con Objective-C](#interop-con-objective-c) +- [Contribuyendo](#contribuyendo) +- [Atribuciones](#atribuciones) + +--- + +## Inicio Rápido + +### Instalación + +```bash +git clone https://github.com/z-libs/Zen-C.git +cd Zen-C +make +sudo make install +``` + +### Construcción Portable (APE) + +Zen C puede compilarse como un **Ejecutable Realmente Portable (APE)** usando [Cosmopolitan Libc](https://github.com/jart/cosmopolitan). Esto produce un único binario (`.com`) que se ejecuta de forma nativa en Linux, macOS, Windows, FreeBSD, OpenBSD y NetBSD en arquitecturas x86_64 y aarch64. + +**Prerrequisitos:** +- Toolchain `cosmocc` (debe estar en tu PATH) + +**Construcción e Instalación:** +```bash +make ape +sudo env "PATH=$PATH" make install-ape +``` + +**Artefactos:** +- `out/bin/zc.com`: El compilador Zen-C portable. Incluye la biblioteca estándar embebida dentro del ejecutable. +- `out/bin/zc-boot.com`: Un instalador bootstrap autónomo para configurar nuevos proyectos Zen-C. + +**Uso:** +```bash +# Ejecutar en cualquier SO compatible +./out/bin/zc.com build hello.zc -o hello +``` + +### Uso + +```bash +# Compilar y ejecutar +zc run hello.zc + +# Construir ejecutable +zc build hello.zc -o hello + +# Shell Interactiva +zc repl +``` + +### Variables de Entorno + +Puedes configurar `ZC_ROOT` para especificar la ubicación de la Biblioteca Estándar (importaciones estándar como `import "std/vector.zc"`). Esto te permite ejecutar `zc` desde cualquier directorio. + +```bash +export ZC_ROOT=/ruta/a/Zen-C +``` + +--- + +## Referencia del Lenguaje + +### 1. Variables y Constantes + +Zen C distingue entre constantes en tiempo de compilación y variables en tiempo de ejecución. + +#### Constantes Manifiestas (`def`) +Valores que existen solo en tiempo de compilación (se pliegan en el código). Úsalos para tamaños de arrays, configuración fija y números mágicos. + +```zc +def MAX_SIZE = 1024; +let buffer: char[MAX_SIZE]; // Tamaño de array válido +``` + +#### Variables (`let`) +Ubicaciones de almacenamiento en memoria. Pueden ser mutables o de solo lectura (`const`). + +```zc +let x = 10; // Mutable +x = 20; // OK + +let y: const int = 10; // Solo lectura (Calificado por tipo) +// y = 20; // Error: no se puede asignar a una constante +``` + +### 2. Tipos Primitivos + +| Tipo | Equivalente en C | Descripción | +|:---|:---|:---| +| `int`, `uint` | `int`, `unsigned int` | Entero estándar de la plataforma | +| `I8` .. `I128` o `i8` .. `i128` | `int8_t` .. `__int128_t` | Enteros con signo de ancho fijo | +| `U8` .. `U128` o `u8` .. `u128` | `uint8_t` .. `__uint128_t` | Enteros sin signo de ancho fijo | +| `isize`, `usize` | `ptrdiff_t`, `size_t` | Enteros del tamaño de un puntero | +| `byte` | `uint8_t` | Alias para U8 | +| `F32`, `F64` o `f32`, `f64` | `float`, `double` | Números de coma flotante | +| `bool` | `bool` | `true` o `false` | +| `char` | `char` | Carácter único | +| `string` | `char*` | Cadena de C (terminada en null) | +| `U0`, `u0`, `void` | `void` | Tipo vacío | + +### 3. Tipos Agregados + +#### Arrays +Arrays de tamaño fijo con semántica de valor. +```zc +def SIZE = 5; +let ints: int[SIZE] = [1, 2, 3, 4, 5]; +let zeros: [int; SIZE]; // Inicializado a cero +``` + +#### Tuplas +Agrupa múltiples valores, accede a los elementos por índice. +```zc +let pair = (1, "Hola"); +let x = pair.0; // 1 +let s = pair.1; // "Hola" +``` + +**Múltiples Valores de Retorno** + +Las funciones pueden retornar tuplas para proporcionar múltiples resultados: +```zc +fn sumar_y_restar(a: int, b: int) -> (int, int) { + return (a + b, a - b); +} + +let resultado = sumar_y_restar(3, 2); +let suma = resultado.0; // 5 +let resta = resultado.1; // 1 +``` + +**Desestructuración** + +Las tuplas pueden desestructurarse directamente en variables: +```zc +let (suma, resta) = sumar_y_restar(3, 2); +// suma = 5, resta = 1 +``` + +#### Structs +Estructuras de datos con campos de bits opcionales. +```zc +struct Point { + x: int; + y: int; +} + +// Inicialización de struct +let p = Point { x: 10, y: 20 }; + +// Campos de bits +struct Flags { + valid: U8 : 1; + mode: U8 : 3; +} +``` + +> **Nota**: Los structs usan [Semántica de Movimiento](#semántica-de-recursos-movimiento-por-defecto) por defecto. Los campos se pueden acceder mediante `.` incluso en punteros (Auto-Dereferencia). + +#### Structs Opacos +Puedes definir un struct como `opaque` para restringir el acceso a sus campos solo al módulo que lo define, permitiendo aún que el struct sea asignado en el stack (el tamaño es conocido). + +```zc +// En user.zc +opaque struct User { + id: int; + name: string; +} + +fn new_user(name: string) -> User { + return User{id: 1, name: name}; // OK: Dentro del módulo +} + +// En main.zc +import "user.zc"; + +fn main() { + let u = new_user("Alice"); + // let id = u.id; // Error: No se puede acceder al campo privado 'id' +} +``` + +#### Enums +Uniones etiquetadas (Tipos suma) capaces de contener datos. +```zc +enum Shape { + Circle(float), // Contiene el radio + Rect(float, float), // Contiene ancho y alto + Point // Sin datos +} +``` + +#### Uniones +Uniones estándar de C (acceso inseguro). +```zc +union Data { + i: int; + f: float; +} +``` + +#### Alias de Tipos +Crea un nuevo nombre para un tipo existente. +```zc +alias ID = int; +alias PointMap = Map<string, Point>; +``` + +#### Alias de Tipos Opacos +Puedes definir un alias de tipo como `opaque` para crear un nuevo tipo que sea distinto de su tipo subyacente fuera del módulo que lo define. Esto proporciona una fuerte encapsulación y seguridad de tipos sin la sobrecarga en tiempo de ejecución de un struct envoltorio. + +```zc +// En library.zc +opaque alias Handle = int; + +fn make_handle(v: int) -> Handle { + return v; // Conversión implícita permitida dentro del módulo +} + +// En main.zc +import "library.zc"; + +fn main() { + let h: Handle = make_handle(42); + // let i: int = h; // Error: Falló la validación de tipos + // let h2: Handle = 10; // Error: Falló la validación de tipos +} +``` + +### 4. Funciones y Lambdas + +#### Funciones +```zc +fn suma(a: int, b: int) -> int { + return a + b; +} + +// Argumentos con nombre soportados en las llamadas +suma(a: 10, b: 20); +``` + +> **Nota**: Los argumentos con nombre deben seguir estrictamente el orden de los parámetros definidos. `suma(b: 20, a: 10)` es inválido. + +#### Argumentos Const +Los argumentos de las funciones pueden marcarse como `const` para imponer una semántica de solo lectura. Este es un calificador de tipo, no una constante manifiesta. + +```zc +fn print_val(v: const int) { + // v = 10; // Error: No se puede asignar a una variable const + println "{v}"; +} +``` + +#### Argumentos por Defecto +Las funciones pueden definir valores por defecto para los argumentos finales. Estos pueden ser literales, expresiones o código válido de Zen C (como constructores de structs). +```zc +// Valor por defecto simple +fn incrementar(val: int, cantidad: int = 1) -> int { + return val + cantidad; +} + +// Valor por defecto por expresión (evaluado en el sitio de la llamada) +fn offset(val: int, pad: int = 10 * 2) -> int { + return val + pad; +} + +// Valor por defecto de tipo struct +struct Config { debug: bool; } +fn init(cfg: Config = Config { debug: true }) { + if cfg.debug { println "Modo Debug"; } +} + +fn main() { + incrementar(10); // 11 + offset(5); // 25 + init(); // Imprime "Modo Debug" +} +``` + +#### Lambdas (Clausuras) +Funciones anónimas que pueden capturar su entorno. +```zc +let factor = 2; +let doble = x -> x * factor; // Sintaxis de flecha +let completo = fn(x: int) -> int { return x * factor; }; // Sintaxis de bloque +``` + +#### Punteros a Funciones Crudos +Zen C soporta punteros a funciones de C crudos usando la sintaxis `fn*`. Esto permite una interoperabilidad perfecta con bibliotecas de C que esperan punteros a funciones sin la sobrecarga de las clausuras. + +```zc +// Función que recibe un puntero a función crudo +fn set_callback(cb: fn*(int)) { + cb(42); +} + +// Función que retorna un puntero a función crudo +fn get_callback() -> fn*(int) { + return mi_manejador; +} + +// Se soportan punteros a punteros de funciones (fn**) +let pptr: fn**(int) = &ptr; +``` + +#### Funciones Variádicas +Las funciones pueden aceptar un número variable de argumentos usando `...` y el tipo `va_list`. +```zc +fn log(lvl: int, fmt: char*, ...) { + let ap: va_list; + va_start(ap, fmt); + vprintf(fmt, ap); // Usa stdio de C + va_end(ap); +} +``` + +### 5. Flujo de Control + +#### Condicionales +```zc +if x > 10 { + print("Grande"); +} else if x > 5 { + print("Mediano"); +} else { + print("Pequeño"); +} + +// Ternario +let y = x > 10 ? 1 : 0; +``` + +#### Coincidencia de Patrones (Pattern Matching) +Una alternativa potente al `switch`. +```zc +match val { + 1 => { print "Uno" }, + 2 || 3 => { print "Dos o Tres" }, // OR con || + 4 or 5 => { print "Cuatro o Cinco" }, // OR con 'or' + 6, 7, 8 => { print "Seis a Ocho" }, // OR con coma + 10 .. 15 => { print "10 a 14" }, // Rango exclusivo (Legado) + 10 ..< 15 => { print "10 a 14" }, // Rango exclusivo (Explícito) + 20 ..= 25 => { print "20 a 25" }, // Rango inclusivo + _ => { print "Otro" }, +} + +// Desestructuración de Enums +match shape { + Shape::Circle(r) => println "Radio: {r}", + Shape::Rect(w, h) => println "Área: {w*h}", + Shape::Point => println "Punto" +} +``` + +#### Vinculación por Referencia (Reference Binding) +Para inspeccionar un valor sin tomar posesión de él (sin moverlo), usa la palabra clave `ref` en el patrón. Esto es esencial para tipos que implementan la Semántica de Movimiento (como `Option`, `Result`, structs que no son Copy). + +```zc +let opt = Some(ValorNoCopy{...}); +match opt { + Some(ref x) => { + // 'x' es un puntero al valor dentro de 'opt' + // 'opt' NO se mueve ni se consume aquí + println "{x.field}"; + }, + None => {} +} +``` + +#### Bucles +```zc +// Rango +for i in 0..10 { ... } // Exclusivo (0 al 9) +for i in 0..<10 { ... } // Exclusivo (Explícito) +for i in 0..=10 { ... } // Inclusivo (0 al 10) +for i in 0..10 step 2 { ... } + +// Iterador (Vec, Array, o Iterable personalizado) +for item in coleccion { ... } + +// While +while x < 10 { ... } + +// Infinito con etiqueta +externo: loop { + if terminado { break externo; } +} + +// Repetir N veces +for _ in 0..5 { ... } +``` + +#### Control Avanzado +```zc +// Guard: Ejecuta else y retorna si la condición es falsa +guard ptr != NULL else { return; } + +// Unless: Si no es verdadero +unless es_valido { return; } +``` + +### 6. Operadores + +Zen C soporta la sobrecarga de operadores para structs definidos por el usuario implementando nombres de métodos específicos. + +#### Operadores Sobrecargables + +| Categoría | Operador | Nombre del Método | +|:---|:---|:---| +| **Aritméticos** | `+`, `-`, `*`, `/`, `%` | `add`, `sub`, `mul`, `div`, `rem` | +| **Comparación** | `==`, `!=` | `eq`, `neq` | +| | `<`, `>`, `<=`, `>=` | `lt`, `gt`, `le`, `ge` | +| **Bitwise** | `&`, `|`, `^` | `bitand`, `bitor`, `bitxor` | +| | `<<`, `>>` | `shl`, `shr` | +| **Unarios** | `-` | `neg` | +| | `!` | `not` | +| | `~` | `bitnot` | +| **Índice** | `a[i]` | `get(a, i)` | +| | `a[i] = v` | `set(a, i, v)` | + +> **Nota sobre la igualdad de cadenas**: +> - `string == string` realiza una **comparación de valores** (equivalente a `strcmp`). +> - `char* == char*` realiza una **comparación de punteros** (comprueba direcciones de memoria). +> - Comparaciones mixtas (ej. `string == char*`) por defecto realizan una **comparación de punteros**. + +**Ejemplo:** +```zc +impl Point { + fn add(self, other: Point) -> Point { + return Point{x: self.x + other.x, y: self.y + other.y}; + } +} + +let p3 = p1 + p2; // Llama a p1.add(p2) +``` + +#### Azúcar Sintáctico + +Estos operadores son características integradas del lenguaje y no pueden sobrecargarse directamente. + +| Operador | Nombre | Descripción | +|:---|:---|:---| +| `|>` | Pipeline | `x |> f(y)` se desazucara a `f(x, y)` | +| `??` | Null Coalescing | `val ?? default` retorna `default` si `val` es NULL (punteros) | +| `??=` | Null Assignment | `val ??= init` asigna si `val` es NULL | +| `?.` | Navegación Segura | `ptr?.campo` accede al campo solo si `ptr` no es NULL | +| `?` | Operador Try | `res?` retorna el error si está presente (tipos Result/Option) | + +**Auto-Dereferencia**: +El acceso a campos por puntero (`ptr.campo`) y las llamadas a métodos (`ptr.metodo()`) dereferencian automáticamente el puntero, equivalente a `(*ptr).campo`. + +### 7. Impresión e Interpolación de Cadenas + +Zen C proporciona opciones versátiles para imprimir en la consola, incluyendo palabras clave y abreviaturas concisas. + +#### Palabras Clave + +- `print "texto"`: Imprime en `stdout` sin un salto de línea al final. +- `println "texto"`: Imprime en `stdout` con un salto de línea al final. +- `eprint "texto"`: Imprime en `stderr` sin un salto de línea al final. +- `eprintln "texto"`: Imprime en `stderr` con un salto de línea al final. + +#### Abreviaturas + +Zen C permite usar literales de cadena directamente como sentencias para una impresión rápida: + +- `"Hola Mundo"`: Equivalente a `println "Hola Mundo"`. (Añade salto de línea implícito) +- `"Hola Mundo"..`: Equivalente a `print "Hola Mundo"`. (Sin salto de línea final) +- `!"Error"`: Equivalente a `eprintln "Error"`. (Salida a stderr) +- `!"Error"..`: Equivalente a `eprint "Error"`. (Salida a stderr, sin salto de línea) + +#### Interpolación de Cadenas (F-strings) + +Puedes embeber expresiones directamente dentro de literales de cadena usando la sintaxis `{}`. Esto funciona con todos los métodos de impresión y abreviaturas de cadena. + +```zc +let x = 42; +let nombre = "Zen"; +println "Valor: {x}, Nombre: {nombre}"; +"Valor: {x}, Nombre: {nombre}"; // abreviatura println +``` + +#### Prompts de Entrada (`?`) + +Zen C soporta una abreviatura para solicitar entrada al usuario usando el prefijo `?`. + +- `? "Texto del prompt"`: Imprime el prompt (sin salto de línea) y espera la entrada (lee una línea). +- `? "Ingresa la edad: " (edad)`: Imprime el prompt y escanea la entrada en la variable `edad`. + - Los especificadores de formato se infieren automáticamente según el tipo de variable. + +```c +let edad: int; +? "¿Cuántos años tienes? " (edad); +println "Tienes {edad} años."; +``` + +### 8. Gestión de Memoria + +Zen C permite la gestión manual de memoria con ayudas ergonómicas. + +#### Defer +Ejecuta código cuando el ámbito actual finaliza. Las sentencias defer se ejecutan en orden LIFO (último en entrar, primero en salir). +```zc +let f = fopen("archivo.txt", "r"); +defer fclose(f); +``` + +> Para prevenir comportamientos indefinidos, las sentencias de flujo de control (`return`, `break`, `continue`, `goto`) **no están permitidas** dentro de un bloque `defer`. + +#### Autofree +Libera automáticamente la variable cuando finaliza el ámbito. +```zc +autofree let tipos = malloc(1024); +``` + +#### Semántica de Recursos (Movimiento por Defecto) +Zen C trata los tipos con destructores (como `File`, `Vec` o punteros de malloc) como **Recursos**. Para prevenir errores de doble liberación (double-free), los recursos no pueden duplicarse implícitamente. + +- **Movimiento por Defecto**: La asignación de una variable de recurso transfiere la posesión. La variable original se vuelve inválida (Movida). +- **Tipos Copy**: Los tipos sin destructores pueden optar por el comportamiento `Copy`, haciendo que la asignación sea una duplicación. + +**Diagnóstico y Filosofía**: +Si ves un error "Use of moved value", el compilador te está diciendo: *"Este tipo posee un recurso (como memoria o un manejador) y copiarlo a ciegas es inseguro."* + +> **Contraste:** A diferencia de C/C++, Zen C no duplica implícitamente los valores que poseen recursos. + +**Argumentos de Función**: +Pasar un valor a una función sigue las mismas reglas que la asignación: los recursos se mueven a menos que se pasen por referencia. + +```zc +fn procesar(r: Recurso) { ... } // 'r' se mueve dentro de la función +fn mirar(r: Recurso*) { ... } // 'r' es prestado (referencia) +``` + +**Clonación Explícita**: +Si *realmente* quieres dos copias de un recurso, hazlo explícito: + +```zc +let b = a.clone(); // Llama al método 'clone' del trait Clone +``` + +**Optar por Copy (Tipos de Valor)**: +Para tipos pequeños sin destructores: + +```zc +struct Point { x: int; y: int; } +impl Copy for Point {} // Optar por la duplicación implícita + +fn main() { + let p1 = Point { x: 1, y: 2 }; + let p2 = p1; // Copiado. p1 sigue siendo válido. +} +``` + +#### RAII / Drop Trait +Implementa `Drop` para ejecutar lógica de limpieza automáticamente. +```zc +impl Drop for MiEstructura { + fn drop(self) { + self.free(); + } +} +``` + +### 9. Programación Orientada a Objetos + +#### Métodos +Define métodos en los tipos usando `impl`. +```zc +impl Point { + // Método estático (convención de constructor) + fn new(x: int, y: int) -> Self { + return Point{x: x, y: y}; + } + + // Método de instancia + fn dist(self) -> float { + return sqrt(self.x * self.x + self.y * self.y); + } +} +``` + +#### Traits +Define un comportamiento compartido. +```zc +struct Circle { radio: f32; } + +trait Dibujable { + fn dibujar(self); +} + +impl Dibujable for Circle { + fn dibujar(self) { ... } +} + +let circulo = Circle{}; +let dibujable: Dibujable = &circulo; +``` + +#### Traits Estándar +Zen C incluye traits estándar que se integran con la sintaxis del lenguaje. + +**Iterable** + +Implementa `Iterable<T>` para habilitar bucles `for-in` para tus tipos personalizados. + +```zc +import "std/iter.zc" + +// Define un Iterador +struct MiIter { + actual: int; + final: int; +} + +impl MiIter { + fn next(self) -> Option<int> { + if self.actual < self.final { + self.actual += 1; + return Option<int>::Some(self.actual - 1); + } + return Option<int>::None(); + } +} + +// Implementa Iterable +impl MiRango { + fn iterator(self) -> MiIter { + return MiIter{actual: self.inicio, final: self.fin}; + } +} + +// Uso en un Bucle +for i in mi_rango { + println "{i}"; +} +``` + +**Drop** + +Implementa `Drop` para definir un destructor que se ejecuta cuando el objeto sale de ámbito (RAII). + +```zc +import "std/mem.zc" + +struct Recurso { + ptr: void*; +} + +impl Drop for Recurso { + fn drop(self) { + if self.ptr != NULL { + free(self.ptr); + } + } +} +``` + +> **Nota:** Si una variable es movida, no se llama a `drop` en la variable original. Se adhiere a la [Semántica de Recursos](#semántica-de-recursos-movimiento-por-defecto). + +**Copy** + +Trait marcador para optar por el comportamiento `Copy` (duplicación implícita) en lugar de la semántica de movimiento. Se usa mediante `@derive(Copy)`. + +> **Regla:** Los tipos que implementan `Copy` no deben definir un destructor (`Drop`). + +```zc +@derive(Copy) +struct Point { x: int; y: int; } + +fn main() { + let p1 = Point{x: 1, y: 2}; + let p2 = p1; // ¡Copiado! p1 sigue siendo válido. +} +``` + +**Clone** + +Implementa `Clone` para permitir la duplicación explícita de tipos que poseen recursos. + +```zc +import "std/mem.zc" + +struct MiBox { val: int; } + +impl Clone for MiBox { + fn clone(self) -> MiBox { + return MiBox{val: self.val}; + } +} + +fn main() { + let b1 = MiBox{val: 42}; + let b2 = b1.clone(); // Copia explícita +} +``` + +#### Composición +Usa `use` para embeber otros structs. Puedes mezclarlos (aplanar campos) o nombrarlos (anidar campos). + +```zc +struct Entity { id: int; } + +struct Player { + // Mezcla (Mixin - Sin nombre): Aplana los campos + use Entity; // Añade 'id' a Player directamente + nombre: string; +} + +struct Match { + // Composición (Con nombre): Anida los campos + use p1: Player; // Accedido mediante match.p1 + use p2: Player; // Accedido mediante match.p2 +} +``` + +### 10. Genéricos + +Plantillas seguras para tipos para Structs y Funciones. + +```zc +// Struct Genérico +struct Box<T> { + item: T; +} + +// Función Genérica +fn identidad<T>(val: T) -> T { + return val; +} + +// Genéricos con múltiples parámetros +struct Par<K, V> { + llave: K; + valor: V; +} +``` + +### 11. Concurrencia (Async/Await) + +Construido sobre pthreads. + +```zc +async fn obtener_datos() -> string { + // Se ejecuta en segundo plano + return "Datos"; +} + +fn main() { + let futuro = obtener_datos(); + let resultado = await futuro; +} +``` + +### 12. Metaprogramación + +#### Comptime +Ejecuta código en tiempo de compilación para generar código fuente o imprimir mensajes. +```zc +comptime { + // Genera código en tiempo de compilación (escrito en stdout) + println "let fecha_compilacion = \"2024-01-01\";"; +} + +println "Fecha de compilación: {fecha_compilacion}"; +``` + +#### Embed +Embebe archivos como los tipos especificados. +```zc +// Por defecto (Slice_char) +let datos = embed "assets/logo.png"; + +// Embed tipado +let texto = embed "shader.glsl" as string; // Embebe como C-string +let rom = embed "bios.bin" as u8[1024]; // Embebe como array fijo +let wav = embed "sound.wav" as u8[]; // Embebe como Slice_u8 +``` + +#### Plugins +Importa plugins del compilador para extender la sintaxis. +```zc +import plugin "regex" +let re = regex! { ^[a-z]+$ }; +``` + +#### Macros de C Genéricas +Pasa macros del preprocesador directamente a C. + +> **Consejo**: Para constantes simples, usa `def` en su lugar. Usa `#define` cuando necesites macros del preprocesador de C o flags de compilación condicional. + +```zc +#define MAX_BUFFER 1024 +``` + +### 13. Atributos + +Decora funciones y structs para modificar el comportamiento del compilador. + +| Atributo | Ámbito | Descripción | +|:---|:---|:---| +| `@must_use` | Fn | Advierte si el valor de retorno es ignorado. | +| `@deprecated("msg")` | Fn/Struct | Advierte sobre el uso con un mensaje. | +| `@inline` | Fn | Sugiere al compilador hacer inlininig. | +| `@noinline` | Fn | Previene el inlining. | +| `@packed` | Struct | Elimina el padding entre campos. | +| `@align(N)` | Struct | Fuerza el alineamiento a N bytes. | +| `@constructor` | Fn | Se ejecuta antes de main. | +| `@destructor` | Fn | Se ejecuta después de que main termine. | +| `@unused` | Fn/Var | Suprime advertencias de variables no usadas. | +| `@weak` | Fn | Enlace de símbolo débil (weak symbol linkage). | +| `@section("nombre")` | Fn | Coloca el código en una sección específica. | +| `@noreturn` | Fn | La función no retorna (ej. exit). | +| `@pure` | Fn | La función no tiene efectos secundarios (sugestión de optimización). | +| `@cold` | Fn | Es poco probable que la función se ejecute (sugestión de predicción de saltos). | +| `@hot` | Fn | La función se ejecuta frecuentemente (sugestión de optimización). | +| `@export` | Fn/Struct | Exporta el símbolo (visibilidad por defecto). | +| `@global` | Fn | CUDA: Punto de entrada del kernel (`__global__`). | +| `@device` | Fn | CUDA: Función de dispositivo (`__device__`). | +| `@host` | Fn | CUDA: Función de host (`__host__`). | +| `@comptime` | Fn | Función auxiliar disponible para ejecución en tiempo de compilación. | +| `@derive(...)` | Struct | Implementa traits automáticamente. Soporta `Debug`, `Eq` (Derivación Inteligente), `Copy`, `Clone`. | +| `@<custom>` | Cualquier | Pasa atributos genéricos a C (ej. `@flatten`, `@alias("nombre")`). | + +#### Atributos Personalizados + +Zen C soporta un potente sistema de **Atributos Personalizados** que te permite usar cualquier `__attribute__` de GCC/Clang directamente en tu código. Cualquier atributo que no sea reconocido explícitamente por el compilador de Zen C es tratado como un atributo genérico y se pasa al código C generado. + +Esto proporciona acceso a características avanzadas del compilador, optimizaciones y directivas del enlazador sin necesidad de soporte explícito en el núcleo del lenguaje. + +#### Mapeo de Sintaxis +Los atributos de Zen C se mapean directamente a atributos de C: +- `@nombre` → `__attribute__((nombre))` +- `@nombre(args)` → `__attribute__((nombre(args)))` +- `@nombre("string")` → `__attribute__((nombre("string")))` + +#### Derivaciones Inteligentes + +Zen C proporciona "Derivaciones Inteligentes" que respetan la Semántica de Movimiento: + +- **`@derive(Eq)`**: Genera un método de igualdad que recibe los argumentos por referencia (`fn eq(self, other: T*)`). + - Al comparar dos structs que no son Copy (`a == b`), el compilador pasa automáticamente `b` por referencia (`&b`) para evitar moverlo. + - Las comprobaciones de igualdad recursivas en los campos también prefieren el acceso por puntero para prevenir la transferencia de posesión. + +### 14. Ensamblador Inline + +Zen C proporciona soporte de primera clase para ensamblador inline, transpilando directamente a `asm` extendido de estilo GCC. + +#### Uso Básico +Escribe ensamblador crudo dentro de bloques `asm`. Las cadenas se concatenan automáticamente. +```zc +asm { + "nop" + "mfence" +} +``` + +#### Volatile +Previene que el compilador optimice y elimine el ensamblador que tiene efectos secundarios. +```zc +asm volatile { + "rdtsc" +} +``` + +#### Restricciones con Nombre +Zen C simplifica la compleja sintaxis de restricciones de GCC con vinculaciones con nombre. + +```zc +// Sintaxis: : out(variable) : in(variable) : clobber(reg) +// Usa la sintaxis de marcador de posición {variable} para legibilidad + +fn sumar(a: int, b: int) -> int { + let resultado: int; + asm { + "add {resultado}, {a}, {b}" + : out(resultado) + : in(a), in(b) + : clobber("cc") + } + return resultado; +} +``` + +| Tipo | Sintaxis | Equivalente GCC | +|:---|:---|:---| +| **Salida** | `: out(variable)` | `"=r"(variable)` | +| **Entrada** | `: in(variable)` | `"r"(variable)` | +| **Clobber** | `: clobber("rax")` | `"rax"` | +| **Memoria** | `: clobber("memory")` | `"memory"` | + +> **Nota:** Cuando uses la sintaxis de Intel (mediante `-masm=intel`), debes asegurarte de que tu construcción esté configurada correctamente (por ejemplo, `//> cflags: -masm=intel`). TCC no soporta el ensamblador con sintaxis Intel. + +### 15. Directivas de Construcción + +Zen C soporta comentarios especiales en la parte superior de tu archivo fuente para configurar el proceso de construcción sin necesidad de un complejo sistema de construcción o Makefile. + +| Directiva | Argumentos | Descripción | +|:---|:---|:---| +| `//> link:` | `-lfoo` o `ruta/a/lib.a` | Enlaza contra una biblioteca o archivo objeto. | +| `//> lib:` | `ruta/a/libs` | Añade una ruta de búsqueda de biblioteca (`-L`). | +| `//> include:` | `ruta/a/headers` | Añade una ruta de búsqueda de cabeceras (`-I`). | +| `//> framework:` | `Cocoa` | Enlaza contra un framework de macOS. | +| `//> cflags:` | `-Wall -O3` | Pasa flags arbitrarios al compilador de C. | +| `//> define:` | `MACRO` o `LLAVE=VAL` | Define una macro del preprocesador (`-D`). | +| `//> pkg-config:` | `gtk+-3.0` | Ejecuta `pkg-config` y añade `--cflags` y `--libs`. | +| `//> shell:` | `comando` | Ejecuta un comando de shell durante la construcción. | +| `//> get:` | `http://url/archivo` | Descarga un archivo si el archivo específico no existe. | + +#### Características + +**1. Protección de SO (OS Guarding)** +Prefija las directivas con el nombre de un SO para aplicarlas solo en plataformas específicas. +Prefijos soportados: `linux:`, `windows:`, `macos:` (o `darwin:`). + +```zc +//> linux: link: -lm +//> windows: link: -lws2_32 +//> macos: framework: Cocoa +``` + +**2. Expansión de Variables de Entorno** +Usa la sintaxis `${VAR}` para expandir variables de entorno en tus directivas. + +```zc +//> include: ${HOME}/mylib/include +//> lib: ${ZC_ROOT}/std +``` + +#### Ejemplos + +```zc +//> include: ./include +//> lib: ./libs +//> link: -lraylib -lm +//> cflags: -Ofast +//> pkg-config: gtk+-3.0 + +import "raylib.h" + +fn main() { ... } +``` + +### 16. Palabras Clave + +Las siguientes palabras clave están reservadas en Zen C. + +#### Declaraciones +`alias`, `def`, `enum`, `fn`, `impl`, `import`, `let`, `module`, `opaque`, `struct`, `trait`, `union`, `use` + +#### Flujo de Control +`async`, `await`, `break`, `catch`, `continue`, `defer`, `else`, `for`, `goto`, `guard`, `if`, `loop`, `match`, `return`, `try`, `unless`, `while` + +#### Especiales +`asm`, `assert`, `autofree`, `comptime`, `const`, `embed`, `launch`, `ref`, `sizeof`, `static`, `test`, `volatile` + +#### Constantes +`true`, `false`, `null` + +#### Reservadas de C +Los siguientes identificadores están reservados porque son palabras clave en C11: +`auto`, `case`, `char`, `default`, `do`, `double`, `extern`, `float`, `inline`, `int`, `long`, `register`, `restrict`, `short`, `signed`, `switch`, `typedef`, `unsigned`, `void`, `_Atomic`, `_Bool`, `_Complex`, `_Generic`, `_Imaginary`, `_Noreturn`, `_Static_assert`, `_Thread_local` + +#### Operadores +`and`, `or` + +--- + +## Biblioteca Estándar + +Zen C incluye una biblioteca estándar (`std`) que cubre las funcionalidades esenciales. + +[Explorar la Documentación de la Biblioteca Estándar](docs/std/README.md) + +### Módulos Clave + +| Módulo | Descripción | Docs | +| :--- | :--- | :--- | +| **`std/vec.zc`** | Array dinámico creíble `Vec<T>`. | [Docs](docs/std/vec.md) | +| **`std/string.zc`** | Tipo `String` asignado en el heap con soporte UTF-8. | [Docs](docs/std/string.md) | +| **`std/queue.zc`** | Cola FIFO (Ring Buffer). | [Docs](docs/std/queue.md) | +| **`std/map.zc`** | Mapa Hash Genérico `Map<V>`. | [Docs](docs/std/map.md) | +| **`std/fs.zc`** | Operaciones del sistema de archivos. | [Docs](docs/std/fs.md) | +| **`std/io.zc`** | Entrada/Salida estándar (`print`/`println`). | [Docs](docs/std/io.md) | +| **`std/option.zc`** | Valores opcionales (`Some`/`None`). | [Docs](docs/std/option.md) | +| **`std/result.zc`** | Gestión de errores (`Ok`/`Err`). | [Docs](docs/std/result.md) | +| **`std/path.zc`** | Manipulación de rutas multiplataforma. | [Docs](docs/std/path.md) | +| **`std/env.zc`** | Variables de entorno del proceso. | [Docs](docs/std/env.md) | +| **`std/net.zc`** | Redes TCP (Sockets). | [Docs](docs/std/net.md) | +| **`std/thread.zc`** | Hilos y Sincronización. | [Docs](docs/std/thread.md) | +| **`std/time.zc`** | Medición de tiempo y espera (sleep). | [Docs](docs/std/time.md) | +| **`std/json.zc`** | Parseo y serialización de JSON. | [Docs](docs/std/json.md) | +| **`std/stack.zc`** | Pila LIFO `Stack<T>`. | [Docs](docs/std/stack.md) | +| **`std/set.zc`** | Conjunto Hash Genérico `Set<T>`. | [Docs](docs/std/set.md) | + +--- + +## Herramientas + +Zen C proporciona un Servidor de Lenguaje y un REPL integrados para mejorar la experiencia de desarrollo. + +### Servidor de Lenguaje (LSP) + +El Servidor de Lenguaje de Zen C (LSP) soporta las características estándar de LSP para integración con editores, proporcionando: + +* **Ir a la Definición** +* **Encontrar Referencias** +* **Información al pasar el ratón (Hover)** +* **Autocompletado** (Nombres de funciones/structs, autocompletado tras punto para métodos/campos) +* **Símbolos del Documento** (Esquema) +* **Ayuda de Firma** +* **Diagnósticos** (Errores sintácticos/semánticos) + +Para iniciar el servidor de lenguaje (normalmente configurado en los ajustes de LSP de tu editor): + +```bash +zc lsp +``` + +Se comunica mediante I/O estándar (JSON-RPC 2.0). + +### REPL + +El bucle Read-Eval-Print te permite experimentar con el código de Zen C de forma interactiva. + +```bash +zc repl +``` + +#### Características + +* **Codificación Interactiva**: Escribe expresiones o sentencias para su evaluación inmediata. +* **Historial Persistente**: Los comandos se guardan en `~/.zprep_history`. +* **Script de Inicio**: Carga automáticamente comandos desde `~/.zprep_init.zc`. + +#### Comandos + +| Comando | Descripción | +|:---|:---| +| `:help` | Muestra los comandos disponibles. | +| `:reset` | Limpia el historial de la sesión actual (variables/funciones). | +| `:vars` | Muestra las variables activas. | +| `:funcs` | Muestra las funciones definidas por el usuario. | +| `:structs` | Muestra los structs definidos por el usuario. | +| `:imports` | Muestra las importaciones activas. | +| `:history` | Muestra el historial de entrada de la sesión. | +| `:type <expr>` | Muestra el tipo de una expresión. | +| `:c <stmt>` | Muestra el código C generado para una sentencia. | +| `:time <expr>` | Benchmark de una expresión (ejecuta 1000 iteraciones). | +| `:edit [n]` | Edita el comando `n` (por defecto: el último) en `$EDITOR`. | +| `:save <file>` | Guarda la sesión actual en un archivo `.zc`. | +| `:load <file>` | Carga y ejecuta un archivo `.zc` en la sesión. | +| `:watch <expr>` | Observa una expresión (se revalúa tras cada entrada). | +| `:unwatch <n>` | Elimina una observación. | +| `:undo` | Elimina el último comando de la sesión. | +| `:delete <n>` | Elimina el comando en el índice `n`. | +| `:clear` | Limpia la pantalla. | +| `:quit` | Sale del REPL. | +| `! <cmd>` | Ejecuta un comando de shell (ej. `!ls`). | + +--- + + +## Soporte del Compilador y Compatibilidad + +Zen C está diseñado para funcionar con la mayoría de los compiladores C11. Algunas características dependen de extensiones de GNU C, pero estas suelen funcionar en otros compiladores. Usa la flag `--cc` para cambiar de backend. + +```bash +zc run app.zc --cc clang +zc run app.zc --cc zig +``` + +### Estado de la Suite de Pruebas + +| Compilador | Tasa de Acierto | Características Soportadas | Limitaciones Conocidas | +|:---|:---:|:---|:---| +| **GCC** | **100%** | Todas las Características | Ninguna. | +| **Clang** | **100%** | Todas las Características | Ninguna. | +| **Zig** | **100%** | Todas las Características | Ninguna. Usa `zig cc` como reemplazo directo del compilador C. | +| **TCC** | **~70%** | Sintaxis Básica, Genéricos, Traits | Sin `__auto_type`, Sin ASM Intel, Sin funciones anidadas. | + +> **Recomendación:** Usa **GCC**, **Clang** o **Zig** para construcciones de producción. TCC es excelente para el prototipado rápido debido a su velocidad de compilación, pero le faltan algunas extensiones de C avanzadas en las que confía Zen C para el soporte total de características. + +### Construyendo con Zig + +El comando `zig cc` de Zig proporciona un reemplazo directo para GCC/Clang con un excelente soporte de compilación cruzada (cross-compilation). Para usar Zig: + +```bash +# Compilar y ejecutar un programa Zen C con Zig +zc run app.zc --cc zig + +# Construir el propio compilador Zen C con Zig +make zig +``` + +### Interop con C++ + +Zen C puede generar código compatible con C++ con la flag `--cpp`, permitiendo una integración perfecta con bibliotecas de C++. + +```bash +# Compilación directa con g++ +zc app.zc --cpp + +# O transpilar para construcción manual +zc transpile app.zc --cpp +g++ out.c mi_lib_cpp.o -o app +``` + +#### Usando C++ en Zen C + +Incluye cabeceras de C++ y usa bloques `raw` para el código C++: + +```zc +include <vector> +include <iostream> + +raw { + std::vector<int> hacer_vec(int a, int b) { + return {a, b}; + } +} + +fn main() { + let v = hacer_vec(1, 2); + raw { std::cout << "Tamaño: " << v.size() << std::endl; } +} +``` + +> **Nota:** La flag `--cpp` cambia el backend a `g++` y emite código compatible con C++ (usa `auto` en lugar de `__auto_type`, sobrecarga de funciones en lugar de `_Generic`, y casts explícitos para `void*`). + +#### Interop con CUDA + +Zen C soporta la programación de GPU transpilando a **CUDA C++**. Esto te permite aprovechar las potentes características de C++ (plantillas, constexpr) dentro de tus kernels mientras mantienes la sintaxis ergonómica de Zen C. + +```bash +# Compilación directa con nvcc +zc run app.zc --cuda + +# O transpilar para construcción manual +zc transpile app.zc --cuda -o app.cu +nvcc app.cu -o app +``` + +#### Atributos Específicos de CUDA + +| Atributo | Equivalente CUDA | Descripción | +|:---|:---|:---| +| `@global` | `__global__` | Función de kernel (se ejecuta en GPU, se llama desde el host) | +| `@device` | `__device__` | Función de dispositivo (se ejecuta en GPU, se llama desde GPU) | +| `@host` | `__host__` | Función de host (explícitamente solo CPU) | + +#### Sintaxis de Lanzamiento de Kernel + +Zen C proporciona una sentencia `launch` limpia para invocar kernels de CUDA: + +```zc +launch nombre_del_kernel(args) with { + grid: num_bloques, + block: hilos_por_bloque, + shared_mem: 1024, // Opcional + stream: mi_stream // Opcional +}; +``` + +Esto se transpila a: `nombre_del_kernel<<<grid, bloque, compartido, stream>>>(args);` + +#### Escribiendo Kernels de CUDA + +Usa la sintaxis de funciones de Zen C con `@global` y la sentencia `launch`: + +```zc +import "std/cuda.zc" + +@global +fn kernel_suma(a: float*, b: float*, c: float*, n: int) { + let i = thread_id(); + if i < n { + c[i] = a[i] + b[i]; + } +} + +fn main() { + def N = 1024; + let d_a = cuda_alloc<float>(N); + let d_b = cuda_alloc<float>(N); + let d_c = cuda_alloc<float>(N); + defer cuda_free(d_a); + defer cuda_free(d_b); + defer cuda_free(d_c); + + // ... inicialización de datos ... + + launch kernel_suma(d_a, d_b, d_c, N) with { + grid: (N + 255) / 256, + block: 256 + }; + + cuda_sync(); +} +``` + +#### Biblioteca Estándar (`std/cuda.zc`) +Zen C proporciona una biblioteca estándar para operaciones comunes de CUDA para reducir los bloques `raw`: + +```zc +import "std/cuda.zc" + +// Gestión de memoria +let d_ptr = cuda_alloc<float>(1024); +cuda_copy_to_device(d_ptr, h_ptr, 1024 * sizeof(float)); +defer cuda_free(d_ptr); + +// Sincronización +cuda_sync(); + +// Indexación de hilos (usar dentro de kernels) +let i = thread_id(); // Índice global +let bid = block_id(); +let tid = local_id(); +``` + + +> **Nota:** La flag `--cuda` establece `nvcc` como el compilador e implica el modo `--cpp`. Requiere el NVIDIA CUDA Toolkit. + +### Interop con Objective-C + +Zen C puede compilarse a Objective-C (`.m`) usando la flag `--objc`, permitiéndote usar frameworks de Objective-C (como Cocoa/Foundation) y su sintaxis. + +```bash +# Compilar con clang (o gcc/gnustep) +zc app.zc --objc --cc clang +``` + +#### Usando Objective-C en Zen C + +Usa `include` para las cabeceras y bloques `raw` para la sintaxis de Objective-C (`@interface`, `[...]`, `@""`). + +```zc +//> macos: framework: Foundation +//> linux: cflags: -fconstant-string-class=NSConstantString -D_NATIVE_OBJC_EXCEPTIONS +//> linux: link: -lgnustep-base -lobjc + +include <Foundation/Foundation.h> + +fn main() { + raw { + NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; + NSLog(@"¡Hola desde Objective-C!"); + [pool drain]; + } + println "¡Zen C también funciona!"; +} +``` + +> **Nota:** La interpolación de cadenas de Zen C funciona con objetos de Objective-C (`id`) llamando a `debugDescription` o `description`. + +--- + +## Contribuyendo + +¡Damos la bienvenida a las contribuciones! Ya sea corrigiendo errores, añadiendo documentación o proponiendo nuevas características. + +### Cómo Contribuir +1. **Haz un Fork del Repositorio**: flujo de trabajo estándar de GitHub. +2. **Crea una Rama de Característica**: `git checkout -b feature/NuevaCosa`. +3. **Guías de Código**: + * Sigue el estilo de C existente. + * Asegúrate de que todas las pruebas pasen: `make test`. + * Añade nuevas pruebas para tu característica en `tests/`. +4. **Envía un Pull Request**: Describe tus cambios claramente. + +### Ejecutando Pruebas +La suite de pruebas es tu mejor amiga. + +```bash +# Ejecutar todas las pruebas (GCC) +make test + +# Ejecutar una prueba específica +./zc run tests/test_match.zc + +# Ejecutar con un compilador diferente +./tests/run_tests.sh --cc clang +./tests/run_tests.sh --cc zig +./tests/run_tests.sh --cc tcc +``` + +### Extendiendo el Compilador +* **Parser**: `src/parser/` - Parser de descenso recursivo. +* **Codegen**: `src/codegen/` - Lógica del transpilador (Zen C -> GNU C/C11). +* **Biblioteca Estándar**: `std/` - Escrita en el propio Zen C. + +--- + +## Atribuciones + +Este proyecto utiliza bibliotecas de terceros. Los textos completos de las licencias pueden encontrarse en el directorio `LICENSES/`. + +* **[cJSON](https://github.com/DaveGamble/cJSON)** (Licencia MIT): Usado para el parseo y generación de JSON en el Servidor de Lenguaje. +* **[zc-ape](https://github.com/OEvgeny/zc-ape)** (Licencia MIT): El port original de Ejecutable Realmente Portable de Zen-C por [Eugene Olonov](https://github.com/OEvgeny). +* **[Cosmopolitan Libc](https://github.com/jart/cosmopolitan)** (Licencia ISC): La biblioteca fundamental que hace posible APE. diff --git a/README_ZH_CN.md b/README_ZH_CN.md new file mode 100644 index 0000000..52acb04 --- /dev/null +++ b/README_ZH_CN.md @@ -0,0 +1,1415 @@ + +<div align="center"> + +[English](README.md) • [简体中文](README_ZH_CN.md) • [繁體中文](README_ZH_TW.md) • [Español](README_ES.md) + +</div> + +<div align="center"> + +# Zen C + +**现代开发体验。零开销。纯净 C。** + +[]() +[]() +[]() +[]() + +*像高级语言一样编写，像 C 一样运行。* + +</div> + +--- + +## 概述 + +**Zen C** 是一种现代系统编程语言，可编译为人类可读的 `GNU C`/`C11`。它提供了一套丰富的特性，包括类型推断、模式匹配、泛型、Trait、async/await 以及具有 RAII 能力的手动内存管理，同时保持 100% 的 C ABI 兼容性。 + +## 社区 + +加入官方 Zen C Discord 服务器，参与讨论、展示 Demo、提问或报告 Bug！ + +- Discord: [点击加入](https://discord.com/invite/q6wEsCmkJP) + +--- + +## 目录 + +- [概述](#概述) +- [社区](#社区) +- [快速入门](#快速入门) + - [安装](#安装) + - [用法](#用法) + - [环境变量](#环境变量) +- [语言参考](#语言参考) + - [1. 变量与常量](#1-变量与常量) + - [2. 原始类型](#2-原始类型) + - [3. 复合类型](#3-复合类型) + - [数组](#数组) + - [元组](#元组) + - [结构体](#结构体) + - [不透明结构体](#不透明结构体) + - [枚举](#枚举) + - [联合体](#联合体) + - [类型别名](#类型别名) + - [不透明类型别名](#不透明类型别名) + - [4. 函数与 Lambda](#4-函数与-lambda) + - [函数](#函数) + - [常量参数](#常量参数) + - [默认参数](#默认参数) + - [Lambda (闭包)](#lambda-闭包) + - [原始函数指针](#原始函数指针) + - [变参函数](#变参函数) + - [5. 控制流](#5-控制流) + - [条件语句](#条件语句) + - [模式匹配](#模式匹配) + - [循环](#循环) + - [高级控制](#高级控制) + - [6. 运算符](#6-运算符) + - [可重载运算符](#可重载运算符) + - [语法糖](#语法糖) + - [7. 打印与字符串插值](#7-打印与字符串插值) + - [关键字](#关键字) + - [简写形式](#简写形式) + - [字符串插值 (F-strings)](#字符串插值-f-strings) + - [输入提示 (`?`)](#输入提示-) + - [8. 内存管理](#8-内存管理) + - [Defer](#defer) + - [Autofree](#autofree) + - [资源语义 (默认移动)](#资源语义-默认移动) + - [RAII / Drop Trait](#raii--drop-trait) + - [9. 面向对象编程](#9-面向对象编程) + - [方法](#方法) + - [Trait](#trait) + - [标准 Trait](#标准-trait) + - [组合](#组合) + - [10. 泛型](#10-泛型) + - [11. 并发 (Async/Await)](#11-并发-asyncawait) + - [12. 元编程](#12-元编程) + - [Comptime](#comptime) + - [Embed](#embed) + - [插件](#插件) + - [泛型 C 宏](#泛型-c-宏) + - [13. 属性](#13-属性) + - [自定义属性](#自定义属性) + - [智能派生](#智能派生) + - [14. 内联汇编](#14-内联汇编) + - [基本用法](#基本用法) + - [Volatile](#volatile) + - [命名约束](#命名约束) + - [15. 构建指令](#15-构建指令) + - [16. 关键字](#16-关键字) +- [标准库](#标准库) +- [工具链](#工具链) + - [语言服务器 (LSP)](#语言服务器-lsp) + - [REPL](#repl) +- [编译器支持与兼容性](#编译器支持与兼容性) + - [测试套件状态](#测试套件状态) + - [使用 Zig 构建](#使用-zig-构建) + - [C++ 互操作](#c-互操作) + - [CUDA 互操作](#cuda-互操作) + - [Objective-C 互操作](#objective-c-互操作) +- [贡献](#贡献) +- [致谢与归属](#致谢与归属) + +--- + +## 快速入门 + +### 安装 + +```bash +git clone https://github.com/z-libs/Zen-C.git +cd Zen-C +make +sudo make install +``` + +### 便携式构建 (APE) + +Zen C 可以通过 [Cosmopolitan Libc](https://github.com/jart/cosmopolitan) 编译为 **Actually Portable Executable (APE)**。这将生成一个单个的可执行文件 (`.com`)，能够原生运行在 Linux, macOS, Windows, FreeBSD, OpenBSD, 和 NetBSD 上的 x86_64 和 aarch64 架构上。 + +**前提条件：** +- `cosmocc` 工具链（必须在 PATH 中） + +**构建与安装：** +```bash +make ape +sudo env "PATH=$PATH" make install-ape +``` + +**产物：** +- `out/bin/zc.com`: 便携式 Zen-C 编译器。已将标准库嵌入到可执行文件中。 +- `out/bin/zc-boot.com`: 一个自包含的引导安装程序，用于设置新的 Zen-C 项目。 + +**用法：** +```bash +# 在任何支持的操作系统上运行 +./out/bin/zc.com build hello.zc -o hello +``` + +### 用法 + +```bash +# 编译并运行 +zc run hello.zc + +# 构建可执行文件 +zc build hello.zc -o hello + +# 交互式 Shell +zc repl +``` + +### 环境变量 + +你可以设置 `ZC_ROOT` 来指定标准库的位置（标准导入如 `import "std/vector.zc"`）。这允许你从任何目录运行 `zc`。 + +```bash +export ZC_ROOT=/path/to/Zen-C +``` + +--- + +## 语言参考 + +### 1. 变量与常量 + +Zen C 区分编译时常量和运行时变量。 + +#### 清单常量 (`def`) +仅在编译时存在的值（折叠到代码中）。用于数组大小、固定配置和魔术数字。 + +```zc +def MAX_SIZE = 1024; +let buffer: char[MAX_SIZE]; // 有效的数组大小 +``` + +#### 变量 (`let`) +内存中的存储位置。可以是可变的或只读的 (`const`)。 + +```zc +let x = 10; // 可变 +x = 20; // 允许 + +let y: const int = 10; // 只读 (类型修饰) +// y = 20; // 错误：无法赋值给 const 变量 +``` + +### 2. 原始类型 + +| 类型 | C 等效类型 | 描述 | +|:---|:---|:---| +| `int`, `uint` | `int`, `unsigned int` | 平台标准整数 | +| `I8` .. `I128` 或 `i8` .. `i128` | `int8_t` .. `__int128_t` | 有符号固定宽度整数 | +| `U8` .. `U128` 或 `u8` .. `u128` | `uint8_t` .. `__uint128_t` | 无符号固定宽度整数 | +| `isize`, `usize` | `ptrdiff_t`, `size_t` | 指针大小的整数 | +| `byte` | `uint8_t` | U8 的别名 | +| `F32`, `F64` 或 `f32`, `f64` | `float`, `double` | 浮点数 | +| `bool` | `bool` | `true` 或 `false` | +| `char` | `char` | 单个字符 | +| `string` | `char*` | C-string (以 null 结尾) | +| `U0`, `u0`, `void` | `void` | 空类型 | + +### 3. 复合类型 + +#### 数组 +具有值语义的固定大小数组。 +```zc +def SIZE = 5; +let ints: int[SIZE] = [1, 2, 3, 4, 5]; +let zeros: [int; SIZE]; // 零初始化的 +``` + +#### 元组 +将多个值组合在一起，通过索引访问元素。 +```zc +let pair = (1, "Hello"); +let x = pair.0; // 1 +let s = pair.1; // "Hello" +``` + +**多个返回值** + +函数可以返回元组以提供多个结果： +```zc +fn add_and_subtract(a: int, b: int) -> (int, int) { + return (a + b, a - b); +} + +let result = add_and_subtract(3, 2); +let sum = result.0; // 5 +let diff = result.1; // 1 +``` + +**解构** + +元组可以直接解构为多个变量： +```zc +let (sum, diff) = add_and_subtract(3, 2); +// sum = 5, diff = 1 +``` + +#### 结构体 +带有可选位域的数据结构。 +```zc +struct Point { + x: int; + y: int; +} + +// 结构体初始化 +let p = Point { x: 10, y: 20 }; + +// 位域 +struct Flags { + valid: U8 : 1; + mode: U8 : 3; +} +``` + +> **注意**：结构体默认使用 [移动语义](#资源语义-默认移动)。即使是指针，也可以通过 `.` 访问字段（自动解引用）。 + +#### 不透明结构体 +你可以将结构体定义为 `opaque`，以将对其字段的访问限制在定义该结构体的模块内部，同时仍允许在栈上分配该结构体（大小已知）。 + +```zc +// 在 user.zc 中 +opaque struct User { + id: int; + name: string; +} + +fn new_user(name: string) -> User { + return User{id: 1, name: name}; // 允许：在模块内部 +} + +// 在 main.zc 中 +import "user.zc"; + +fn main() { + let u = new_user("Alice"); + // let id = u.id; // 错误：无法访问私有字段 'id' +} +``` + +#### 枚举 +能够持有数据的标签联合 (Sum types)。 +```zc +enum Shape { + Circle(float), // 持有半径 + Rect(float, float), // 持有宽、高 + Point // 不带数据 +} +``` + +#### 联合体 +标准 C 联合体（不安全访问）。 +```zc +union Data { + i: int; + f: float; +} +``` + +#### 类型别名 +为现有类型创建新名称。 +```zc +alias ID = int; +alias PointMap = Map<string, Point>; +``` + +#### 不透明类型别名 +你可以将类型别名定义为 `opaque`，从而在定义模块之外创建一个与基础类型不同的新类型。这提供了强大的封装和类型安全性，而没有包装结构体的运行时开销。 + +```zc +// 在 library.zc 中 +opaque alias Handle = int; + +fn make_handle(v: int) -> Handle { + return v; // 允许在模块内部进行隐式转换 +} + +// 在 main.zc 中 +import "library.zc"; + +fn main() { + let h: Handle = make_handle(42); + // let i: int = h; // 错误：类型验证失败 + // let h2: Handle = 10; // 错误：类型验证失败 +} +``` + +### 4. 函数与 Lambda + +#### 函数 +```zc +fn add(a: int, b: int) -> int { + return a + b; +} + +// 调用时支持命名参数 +add(a: 10, b: 20); +``` + +> **注意**：命名参数必须严格遵循定义的参数顺序。`add(b: 20, a: 10)` 是无效的。 + +#### 常量参数 +函数参数可以标记为 `const` 以强制执行只读语义。这是一个类型修饰符，而不是清单常量。 + +```zc +fn print_val(v: const int) { + // v = 10; // 错误：无法赋值给 const 变量 + println "{v}"; +} +``` + +#### 默认参数 +函数可以为尾部参数定义默认值。这些值可以是字面量、表达式或有效的 Zen C 代码（如结构体构造函数）。 +```zc +// 简单默认值 +fn increment(val: int, amount: int = 1) -> int { + return val + amount; +} + +// 表达式默认值（在调用处计算） +fn offset(val: int, pad: int = 10 * 2) -> int { + return val + pad; +} + +// 结构体默认值 +struct Config { debug: bool; } +fn init(cfg: Config = Config { debug: true }) { + if cfg.debug { println "调试模式"; } +} + +fn main() { + increment(10); // 11 + offset(5); // 25 + init(); // 打印 "调试模式" +} +``` + +#### Lambda (闭包) +可以捕获环境的匿名函数。 +```zc +let factor = 2; +let double = x -> x * factor; // 箭头语法 +let full = fn(x: int) -> int { return x * factor; }; // 块语法 +``` + +#### 原始函数指针 +Zen C 使用 `fn*` 语法支持原始 C 函数指针。这允许与期望函数指针且没有闭包开销的 C 库进行无缝互操作。 + +```zc +// 接受原始函数指针的函数 +fn set_callback(cb: fn*(int)) { + cb(42); +} + +// 返回原始函数指针的函数 +fn get_callback() -> fn*(int) { + return my_handler; +} + +// 支持指向函数指针的指针 (fn**) +let pptr: fn**(int) = &ptr; +``` + +#### 变参函数 +函数可以使用 `...` 和 `va_list` 类型接受可变数量的参数。 +```zc +fn log(lvl: int, fmt: char*, ...) { + let ap: va_list; + va_start(ap, fmt); + vprintf(fmt, ap); // 使用 C stdio + va_end(ap); +} +``` + +### 5. 控制流 + +#### 条件语句 +```zc +if x > 10 { + print("Large"); +} else if x > 5 { + print("Medium"); +} else { + print("Small"); +} + +// 三元运算符 +let y = x > 10 ? 1 : 0; +``` + +#### 模式匹配 +`switch` 的强大替代方案。 +```zc +match val { + 1 => { print "One" }, + 2 || 3 => { print "Two or Three" }, // 使用 || 进行 或 操作 + 4 or 5 => { print "Four or Five" }, // 使用 'or' 进行 或 操作 + 6, 7, 8 => { print "Six to Eight" }, // 使用逗号进行 或 操作 + 10 .. 15 => { print "10 to 14" }, // 左闭右开区间 (旧语法) + 10 ..< 15 => { print "10 to 14" }, // 左闭右开区间 (显式) + 20 ..= 25 => { print "20 to 25" }, // 全闭区间 + _ => { print "Other" }, +} + +// 解构枚举 +match shape { + Shape::Circle(r) => println "半径: {r}", + Shape::Rect(w, h) => println "面积: {w*h}", + Shape::Point => println "点" +} +``` + +#### 引用绑定 +为了在不获取所有权（移动）的情况下检查一个值，在模式中使用 `ref` 关键字。这对于实现了移动语义的类型（如 `Option`, `Result`, 非 Copy 结构体）至关重要。 + +```zc +let opt = Some(NonCopyVal{...}); +match opt { + Some(ref x) => { + // 'x' 是指向 'opt' 内部值的指针 + // 'opt' 在此处不会被移动/消耗 + println "{x.field}"; + }, + None => {} +} +``` + +#### 循环 +```zc +// 区间迭代 +for i in 0..10 { ... } // 左闭右开 (0 到 9) +for i in 0..<10 { ... } // 左闭右开 (显式) +for i in 0..=10 { ... } // 全闭 (0 到 10) +for i in 0..10 step 2 { ... } + +// 迭代器 (Vec, Array, 或自定义 Iterable) +for item in collection { ... } + +// While 循环 +while x < 10 { ... } + +// 带标签的无限循环 +outer: loop { + if done { break outer; } +} + +// 重复 N 次 +for _ in 0..5 { ... } +``` + +#### 高级控制 +```zc +// Guard: 如果条件为假，则执行 else 块并返回 +guard ptr != NULL else { return; } + +// Unless: 除非为真（即如果为假） +unless is_valid { return; } +``` + +### 6. 运算符 + +Zen C 通过实现特定的方法名来支持用户定义结构体的运算符重载。 + +#### 可重载运算符 + +| 类别 | 运算符 | 方法名 | +|:---|:---|:---| +| **算术** | `+`, `-`, `*`, `/`, `%` | `add`, `sub`, `mul`, `div`, `rem` | +| **比较** | `==`, `!=` | `eq`, `neq` | +| | `<`, `>`, `<=`, `>=` | `lt`, `gt`, `le`, `ge` | +| **位运算** | `&`, `|`, `^` | `bitand`, `bitor`, `bitxor` | +| | `<<`, `>>` | `shl`, `shr` | +| **一元** | `-` | `neg` | +| | `!` | `not` | +| | `~` | `bitnot` | +| **索引** | `a[i]` | `get(a, i)` | +| | `a[i] = v` | `set(a, i, v)` | + +> **关于字符串相等性的说明**： +> - `string == string` 进行 **值比较**（等同于 `strcmp`）。 +> - `char* == char*` 进行 **指针比较**（检查内存地址）。 +> - 混合比较（例如 `string == char*`）默认为 **指针比较**。 + +**示例：** +```zc +impl Point { + fn add(self, other: Point) -> Point { + return Point{x: self.x + other.x, y: self.y + other.y}; + } +} + +let p3 = p1 + p2; // 调用 p1.add(p2) +``` + +#### 语法糖 + +这些运算符是内置语言特性，不能直接重载。 + +| 运算符 | 名称 | 描述 | +|:---|:---|:---| +| `|>` | 管道 | `x |> f(y)` 脱糖为 `f(x, y)` | +| `??` | 空合并 | 如果 `val` 为 NULL，`val ?? default` 返回 `default` (用于指针) | +| `??=` | 空赋值 | 如果 `val` 为 NULL 则赋值 | +| `?.` | 安全导航 | 仅当 `ptr` 不为 NULL 时访问字段 | +| `?` | Try 运算符 | 如果存在错误则返回 (用于 Result/Option 类型) | + +**自动解引用**： +指针字段访问 (`ptr.field`) 和方法调用 (`ptr.method()`) 会自动解引用指针，等同于 `(*ptr).field`。 + +### 7. 打印与字符串插值 + +Zen C 提供了多种控制台打印选项，包括关键字和简洁的简写形式。 + +#### 关键字 + +- `print "text"`: 打印到 `stdout`，不带尾随换行符。 +- `println "text"`: 打印到 `stdout`，带尾随换行符。 +- `eprint "text"`: 打印到 `stderr`，不带尾随换行符。 +- `eprintln "text"`: 打印到 `stderr`，带尾随换行符。 + +#### 简写形式 + +Zen C 允许直接将字符串字面量用作语句来进行快速打印： + +- `"Hello World"`: 等同于 `println "Hello World"`。(隐式添加换行符) +- `"Hello World"..`: 等同于 `print "Hello World"`。(不带尾随换行符) +- `!"Error"`: 等同于 `eprintln "Error"`。(输出到 stderr) +- `!"Error"..`: 等同于 `eprint "Error"`。(输出到 stderr，不带换行符) + +#### 字符串插值 (F-strings) + +你可以使用 `{}` 语法将表达式直接嵌入到字符串字面量中。这适用于所有打印方法和字符串简写。 + +```zc +let x = 42; +let name = "Zen"; +println "值: {x}, 名称: {name}"; +"值: {x}, 名称: {name}"; // 简写形式的 println +``` + +#### 输入提示 (`?`) + +Zen C 支持使用 `?` 前缀进行用户输入提示的简写。 + +- `? "提示文本"`: 打印提示信息（不换行）并等待输入（读取一行）。 +- `? "输入年龄: " (age)`: 打印提示并扫描输入到变量 `age` 中。 + - 格式说明符会根据变量类型自动推断。 + +```c +let age: int; +? "你多大了？ " (age); +println "你 {age} 岁了。"; +``` + +### 8. 内存管理 + +Zen C 允许带有符合人体工程学辅助的手动内存管理。 + +#### Defer +在当前作用域退出时执行代码。Defer 语句按照后进先出 (LIFO) 的顺序执行。 +```zc +let f = fopen("file.txt", "r"); +defer fclose(f); +``` + +> 为了防止未定义行为，`defer` 块内不允许使用控制流语句（`return`, `break`, `continue`, `goto`）。 + +#### Autofree +在作用域退出时自动释放变量。 +```zc +autofree let types = malloc(1024); +``` + +#### 资源语义 (默认移动) +Zen C 将带有析构函数（如 `File`, `Vec`, 或 malloc 的指针）的类型视为 **资源**。为了防止双重释放错误，资源不能被隐式复制。 + +- **默认移动**：分配资源变量会转移所有权。原始变量变得无效（已移动）。 +- **复制类型**：没有析构函数的类型可以申请参与 `Copy` 行为，使赋值变成复制。 + +**诊断与哲学**： +如果你看到错误 "Use of moved value"，编译器是在告诉你：*"此类型拥有一个资源（如内存或句柄），盲目复制它是不安全的。"* + +> **对比：** 与 C/C++ 不同，Zen C 不会隐式复制拥有资源的值。 + +**函数参数**： +将值传递给函数遵循与赋值相同的规则：资源会被移动，除非通过引用传递。 + +```zc +fn process(r: Resource) { ... } // 'r' 被移动进函数 +fn peek(r: Resource*) { ... } // 'r' 被借用 (引用) +``` + +**显式克隆**： +如果你 *确实* 想要一个资源的两个副本，请显式执行： + +```zc +let b = a.clone(); // 调用 Clone trait 中的 'clone' 方法 +``` + +**选择性复制 (值类型)**： +对于没有析构函数的小型类型： + +```zc +struct Point { x: int; y: int; } +impl Copy for Point {} // 选择参与隐式复制 + +fn main() { + let p1 = Point { x: 1, y: 2 }; + let p2 = p1; // 已复制。p1 保持有效。 +} +``` + +#### RAII / Drop Trait +实现 `Drop` 以自动运行清理逻辑。 +```zc +impl Drop for MyStruct { + fn drop(self) { + self.free(); + } +} +``` + +### 9. 面向对象编程 + +#### 方法 +使用 `impl` 为类型定义方法。 +```zc +impl Point { + // 静态方法 (构造函数惯例) + fn new(x: int, y: int) -> Self { + return Point{x: x, y: y}; + } + + // 实例方法 + fn dist(self) -> float { + return sqrt(self.x * self.x + self.y * self.y); + } +} +``` + +#### Trait +定义共享行为。 +```zc +struct Circle { radius: f32; } + +trait Drawable { + fn draw(self); +} + +impl Drawable for Circle { + fn draw(self) { ... } +} + +let circle = Circle{}; +let drawable: Drawable = &circle; +``` + +#### 标准 Trait +Zen C 包含与语言语法集成的标准 Trait。 + +**Iterable** + +实现 `Iterable<T>` 以便为你的自定义类型启用 `for-in` 循环。 + +```zc +import "std/iter.zc" + +// 定义一个迭代器 +struct MyIter { + curr: int; + stop: int; +} + +impl MyIter { + fn next(self) -> Option<int> { + if self.curr < self.stop { + self.curr += 1; + return Option<int>::Some(self.curr - 1); + } + return Option<int>::None(); + } +} + +// 实现 Iterable +impl MyRange { + fn iterator(self) -> MyIter { + return MyIter{curr: self.start, stop: self.end}; + } +} + +// 在循环中使用 +for i in my_range { + println "{i}"; +} +``` + +**Drop** + +实现 `Drop` 来定义一个在对象超出范围时运行的析构函数 (RAII)。 + +```zc +import "std/mem.zc" + +struct Resource { + ptr: void*; +} + +impl Drop for Resource { + fn drop(self) { + if self.ptr != NULL { + free(self.ptr); + } + } +} +``` + +> **注意：** 如果一个变量被移动，则原始变量不会调用 `drop`。它遵循 [资源语义](#资源语义-默认移动)。 + +**Copy** + +标记 Trait，用于选择支持 `Copy` 行为（隐式复制）而不是移动语义。通过 `@derive(Copy)` 使用。 + +> **规则：** 实现了 `Copy` 的类型不得定义析构函数 (`Drop`)。 + +```zc +@derive(Copy) +struct Point { x: int; y: int; } + +fn main() { + let p1 = Point{x: 1, y: 2}; + let p2 = p1; // 已复制！p1 保持有效。 +} +``` + +**Clone** + +实现 `Clone` 以允许显式复制拥有资源的类型。 + +```zc +import "std/mem.zc" + +struct MyBox { val: int; } + +impl Clone for MyBox { + fn clone(self) -> MyBox { + return MyBox{val: self.val}; + } +} + +fn main() { + let b1 = MyBox{val: 42}; + let b2 = b1.clone(); // 显式复制 +} +``` + +#### 组合 +使用 `use` 嵌入其他结构体。你可以将它们混合进来（展平字段）或者为它们命名（嵌套字段）。 + +```zc +struct Entity { id: int; } + +struct Player { + // 混入 (未命名): 展平字段 + use Entity; // 直接将 'id' 添加到 Player + name: string; +} + +struct Match { + // 组合 (命名): 嵌套字段 + use p1: Player; // 通过 match.p1 访问 + use p2: Player; // 通过 match.p2 访问 +} +``` + +### 10. 泛型 + +结构体和函数的类型安全模板。 + +```zc +// 泛型结构体 +struct Box<T> { + item: T; +} + +// 泛型函数 +fn identity<T>(val: T) -> T { + return val; +} + +// 多参数泛型 +struct Pair<K, V> { + key: K; + value: V; +} +``` + +### 11. 并发 (Async/Await) + +基于 pthreads 构建。 + +```zc +async fn fetch_data() -> string { + // 在后台运行 + return "Data"; +} + +fn main() { + let future = fetch_data(); + let result = await future; +} +``` + +### 12. 元编程 + +#### Comptime +在编译时运行代码以生成源码或打印消息。 +```zc +comptime { + // 在编译时生成代码 (写入 stdout) + println "let build_date = \"2024-01-01\";"; +} + +println "构建日期: {build_date}"; +``` + +#### Embed +将文件嵌入为指定类型。 +```zc +// 默认 (Slice_char) +let data = embed "assets/logo.png"; + +// 类型化嵌入 +let text = embed "shader.glsl" as string; // 嵌入为 C-string +let rom = embed "bios.bin" as u8[1024]; // 嵌入为固定数组 +let wav = embed "sound.wav" as u8[]; // 嵌入为 Slice_u8 +``` + +#### 插件 +导入编译器插件以扩展语法。 +```zc +import plugin "regex" +let re = regex! { ^[a-z]+$ }; +``` + +#### 泛型 C 宏 +将预处理器宏传递给 C。 + +> **提示**：对于简单的常量，请使用 `def`。当你需要 C 预处理器宏或条件编译标志时，请使用 `#define`。 + +```zc +#define MAX_BUFFER 1024 +``` + +### 13. 属性 + +修饰函数和结构体以修改编译器行为。 + +| 属性 | 作用域 | 描述 | +|:---|:---|:---| +| `@must_use` | 函数 | 如果忽略返回值则发出警告。 | +| `@deprecated("msg")` | 函数/结构体 | 使用时发出带有消息的警告。 | +| `@inline` | 函数 | 提示编译器进行内联。 | +| `@noinline` | 函数 | 防止内联。 | +| `@packed` | 结构体 | 移除字段间的填充。 | +| `@align(N)` | 结构体 | 强制按 N 字节对齐。 | +| `@constructor` | 函数 | 在 main 之前运行。 | +| `@destructor` | 函数 | 在 main 退出后运行。 | +| `@unused` | 函数/变量 | 抑制未使用变量警告。 | +| `@weak` | 函数 | 弱符号链接。 | +| `@section("name")` | 函数 | 将代码放置在特定段中。 | +| `@noreturn` | 函数 | 函数不会返回 (例如 exit)。 | +| `@pure` | 函数 | 函数无副作用 (优化提示)。 | +| `@cold` | 函数 | 函数不太可能被执行 (分支预测提示)。 | +| `@hot` | 函数 | 函数频繁执行 (优化提示)。 | +| `@export` | 函数/结构体 | 导出符号 (默认可见性)。 | +| `@global` | 函数 | CUDA: 内核入口点 (`__global__`)。 | +| `@device` | 函数 | CUDA: 设备函数 (`__device__`)。 | +| `@host` | 函数 | CUDA: 主机函数 (`__host__`)。 | +| `@comptime` | 函数 | 用于编译时执行的辅助函数。 | +| `@derive(...)` | 结构体 | 自动实现 Trait。支持 `Debug`, `Eq` (智能派生), `Copy`, `Clone`。 | +| `@<custom>` | 任意 | 将泛型属性传递给 C (例如 `@flatten`, `@alias("name")`)。 | + +#### 自定义属性 + +Zen C 支持强大的 **自定义属性** 系统，允许你在代码中直接使用任何 GCC/Clang 的 `__attribute__`。任何不被 Zen C 编译器显式识别的属性都会被视为泛型属性并传递给生成的 C 代码。 + +这提供了对高级编译器特性、优化和链接器指令的访问，而无需在语言核心中提供显式支持。 + +#### 语法映射 +Zen C 属性直接映射到 C 属性： +- `@name` → `__attribute__((name))` +- `@name(args)` → `__attribute__((name(args)))` +- `@name("string")` → `__attribute__((name("string")))` + +#### 智能派生 + +Zen C 提供了尊重移动语义的 "智能派生"： + +- **`@derive(Eq)`**：生成一个通过引用获取参数的相等性方法 (`fn eq(self, other: T*)`)。 + - 当比较两个非 Copy 结构体 (`a == b`) 时，编译器会自动通过引用传递 `b` (`&b`) 以避免移动它。 + - 字段上的递归相等性检查也会优先使用指针访问，以防止所有权转移。 + +### 14. 内联汇编 + +Zen C 为内联汇编提供了一流支持，直接转译为 GCC 风格的扩展 `asm`。 + +#### 基本用法 +在 `asm` 块内编写原始汇编。字符串会自动拼接。 +```zc +asm { + "nop" + "mfence" +} +``` + +#### Volatile +防止编译器优化掉具有副作用的汇编代码。 +```zc +asm volatile { + "rdtsc" +} +``` + +#### 命名约束 +Zen C 通过命名绑定简化了复杂的 GCC 约束语法。 + +```zc +// 语法: : out(变量) : in(变量) : clobber(寄存器) +// 使用 {变量} 占位符语法以提高可读性 + +fn add(a: int, b: int) -> int { + let result: int; + asm { + "add {result}, {a}, {b}" + : out(result) + : in(a), in(b) + : clobber("cc") + } + return result; +} +``` + +| 类型 | 语法 | GCC 等效项 | +|:---|:---|:---| +| **输出** | `: out(variable)` | `"=r"(variable)` | +| **输入** | `: in(variable)` | `"r"(variable)` | +| **破坏** | `: clobber("rax")` | `"rax"` | +| **内存** | `: clobber("memory")` | `"memory"` | + +> **注意：** 使用 Intel 语法时（通过 `-masm=intel`），必须确保你的构建配置正确（例如，`//> cflags: -masm=intel`）。TCC 不支持 Intel 语法的汇编。 + +### 15. 构建指令 + +Zen C 支持在源文件顶部使用特殊注释来配置构建过程，无需复杂的构建系统或 Makefile。 + +| 指令 | 参数 | 描述 | +|:---|:---|:---| +| `//> link:` | `-lfoo` 或 `path/to/lib.a` | 链接库或对象文件。 | +| `//> lib:` | `path/to/libs` | 添加库搜索路径 (`-L`)。 | +| `//> include:` | `path/to/headers` | 添加包含头文件搜索路径 (`-I`)。 | +| `//> framework:` | `Cocoa` | 链接 macOS Framework。 | +| `//> cflags:` | `-Wall -O3` | 向 C 编译器传递任意标志。 | +| `//> define:` | `MACRO` 或 `KEY=VAL` | 定义预处理器宏 (`-D`)。 | +| `//> pkg-config:` | `gtk+-3.0` | 运行 `pkg-config` 并追加 `--cflags` 和 `--libs`。 | +| `//> shell:` | `command` | 在构建期间执行 shell 命令。 | +| `//> get:` | `http://url/file` | 如果特定文件不存在，则下载该文件。 | + +#### 特性 + +**1. 操作系统守护 (OS Guarding)** +在指令前加上操作系统名称，以使其仅在特定平台上应用。 +受支持的前缀：`linux:`, `windows:`, `macos:` (或 `darwin:`)。 + +```zc +//> linux: link: -lm +//> windows: link: -lws2_32 +//> macos: framework: Cocoa +``` + +**2. 环境变量展开** +使用 `${VAR}` 语法在指令中展开环境变量。 + +```zc +//> include: ${HOME}/mylib/include +//> lib: ${ZC_ROOT}/std +``` + +#### 示例 + +```zc +//> include: ./include +//> lib: ./libs +//> link: -lraylib -lm +//> cflags: -Ofast +//> pkg-config: gtk+-3.0 + +import "raylib.h" + +fn main() { ... } +``` + +### 16. 关键字 + +以下关键字在 Zen C 中是保留的。 + +#### 声明 +`alias`, `def`, `enum`, `fn`, `impl`, `import`, `let`, `module`, `opaque`, `struct`, `trait`, `union`, `use` + +#### 控制流 +`async`, `await`, `break`, `catch`, `continue`, `defer`, `else`, `for`, `goto`, `guard`, `if`, `loop`, `match`, `return`, `try`, `unless`, `while` + +#### 特殊 +`asm`, `assert`, `autofree`, `comptime`, `const`, `embed`, `launch`, `ref`, `sizeof`, `static`, `test`, `volatile` + +#### 常量 +`true`, `false`, `null` + +#### C 保留字 +以下标识符是保留的，因为它们是 C11 中的关键字： +`auto`, `case`, `char`, `default`, `do`, `double`, `extern`, `float`, `inline`, `int`, `long`, `register`, `restrict`, `short`, `signed`, `switch`, `typedef`, `unsigned`, `void`, `_Atomic`, `_Bool`, `_Complex`, `_Generic`, `_Imaginary`, `_Noreturn`, `_Static_assert`, `_Thread_local` + +#### 运算符 +`and`, `or` + +--- + +## 标准库 + +Zen C 包含一个涵盖基本功能的标准库 (`std`)。 + +[浏览标准库文档](docs/std/README.md) + +### 核心模块 + +| 模块 | 描述 | 文档 | +| :--- | :--- | :--- | +| **`std/vec.zc`** | 可增长动态数组 `Vec<T>`。 | [文档](docs/std/vec.md) | +| **`std/string.zc`** | 堆分配的 `String` 类型，支持 UTF-8。 | [文档](docs/std/string.md) | +| **`std/queue.zc`** | 先进先出队列 (环形缓冲区)。 | [文档](docs/std/queue.md) | +| **`std/map.zc`** | 泛型哈希表 `Map<V>`。 | [文档](docs/std/map.md) | +| **`std/fs.zc`** | 文件系统操作。 | [文档](docs/std/fs.md) | +| **`std/io.zc`** | 标准输入/输出 (`print`/`println`)。 | [文档](docs/std/io.md) | +| **`std/option.zc`** | 可选值 (`Some`/`None`)。 | [文档](docs/std/option.md) | +| **`std/result.zc`** | 错误处理 (`Ok`/`Err`)。 | [文档](docs/std/result.md) | +| **`std/path.zc`** | 跨平台路径操作。 | [文档](docs/std/path.md) | +| **`std/env.zc`** | 进程环境变量。 | [文档](docs/std/env.md) | +| **`std/net.zc`** | TCP 网络 (套接字)。 | [文档](docs/std/net.md) | +| **`std/thread.zc`** | 线程与同步。 | [文档](docs/std/thread.md) | +| **`std/time.zc`** | 时间测量与睡眠。 | [文档](docs/std/time.md) | +| **`std/json.zc`** | JSON 解析与序列化。 | [文档](docs/std/json.md) | +| **`std/stack.zc`** | 后进先出栈 `Stack<T>`。 | [文档](docs/std/stack.md) | +| **`std/set.zc`** | 泛型哈希集合 `Set<T>`。 | [文档](docs/std/set.md) | + +--- + +## 工具链 + +Zen C 提供内置的语言服务器 (LSP) 和 REPL 以增强开发体验。 + +### 语言服务器 (LSP) + +Zen C 语言服务器 (LSP) 支持标准的 LSP 特性，用于编辑器集成： + +* **转到定义** +* **查找引用** +* **悬停信息** +* **补全** (函数/结构体名，方法/字段的点补全) +* **文档符号** (大纲) +* **签名帮助** +* **诊断** (语法/语义错误) + +启动语言服务器（通常在编辑器的 LSP 设置中配置）： + +```bash +zc lsp +``` + +它通过标准 I/O (JSON-RPC 2.0) 进行通信。 + +### REPL + +Read-Eval-Print Loop 允许你交互式地尝试 Zen C 代码。 + +```bash +zc repl +``` + +#### 特性 + +* **交互式编码**：输入表达式或语句以立即求值。 +* **持久历史**：命令保存在 `~/.zprep_history` 中。 +* **启动脚本**：自动加载 `~/.zprep_init.zc` 中的命令。 + +#### 命令 + +| 命令 | 描述 | +|:---|:---| +| `:help` | 显示可用命令。 | +| `:reset` | 清除当前会话历史 (变量/函数)。 | +| `:vars` | 显示活跃变量。 | +| `:funcs` | 显示用户定义的函数。 | +| `:structs` | 显示用户定义的结构体。 | +| `:imports` | 显示活跃导入。 | +| `:history` | 显示会话输入历史。 | +| `:type <expr>` | 显示表达式的类型。 | +| `:c <stmt>` | 显示语句生成的 C 代码。 | +| `:time <expr>` | 基准测试表达式 (运行 1000 次迭代)。 | +| `:edit [n]` | 在 `$EDITOR` 中编辑命令 `n` (默认：最后一条)。 | +| `:save <file>` | 将当前会话保存到 `.zc` 文件。 | +| `:load <file>` | 将 `.zc` 文件加载并执行到会话中。 | +| `:watch <expr>` | 监视表达式 (每次输入后重新求值)。 | +| `:unwatch <n>` | 移除监视。 | +| `:undo` | 从会话中移除最后一条命令。 | +| `:delete <n>` | 移除索引为 `n` 的命令。 | +| `:clear` | 清屏。 | +| `:quit` | 退出 REPL。 | +| `! <cmd>` | 运行 shell 命令 (如 `!ls`)。 | + +--- + + +## 编译器支持与兼容性 + +Zen C 旨在与大多数 C11 编译器配合使用。某些特性依赖于 GNU C 扩展，但这些扩展通常在其他编译器中也能工作。使用 `--cc` 标志切换后端。 + +```bash +zc run app.zc --cc clang +zc run app.zc --cc zig +``` + +### 测试套件状态 + +| 编译器 | 通过率 | 受支持特性 | 已知局限性 | +|:---|:---:|:---|:---| +| **GCC** | **100%** | 所有特性 | 无。 | +| **Clang** | **100%** | 所有特性 | 无。 | +| **Zig** | **100%** | 所有特性 | 无。使用 `zig cc` 作为替代 C 编译器。 | +| **TCC** | **~70%** | 基本语法, 泛型, Trait | 不支持 `__auto_type`, 不支持 Intel ASM, 不支持嵌套函数。 | + +> **建议：** 生产环境构建请使用 **GCC**, **Clang**, 或 **Zig**。TCC 非常适合快速原型开发，因为它编译速度极快，但缺少 Zen C 全面支持所需的一些高级 C 扩展。 + +### 使用 Zig 构建 + +Zig 的 `zig cc` 命令提供了 GCC/Clang 的替代方案，具有出色的跨平台编译支持。使用 Zig： + +```bash +# 使用 Zig 编译并运行 Zen C 程序 +zc run app.zc --cc zig + +# 使用 Zig 构建 Zen C 编译器本身 +make zig +``` + +### C++ 互操作 + +Zen C 可以通过 `--cpp` 标志生成 C++ 兼容的代码，从而实现与 C++ 库的无缝集成。 + +```bash +# 直接使用 g++ 编译 +zc app.zc --cpp + +# 或者转译用于手动构建 +zc transpile app.zc --cpp +g++ out.c my_cpp_lib.o -o app +``` + +#### 在 Zen C 中使用 C++ + +包含 C++ 头文件并在 `raw` 块中使用 C++ 代码： + +```zc +include <vector> +include <iostream> + +raw { + std::vector<int> make_vec(int a, int b) { + return {a, b}; + } +} + +fn main() { + let v = make_vec(1, 2); + raw { std::cout << "Size: " << v.size() << std::endl; } +} +``` + +> **注意：** `--cpp` 标志会将后端切换为 `g++` 并发出 C++ 兼容的代码（使用 `auto` 代替 `__auto_type`，使用函数重载代替 `_Generic`，以及对 `void*` 进行显式转换）。 + +#### CUDA 互操作 + +Zen C 通过转译为 **CUDA C++** 来支持 GPU 编程。这使你在维持 Zen C 人体工程学语法的同时，能够利用内核中的强大 C++ 特性（模板、constexpr）。 + +```bash +# 直接使用 nvcc 编译 +zc run app.zc --cuda + +# 或者转译用于手动构建 +zc transpile app.zc --cuda -o app.cu +nvcc app.cu -o app +``` + +#### CUDA 特定属性 + +| 属性 | CUDA 等效项 | 描述 | +|:---|:---|:---| +| `@global` | `__global__` | 内核函数 (运行在 GPU，从主机调用) | +| `@device` | `__device__` | 设备函数 (运行在 GPU，从 GPU 调用) | +| `@host` | `__host__` | 主机函数 (明确仅 CPU 运行) | + +#### 内核启动语法 + +Zen C 提供了一个简洁的 `launch` 语句用于调用 CUDA 内核： + +```zc +launch kernel_name(args) with { + grid: num_blocks, + block: threads_per_block, + shared_mem: 1024, // 可选 + stream: my_stream // 可选 +}; +``` + +这转译为：`kernel_name<<<grid, block, shared, stream>>>(args);` + +#### 编写 CUDA 内核 + +使用带有 `@global` 的 Zen C 函数语法和 `launch` 语句： + +```zc +import "std/cuda.zc" + +@global +fn add_kernel(a: float*, b: float*, c: float*, n: int) { + let i = thread_id(); + if i < n { + c[i] = a[i] + b[i]; + } +} + +fn main() { + def N = 1024; + let d_a = cuda_alloc<float>(N); + let d_b = cuda_alloc<float>(N); + let d_c = cuda_alloc<float>(N); + defer cuda_free(d_a); + defer cuda_free(d_b); + defer cuda_free(d_c); + + // ... 初始化数据 ... + + launch add_kernel(d_a, d_b, d_c, N) with { + grid: (N + 255) / 256, + block: 256 + }; + + cuda_sync(); +} +``` + +#### 标准库 (`std/cuda.zc`) +Zen C 为常见的 CUDA 操作提供了一个标准库，以减少 `raw` 块的使用： + +```zc +import "std/cuda.zc" + +// 内存管理 +let d_ptr = cuda_alloc<float>(1024); +cuda_copy_to_device(d_ptr, h_ptr, 1024 * sizeof(float)); +defer cuda_free(d_ptr); + +// 同步 +cuda_sync(); + +// 线程索引 (在内核内部使用) +let i = thread_id(); // 全局索引 +let bid = block_id(); +let tid = local_id(); +``` + + +> **注意：** `--cuda` 标志设置 `nvcc` 为编译器并隐含 `--cpp` 模式。需要安装 NVIDIA CUDA Toolkit。 + +### Objective-C 互操作 + +Zen C 可以通过 `--objc` 标志编译为 Objective-C (`.m`)，允许你使用 Objective-C 框架（如 Cocoa/Foundation）和语法。 + +```bash +# 使用 clang (或 gcc/gnustep) 编译 +zc app.zc --objc --cc clang +``` + +#### 在 Zen C 中使用 Objective-C + +使用 `include` 包含头文件，并在 `raw` 块中使用 Objective-C 语法 (`@interface`, `[...]`, `@""`)。 + +```zc +//> macos: framework: Foundation +//> linux: cflags: -fconstant-string-class=NSConstantString -D_NATIVE_OBJC_EXCEPTIONS +//> linux: link: -lgnustep-base -lobjc + +include <Foundation/Foundation.h> + +fn main() { + raw { + NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; + NSLog(@"来自 Objective-C 的问候！"); + [pool drain]; + } + println "Zen C 也能正常工作！"; +} +``` + +> **注意：** Zen C 字符串插值通过调用 `debugDescription` 或 `description` 同样适用于 Objective-C 对象 (`id`)。 + +--- + +## 贡献 + +我们欢迎各类贡献！无论是修复 Bug、完善文档，还是提出新功能建议。 + +### 如何贡献 +1. **Fork 仓库**：标准的 GitHub 工作流程。 +2. **创建功能分支**：`git checkout -b feature/NewThing`。 +3. **代码规范**： + * 遵循现有的 C 风格。 + * 确保所有测试通过：`make test`。 + * 在 `tests/` 中为你的功能添加新测试。 +4. **提交拉取请求**：清晰地描述你的更改。 + +### 运行测试 +测试套件是你最好的朋友。 + +```bash +# 运行所有测试 (GCC) +make test + +# 运行特定的测试 +./zc run tests/test_match.zc + +# 使用不同的编译器运行 +./tests/run_tests.sh --cc clang +./tests/run_tests.sh --cc zig +./tests/run_tests.sh --cc tcc +``` + +### 扩展编译器 +* **解析器 (Parser)**：`src/parser/` - 递归下降解析器。 +* **代码生成 (Codegen)**：`src/codegen/` - 转译逻辑 (Zen C -> GNU C/C11)。 +* **标准库 (Standard Library)**：`std/` - 使用 Zen C 本身编写。 + +--- + +## 致谢与归属 + +本项目使用了第三方库。完整许可证文本可在 `LICENSES/` 目录中找到。 + +* **[cJSON](https://github.com/DaveGamble/cJSON)** (MIT 许可证)：用于语言服务器中的 JSON 解析和生成。 +* **[zc-ape](https://github.com/OEvgeny/zc-ape)** (MIT 许可证)：由 [Eugene Olonov](https://github.com/OEvgeny) 开发的原版 Zen-C 实际上便携的可执行文件 (APE) 端口。 +* **[Cosmopolitan Libc](https://github.com/jart/cosmopolitan)** (ISC 许可证)：使 APE 成为可能的基础库。 diff --git a/README_ZH_TW.md b/README_ZH_TW.md new file mode 100644 index 0000000..b9b5511 --- /dev/null +++ b/README_ZH_TW.md @@ -0,0 +1,1415 @@ + +<div align="center"> + +[English](README.md) • [简体中文](README_ZH_CN.md) • [繁體中文](README_ZH_TW.md) • [Español](README_ES.md) + +</div> + +<div align="center"> + +# Zen C + +**現代開發體驗。零開銷。純淨 C。** + +[]() +[]() +[]() +[]() + +*像高級語言一樣編寫，像 C 一樣運行。* + +</div> + +--- + +## 概述 + +**Zen C** 是一種現代系統編程語言，可編譯為人類可讀的 `GNU C`/`C11`。它提供了一套豐富的特性，包括類型推斷、模式匹配、泛型、Trait、async/await 以及具有 RAII 能力的手動內存管理，同時保持 100% 的 C ABI 兼容性。 + +## 社區 + +加入官方 Zen C Discord 服務器，參與討論、展示 Demo、提問或報告 Bug！ + +- Discord: [點擊加入](https://discord.com/invite/q6wEsCmkJP) + +--- + +## 目錄 + +- [概述](#概述) +- [社區](#社區) +- [快速入門](#快速入門) + - [安裝](#安裝) + - [用法](#用法) + - [環境變量](#環境變量) +- [語言參考](#語言參考) + - [1. 變量與常量](#1-變量與常量) + - [2. 原始類型](#2-原始類型) + - [3. 複合類型](#3-複合類型) + - [數組](#數組) + - [元組](#元組) + - [結構體](#結構體) + - [不透明結構體](#不透明結構體) + - [枚舉](#枚舉) + - [聯合體](#聯合體) + - [類型別名](#類型別名) + - [不透明類型別名](#不透明類型別名) + - [4. 函數與 Lambda](#4-函數與-lambda) + - [函數](#函數) + - [常量參數](#常量參數) + - [默認參數](#默認參數) + - [Lambda (閉包)](#lambda-閉包) + - [原始函數指針](#原始函數指針) + - [變參函數](#變參函數) + - [5. 控制流](#5-控制流) + - [條件語句](#條件語句) + - [模式匹配](#模式匹配) + - [循環](#循環) + - [高級控制](#高級控制) + - [6. 運算符](#6-運算符) + - [可重載運算符](#可重載運算符) + - [語法糖](#語法糖) + - [7. 打印與字符串插值](#7-打印與字符串插值) + - [關鍵字](#關鍵字) + - [簡寫形式](#簡寫形式) + - [字符串插值 (F-strings)](#字符串插值-f-strings) + - [輸入提示 (`?`)](#輸入提示-) + - [8. 內存管理](#8-內存管理) + - [Defer](#defer) + - [Autofree](#autofree) + - [資源語義 (默認移動)](#資源語義-默認移動) + - [RAII / Drop Trait](#raii--drop-trait) + - [9. 面向對象編程](#9-面向對象編程) + - [方法](#方法) + - [Trait](#trait) + - [標準 Trait](#標準-trait) + - [組合](#組合) + - [10. 泛型](#10-泛型) + - [11. 並發 (Async/Await)](#11-並發-asyncawait) + - [12. 元編程](#12-元編程) + - [Comptime](#comptime) + - [Embed](#embed) + - [插件](#插件) + - [泛型 C 宏](#泛型-c-宏) + - [13. 屬性](#13-屬性) + - [自定義屬性](#自定義屬性) + - [智能派生](#智能派生) + - [14. 內聯匯編](#14-內聯匯編) + - [基本用法](#基本用法) + - [Volatile](#volatile) + - [命名約束](#命名約束) + - [15. 構建指令](#15-構建指令) + - [16. 關鍵字](#16-關鍵字) +- [標準庫](#標準庫) +- [工具鏈](#工具鏈) + - [語言服務器 (LSP)](#語言服務器-lsp) + - [REPL](#repl) +- [編譯器支持與兼容性](#編譯器支持與兼容性) + - [測試套件狀態](#測試套件狀態) + - [使用 Zig 構建](#使用-zig-構建) + - [C++ 互操作](#c-互操作) + - [CUDA 互操作](#cuda-互操作) + - [Objective-C 互操作](#objective-c-互操作) +- [貢獻](#貢獻) +- [致謝與歸屬](#致謝與歸屬) + +--- + +## 快速入門 + +### 安裝 + +```bash +git clone https://github.com/z-libs/Zen-C.git +cd Zen-C +make +sudo make install +``` + +### 便攜式構建 (APE) + +Zen C 可以通過 [Cosmopolitan Libc](https://github.com/jart/cosmopolitan) 編譯為 **Actually Portable Executable (APE)**。這將生成一個單個的可執行文件 (`.com`)，能夠原生運行在 Linux, macOS, Windows, FreeBSD, OpenBSD, 和 NetBSD 上的 x86_64 和 aarch64 架構上。 + +**前提條件：** +- `cosmocc` 工具鏈（必須在 PATH 中） + +**構建與安裝：** +```bash +make ape +sudo env "PATH=$PATH" make install-ape +``` + +**產物：** +- `out/bin/zc.com`: 便攜式 Zen-C 編譯器。已將標準庫嵌入到可執行文件中。 +- `out/bin/zc-boot.com`: 一個自包含的引導安裝程序，用於設置新的 Zen-C 項目。 + +**用法：** +```bash +# 在任何支持的操作系統上運行 +./out/bin/zc.com build hello.zc -o hello +``` + +### 用法 + +```bash +# 編譯並運行 +zc run hello.zc + +# 構建可執行文件 +zc build hello.zc -o hello + +# 交互式 Shell +zc repl +``` + +### 環境變量 + +你可以設置 `ZC_ROOT` 來指定標準庫的位置（標準導入如 `import "std/vector.zc"`）。這允許你從任何目錄運行 `zc`。 + +```bash +export ZC_ROOT=/path/to/Zen-C +``` + +--- + +## 語言參考 + +### 1. 變量與常量 + +Zen C 區分編譯時常量和運行時變量。 + +#### 清單常量 (`def`) +僅在編譯時存在的值（折疊到代碼中）。用於數組大小、固定配置和魔術數字。 + +```zc +def MAX_SIZE = 1024; +let buffer: char[MAX_SIZE]; // 有效的數組大小 +``` + +#### 變量 (`let`) +內存中的存儲位置。可以是可變的或只讀的 (`const`)。 + +```zc +let x = 10; // 可變 +x = 20; // 允許 + +let y: const int = 10; // 只讀 (類型修飾) +// y = 20; // 錯誤：無法賦值給 const 變量 +``` + +### 2. 原始類型 + +| 類型 | C 等效類型 | 描述 | +|:---|:---|:---| +| `int`, `uint` | `int`, `unsigned int` | 平台標準整數 | +| `I8` .. `I128` 或 `i8` .. `i128` | `int8_t` .. `__int128_t` | 有符號固定寬度整數 | +| `U8` .. `U128` 或 `u8` .. `u128` | `uint8_t` .. `__uint128_t` | 無符號固定寬度整數 | +| `isize`, `usize` | `ptrdiff_t`, `size_t` | 指針大小的整數 | +| `byte` | `uint8_t` | U8 的別名 | +| `F32`, `F64` 或 `f32`, `f64` | `float`, `double` | 浮點數 | +| `bool` | `bool` | `true` 或 `false` | +| `char` | `char` | 單個字符 | +| `string` | `char*` | C-string (以 null 結尾) | +| `U0`, `u0`, `void` | `void` | 空類型 | + +### 3. 複合類型 + +#### 數組 +具有值語義的固定大小數組。 +```zc +def SIZE = 5; +let ints: int[SIZE] = [1, 2, 3, 4, 5]; +let zeros: [int; SIZE]; // 零初始化的 +``` + +#### 元組 +將多個值組合在一起，通過索引訪問元素。 +```zc +let pair = (1, "Hello"); +let x = pair.0; // 1 +let s = pair.1; // "Hello" +``` + +**多個返回值** + +函數可以返回元組以提供多個結果： +```zc +fn add_and_subtract(a: int, b: int) -> (int, int) { + return (a + b, a - b); +} + +let result = add_and_subtract(3, 2); +let sum = result.0; // 5 +let diff = result.1; // 1 +``` + +**解構** + +元組可以直接解構為多個變量： +```zc +let (sum, diff) = add_and_subtract(3, 2); +// sum = 5, diff = 1 +``` + +#### 結構體 +帶有可選位域的數據結構。 +```zc +struct Point { + x: int; + y: int; +} + +// 結構體初始化 +let p = Point { x: 10, y: 20 }; + +// 位域 +struct Flags { + valid: U8 : 1; + mode: U8 : 3; +} +``` + +> **注意**：結構體默認使用 [移動語義](#資源語義-默認移動)。即使是指針，也可以通過 `.` 訪問字段（自動解引用）。 + +#### 不透明結構體 +你可以將結構體定義為 `opaque`，以將對其字段的訪問限制在定義該結構體的模塊內部，同時仍允許在棧上分配該結構體（大小已知）。 + +```zc +// 在 user.zc 中 +opaque struct User { + id: int; + name: string; +} + +fn new_user(name: string) -> User { + return User{id: 1, name: name}; // 允許：在模塊內部 +} + +// 在 main.zc 中 +import "user.zc"; + +fn main() { + let u = new_user("Alice"); + // let id = u.id; // 錯誤：無法訪問私有字段 'id' +} +``` + +#### 枚舉 +能夠持有數據的標籤聯合 (Sum types)。 +```zc +enum Shape { + Circle(float), // 持有半徑 + Rect(float, float), // 持有寬、高 + Point // 不帶數據 +} +``` + +#### 聯合體 +標準 C 聯合體（不安全訪問）。 +```zc +union Data { + i: int; + f: float; +} +``` + +#### 類型別名 +為現有類型創建新名稱。 +```zc +alias ID = int; +alias PointMap = Map<string, Point>; +``` + +#### 不透明類型別名 +你可以將類型別名定義為 `opaque`，從而在定義模塊之外創建一個與基礎類型不同的新類型。這提供了強大的封裝和類型安全性，而沒有包裝結構體的運行時開銷。 + +```zc +// 在 library.zc 中 +opaque alias Handle = int; + +fn make_handle(v: int) -> Handle { + return v; // 允許在模塊內部進行隱式轉換 +} + +// 在 main.zc 中 +import "library.zc"; + +fn main() { + let h: Handle = make_handle(42); + // let i: int = h; // 錯誤：類型驗證失敗 + // let h2: Handle = 10; // 錯誤：類型驗證失敗 +} +``` + +### 4. 函數與 Lambda + +#### 函數 +```zc +fn add(a: int, b: int) -> int { + return a + b; +} + +// 調用時支持命名參數 +add(a: 10, b: 20); +``` + +> **注意**：命名參數必須嚴格遵循定義的參數順序。`add(b: 20, a: 10)` 是無效的。 + +#### 常量參數 +函數參數可以標記為 `const` 以強制執行只讀語義。這是一個類型修飾符，而不是清單常量。 + +```zc +fn print_val(v: const int) { + // v = 10; // 錯誤：無法賦值給 const 變量 + println "{v}"; +} +``` + +#### 默認參數 +函數可以為尾部參數定義默認值。這些值可以是字面量、表達式或有效的 Zen C 代碼（如結構體構造函數）。 +```zc +// 簡單默認值 +fn increment(val: int, amount: int = 1) -> int { + return val + amount; +} + +// 表達式默認值（在調用處計算） +fn offset(val: int, pad: int = 10 * 2) -> int { + return val + pad; +} + +// 結構體默認值 +struct Config { debug: bool; } +fn init(cfg: Config = Config { debug: true }) { + if cfg.debug { println "調試模式"; } +} + +fn main() { + increment(10); // 11 + offset(5); // 25 + init(); // 打印 "調試模式" +} +``` + +#### Lambda (閉包) +可以捕獲環境的匿名函數。 +```zc +let factor = 2; +let double = x -> x * factor; // 箭頭語法 +let full = fn(x: int) -> int { return x * factor; }; // 塊語法 +``` + +#### 原始函數指針 +Zen C 使用 `fn*` 語法支持原始 C 函數指針。這允許與期望函數指針且沒有閉包開銷的 C 庫進行無縫互操作。 + +```zc +// 接受原始函數指針的函數 +fn set_callback(cb: fn*(int)) { + cb(42); +} + +// 返回原始函數指針的函數 +fn get_callback() -> fn*(int) { + return my_handler; +} + +// 支持指向函數指針的指針 (fn**) +let pptr: fn**(int) = &ptr; +``` + +#### 變參函數 +函數可以使用 `...` 和 `va_list` 類型接受可變數量的參數。 +```zc +fn log(lvl: int, fmt: char*, ...) { + let ap: va_list; + va_start(ap, fmt); + vprintf(fmt, ap); // 使用 C stdio + va_end(ap); +} +``` + +### 5. 控制流 + +#### 条件语句 +```zc +if x > 10 { + print("Large"); +} else if x > 5 { + print("Medium"); +} else { + print("Small"); +} + +// 三元運算符 +let y = x > 10 ? 1 : 0; +``` + +#### 模式匹配 +`switch` 的強大替代方案。 +```zc +match val { + 1 => { print "One" }, + 2 || 3 => { print "Two or Three" }, // 使用 || 進行 或 操作 + 4 or 5 => { print "Four or Five" }, // 使用 'or' 進行 或 操作 + 6, 7, 8 => { print "Six to Eight" }, // 使用逗號進行 或 操作 + 10 .. 15 => { print "10 to 14" }, // 左閉右開區間 (舊語法) + 10 ..< 15 => { print "10 to 14" }, // 左閉右開區間 (顯式) + 20 ..= 25 => { print "20 to 25" }, // 全閉區間 + _ => { print "Other" }, +} + +// 解構枚舉 +match shape { + Shape::Circle(r) => println "半徑: {r}", + Shape::Rect(w, h) => println "面積: {w*h}", + Shape::Point => println "點" +} +``` + +#### 引用綁定 +為了在不獲取所有權（移動）的情況下檢查一個值，在模式中使用 `ref` 關鍵字。這對於實現了移動語義的類型（如 `Option`, `Result`, 非 Copy 結構體）至關重要。 + +```zc +let opt = Some(NonCopyVal{...}); +match opt { + Some(ref x) => { + // 'x' 是指向 'opt' 內部值的指針 + // 'opt' 在此處不會被移動/消耗 + println "{x.field}"; + }, + None => {} +} +``` + +#### 循環 +```zc +// 區間迭代 +for i in 0..10 { ... } // 左閉右開 (0 到 9) +for i in 0..<10 { ... } // 左閉右開 (顯式) +for i in 0..=10 { ... } // 全閉 (0 到 10) +for i in 0..10 step 2 { ... } + +// 迭代器 (Vec, Array, 或自定義 Iterable) +for item in collection { ... } + +// While 循環 +while x < 10 { ... } + +// 帶標籤的無限循環 +outer: loop { + if done { break outer; } +} + +// 重複 N 次 +for _ in 0..5 { ... } +``` + +#### 高級控制 +```zc +// Guard: 如果條件為假，則執行 else 塊並返回 +guard ptr != NULL else { return; } + +// Unless: 除非為真（即如果為假） +unless is_valid { return; } +``` + +### 6. 運算符 + +Zen C 通過實現特定的方法名來支持用戶定義結構體的運算符重載。 + +#### 可重載運算符 + +| 類別 | 運算符 | 方法名 | +|:---|:---|:---| +| **算術** | `+`, `-`, `*`, `/`, `%` | `add`, `sub`, `mul`, `div`, `rem` | +| **比較** | `==`, `!=` | `eq`, `neq` | +| | `<`, `>`, `<=`, `>=` | `lt`, `gt`, `le`, `ge` | +| **位運算** | `&`, `|`, `^` | `bitand`, `bitor`, `bitxor` | +| | `<<`, `>>` | `shl`, `shr` | +| **一元** | `-` | `neg` | +| | `!` | `not` | +| | `~` | `bitnot` | +| **索引** | `a[i]` | `get(a, i)` | +| | `a[i] = v` | `set(a, i, v)` | + +> **關於字符串相等性的說明**： +> - `string == string` 進行 **值比較**（等同於 `strcmp`）。 +> - `char* == char*` 進行 **指針比較**（檢查內存地址）。 +> - 混合比較（例如 `string == char*`）默認為 **指針比較**。 + +**示例：** +```zc +impl Point { + fn add(self, other: Point) -> Point { + return Point{x: self.x + other.x, y: self.y + other.y}; + } +} + +let p3 = p1 + p2; // 調用 p1.add(p2) +``` + +#### 語法糖 + +這些運算符是內置語言特性，不能直接重載。 + +| 運算符 | 名稱 | 描述 | +|:---|:---|:---| +| `|>` | 管道 | `x |> f(y)` 脫糖為 `f(x, y)` | +| `??` | 空合併 | 如果 `val` 為 NULL，`val ?? default` 返回 `default` (用於指針) | +| `??=` | 空賦值 | 如果 `val` 為 NULL 則賦值 | +| `?.` | 安全導航 | 僅當 `ptr` 不為 NULL 時訪問字段 | +| `?` | Try 運算符 | 如果存在錯誤則返回 (用於 Result/Option 類型) | + +**自動解引用**： +指針字段訪問 (`ptr.field`) 和方法調用 (`ptr.method()`) 會自動解引用指針，等同於 `(*ptr).field`。 + +### 7. 打印與字符串插值 + +Zen C 提供了多種控制台打印選項，包括關鍵字和簡潔的簡寫形式。 + +#### 關鍵字 + +- `print "text"`: 打印到 `stdout`，不帶尾隨換行符。 +- `println "text"`: 打印到 `stdout`，帶尾隨換行符。 +- `eprint "text"`: 打印到 `stderr`，不帶尾隨換行符。 +- `eprintln "text"`: 打印到 `stderr`，帶尾隨換行符。 + +#### 簡寫形式 + +Zen C 允許直接將字符串字面量用作語句來進行快速打印： + +- `"Hello World"`: 等同於 `println "Hello World"`。(隱式添加換行符) +- `"Hello World"..`: 等同於 `print "Hello World"`。(不帶尾隨換行符) +- `!"Error"`: 等同於 `eprintln "Error"`。(輸出到 stderr) +- `!"Error"..`: 等同於 `eprint "Error"`。(輸出到 stderr，不帶換行符) + +#### 字符串插值 (F-strings) + +你可以使用 `{}` 語法將表達式直接嵌入到字符串字面量中。這適用於所有打印方法和字符串簡寫。 + +```zc +let x = 42; +let name = "Zen"; +println "值: {x}, 名稱: {name}"; +"值: {x}, 名稱: {name}"; // 簡寫形式的 println +``` + +#### 輸入提示 (`?`) + +Zen C 支持使用 `?` 前綴進行用戶輸入提示的簡寫。 + +- `? "提示文本"`: 打印提示信息（不換行）並等待輸入（讀取一行）。 +- `? "輸入年齡: " (age)`: 打印提示並掃描輸入到變量 `age` 中。 + - 格式說明符會根據變量類型自動推斷。 + +```c +let age: int; +? "你多大了？ " (age); +println "你 {age} 歲了。"; +``` + +### 8. 內存管理 + +Zen C 允許帶有符合人體工程學輔助的手動內存管理。 + +#### Defer +在當前作用域退出時執行代碼。Defer 語句按照後進先出 (LIFO) 的順序執行。 +```zc +let f = fopen("file.txt", "r"); +defer fclose(f); +``` + +> 為了防止未定義行為，`defer` 塊內不允許使用控制流語句（`return`, `break`, `continue`, `goto`）。 + +#### Autofree +在作用域退出時自動釋放變量。 +```zc +autofree let types = malloc(1024); +``` + +#### 資源語義 (默認移動) +Zen C 將帶有析構函數（如 `File`, `Vec`, 或 malloc 的指針）的類型視為 **資源**。為了防止雙重釋放錯誤，資源不能被隱式複製。 + +- **默認移動**：分配資源變量會轉移所有權。原始變量變得無效（已移動）。 +- **複製類型**：沒有析構函數的類型可以申請參與 `Copy` 行為，使賦值變成複製。 + +**診斷與哲學**： +如果你看到錯誤 "Use of moved value"，編譯器是在告訴你：*"此類型擁有一個資源（如內存或句柄），盲目複製它是不安全的。"* + +> **對比：** 與 C/C++ 不同，Zen C 不會隱式複製擁有資源的值。 + +**函數參數**： +將值傳遞給函數遵循與賦值相同的規則：資源會被移動，除非通過引用傳遞。 + +```zc +fn process(r: Resource) { ... } // 'r' 被移動進函數 +fn peek(r: Resource*) { ... } // 'r' 被借用 (引用) +``` + +**顯式克隆**： +如果你 *確實* 想要一個資源的兩個副本，請顯式執行： + +```zc +let b = a.clone(); // 調用 Clone trait 中的 'clone' 方法 +``` + +**選擇性複製 (值類型)**： +對於沒有析構函數的小型類型： + +```zc +struct Point { x: int; y: int; } +impl Copy for Point {} // 選擇參與隱式複製 + +fn main() { + let p1 = Point { x: 1, y: 2 }; + let p2 = p1; // 已複製。p1 保持有效。 +} +``` + +#### RAII / Drop Trait +實現 `Drop` 以自動運行清理邏輯。 +```zc +impl Drop for MyStruct { + fn drop(self) { + self.free(); + } +} +``` + +### 9. 面向對象編程 + +#### 方法 +使用 `impl` 為類型定義方法。 +```zc +impl Point { + // 靜態方法 (構造函數慣例) + fn new(x: int, y: int) -> Self { + return Point{x: x, y: y}; + } + + // 實例方法 + fn dist(self) -> float { + return sqrt(self.x * self.x + self.y * self.y); + } +} +``` + +#### Trait +定義共享行為。 +```zc +struct Circle { radius: f32; } + +trait Drawable { + fn draw(self); +} + +impl Drawable for Circle { + fn draw(self) { ... } +} + +let circle = Circle{}; +let drawable: Drawable = &circle; +``` + +#### 標準 Trait +Zen C 包含與語言語法集成的標準 Trait。 + +**Iterable** + +實現 `Iterable<T>` 以便為你的自定義類型啟用 `for-in` 循環。 + +```zc +import "std/iter.zc" + +// 定義一個迭代器 +struct MyIter { + curr: int; + stop: int; +} + +impl MyIter { + fn next(self) -> Option<int> { + if self.curr < self.stop { + self.curr += 1; + return Option<int>::Some(self.curr - 1); + } + return Option<int>::None(); + } +} + +// 實現 Iterable +impl MyRange { + fn iterator(self) -> MyIter { + return MyIter{curr: self.start, stop: self.end}; + } +} + +// 在循環中使用 +for i in my_range { + println "{i}"; +} +``` + +**Drop** + +實現 `Drop` 來定義一個在對象超出範圍時運行的析構函數 (RAII)。 + +```zc +import "std/mem.zc" + +struct Resource { + ptr: void*; +} + +impl Drop for Resource { + fn drop(self) { + if self.ptr != NULL { + free(self.ptr); + } + } +} +``` + +> **注意：** 如果一個變量被移動，則原始變量不會調用 `drop`。它遵循 [資源語義](#資源語義-默認移動)。 + +**Copy** + +標記 Trait，用於選擇支持 `Copy` 行為（隱式複製）而不是移動語義。通過 `@derive(Copy)` 使用。 + +> **規則：** 實現了 `Copy` 的類型不得定義析構函數 (`Drop`)。 + +```zc +@derive(Copy) +struct Point { x: int; y: int; } + +fn main() { + let p1 = Point{x: 1, y: 2}; + let p2 = p1; // 已複製！p1 保持有效。 +} +``` + +**Clone** + +實現 `Clone` 以允許顯式複製擁有資源的類型。 + +```zc +import "std/mem.zc" + +struct MyBox { val: int; } + +impl Clone for MyBox { + fn clone(self) -> MyBox { + return MyBox{val: self.val}; + } +} + +fn main() { + let b1 = MyBox{val: 42}; + let b2 = b1.clone(); // 顯式複製 +} +``` + +#### 組合 +使用 `use` 嵌入其他結構體。你可以將它們混合進來（展平字段）或者為它們命名（嵌套字段）。 + +```zc +struct Entity { id: int; } + +struct Player { + // 混入 (未命名): 展平字段 + use Entity; // 直接將 'id' 添加到 Player + name: string; +} + +struct Match { + // 組合 (命名): 嵌套字段 + use p1: Player; // 通過 match.p1 訪問 + use p2: Player; // 通過 match.p2 訪問 +} +``` + +### 10. 泛型 + +結構體和函數的類型安全模板。 + +```zc +// 泛型結構體 +struct Box<T> { + item: T; +} + +// 泛型函數 +fn identity<T>(val: T) -> T { + return val; +} + +// 多參數泛型 +struct Pair<K, V> { + key: K; + value: V; +} +``` + +### 11. 並發 (Async/Await) + +基於 pthreads 構建。 + +```zc +async fn fetch_data() -> string { + // 在後台運行 + return "Data"; +} + +fn main() { + let future = fetch_data(); + let result = await future; +} +``` + +### 12. 元編程 + +#### Comptime +在編譯時運行代碼以生成源碼或打印消息。 +```zc +comptime { + // 在編譯時生成代碼 (寫入 stdout) + println "let build_date = \"2024-01-01\";"; +} + +println "構建日期: {build_date}"; +``` + +#### Embed +將文件嵌入為指定類型。 +```zc +// 默認 (Slice_char) +let data = embed "assets/logo.png"; + +// 類型化嵌入 +let text = embed "shader.glsl" as string; // 嵌入為 C-string +let rom = embed "bios.bin" as u8[1024]; // 嵌入為固定數組 +let wav = embed "sound.wav" as u8[]; // 嵌入為 Slice_u8 +``` + +#### 插件 +導入編譯器插件以擴展語法。 +```zc +import plugin "regex" +let re = regex! { ^[a-z]+$ }; +``` + +#### 泛型 C 宏 +將預處理器宏傳遞給 C。 + +> **提示**：對於簡單的常量，請使用 `def`。當你需要 C 預處理器宏或條件編譯標誌時，請使用 `#define`。 + +```zc +#define MAX_BUFFER 1024 +``` + +### 13. 屬性 + +修飾函數和結構體以修改編譯器行為。 + +| 屬性 | 作用域 | 描述 | +|:---|:---|:---| +| `@must_use` | 函數 | 如果忽略返回值則發出警告。 | +| `@deprecated("msg")` | 函數/結構體 | 使用時發出帶有消息的警告。 | +| `@inline` | 函數 | 提示編譯器進行內聯。 | +| `@noinline` | 函數 | 防止內聯。 | +| `@packed` | 結構體 | 移除字段間的填充。 | +| `@align(N)` | 結構體 | 強制按 N 字节對齊。 | +| `@constructor` | 函數 | 在 main 之前運行。 | +| `@destructor` | 函數 | 在 main 退出後運行。 | +| `@unused` | 函數/變量 | 抑制未使用變量警告。 | +| `@weak` | 函數 | 弱符號鏈接。 | +| `@section("name")` | 函數 | 將代碼放置在特定段中。 | +| `@noreturn` | 函數 | 函數不會返回 (例如 exit)。 | +| `@pure` | 函數 | 函數無副作用 (優化提示)。 | +| `@cold` | 函數 | 函數不太可能被執行 (分支預測提示)。 | +| `@hot` | 函數 | 函數頻繁執行 (優化提示)。 | +| `@export` | 函數/結構體 | 導出符號 (默認可見性)。 | +| `@global` | 函數 | CUDA: 內核入口點 (`__global__`)。 | +| `@device` | 函數 | CUDA: 設備函數 (`__device__`)。 | +| `@host` | 函數 | CUDA: 主機函數 (`__host__`)。 | +| `@comptime` | 函數 | 用於編譯時執行的輔助函數。 | +| `@derive(...)` | 結構體 | 自動實現 Trait。支持 `Debug`, `Eq` (智能派生), `Copy`, `Clone`。 | +| `@<custom>` | 任意 | 將泛型屬性傳遞給 C (例如 `@flatten`, `@alias("name")`)。 | + +#### 自定義屬性 + +Zen C 支持強大的 **自定義屬性** 系統，允許你在代碼中直接使用任何 GCC/Clang 的 `__attribute__`。任何不被 Zen C 編譯器顯式識別的屬性都會被視為泛型屬性並傳遞給生成的 C 代碼。 + +這提供了對高級編譯器特性、優化和鏈接器指令的訪問，而無需在語言核心中提供顯式支持。 + +#### 語法映射 +Zen C 屬性直接映射到 C 屬性： +- `@name` → `__attribute__((name))` +- `@name(args)` → `__attribute__((name(args)))` +- `@name("string")` → `__attribute__((name("string")))` + +#### 智能派生 + +Zen C 提供了尊重移動語義的 "智能派生"： + +- **`@derive(Eq)`**：生成一個通過引用獲取參數的相等性方法 (`fn eq(self, other: T*)`)。 + - 當比較兩個非 Copy 結構體 (`a == b`) 時，編譯器會自動通過引用傳遞 `b` (`&b`) 以避免移動它。 + - 字段上的遞歸相等性檢查也會優先使用指針訪問，以防止所有權轉移。 + +### 14. 內聯匯編 + +Zen C 為內聯匯編提供了一流支持，直接轉譯為 GCC 風格的擴展 `asm`。 + +#### 基本用法 +在 `asm` 塊內編寫原始匯編。字符串會自動拼接。 +```zc +asm { + "nop" + "mfence" +} +``` + +#### Volatile +防止編譯器優化掉具有副作用的匯編代碼。 +```zc +asm volatile { + "rdtsc" +} +``` + +#### 命名約束 +Zen C 通過命名綁定簡化了複雜的 GCC 約束語法。 + +```zc +// 語法: : out(變量) : in(變量) : clobber(寄存器) +// 使用 {變量} 佔位符語法以提高可讀性 + +fn add(a: int, b: int) -> int { + let result: int; + asm { + "add {result}, {a}, {b}" + : out(result) + : in(a), in(b) + : clobber("cc") + } + return result; +} +``` + +| 類型 | 語法 | GCC 等效項 | +|:---|:---|:---| +| **輸出** | `: out(variable)` | `"=r"(variable)` | +| **輸入** | `: in(variable)` | `"r"(variable)` | +| **破壞** | `: clobber("rax")` | `"rax"` | +| **內存** | `: clobber("memory")` | `"memory"` | + +> **注意：** 使用 Intel 語法時（通過 `-masm=intel`），必須確保你的構建配置正確（例如，`//> cflags: -masm=intel`）。TCC 不支持 Intel 語法的匯編。 + +### 15. 構建指令 + +Zen C 支持在源文件頂部使用特殊註釋來配置構建過程，無需複雜的構建系統或 Makefile。 + +| 指令 | 參數 | 描述 | +|:---|:---|:---| +| `//> link:` | `-lfoo` 或 `path/to/lib.a` | 鏈接庫或對象文件。 | +| `//> lib:` | `path/to/libs` | 添加庫搜索路徑 (`-L`)。 | +| `//> include:` | `path/to/headers` | 添加包含頭文件搜索路徑 (`-I`)。 | +| `//> framework:` | `Cocoa` | 鏈接 macOS Framework。 | +| `//> cflags:` | `-Wall -O3` | 向 C 編譯器傳遞任意標誌。 | +| `//> define:` | `MACRO` 或 `KEY=VAL` | 定義預處理器宏 (`-D`)。 | +| `//> pkg-config:` | `gtk+-3.0` | 運行 `pkg-config` 並追加 `--cflags` 和 `--libs`。 | +| `//> shell:` | `command` | 在構建期間執行 shell 命令。 | +| `//> get:` | `http://url/file` | 如果特定文件不存在，則下載該文件。 | + +#### 特性 + +**1. 操作系統守護 (OS Guarding)** +在指令前加上操作系統名稱，以使其僅在特定平台上應用。 +受支持的前綴：`linux:`, `windows:`, `macos:` (或 `darwin:`)。 + +```zc +//> linux: link: -lm +//> windows: link: -lws2_32 +//> macos: framework: Cocoa +``` + +**2. 環境變量展開** +使用 `${VAR}` 語法在指令中展開環境變量。 + +```zc +//> include: ${HOME}/mylib/include +//> lib: ${ZC_ROOT}/std +``` + +#### 示例 + +```zc +//> include: ./include +//> lib: ./libs +//> link: -lraylib -lm +//> cflags: -Ofast +//> pkg-config: gtk+-3.0 + +import "raylib.h" + +fn main() { ... } +``` + +### 16. 關鍵字 + +以下關鍵字在 Zen C 中是保留的。 + +#### 聲明 +`alias`, `def`, `enum`, `fn`, `impl`, `import`, `let`, `module`, `opaque`, `struct`, `trait`, `union`, `use` + +#### 控制流 +`async`, `await`, `break`, `catch`, `continue`, `defer`, `else`, `for`, `goto`, `guard`, `if`, `loop`, `match`, `return`, `try`, `unless`, `while` + +#### 特殊 +`asm`, `assert`, `autofree`, `comptime`, `const`, `embed`, `launch`, `ref`, `sizeof`, `static`, `test`, `volatile` + +#### 常量 +`true`, `false`, `null` + +#### C 保留字 +以下標識符是保留的，因為它們是 C11 中的關鍵字： +`auto`, `case`, `char`, `default`, `do`, `double`, `extern`, `float`, `inline`, `int`, `long`, `register`, `restrict`, `short`, `signed`, `switch`, `typedef`, `unsigned`, `void`, `_Atomic`, `_Bool`, `_Complex`, `_Generic`, `_Imaginary`, `_Noreturn`, `_Static_assert`, `_Thread_local` + +#### 運算符 +`and`, `or` + +--- + +## 標準庫 + +Zen C 包含一個涵蓋基本功能的標準庫 (`std`)。 + +[瀏覽標準庫文檔](docs/std/README.md) + +### 核心模塊 + +| 模塊 | 描述 | 文檔 | +| :--- | :--- | :--- | +| **`std/vec.zc`** | 可增長動態數組 `Vec<T>`。 | [文檔](docs/std/vec.md) | +| **`std/string.zc`** | 堆分配的 `String` 類型，支持 UTF-8。 | [文檔](docs/std/string.md) | +| **`std/queue.zc`** | 先進先出隊列 (環形緩衝區)。 | [文檔](docs/std/queue.md) | +| **`std/map.zc`** | 泛型哈希表 `Map<V>`。 | [文檔](docs/std/map.md) | +| **`std/fs.zc`** | 文件系統操作。 | [文檔](docs/std/fs.md) | +| **`std/io.zc`** | 標準輸入/輸出 (`print`/`println`)。 | [文檔](docs/std/io.md) | +| **`std/option.zc`** | 可選值 (`Some`/`None`)。 | [文檔](docs/std/option.md) | +| **`std/result.zc`** | 錯誤處理 (`Ok`/`Err`)。 | [文檔](docs/std/result.md) | +| **`std/path.zc`** | 跨平台路徑操作。 | [文檔](docs/std/path.md) | +| **`std/env.zc`** | 進程環境變量。 | [文檔](docs/std/env.md) | +| **`std/net.zc`** | TCP 網絡 (套接字)。 | [文檔](docs/std/net.md) | +| **`std/thread.zc`** | 線程與同步。 | [文檔](docs/std/thread.md) | +| **`std/time.zc`** | 時間測量與睡眠。 | [文檔](docs/std/time.md) | +| **`std/json.zc`** | JSON 解析與序列化。 | [文檔](docs/std/json.md) | +| **`std/stack.zc`** | 後進先出棧 `Stack<T>`。 | [文檔](docs/std/stack.md) | +| **`std/set.zc`** | 泛型哈希集合 `Set<T>`。 | [文檔](docs/std/set.md) | + +--- + +## 工具鏈 + +Zen C 提供內置的語言服務器 (LSP) 和 REPL 以增強開發體驗。 + +### 語言服務器 (LSP) + +Zen C 語言服務器 (LSP) 支持標準的 LSP 特性，用於編輯器集成： + +* **轉到定義** +* **查找引用** +* **懸停信息** +* **補全** (函數/結構體名，方法/字段的點補全) +* **文檔符號** (大綱) +* **簽名幫助** +* **診斷** (語法/語義錯誤) + +啟動語言服務器（通常在編輯器的 LSP 設置中配置）： + +```bash +zc lsp +``` + +它通過標準 I/O (JSON-RPC 2.0) 進行通信。 + +### REPL + +Read-Eval-Print Loop 允許你交互式地嘗試 Zen C 代碼。 + +```bash +zc repl +``` + +#### 特性 + +* **交互式編碼**：輸入表達式或語句以立即求值。 +* **持久歷史**：命令保存在 `~/.zprep_history` 中。 +* **啟動腳本**：自動加載 `~/.zprep_init.zc` 中的命令。 + +#### 命令 + +| 命令 | 描述 | +|:---|:---| +| `:help` | 顯示可用命令。 | +| `:reset` | 清除當前會話歷史 (變量/函數)。 | +| `:vars` | 顯示活躍變量。 | +| `:funcs` | 顯示用戶定義的函數。 | +| `:structs` | 顯示用戶定義的結構體。 | +| `:imports` | 顯示活躍導入。 | +| `:history` | 顯示會話輸入歷史。 | +| `:type <expr>` | 顯示表達式的類型。 | +| `:c <stmt>` | 顯示語句生成的 C 代碼。 | +| `:time <expr>` | 基准測試表達式 (運行 1000 次迭代)。 | +| `:edit [n]` | 在 `$EDITOR` 中編輯命令 `n` (默認：最後一條)。 | +| `:save <file>` | 將當前會話保存到 `.zc` 文件。 | +| `:load <file>` | 將 `.zc` 文件加載並執行到會話中。 | +| `:watch <expr>` | 監視表達式 (每次輸入後重新求值)。 | +| `:unwatch <n>` | 移除監視。 | +| `:undo` | 從會話中移除最後一條命令。 | +| `:delete <n>` | 移除索引為 `n` 的命令。 | +| `:clear` | 清屏。 | +| `:quit` | 退出 REPL。 | +| `! <cmd>` | 運行 shell 命令 (如 `!ls`)。 | + +--- + + +## 編譯器支持與兼容性 + +Zen C 旨在與大多數 C11 編譯器配合使用。某些特性依賴於 GNU C 擴展，但這些擴展通常在其他編譯器中也能工作。使用 `--cc` 標誌切換後端。 + +```bash +zc run app.zc --cc clang +zc run app.zc --cc zig +``` + +### 測試套件狀態 + +| 編譯器 | 通過率 | 受支持特性 | 已知局限性 | +|:---|:---:|:---|:---| +| **GCC** | **100%** | 所有特性 | 無。 | +| **Clang** | **100%** | 所有特性 | 無。 | +| **Zig** | **100%** | 所有特性 | 無。使用 `zig cc` 作為替代 C 編譯器。 | +| **TCC** | **~70%** | 基本語法, 泛型, Trait | 不支持 `__auto_type`, 不支持 Intel ASM, 不支持嵌套函數。 | + +> **建議：** 生產環境構建請使用 **GCC**, **Clang**, 或 **Zig**。TCC 非常適合快速原型開發，因為它編譯速度極快，但缺少 Zen C 全面支持所需的一些高級 C 擴展。 + +### 使用 Zig 構建 + +Zig 的 `zig cc` 命令提供了 GCC/Clang 的替代方案，具有出色的跨平台編譯支持。使用 Zig： + +```bash +# 使用 Zig 編譯並運行 Zen C 程序 +zc run app.zc --cc zig + +# 使用 Zig 構建 Zen C 編譯器本身 +make zig +``` + +### C++ 互操作 + +Zen C 可以通過 `--cpp` 標誌生成 C++ 兼容的代碼，從而實現與 C++ 庫的無縫集成。 + +```bash +# 直接使用 g++ 編譯 +zc app.zc --cpp + +# 或者轉譯用於手動構建 +zc transpile app.zc --cpp +g++ out.c my_cpp_lib.o -o app +``` + +#### 在 Zen C 中使用 C++ + +包含 C++ 頭文件並在 `raw` 塊中使用 C++ 代碼： + +```zc +include <vector> +include <iostream> + +raw { + std::vector<int> make_vec(int a, int b) { + return {a, b}; + } +} + +fn main() { + let v = make_vec(1, 2); + raw { std::cout << "Size: " << v.size() << std::endl; } +} +``` + +> **注意：** `--cpp` 標誌會將後端切換為 `g++` 並發出 C++ 兼容的代碼（使用 `auto` 代替 `__auto_type`，使用函數重載代替 `_Generic`，以及對 `void*` 進行顯式轉換）。 + +#### CUDA 互操作 + +Zen C 通過轉譯為 **CUDA C++** 來支持 GPU 編程。這使你在維持 Zen C 人體工程學語法的同時，能夠利用內核中的強大 C++ 特性（模板、constexpr）。 + +```bash +# 直接使用 nvcc 編譯 +zc run app.zc --cuda + +# 或者轉譯用於手動構建 +zc transpile app.zc --cuda -o app.cu +nvcc app.cu -o app +``` + +#### CUDA 特定屬性 + +| 屬性 | CUDA 等效項 | 描述 | +|:---|:---|:---| +| `@global` | `__global__` | 內核函數 (運行在 GPU，從主機調用) | +| `@device` | `__device__` | 設備函數 (運行在 GPU，從 GPU 調用) | +| `@host` | `__host__` | 主機函數 (明確僅 CPU 運行) | + +#### 內核啟動語法 + +Zen C 提供了一個簡潔的 `launch` 語句用於調用 CUDA 內核： + +```zc +launch kernel_name(args) with { + grid: num_blocks, + block: threads_per_block, + shared_mem: 1024, // 可選 + stream: my_stream // 可選 +}; +``` + +這轉譯為：`kernel_name<<<grid, block, shared, stream>>>(args);` + +#### 編寫 CUDA 內核 + +使用帶有 `@global` 的 Zen C 函數語法和 `launch` 語句： + +```zc +import "std/cuda.zc" + +@global +fn add_kernel(a: float*, b: float*, c: float*, n: int) { + let i = thread_id(); + if i < n { + c[i] = a[i] + b[i]; + } +} + +fn main() { + def N = 1024; + let d_a = cuda_alloc<float>(N); + let d_b = cuda_alloc<float>(N); + let d_c = cuda_alloc<float>(N); + defer cuda_free(d_a); + defer cuda_free(d_b); + defer cuda_free(d_c); + + // ... 初始化數據 ... + + launch add_kernel(d_a, d_b, d_c, N) with { + grid: (N + 255) / 256, + block: 256 + }; + + cuda_sync(); +} +``` + +#### 標準庫 (`std/cuda.zc`) +Zen C 為常見的 CUDA 操作提供了一個標準庫，以減少 `raw` 塊的使用： + +```zc +import "std/cuda.zc" + +// 內存管理 +let d_ptr = cuda_alloc<float>(1024); +cuda_copy_to_device(d_ptr, h_ptr, 1024 * sizeof(float)); +defer cuda_free(d_ptr); + +// 同步 +cuda_sync(); + +// 線程索引 (在內核內部使用) +let i = thread_id(); // 全局索引 +let bid = block_id(); +let tid = local_id(); +``` + + +> **注意：** `--cuda` 標誌設置 `nvcc` 為編譯器並隱含 `--cpp` 模式。需要安裝 NVIDIA CUDA Toolkit。 + +### Objective-C 互操作 + +Zen C 可以通過 `--objc` 標誌編譯為 Objective-C (`.m`)，允許你使用 Objective-C 框架（如 Cocoa/Foundation）和語法。 + +```bash +# 使用 clang (或 gcc/gnustep) 編譯 +zc app.zc --objc --cc clang +``` + +#### 在 Zen C 中使用 Objective-C + +使用 `include` 包含頭文件，並在 `raw` 塊中使用 Objective-C 語法 (`@interface`, `[...]`, `@""`)。 + +```zc +//> macos: framework: Foundation +//> linux: cflags: -fconstant-string-class=NSConstantString -D_NATIVE_OBJC_EXCEPTIONS +//> linux: link: -lgnustep-base -lobjc + +include <Foundation/Foundation.h> + +fn main() { + raw { + NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; + NSLog(@"來自 Objective-C 的問候！"); + [pool drain]; + } + println "Zen C 也能正常工作！"; +} +``` + +> **注意：** Zen C 字符串插值通過調用 `debugDescription` 或 `description` 同樣適用於 Objective-C 對象 (`id`)。 + +--- + +## 貢獻 + +我們歡迎各類貢獻！無論是修復 Bug、完善文檔，還是提出新功能建議。 + +### 如何貢獻 +1. **Fork 倉庫**：標準的 GitHub 工作流程。 +2. **創建功能分支**：`git checkout -b feature/NewThing`。 +3. **代碼規範**： + * 遵循現有的 C 風格。 + * 確保所有測試通過：`make test`。 + * 在 `tests/` 中為你的功能添加新測試。 +4. **提交拉取請求**：清晰地描述你的更改。 + +### 運行測試 +測試套件是你最好的朋友。 + +```bash +# 運行所有測試 (GCC) +make test + +# 運行特定的測試 +./zc run tests/test_match.zc + +# 使用不同的編譯器運行 +./tests/run_tests.sh --cc clang +./tests/run_tests.sh --cc zig +./tests/run_tests.sh --cc tcc +``` + +### 擴展編譯器 +* **解析器 (Parser)**：`src/parser/` - 遞歸下降解析器。 +* **代碼生成 (Codegen)**：`src/codegen/` - 轉譯邏輯 (Zen C -> GNU C/C11)。 +* **標準庫 (Standard Library)**：`std/` - 使用 Zen C 本身編寫。 + +--- + +## 致謝與歸属 + +本項目使用了第三方庫。完整許可證文本可在 `LICENSES/` 目錄中找到。 + +* **[cJSON](https://github.com/DaveGamble/cJSON)** (MIT 許可證)：用於語言服務器中的 JSON 解析和生成。 +* **[zc-ape](https://github.com/OEvgeny/zc-ape)** (MIT 許可證)：由 [Eugene Olonov](https://github.com/OEvgeny) 開發的原版 Zen-C 實際上便攜的可執行文件 (APE) 端口。 +* **[Cosmopolitan Libc](https://github.com/jart/cosmopolitan)** (ISC 許可證)：使 APE 成為可能納基礎庫。 |