# Iron

> Iron is a general-purpose, statically typed native language that compiles to C. It favors explicit control and readable code: no garbage collector, no operator overloading, no implicit conversions, and no package manager.

Key rules for writing Iron (the language is in alpha; older examples online
may use removed syntax):

- Comments start with `--`. Blocks use braces; no semicolons.
- `val` is immutable, `var` is mutable. A binding must be `var` to be
  reassigned, to have its fields written, or to call a mutating method.
- String interpolation: `"{name} has {hp} HP"`. Print with `println`.
- Methods are declared inside `object` blocks and use `self.`; constructors
  are `init` blocks. `match` arms use `->`.
- Multiple results use tuples: `func f() -> (Int, Int)` and `val (a, b) = f()`.
- Stdlib calls go through the capitalized module object after importing the
  lowercase module: `import io` then `IO.read_file(path)`.
- No package manager: copy third-party Iron code into `vendor/`; `iron build`
  compiles it with the project.

## Docs

- [Iron reference manual](https://ironlang.dev/llms/reference.md): the complete language definition: lexical rules, types, expressions, statements, declarations, memory, concurrency, comptime, the standard library and every diagnostic code; every example is compiled in CI (HTML version at /docs/)
- [Iron language guide for LLMs](https://ironlang.dev/llms/iron.md): syntax, objects, enums, memory, concurrency, stdlib usage, and known gaps; every example is compiled in CI
- [Networking guide](https://ironlang.dev/llms/networking.md): TCP, UDP, DNS, HTTP/HTTPS, REST servers, WebSocket
- [JSON guide](https://ironlang.dev/llms/json.md): JSON values, strict parsing, serialization, JsonWriter and JsonReader streaming, encoding your own types
- [Cryptography guide](https://ironlang.dev/llms/crypto.md): binary data as String, hashing, HMAC and request signing, key derivation, password hashing, random numbers, authenticated encryption, RSA-OAEP, hex and base64
- [MySQL guide](https://ironlang.dev/llms/mysql.md): connecting, TLS and auth, prepared statements, typed results, transactions, connection pools, errors (HTML version at /mysql/)
- [Runnable examples](https://ironlang.dev/llms/examples.md): small complete programs
- [Project guide](https://ironlang.dev/llms/guide.md): iron init/build/run/check/test, iron.toml, vendoring (HTML version at /guide/)
- [Raylib guide](https://ironlang.dev/llms/raylib.md): windows, 2D and 3D drawing, input, audio, shaders and the examples (HTML version at /raylib/, API reference at /raylib/reference/)

## Standard library

- [io](https://ironlang.dev/llms/stdlib/io.md): Files, directories, and paths: read, write, copy, move, list, file info
- [math](https://ironlang.dev/llms/stdlib/math.md): Math functions and constants on the Math object
- [time](https://ironlang.dev/llms/stdlib/time.md): Clock, sleep, timers, durations
- [log](https://ironlang.dev/llms/stdlib/log.md): Leveled logging
- [net](https://ironlang.dev/llms/stdlib/net.md): TCP, UDP, and DNS
- [http](https://ironlang.dev/llms/stdlib/http.md): HTTP/HTTPS clients and servers, REST, static files
- [websocket](https://ironlang.dev/llms/stdlib/websocket.md): WebSocket and secure WebSocket clients and servers
- [url](https://ironlang.dev/llms/stdlib/url.md): URL parsing, building, resolving, and percent-encoding
- [json](https://ironlang.dev/llms/stdlib/json.md): JSON values, strict parser, serializer and streaming writer
- [crypto](https://ironlang.dev/llms/stdlib/crypto.md): Hashing, HMAC, HKDF, PBKDF2, scrypt, password hashing, secure random, AES-GCM and ChaCha20-Poly1305, RSA-OAEP
- [encoding](https://ironlang.dev/llms/stdlib/encoding.md): Hex and base64 (standard and URL-safe) encoders and decoders
- [mysql](https://ironlang.dev/llms/stdlib/mysql.md): MySQL and MariaDB client: TLS, prepared statements, typed results, connection pool
- [string](https://ironlang.dev/llms/stdlib/string.md): String methods
- [list](https://ironlang.dev/llms/stdlib/list.md): List methods (map, filter, reduce, sum)
- [int](https://ironlang.dev/llms/stdlib/int.md): Integer to_string
- [float](https://ironlang.dev/llms/stdlib/float.md): Float to_string
- [box](https://ironlang.dev/llms/stdlib/box.md): Box[T]: checked single-owner heap box
- [arena](https://ironlang.dev/llms/stdlib/arena.md): Arena allocation
- [channel](https://ironlang.dev/llms/stdlib/channel.md): Channels for message passing between tasks
- [mutex](https://ironlang.dev/llms/stdlib/mutex.md): Mutex
- [rwlock](https://ironlang.dev/llms/stdlib/rwlock.md): Read-write lock
- [filehandle](https://ironlang.dev/llms/stdlib/filehandle.md): Low-level file handles
- [rawptr](https://ironlang.dev/llms/stdlib/rawptr.md): Raw pointers for FFI
- [hashable](https://ironlang.dev/llms/stdlib/hashable.md): Hashable interface for map keys
- [hint](https://ironlang.dev/llms/stdlib/hint.md): Hint.black_box to keep values from being optimized away
- [map](https://ironlang.dev/llms/stdlib/map.md): Map[K, V]: hash table (put, get, get_or, has, remove, keys, values)
- [set](https://ironlang.dev/llms/stdlib/set.md): Set[T]: hash set (add, has, remove, values)

## Optional

- [llms-full.txt](https://ironlang.dev/llms-full.txt): the reference manual, guide, networking and crypto guides, stdlib declarations, and examples in one file
- [raylib](https://ironlang.dev/llms/stdlib/raylib.md): Raylib bindings for graphics, input, and audio (large)
- [Raylib API reference](https://ironlang.dev/raylib/reference/types.html): fourteen HTML pages, one per category