====== Dokumentasi Bahasa Pemrograman c77 ======

Selamat datang di dokumentasi teknis untuk **c77**, sebuah bahasa pemrograman berbasis skrip yang dirancang untuk pembuatan bot interaktif dengan sintaks yang sederhana dan mudah dibaca.

Dokumen ini menjelaskan sintaks dasar, konfigurasi perintah, fungsi bawaan (API), dan struktur kontrol alur.

===== 1. Sintaks Dasar =====

==== Deklarasi Label ====

Label berfungsi sebagai penanda titik awal sebuah blok logika atau fungsi. Sistem akan melompat ke label ini ketika dipanggil oleh //event handler// atau perintah lompatan.

  * **Aturan:** Nama label wajib diawali dengan tanda titik (.).
  * **Sintaks:** ''.nama_label''
  * **Contoh:**

<code>
.fungsi_logika
    print "Logika dimulai di sini"
</code>

==== Komentar ====

Komentar digunakan untuk memberikan catatan pada kode program. Bagian ini tidak akan dieksekusi oleh mesin.

  * **Simbol:** Titik koma (;)
  * **Contoh:**

<code>
; Ini adalah komentar baris penuh
count = 0 ; Ini komentar di akhir baris
</code>

==== Variabel & Tipe Data ====

Pendefinisian variabel dilakukan secara dinamis (tanpa tipe data eksplisit).

  * **String:** Teks harus diapit tanda kutip ganda (").
  * **Integer:** Angka ditulis langsung.
  * **Operator Penggabungan:** Gunakan tanda plus (+) untuk menggabungkan string atau variabel.
  * **Contoh:**

<code>
nama = "User"
skor = 100
pesan = "Halo " + nama
</code>

===== 2. Konfigurasi Perintah (Event Listener) =====

Bagian ini digunakan untuk memetakan perintah yang diketik pengguna (Trigger) ke Label logika yang sesuai.

**Sintaks:**
''saat_perintah [trigger] lompat [label_tujuan]''

**Parameter:**
  - ''trigger'': Kata kunci perintah (contoh: /start).
  - ''lompat'': Kata kunci wajib (keyword).
  - ''label_tujuan'': Label yang akan dieksekusi saat trigger diterima.

**Contoh:**
<code>
saat_perintah /start lompat .cmd_start
saat_perintah /menu  lompat .cmd_menu
</code>

===== 3. Fungsi Bawaan (API Reference) =====

Berikut adalah daftar fungsi yang tersedia, cara penggunaannya, dan argumen yang dibutuhkan.

==== send ====
Mengirim pesan teks ke pengguna.

  * **Argumen 1:** ''target_id'' (Biasanya menggunakan variabel sistem ''chat_id'').
  * **Argumen 2:** ''pesan'' (String atau Variabel).
  * **Contoh:**

<code>
send chat_id "Halo, selamat datang!"
</code>

==== send_photo ====
Mengirim file gambar disertai dengan teks keterangan (caption).

  * **PENTING:** File gambar hanya dibaca dari dalam folder **bot_config**.
  * **Argumen 1:** ''target_id''
  * **Argumen 2:** ''path_file'' (String, lokasi file gambar relatif terhadap bot_config).
  * **Argumen 3:** ''caption'' (String, teks keterangan).
  * **Contoh:**

<code>
path = "qris.png" ; File harus ada di folder bot_config/qris.png
desc = "Ini adalah menu kami"
send_photo chat_id path desc
</code>

==== kirim_vidio====
Mengirim file vidio disertai dengan teks keterangan (caption).

  * **PENTING:** File gambar hanya dibaca dari dalam folder **bot_config**.
  * **Argumen 1:** ''target_id''
  * **Argumen 2:** ''path_file'' (String, lokasi file gambar relatif terhadap bot_config).
  * **Argumen 3:** ''caption'' (String, teks keterangan).
  * **Contoh:**

<code>
path = "tutorial.mp4" ; File harus ada di folder bot_config/tutorial.mp4
desc = "Ini adalah menu kami"
kirim_vidio chat_id path desc
</code>


==== print ====
Mencetak log ke konsol server. Fungsi ini berguna untuk //debugging// dan tidak akan terlihat oleh pengguna bot.

  * **Argumen 1:** ''teks'' (String/Variabel).
  * **Contoh:**

<code>
print "User telah menekan tombol start"
</code>

==== sleep ====
Menunda eksekusi program selama beberapa milidetik (delay).

  * **Argumen 1:** ''milidetik'' (Integer).
  * **Contoh:**

<code>
sleep 1000 ; Menunggu selama 1 detik
</code>

==== baca_file ====
Membaca isi file teks dari penyimpanan lokal dan menyimpannya ke dalam variabel.

  * **Argumen 1:** ''path_file'' (String).
  * **Return:** Mengembalikan isi file sebagai String.
  * **Contoh:**

<code>
konten = baca_file "catatan.txt"
send chat_id konten
</code>

==== tulis_file ====
Menulis teks ke dalam file. Jika file tidak ada, akan dibuat. Jika ada, akan ditimpa/ditambah (tergantung implementasi sistem).

  * **PENTING:** File akan otomatis disimpan/ditulis ke dalam folder **bot_config**.
  * **Argumen 1:** ''path_file'' (String).
  * **Argumen 2:** ''isi_konten'' (String/Variabel).
  * **Contoh:**

<code>
data = "Log aktivitas baru"
tulis_file "log.txt" data ; Akan tersimpan di bot_config/log.txt
</code>

==== baris_keyboard ====
Menambahkan baris inline keyboard pada bot.

  * **Argumen :** ''label_button'' (String).
  * **Contoh:**

<code>
baris_keyboard "/halo" "/start" "/sawer" ; Ini bakal jadi baris 1
baris_keyboard "/co gratis" "/cetak uang" ; Ini bakal jadi baris 2
</code>


===== 4. Kontrol Alur (Flow Control) =====

Mengatur jalannya logika program, seperti percabangan dan pengulangan.

==== lompat (Unconditional Jump) ====
Memindahkan eksekusi program langsung ke label lain tanpa syarat.

  * **Sintaks:** ''lompat [label]''
  * **Contoh:** ''lompat .menu_utama''

==== jika (Conditional Jump / If) ====
Melakukan lompatan hanya jika kondisi terpenuhi.

  * **Sintaks:** ''jika [nilai_kiri] [operator] [nilai_kanan] lompat [label]''
  * **Operator:**
    * < (Kurang dari)
    * > (Lebih dari)
    * = (Sama dengan)
    * != (Tidak sama dengan)
  * **Contoh:**

<code>
count = 0
max = 5
.looping
count = count + 1
jika count < max lompat .looping
</code>

==== stop ====
Menghentikan eksekusi skrip pada baris tersebut. **Wajib** diletakkan di akhir setiap blok label agar kode tidak "bocor" (fall-through) ke label di bawahnya.

  * **Sintaks:** ''stop''

===== 5. Variabel Built-in =====

Variabel ini disediakan otomatis oleh sistem saat perintah dijalankan. Anda tidak perlu mendeklarasikannya secara manual.

^ Nama Variabel ^ Tipe Data ^ Deskripsi ^
| **sender_name** | String | Nama tampilan (//display name//) pengirim pesan. |
| **chat_id** | Int/String | ID unik pengguna atau grup tempat pesan dikirim. |
| **user_id** | Int | ID unik pengguna. |
| **raw_text** | String | Raw text pesan yang di kirim oleh user. |
| **agrs** | String | Argumen tambahan yang diketik user setelah perintah utama. |

**Contoh Penggunaan agrs:**
Jika pengguna mengetik: ''/echo halo dunia''
Maka:
  * Command: ''/echo''
  * agrs: ''"halo dunia"''

<code>
.cmd_echo
    msg = "Anda mengetik: " + agrs
    send chat_id msg
    stop
</code>

===== 6. Contoh Best Practice (Sistem Tiket) =====

Berikut adalah contoh implementasi kode yang bersih dan terstruktur untuk sistem "Support Ticket" sederhana. Perhatikan penggunaan komentar header, penamaan variabel yang jelas, dan pemisahan logika.

<code>
; ==================================================
; APLIKASI HELPDESK MINI
; Deskripsi: Menerima keluhan user dan menyimpannya
; ==================================================

; --- BAGIAN 1: KONFIGURASI HANDLER ---
saat_perintah /tiket   lompat .handler_buat_tiket
saat_perintah /cek_db  lompat .handler_baca_database
saat_perintah /reset   lompat .handler_reset_data

; --- BAGIAN 2: LOGIKA PROGRAM ---

.handler_buat_tiket
    ; 1. Persiapan Data
    ; Menggabungkan nama pengirim dengan isi pesan (agrs)
    log_entry = "Pengirim: " + sender_name
    log_entry = log_entry + " | Keluhan: "
    log_entry = log_entry + agrs
    
    ; 2. Simpan ke File (Persistent Storage)
    ; Data akan tersimpan di folder bot_config
    tulis_file "database_tiket.txt" log_entry
    
    ; 3. Feedback ke User
    reply = "Halo " + sender_name
    reply = reply + ", tiket Anda berhasil kami simpan."
    send chat_id reply
    
    ; 4. Log Internal
    print "Tiket baru telah dibuat."
    stop

.handler_baca_database
    ; Membaca seluruh isi file keluhan
    isi_db = baca_file "bot_config/database_tiket.txt"
    
    header = "=== DATA TIKET MASUK ==="
    send chat_id header
    send chat_id isi_db
    stop

.handler_reset_data
    ; Mengosongkan file dengan menimpa string default
    default_msg = "[DATABASE KOSONG]"
    tulis_file "database_tiket.txt" default_msg
    
    send chat_id "Database telah di-reset oleh Admin."
    stop
</code>