Panduan bertahap · Indonesia / English · compiler preview 0.1.0

Belajar YAZA dari satu baris pertama.

Panduan ini memecah sintaks menjadi pelajaran kecil: contoh, hasil, arti setiap bagian, dan status dukungannya. YAZA masih berkembang; contoh mengacu pada kemampuan compiler native yang tercatat di repository.

Coba contoh di Playground

Status materi: development preview.

Playground menjalankan subset sintaks di browser. Contoh file, proses, PostgreSQL, dan API harus dijalankan melalui CLI native. Status dukungan dijelaskan pada tiap pelajaran.

Cara membaca contoh YAZA

Cuplikan menunjukkan kode dalam file .yz. Nama tipe menjelaskan bentuk nilai, titik dua membuka blok, dan indentasi empat spasi menunjukkan baris mana yang berada di dalam blok. Tombol Salin kode menyalin hanya cuplikan tersebut.

Label Didukung berarti sintaks terlihat pada compiler/library saat ini; itu bukan jaminan bahwa API stabil atau siap produksi. Preview browser berarti contoh sederhana dapat dicoba di halaman Playground.

00 · Bagian terkecil dari sintaks

Sebelum membaca program, kenali potongan kecil yang dibaca compiler. File sumber YAZA memakai ekstensi .yz. Huruf besar dan kecil dibedakan: Text, text, dan TEXT adalah ejaan yang berbeda.

small_parts.yz
# A whole-line comment
start:
    let price: Number = 7
    var total: Number = price * 3
    set total = total + 1
    say "Total: {total}"
Total: 22
PotonganArtinyaContoh penggunaan
#Mulai komentar sampai ujung baris.# note
start, let, sayKata khusus bahasa: titik mulai, deklarasi tetap, dan output.let total: Number = 22
price, totalIdentifier atau nama yang dipilih programmer. Nama identifier dimulai huruf atau garis bawah, lalu boleh berisi angka.find_score
7, true, "YAZA"Literal: nilai yang ditulis langsung di source. Angka tidak memakai tanda kutip; teks memakai kutip ganda.42, false
:Mengakhiri header blok atau memisahkan nama variabel dan anotasi tipenya.start: · price: Number
=Memberi nilai awal atau nilai baru melalui set; bukan operator perbandingan.set total = 10
(), ,Kurung membatasi argumen fungsi; koma memisahkan argumen.add(2, 3)
[]Menuliskan parameter tipe list, misalnya list berisi Number.List[Number]
.Mengakses field milik sebuah nilai shape.product.price
->Menyatakan tipe hasil fungsi, bukan nilai yang dikembalikan.fn add(...) -> Number:
Empat spasiMenentukan baris mana yang termasuk ke dalam blok. Gunakan indentasi konsisten; jangan campur tab dan spasi.start: lalu say ...

Baris program selesai saat baris baru tiba; tidak perlu titik koma. Tanda kurung kurawal untuk blok tidak dipakai. Pada ekspresi, tanda kurung (...) dapat mengelompokkan perhitungan; perkalian/pembagian dikerjakan sebelum penjumlahan/pengurangan, lalu perbandingan, and, dan or. Gunakan tanda kurung bila urutannya ingin terlihat jelas.

01 · Program pertama: Hello World

Buat file hello.yz. Baris pertama menyatakan titik mulai; baris kedua mencetak teks.

hello.yz
start:
    say "Hello, world!"
Hello, world!
  1. start:

    Titik masuk program. Compiler menjalankan isi blok ini. Tanda : membuka blok.

  2. say

    Perintah output YAZA. Nilai setelahnya ditampilkan sebagai satu baris.

  3. "Hello, world!"

    Nilai teks literal. Tanda kutip membedakan teks dari nama variabel atau kata bahasa.

  4. 4 spaces

    Indentasi menandakan bahwa say berada di dalam start. Pakai empat spasi secara konsisten.

02 · Komentar dan blok

Tanda # memulai komentar sampai akhir baris. Komentar membantu manusia; compiler mengabaikannya. YAZA memakai indentasi dan tanda titik dua untuk menandai blok, bukan kurung kurawal.

comments.yz
# This is a comment.
start:
    # This statement belongs to start.
    say "Comments do not run."
  1. # ...

    Keterangan di baris ini tidak menjadi output dan tidak mengubah nilai program.

  2. start:

    Membuka blok utama dengan indentasi nol.

  3. say ...

    Empat spasi menempatkan perintah dalam blok. Salah indentasi akan membuat batas blok keliru.

03 · Variabel: let, var, dan set

let membuat binding yang tidak dapat diganti. var membuat binding yang boleh diperbarui; set melakukan pembaruan. Setiap deklarasi menuliskan tipe setelah nama.

variables.yz
start:
    let name: Text = "Dina"
    var attempts: Number = 1
    set attempts = attempts + 1
    say name
    say attempts
Dina
2
  1. let name

    Membuat nama name dengan nilai yang tidak dapat ditimpa oleh perintah set.

  2. : Text

    Anotasi tipe menyatakan bahwa nilainya berupa teks. Nilai awal harus cocok dengan tipe ini.

  3. var attempts

    Nilai ini boleh diubah karena dideklarasikan dengan var.

  4. set attempts = ...

    Membaca nilai lama, menambah satu, lalu menyimpan hasilnya kembali.

  5. say name

    Tanpa tanda kutip, name berarti baca nilai variabel. Dengan kutip, "name" adalah teks literal.

04 · Tipe data yang tersedia

Tipe diperiksa compiler. Berikut tipe inti yang dipakai pada contoh saat ini; tipe turunan dan library memiliki batas dukungan masing-masing.

TipeArtiContoh
TextTeks UTF-8 yang direpresentasikan sebagai string berakhiran NUL pada runtime native."YAZA"
NumberInteger bertanda 64-bit pada compiler native.42
Int32Integer bertanda 32-bit dengan rentang yang diperiksa.int32_from_number(42)
Float64Bilangan pecahan 64-bit; operasi non-finite ditolak pada jalur yang diperiksa.float64_parse("1.25")
BooleanNilai logika true atau false.true
TextListDaftar teks untuk API list dasar.text_split("a,b", ",")
List[T]Daftar bertipe yang elemennya memiliki tipe T, misalnya List[Number] atau List[Product].List[Number]()
BytesData biner dengan panjang eksplisit dan batas ukuran per nilai.bytes_from_text("abc")
shape, variantTipe data buatan programmer; dipelajari di pelajaran 15–16.Product, DeliveryState
Option[T], Result[T,E]Tipe pembungkus untuk nilai opsional dan hasil sukses/gagal.Option[Text]

Koleksi umum yang tersedia saat ini adalah TextList dan List[T]. Tipe tuple, set, dan map/dictionary belum tersedia sebagai koleksi umum. TextList hanya menyimpan teks, bukan pasangan kunci dan nilai.

05 · Teks, interpolation, panjang, dan pencarian

Teks diapit tanda kutip ganda. Bentuk {namaVariabel} menyisipkan nilai variabel ke dalam teks. Fungsi text_length mengukur byte UTF-8, sedangkan text_find memberi offset byte atau -1 jika tidak ditemukan.

text_search.yz
start:
    let language: Text = "YAZA"
    let message: Text = "Belajar {language}"
    let position: Number = text_find(message, "YAZA")
    let missing: Number = text_find(message, "Rust")
    say message
    say text_length(message)
    say position
    say missing
Belajar YAZA
12
8
-1
  1. {language}

    Compiler mengganti placeholder dengan isi variabel language.

  2. text_find(text, needle)

    Mencari teks kedua di dalam teks pertama. Contoh memakai karakter ASCII agar offset byte mudah dibaca; teks multibyte menghasilkan offset byte, bukan indeks karakter.

  3. text_split / text_join

    Memecah satu teks menjadi TextList atau menggabungkan list dengan pemisah. Pemisah kosong tidak valid untuk text_split.

06 · Angka, aritmetika, dan konversi

Number dipakai untuk integer umum; Int32 untuk integer dengan batas 32-bit; Float64 untuk pecahan. Konversi ditulis eksplisit supaya batas dan perubahan representasi terlihat.

numbers.yz
start:
    let width: Number = 7
    let height: Number = 6
    let area: Number = width * height
    let price: Int32 = int32_from_number(1499)
    let ratio: Float64 = float64_from_number(3)
    say area
    say int32_text(price)
    say float64_text(ratio)
42
1499
3
  1. + - * /

    Operator aritmetika bekerja pada nilai numerik. Pembagian Number adalah pembagian integer; gunakan Float64 untuk hasil pecahan.

  2. int32_from_number

    Memeriksa bahwa nilai berada pada rentang Int32. Konversi yang di luar rentang gagal, bukan diam-diam dipotong.

  3. float64_from_number

    Mengubah integer menjadi Float64. Fungsi pasangan seperti number_from_int32, float64_parse, dan float64_text tersedia untuk konversi lain.

07 · Operator perbandingan dan logika

==, !=, <, <=, >, dan >= membandingkan nilai. Operator and, or, dan not menggabungkan atau membalik kondisi Boolean.

operators.yz
start:
    let age: Number = 20
    let has_ticket: Boolean = true
    let can_enter: Boolean = age >= 17 and has_ticket
    say can_enter
    say not has_ticket
true
false

Gunakan == untuk membandingkan. Satu tanda = dipakai saat memberi nilai awal, bukan untuk membandingkan.

08 · Kondisi: if, elif, else

Pilih blok dengan if. Jika kondisi pertama salah, elif memeriksa kondisi berikutnya; else menangani sisa kemungkinan.

conditions.yz
fn label(score: Number) -> Text:
    if score < 75:
        return "Practice more"
    elif score == 75:
        return "On the line"
    else:
        return "Passed"

start:
    say label(82)
    say label(70)
Passed
Practice more
  1. if score < 75:

    Kondisi harus menghasilkan Boolean. Jika benar, jalankan blok yang menjorok di bawahnya.

  2. elif

    Hanya diperiksa bila cabang sebelumnya tidak dipilih. Beberapa elif dapat dirangkai.

  3. return

    Menghentikan fungsi dan mengembalikan nilai yang tipenya sesuai anotasi setelah tanda panah.

09 · Perulangan while

while mengulang blok selama kondisi benar. Perbarui variabel kondisi agar loop selesai; compiler tidak otomatis menghentikan loop yang tidak berujung.

while.yz
start:
    var count: Number = 1
    while count <= 3:
        say count
        set count = count + 1
1
2
3

Urutannya: uji kondisi, jalankan isi loop, ubah count, lalu uji lagi. Kata break dapat keluar lebih awal; continue lompat ke iterasi berikutnya.

10 · Perulangan for, range, break, continue

for mengunjungi setiap nilai pada range atau list. Pada 1..6, batas akhir tidak ikut: hasilnya 1 sampai 5.

for_loop.yz
start:
    for value in 1..6:
        if value == 3:
            continue
        if value == 5:
            break
        say value
1
2
4
  1. for value in ...

    Memberi nama value pada nilai saat ini selama satu putaran.

  2. continue

    Melewati say saat nilainya 3 dan melanjutkan loop.

  3. break

    Mengakhiri seluruh loop saat nilainya 5.

11 · Fungsi, parameter, dan hasil

Fungsi diberi nama dengan fn. Setiap parameter dan hasil memiliki tipe. Fungsi membuat langkah yang dapat dipanggil dari beberapa tempat.

functions.yz
fn add(left: Number, right: Number) -> Number:
    return left + right

fn twice(value: Number) -> Number:
    return add(value, value)

start:
    let result: Number = twice(21)
    say result
42
  1. fn add(...)

    Nama fungsi diikuti daftar parameter. Setiap parameter ditulis nama: Tipe.

  2. -> Number

    Menyatakan tipe hasil fungsi. Tanda panah bukan operator di dalam baris pengembalian.

  3. add(value, value)

    Memanggil fungsi lain dan meneruskan dua argumen bertipe Number.

12 · List: TextList dan List[T]

List dibuat bertipe dan diisi satu per satu. TextList adalah bentuk list khusus teks; List[Number] menyimpan integer, dan List[Product] dapat menyimpan nilai shape.

lists.yz
start:
    var scores: List[Number] = List[Number]()
    list_push(scores, 82)
    list_push(scores, 95)
    let count: Number = list_count(scores)
    let first: Number = list_get(scores, 0)
    list_set(scores, 0, 90)
    say count
    say first
    say list_get(scores, 0)
2
82
90
  1. List[Number]()

    Membuat list kosong dengan tipe elemen Number. Tipe tidak boleh dicampur sembarang.

  2. list_push

    Menambahkan item ke akhir list. Tipe item harus cocok dengan T.

  3. list_get(list, index)

    Mengambil item berdasarkan indeks mulai dari nol. Indeks di luar rentang merupakan error.

  4. list_try_get

    Mengembalikan Option[T] sehingga indeks negatif/di luar list dapat ditangani tanpa akses langsung yang gagal.

  5. list_set

    Mengganti item yang sudah ada pada indeks tertentu; tidak menambahkan elemen baru di luar panjang list.

Untuk teks, gunakan text_find. Untuk mencari nilai dalam typed list, belum ada fungsi umum list_find; tulis loop, bandingkan item, lalu kembalikan indeks atau penanda -1.

linear_search.yz
fn find_score(values: List[Number], target: Number) -> Number:
    var index: Number = 0
    while index < list_count(values):
        if list_get(values, index) == target:
            return index
        set index = index + 1
    return -1

start:
    var scores: List[Number] = List[Number]()
    list_push(scores, 82)
    list_push(scores, 95)
    list_push(scores, 76)
    say find_score(scores, 95)
    say find_score(scores, 100)
1
-1
  1. index = 0

    Pencarian dimulai dari item pertama. Indeks list YAZA dimulai dari nol.

  2. list_get(...) == target

    Bandingkan satu item dengan nilai yang dicari. Ini disebut linear search karena item diperiksa berurutan.

  3. return index

    Menghentikan pencarian ketika ditemukan. Jika loop selesai, fungsi mengembalikan -1.

Biaya pencarian ini bertambah sebanding dengan jumlah item: untuk list berisi n item, kasus terburuk memeriksa n item. Belum ada index/hash map umum bawaan.

Membaca fungsi pencarian satu bagian demi satu bagian

KodeYang terjadi
fn find_score(...)Mendeklarasikan fungsi pencarian. Ia menerima list bernama values dan satu nilai target; keduanya bertipe Number.
-> NumberHasil fungsi adalah angka yang dipakai sebagai indeks. Konvensi contoh ini memakai -1 untuk “tidak ditemukan”.
var index = 0Membuat penghitung posisi mulai dari indeks pertama. Indeks pertama bernomor 0, yang kedua 1, dan seterusnya.
while index < list_count(values)Mengulang hanya selama indeks masih lebih kecil dari jumlah item. Bila jumlah item 3, indeks validnya 0, 1, 2; kondisi ini mencegah baca indeks 3.
list_get(values, index)Mengambil nilai pada posisi saat ini. Akses langsung aman karena kondisi while membatasi indeks.
== targetMembandingkan item dan target. Hasil perbandingan adalah Boolean, yaitu true atau false.
return indexMengakhiri fungsi segera saat item sama. Jika ada nilai kembar, linear search ini mengembalikan kecocokan pertama.
set index = index + 1Jika tidak cocok, maju satu posisi. Tanpa pembaruan ini loop akan terus memeriksa item yang sama.
return -1Dicapai hanya setelah semua item diperiksa tanpa kecocokan. Untuk list kosong, loop langsung dilewati lalu hasilnya juga -1.
list_push(...)Menyusun data contoh menjadi [82, 95, 76]. Argumen kedua pada find_score(scores, 95) adalah nilai yang dicari, bukan indeks.

Jejak pencarian 95: indeks 0 berisi 82 (tidak cocok), indeks 1 berisi 95 (cocok), maka hasilnya 1 dan indeks 2 tidak pernah diperiksa. Jejak pencarian 100: 82 → 95 → 76 (semuanya tidak cocok), lalu hasilnya -1.

Syarat penting: data harus terurut naik.

Binary search membuang setengah ruang pencarian pada tiap langkah. Jika urutan list tidak benar, hasilnya bisa salah meskipun target ada. Untuk list kecil atau data yang belum diurutkan, gunakan linear search di atas.

binary_search.yz
fn binary_search(values: List[Number], target: Number) -> Number:
    var low: Number = 0
    var high: Number = list_count(values) - 1
    while low <= high:
        let middle: Number = low + (high - low) / 2
        let current: Number = list_get(values, middle)
        if current == target:
            return middle
        elif current < target:
            set low = middle + 1
        else:
            set high = middle - 1
    return -1

start:
    var ordered: List[Number] = List[Number]()
    list_push(ordered, 7)
    list_push(ordered, 19)
    list_push(ordered, 42)
    list_push(ordered, 61)
    list_push(ordered, 85)
    say binary_search(ordered, 42)
    say binary_search(ordered, 50)
2
-1
NamaPeran
lowBatas indeks paling kiri yang belum dieliminasi.
highBatas indeks paling kanan yang belum dieliminasi. Nilai awal jumlah item dikurangi satu.
middleTitik tengah rentang aktif. Rumus low + (high - low) / 2 memilih indeks integer di tengah.
current < targetSemua angka di kiri atau sama dengan current tidak mungkin menjadi target; geser low melewati tengah.
elseKarena nilai tidak sama dan tidak lebih kecil, ia lebih besar. Geser high ke kiri tengah.
low > highRentang kosong berarti target tidak ada. Loop berhenti dan fungsi mengembalikan -1.

Jejak untuk target 50 di list [7, 19, 42, 61, 85]: tengah indeks 2 adalah 42, jadi cari kanan; tengah indeks 3 adalah 61, jadi cari kiri; kini batas bertemu terbalik, sehingga hasilnya -1. Jumlah pemeriksaan tumbuh kira-kira seperti log₂(n). Bila ada angka kembar, contoh ini boleh mengembalikan salah satu indeks yang berisi nilai itu, tidak dijamin indeks pertama.

14 · Sorting: urutkan angka dengan selection sort

Compiler belum menyediakan list_sort. Contoh ini mengajarkan algoritma selection sort memakai list_get dan list_set: setiap putaran mencari nilai terkecil di bagian yang belum urut, lalu menukarnya ke depan.

selection_sort.yz
fn selection_sort(values: List[Number]) -> Number:
    let size: Number = list_count(values)
    var index: Number = 0
    while index < size - 1:
        var smallest: Number = index
        var scan: Number = index + 1
        while scan < size:
            if list_get(values, scan) < list_get(values, smallest):
                set smallest = scan
            set scan = scan + 1
        if smallest != index:
            let current: Number = list_get(values, index)
            let minimum: Number = list_get(values, smallest)
            list_set(values, index, minimum)
            list_set(values, smallest, current)
        set index = index + 1
    return size

start:
    var scores: List[Number] = List[Number]()
    list_push(scores, 42)
    list_push(scores, 7)
    list_push(scores, 19)
    let sorted_count: Number = selection_sort(scores)
    var position: Number = 0
    while position < sorted_count:
        say list_get(scores, position)
        set position = position + 1
7
19
42
  1. smallest

    Menyimpan indeks nilai terkecil yang ditemukan pada bagian sisa list.

  2. scan

    Memeriksa setiap posisi setelah posisi yang sedang diisi.

  3. list_set

    Dua pemanggilan menukar nilai lama dengan nilai minimum. Algoritma ini mudah dipelajari tetapi lambat untuk list besar: waktunya O(n²).

Arti bagian selection sort

KodeArti dan alasan
fn selection_sort(values: List[Number])Fungsi menerima list integer. Karena list bertipe List[Number], nilainya tidak dicampur dengan teks atau Boolean.
size = list_count(values)Menyimpan panjang list sekali agar kondisi loop mudah dibaca. size adalah jumlah item, bukan indeks terakhir.
index = 0Menunjuk slot depan yang akan diisi dengan nilai terkecil berikutnya.
index < size - 1Cukup mengerjakan sampai slot kedua dari belakang. Setelah itu, satu item tersisa pasti sudah berada pada tempatnya. List kosong atau satu item tidak perlu diubah.
smallest = indexAnggap dahulu nilai pada slot depan sebagai nilai terkecil sementara. Variabel ini menyimpan indeks, bukan nilai angkanya.
scan = index + 1Mulai memeriksa bagian yang belum terurut di sebelah kanan slot depan.
list_get(values, scan) < list_get(values, smallest)Membaca dua angka lalu membandingkannya. Jika nilai yang sedang dipindai lebih kecil, catat posisinya sebagai kandidat terkecil baru.
set smallest = scanMemperbarui indeks kandidat. Nilai dalam list belum dipindah sampai semua kandidat selesai dibandingkan.
set scan = scan + 1Maju ke item berikutnya. Pembaruan ini berada di dalam loop kedua, jadi setiap item sisa hanya diperiksa sekali pada putaran tersebut.
current dan minimumMenyimpan kedua angka sebelum menulis ulang list. Variabel sementara mencegah nilai pertama hilang saat penukaran.
list_set(...)Menaruh nilai terkecil ke slot depan lalu memindahkan nilai lama ke slot asal minimum. List yang diberikan ke fungsi berubah langsung.
index = index + 1Menyelesaikan satu slot dan berpindah ke slot berikutnya. Bagian sebelum index kini sudah terurut.
return sizeMengembalikan jumlah item agar pemanggil tahu berapa banyak nilai yang dapat dicetak. List yang terurut tetap berada di variabel aslinya.
position dan list_getLoop terakhir hanya menampilkan hasil dari indeks 0 sampai sorted_count - 1; indeks akhir tidak boleh ikut.

Jejak perubahan nilai

PutaranBagian yang diperiksaTindakanIsi list setelahnya
1[42, 7, 19]Minimum 7; tukar indeks 0 dan 1.[7, 42, 19]
2[42, 19]Minimum 19; tukar indeks 1 dan 2.[7, 19, 42]
3Tidak ada; satu nilai tersisa.Loop berhenti karena index < size - 1 salah.[7, 19, 42]

Contoh ini mengurutkan naik karena membandingkan dengan <. Untuk urutan turun, pilih nilai terbesar dan ubah perbandingannya menjadi >. Item kembar tetap ada; sorting tidak menghapus duplikat. Nilai negatif juga dapat diurutkan. List kosong dan list satu item langsung selesai. Algoritma ini memakai sekitar n × (n - 1) / 2 perbandingan, sehingga waktu tumbuh kuadratik O(n²); ia cocok untuk belajar dan data kecil, bukan list besar. Implementasi ini menukar item langsung di list dan memakai beberapa variabel sementara, sehingga ruang tambahan konstan. Belum ada fungsi bawaan list_sort; insertion sort, merge sort, atau API sorting standar belum didokumentasikan sebagai fitur library stabil.

15 · Shape: mendefinisikan bentuk data

shape mendeklarasikan record bertipe: nama tipe dan daftar field tetap. Compiler memeriksa nama field, jumlah argumen constructor, dan tipe setiap nilai. Constructor mengisi field menurut urutan deklarasi.

product.yz
shape Product:
    id: Number
    name: Text
    price: Int32
    available: Boolean

fn rename(product: Product, name: Text) -> Product:
    return Product(product.id, name, product.price, product.available)

fn product_label(product: Product) -> Text:
    return product.name + " (" + int32_text(product.price) + ")"

start:
    let book: Product = Product(7, "YAZA Guide", int32_from_number(1499), true)
    let renamed: Product = rename(book, "YAZA Programming Guide")
    say product_label(renamed)
    say renamed.available
    var editable: Product = book
    set editable.price = int32_from_number(1599)
    say int32_text(editable.price)
YAZA Programming Guide (1499)
true
1599
  1. shape Product:

    Mendaftarkan tipe baru bernama Product. Semua nilai Product memiliki field yang dideklarasikan.

  2. price: Int32

    Nama field adalah price; tipenya Int32. Memberi teks atau Boolean pada posisi ini akan ditolak compiler.

  3. Product(...)

    Membuat nilai dengan empat argumen sesuai urutan field: id, name, price, available. Jumlah atau tipe yang salah menjadi error.

  4. product.name

    Akses field menggunakan titik. Compiler menolak field yang tidak dideklarasikan.

  5. set editable.price

    Field dapat diperbarui melalui variabel var. Bentuk let tidak boleh dimutasi seperti ini.

  6. fn product_label(...)

    Operasi terhadap data ditulis sebagai fungsi biasa yang menerima shape. Belum ada method syntax, self, inheritance, atau dynamic dispatch.

16 · Variant dan match

variant mendefinisikan salah satu dari beberapa kasus bernama. Kasus boleh membawa payload bertipe. match memeriksa setiap kemungkinan secara jelas.

delivery.yz
variant DeliveryState:
    Queued
    InTransit(tracking_code: Text)
    Delivered(recipient: Text)

fn describe(state: DeliveryState) -> Text:
    match state:
        Queued:
            return "queued"
        InTransit(code):
            return "tracking " + code
        Delivered(recipient):
            return "delivered to " + recipient

start:
    let state: DeliveryState = DeliveryState::InTransit("YZ-2048")
    say describe(state)
tracking YZ-2048
  1. Queued

    Kasus tanpa payload. Kasus ini dibuat dengan konstruktor berscope seperti DeliveryState::Queued().

  2. InTransit(Text)

    Kasus yang membawa nilai teks. Pola InTransit(code) mengikat payload itu ke nama lokal.

  3. match

    Compiler memeriksa nama kasus, tipe payload, duplikasi, dan kelengkapan match untuk variant yang didukung.

17 · Option, Result, dan kegagalan

Option[T] berarti ada nilai (some) atau tidak ada (none). Result[T,E] membedakan sukses (ok) dari gagal (err). Ini pola eksplisit untuk nilai yang mungkin tidak tersedia atau operasi yang bisa gagal.

result.yz
fn positive(value: Number) -> Result[Number, Text]:
    if value > 0:
        return ok(value)
    return err("value must be positive")

fn doubled_positive(value: Number) -> Result[Number, Text]:
    let accepted: Number = positive(value)?
    return ok(accepted * 2)

start:
    let good: Result[Number, Text] = doubled_positive(4)
    let bad: Result[Number, Text] = doubled_positive(-1)
    say result_unwrap(good)
    say result_unwrap_error(bad)
8
value must be positive
  1. ok(value)

    Membungkus hasil sukses ke dalam Result.

  2. err(message)

    Membungkus nilai error. Jenis error di contoh ini adalah Text.

  3. positive(value)?

    Operator ? meneruskan error ke pemanggil dan mengambil nilai sukses. Fungsi pembungkus juga harus mengembalikan Result yang kompatibel.

  4. result_unwrap

    Akses langsung dapat gagal jika Result ternyata berisi error. Periksa result_is_ok atau gunakan match pada program nyata.

Gunakan Result untuk operasi yang dapat gagal dan Option untuk nilai yang mungkin tidak tersedia. Periksa hasilnya dengan match atau fungsi pemeriksa sebelum mengambil nilainya; jangan menutupi kegagalan dengan nilai default tanpa alasan.

18 · Module dan import dengan use

use mengimpor file module YAZA. Compiler mengembangkan module lokal yang dirujuk oleh path. Dependency jarak jauh, registri package, dan alias dependency belum tersedia.

examples/modules/main.yz
use "math"

start:
    let total: Number = sum_to(10)
    say "Sum: {total}"

File math.yz mendeklarasikan fungsi sum_to. Path di-resolve dari file yang mengimpor. Ikuti aturan project/module yang didukung CLI dan gunakan nama module yang jelas.

19 · File handling: membaca dan menulis file

Runtime native menyediakan operasi file teks/biner dan direktori. Contoh berikut menulis, memeriksa, membaca, lalu menambahkan teks. Jalankan dari direktori kerja yang kamu pahami; path relatif dihitung dari direktori proses.

file_text.yz
start:
    let path: Text = "notes.txt"
    let write_status: Number = file_write(path, "First line.\n")
    let exists: Boolean = file_exists(path)
    let contents: Text = file_read(path)
    let append_status: Number = file_append(path, "Second line.\n")
    let updated: Text = file_read(path)
    say exists
    say contents
    say updated
    say write_status
    say append_status
true
First line.
First line.
Second line.
0
0
  1. file_write(path, text)

    Menulis teks ke path dan mengembalikan kode status numerik; contoh runtime saat ini memakai 0 untuk sukses.

  2. file_exists(path)

    Memeriksa apakah file tersedia sebelum membacanya.

  3. file_read(path)

    Membaca isi file sebagai Text. Untuk data biner, gunakan keluarga file_read_bytes / file_write_bytes.

  4. file_append(path, text)

    Menambahkan teks di akhir file. file_write_atomic tersedia untuk mengganti file secara atomik pada operasi yang didukung.

API lain mencakup file_remove, directory_create, directory_list, path_join, stdin_read, dan byte buffer. Playground browser tidak bisa membaca atau menulis file lokal; gunakan CLI.

20 · PostgreSQL: koneksi dan query berparameter

YAZA memiliki client PostgreSQL native dan API query. Contoh proyek examples/pg_wire_query.yz membaca konfigurasi dari environment, membuat koneksi dengan timeout, lalu mengirim parameter terpisah dari SQL. Siapkan YAZA_PG_HOST, YAZA_PG_PORT, YAZA_PG_USER, YAZA_PG_DATABASE, dan YAZA_PG_PASSWORD sebelum menjalankannya.

examples/pg_wire_query.yz · core
use "../std/pg/transport"

start:
    let host: Text = env_get("YAZA_PG_HOST")
    let port: Number = number_parse(env_get("YAZA_PG_PORT"))
    let username: Text = env_get("YAZA_PG_USER")
    let database: Text = env_get("YAZA_PG_DATABASE")
    let password: Text = env_get("YAZA_PG_PASSWORD")
    let connected: Result[Number, Text] = pg_connect(host, port, username, database, password, 5000)
    if result_is_ok(connected):
        let connection: Number = result_unwrap(connected)
        let parameters: PgParameters = pg_parameters_new()
        let added: Result[Boolean, Text] = pg_parameters_add_text(parameters, "YAZA")
        let query: Result[PgQueryResult, Text] = pg_query_with_parameters(connection, "SELECT $1 AS greeting", parameters, 5000)
        if result_is_ok(added) and result_is_ok(query):
            let rows: PgQueryResult = result_unwrap(query)
            let value: Result[PgValue, Text] = pg_query_value(rows, 0, 0)
            if result_is_ok(value):
                match result_unwrap(value):
                    TextValue(text):
                        say text
                    Null:
                        say "NULL"
                    NumberValue(_):
                        say "Unexpected number"
                    BooleanValue(_):
                        say "Unexpected Boolean"
                    BytesValue(_):
                        say "Unexpected bytes"
        let closed: Number = pg_disconnect(connection)
    else:
        say "PostgreSQL connection failed."
YAZA
  1. pg_connect(..., 5000)

    Membuka koneksi dengan timeout 5.000 milidetik. Nilainya adalah Result, jadi program harus memeriksa sukses/gagal.

  2. PgParameters

    Nilai query ditambahkan dengan fungsi bertipe seperti pg_parameters_add_text atau pg_parameters_add_number.

  3. $1

    Placeholder PostgreSQL mengacu ke parameter pertama. Jangan gabungkan input pengguna ke string SQL.

  4. pg_query_value

    Membaca sel dari hasil berdasarkan indeks baris dan kolom yang dimulai dari nol. PgValue diperiksa dengan match.

  5. pg_disconnect

    Menutup koneksi setelah pekerjaan selesai. Kode lengkap memeriksa juga kegagalan penambahan parameter, query, dan hasil.

Untuk filter/sort/page yang lebih terstruktur, library punya db_select_new, db_select_where, db_select_order_by, db_select_page, dan db_postgres_select. Query builder hanya menerima identifier tervalidasi dan nilai bind terpisah. Contoh lengkap ada di tests/db_postgres_live_smoke.yz. Dukungan PostgreSQL masih testing/development; TLS remote, versi server tambahan, dan CI database menyeluruh masih terbuka.

Buka contoh transaksi PostgreSQL → · Pelajari API HTTP dan PostgreSQL →

21 · Input terminal, argumen, dan environment

Runtime CLI menyediakan stdin_read() untuk membaca teks dari standard input, arg(index) untuk argumen program, dan env_get(name) untuk environment variable. Jangan menaruh password/database secret sebagai literal di source atau log.

cli_input.yz
start:
    let input: Text = stdin_read()
    let file_name: Text = arg(1)
    let mode: Text = env_get("YAZA_MODE")
    say "Input: {input}"
    say "File: {file_name}"
    say "Mode: {mode}"

Jalankan dengan input pipe atau argumen setelah --, sesuai perintah CLI. Browser preview tidak memiliki stdin atau akses environment proses.

22 · Assert dan menjalankan test

assert kondisi menghentikan test bila kondisinya tidak benar. File test memakai ekstensi .test.yz dan dijalankan oleh test runner CLI.

tests/math.test.yz
fn add(left: Number, right: Number) -> Number:
    return left + right

start:
    assert add(20, 22) == 42
Terminal
dist/yaza test tests

Jalankan contoh dengan compiler native

Playground browser mendukung subset sintaks yang ditampilkan pada contoh interaktif. Jalankan PostgreSQL, file, API, module, dan test dari root repository memakai compiler native yang sesuai platform.

Terminal
dist/yaza check examples/shapes.yz
dist/yaza run examples/shapes.yz
dist/yaza run examples/pg_wire_query.yz
Lanjutkan ke: API dan database

Baca panduan API YAZA untuk route, request JSON, CRUD, autentikasi, PostgreSQL, dan batas yang masih dikembangkan.