Dokumentacja H# - Pełny Przewodnik

1. Wstęp do Dokumentacji H#

Witaj w kompleksowej, rozbudowanej dokumentacji języka programowania H#! Ta dokumentacja została zaprojektowana z myślą o początkujących i zaawansowanych użytkownikach, kładąc nacisk na początkowych i zaawansowanych użytkownikach, kładąc nacisk na stabilność, czytelność oraz ogromną ilość praktycznych przykładów kodu. Każdy rozdział zawiera szczegółowe wyjaśnienia, przykłady, wskazówki, ostrzeżenia oraz tabele referencyjne. Dokumentacja jest podzielona na logiczne sekcje, z bocznym menu dla łatwej nawigacji.

H# (H Sharp) to nowoczesny język interpretowany, zoptymalizowany pod kątem szybkości dzięki JIT compilation, wsparciu dla bytecode i elastycznemu zarządzaniu pamięcią. Język jest rozwijany przez zespół HackerOS i jest idealny do skryptowania, aplikacji desktopowych oraz eksperymentów z niskopoziomowymi operacjami pamięci.

Pliki źródłowe H# mają rozszerzenie .hcs. Interpreter H# parsuje kod, kompiluje do bytecode (z cache'em dla szybkości) i wykonuje z użyciem JIT dla kluczowych części.

2. Instalacja i Uruchamianie Programów

Aby zainstalować H#, postępuj zgodnie z instrukcjami w sekcji Pobierz. Po instalacji, uruchom program za pomocą:

h# -i plik.hcs

Lub w trybie interaktywnym (REPL):

h# repl

Wymagania systemowe:

• Linux (zalecany HackerOS)
• Rust 1.92+ (do budowania z źródła)
• odin (dla narzedzia cli virus)
• c (opcjonalne jeżeli chcesz równiez od zera kompilować hsaa czy hssm czy hsmm)
• Biblioteki: libloading, dynasmrt, serde, bincode, sha2, hex, users

Budowanie z Źródła:

cargo build --release
wejdz do folderu source-code i nastepnie do h# i potem hs1 h2 i h3 i opcjonalnie virus (binarka hs1 hs2 hs3 musza trafić do /home/root/.H#/bin/) natomiast reszta binarke do /usr/bin/
./target/release/h# plik.hcs

3. Podstawy: Struktura Pliku .hcs

Plik .hcs może zaczynać się od deklaracji trybu pamięci (opcjonalnie). Następnie umieszczasz globalne deklaracje, funkcje i instrukcje. Komentarze: @ dla liniowych, *@ ... @* dla blokowych.

Przykład minimalnego programu:

---auto---
@ Prosty program H#
log "Witaj w H#!";
log 2 + 3; @ Wyświetli 5

Wyjaśnienie: Kod jest wykonywany sekwencyjnie. log to wbudowana funkcja do outputu. Semi-kolumna (;) jest opcjonalna na końcu linii.

Konwencje kodowania:

• Indentacja: 4 spacje lub tab (zalecane spacje dla konsystencji).
• Nazwy: Snake_case dla zmiennych, CamelCase dla typów.
• Bloki: Zawsze w [] dla czytelności.

4. Zmienne i Typy Danych

Deklaruj zmienne za pomocą let (immutable) lub mut (mutable). Typy są inferowane, ale jawne typy poprawiają czytelność i pozwalają na błędy w kompilacji.

Lista typów:

Przykłady:

let stała: Number = 100;
mut zmienna: String = "H#";
zmienna += " jest super!";
log zmienna; @ H# jest super!

Konwersje typów: H# automatycznie konwertuje w wyrażeniach (np. int + float → float).

Zaawansowane: Typy użytkownika

type MojaLista = List<Number>;

5. Operatory i Wyrażenia

Operatory mają standardowe priorytety (MUL > ADD > REL > EQ > LOGIC). Wsparcie dla łańcuchowania (np. 1 < x < 10).

Pełna tabela operatorów:

Przykłady złożonych wyrażeń:

let wynik = (5 + 3) * 2 > 10 and true; @ true
let str = "Liczba: ${2 + 2}"; @ Liczba: 4

6. Funkcje

Funkcje to bloki kodu wielokrotnego użycia. Wsparcie dla parametrów domyślnych, typów, rest args i closures.

Syntax:

func nazwa(param1: Typ = domyślny, ...rest: List<Any>): Zwrotny [
    @ Ciało
    return wartość;
]

Przykłady:

func suma(...liczby: List<Number>): Number [
    mut total = 0;
    for l in liczby [ total += l; ]
    return total;
]
log suma(1, 2, 3); @ 6

Closures (funkcje anonimowe):

let mnoznik = func(x) [ return func(y) [ return x * y; ]; ];
let razy2 = mnoznik(2);
log razy2(5); @ 10

Natywne funkcje:

native "system"("echo Hello"); @ Wywołuje komendę systemową

7. Struktury Kontrolne

H# oferuje pełne wsparcie dla warunkowych i pętli, z obsługą break/continue/return/throw.

If-Else (z chaining):

if x > 10 [
    log "Duże";
] else if x > 5 [
    log "Średnie";
] else if x > 0 [
    log "Małe";
] else [
    log "Negatywne";
]

While i Do-While (emulowane):

mut i = 0;
while i < 10 [
    log i;
    i += 1;
]
@ Emulacja do-while
mut j = 0;
loop [
    log j;
    j += 1;
    if j >= 10 [ break; ]
]

For (iteracja, range, multiple vars):

for i in 1..10 [ log i; ] @ 1 do 9
for klucz, wartosc in mapa [
    log "${klucz}: ${wartosc}";
]

Match (pattern matching):

match wartosc [
    case 1 or 2: [ log "Mała"; ]
    case pat where pat > 10: [ log "Duża"; ] @ Zaawansowane patterny
    default: [ log "Inna"; ]
]

Try-Catch-Finally (finally emulowane):

try [
    let div = 10 / 0;
] catch (err) [
    log "Błąd: ${err}";
] finally [ @ Emulacja via defer-like
    log "Czyszczenie";
]

8. Kolekcje: Listy, Mapy i Zbiory

Listy i mapy są wbudowane z metodami. Zbiory emulowane via mapy z null wartościami.

Metody List:

mut lista = [3, 1, 4];
lista.sort();
log lista; @ [1, 3, 4]

Metody Map:

mut mapa = ["a": 1, "b": 2];
mapa.remove("a");
log mapa.len(); @ 1

Emulacja Zbiorów:

mut zbior = ["val1": null, "val2": null];
if zbior.has("val1") [ log "Istnieje"; ]

9. Obiekty, Klasy i Prototypy

Obiekty to struktury z polami i metodami. Wsparcie dla konstruktorów, getterów/setterów i prototypowego dziedziczenia.

Definicja obiektu:

object Figura [
    let typ: String;
    func area(): Number [ return 0; ] @ Metoda wirtualna
]
object Kwadrat extend Figura [
    let bok: Number;
    func area(): Number [ return self.bok ^ 2; ]
    func new(b: Number) [ self.bok = b; self.typ = "Kwadrat"; ]
]
let kw = new Kwadrat(5);
log kw.area(); @ 25

Prototypy i Dziedziczenie:

object Dziecko extend Rodzic [
    @ Nadpisuje metody rodzica
]

Zaawansowane: Mixins:

object Mixin [
    func mixinMetoda() [ log "Mixin"; ]
]
object Klasa extend Mixin, Figura [ ... ]

10. Importy, Moduły i Biblioteki

Modułowość poprzez importy. Wsparcie dla repozytorii i dynamicznego ładowania (require).

Import:

import ; @ Z repo 'virus', lib 'utils'
log utils.funkcja();

Require:

require ; @ Ładuje bibliotekę dynamiczną

Eksporty w modułach:

W plikach modułów używaj globalnych func/object do eksportu.

@ modul.hcs
func eksportowana() [ ... ]

11. Zarządzanie Pamięcią i Tryby

H# oferuje trzy tryby dla elastyczności: Auto (szybki), Manual (kontrola), Safe (bezpieczny).

Porównanie trybów:

Przykłady użycia:

---manual---
let ptr = hsmm_malloc(1024);
@ Użyj ptr
hsmm_free(ptr);

---safe---
let arc = hssm_arc_new(data, deleter, size, cloner);
let data = hssm_arc_get(arc);
hssm_arc_drop(arc);

Zaawansowane: Copy-on-Write w Safe:

let mut_data = hssm_arc_make_mut(&arc);

12. Zaawansowane Tematy

Bytecode i Kompilacja:

Kod jest kompilowany do bytecode (OpCode), cache'owany via SHA256 hash. JIT (DynASM) optymalizuje pętle i expr.

@ Przykładowy bytecode: LoadConst, Add, Print

FFI i Integracja:

extern "C" fn moja_funkcja() { ... }
native "moja_funkcja"();

Współbieżność:

Planowana w przyszłości; obecnie single-threaded. Używaj ARC dla bezpiecznych shared data.

Meta-programowanie:

@ Makra emulowane via func generujące kod jako stringi

13. Błędy, Debugowanie i Testowanie

Parser używa Chumsky + Ariadne dla kolorowych błędów. Runtime błędy rzucane via throw.

Obsługa błędów:

try [ ... ] catch (e) [ log e; ]

Debugowanie:

• Używaj log do trace.
• Breakpointy via native "debug_break"().
• Stack traces w błędach runtime.

Testy jednostkowe:

func test_dodaj() [
    assert 2 + 2 == 4, "Błąd dodawania";
]

14. Optymalizacje i Wydajność

H# jest zoptymalizowany via JIT i bytecode cache. Wskazówki:

1. Używaj Auto dla prędkości.
2. Unikaj alokacji w pętlach.
3. Używaj natywnych dla hot paths.
4. Profiluj via external tools (perf).
5. K Batch operacje na kolekcjach.

Porównanie wydajności:

W benchmarkach H# jest 2-5x szybszy od Pythona w pętlach dzięki JIT.

15. Przykłady Projektów

Prosty Serwer HTTP (używając native):

import <core:net>;
func main() [
    let server = net.server(8080);
    while true [
        let req = server.accept();
        req.respond("HTTP/1.1 200 OK\n\nWitaj!");
    ]
]
main();

Gra Tic-Tac-Toe:

@ Pełny kod gry z planszą, turami, wygraną (ok. 100 linii)

Analizator Danych:

import <core:stats>;
let dane = [1,2,3,4,5];
log stats.mean(dane); @ 3

Skrypt Automatyzacji:

require <system:fs>;
for file in fs.dir(".") [
    if file.ends_with(".txt") [ fs.remove(file); ]
]

16. FAQ - Często Zadawane Pytania

Jak zainstalować H#?

Sprawdź sekcję Pobierz.

Dlaczego H# jest szybki?

Dzięki JIT i bytecode cache.

Czy H# wspiera GUI?

Tak, via require bibliotek jak GTK lub Qt.

Jak zgłosić błąd?

Na GitHub repo HackerOS/H#.

Czy H# jest thread-safe?

W trybie Safe tak, ale core jest single-threaded.

17. Dodatkowe Zasoby i Społeczność

• GitHub: Repo H#
• Forum: Forum H#
• Źródła: Pełny kod interpretera/translatora w Rust/C/Odin
• Kontributcja: Pull requests mile widziane!

Dokumentacja ostatnia aktualizacja: Styczeń 2026. Wersja H#: 0.4