KAL
Menu

Alur kerja editor dan dokumentasi

Memasang dukungan VS Code dan menjadikan docs.modular.com kebiasaan mencari API.

Daftar isi

Editor dan dokumentasi resmi adalah dua perkakas kerja yang menentukan kecepatan menulis Mojo. Ekstensi Mojo untuk VS Code menyediakan penyorotan sintaks, pelengkapan nama, dan diagnostik yang bekerja selagi kode diketik, sedangkan situs dokumentasi menyediakan daftar API yang menjadi rujukan akhir untuk setiap tipe dan fungsi. Topik ini membahas pemasangan ekstensi, menghubungkan diagnostik editor dengan pesan compiler melalui berkas contoh yang gagal dan berhasil dijalankan, lalu menutupnya dengan kebiasaan mencari API di dokumentasi resmi.

Memasang ekstensi Mojo di VS Code#

Ekstensi resmi bernama Mojo dipublikasikan oleh penerbit modular-mojotools pada marketplace VS Code. Pemasangan dilakukan dari panel Extensions, yaitu mencari kata Mojo, memilih ekstensi dengan penerbit tersebut, lalu menekan tombol Install.

bash 
# tidak-dijalankan
# pemasangan ekstensi memodifikasi lingkungan editor
code --install-extension modular-mojotools.vscode-mojo

Setelah terpasang, berkas .mojo yang dibuka otomatis mendapat penyorotan sintaks, pelengkapan nama fungsi dan metode, serta lompatan ke definisi. Dukungan bahasanya bergantung pada instalasi Mojo di mesin yang sama, sehingga pemeriksaan pertama ketika fitur terasa tidak jalan adalah memastikan mojo --version berjalan di terminal sebelum mengutak-atik pengaturan editor. Panel Extensions juga menampilkan nomor versi ekstensi, dan memperbaruinya bersama pembaruan Mojo menjaga perilaku keduanya tetap selaras.

Diagnostik yang berjalan selama penyuntingan memanggil compiler Mojo di belakang layar, sehingga komputer yang menjalankan editor perlu memiliki instalasi Mojo yang berfungsi dengan baik. Proyek dengan lingkungan pixi atau uv menambahkan satu langkah, yaitu memastikan editor membuka proyek dari lingkungan yang sama dengan yang dipakai terminal, karena pelengkapan dan diagnostik mengikuti versi pustaka standar yang terbaca di sana. Ketidakcocokan versi antara editor dan terminal dapat memunculkan diagnostik yang tidak sesuai dengan hasil mojo run, dan penyelesaiannya adalah menyamakan sumber versi keduanya.

Diagnostik editor dan pesan compiler#

Berkas berikut memanggil metode length yang tidak dimiliki tipe String, dan compiler menolaknya pada saat dijalankan.

mojo cek-api-gagal.mojo 
def main():
    var teks = "daftar belanja"
    print(teks.length())
bash 
# compiler menolak berkas karena metodenya tidak ada
mojo run cek-api-gagal.mojo
text Keluaran 
/home/kal/my-project/content/mojo/package-dan-perkakas/alur-kerja-editor/cek-api-gagal.mojo:3:15: error: 'String' value has no attribute 'length'
    print(teks.length())
          ~~~~^
/home/kal/.pixi/envs/mojo/bin/mojo: error: failed to parse the provided Mojo source module

Pesan error memuat tiga petunjuk, yaitu lokasi berkas beserta nomor baris dan kolom, kutipan baris yang bermasalah, serta penanda posisi kode yang ditolak. Dua alamat pada pesan mengikuti lingkungan tempat perintah dijalankan, yaitu lokasi berkas dan lokasi program mojo, sehingga bentuknya berbeda di setiap komputer. Di dalam editor, diagnostik yang serupa umumnya muncul di bawah teks yang bermasalah selagi diketik, sehingga kesalahan nama metode tertangkap sebelum perintah run dijalankan. Apabila diagnostik itu tidak muncul, jalankan berkas melalui terminal, karena pesan compiler adalah sumber yang sama dengan yang dipakai editor.

Memperbaiki dengan bantuan dokumentasi#

Dokumentasi pustaka standar memuat daftar metode String, dan halaman itulah tempat pertama untuk mencari pengganti metode yang tidak ada. Dari daftarnya diketahui bahwa tipe String menyediakan count_codepoints untuk menghitung karakter dan byte_length untuk menghitung jumlah byte.

mojo cek-api.mojo 
def main():
    var teks = "daftar belanja"
    print(teks.count_codepoints())
    print(teks.byte_length())
bash 
# versi yang benar dijalankan ulang
mojo run cek-api.mojo
text Keluaran 
14
14

Teks daftar belanja terdiri atas 14 karakter ASCII yang masing-masing berukuran satu byte, sehingga kedua metode mencetak 14. Perbedaan keduanya muncul pada teks yang memuat karakter multi-byte, misalnya karakter beraksen atau emoji, karena satu karakternya dapat terdiri atas lebih dari satu byte. Memilih metode berdasarkan arti yang dicari, bukan berdasarkan kebiasaan dari bahasa pemrograman lain, adalah inti kebiasaan ini.

Menyusun rujukan cepat dari berkas sendiri#

Dokumentasi pustaka standar mencakup API yang dikirim bersama Mojo, sedangkan API buatan sendiri perlu dirujuk dari berkasnya. Subperintah doc menyusun daftar deklarasi dari satu berkas menjadi keluaran JSON yang memuat nama, tipe argumen, dan konvensi setiap fungsi.

mojo demonstrasi-doc.mojo 
def jumlah(a: Int, b: Int) -> Int:
    return a + b

def selisih(a: Int, b: Int) -> Int:
    return a - b
bash 
# daftar nama fungsi dari keluaran JSON mojo doc
mojo doc demonstrasi-doc.mojo | python3 -c "import json, sys; [print(f['name']) for f in json.load(sys.stdin)['decl']['functions']]"
text Keluaran 
jumlah
selisih

Keluaran JSON yang lengkap memuat rincian setiap argumen beserta jenis konvensinya, sehingga dapat dipakai sebagai bahan bagi perkakas dokumentasi otomatis untuk package buatan sendiri. Untuk pekerjaan sehari-hari, kebiasaan yang paling murah tetap membuka halaman API di browser di samping editor, dan mojo doc dipakai saat daftar API perlu diproses oleh program lain.

Alamat dokumentasi dan kebiasaan mencari#

Dokumentasi resmi Mojo berada di mojolang.org, dengan indeks pustaka standar pada alamat mojolang.org/docs/std dan manual bahasa pada mojolang.org/docs/manual.

Kebiasaan mencari API dijaga dengan tiga langkah tetap. Pertama, cocokkan versi dokumentasi dengan versi compiler, karena mojo --version mencetak nomor versi terpasang dan halaman mojolang.org/releases memuat daftar rilisnya, sedangkan contoh pada jalur ini memakai versi 1.2.0. Kedua, cari berdasarkan nama tipe yang sedang dipakai, misalnya halaman String, karena daftar metode, parameter, dan nilai kembalinya tersusun di sana. Ketiga, baca contoh pemanggilan pada halaman yang sama sebelum menyalin pola dari bahasa lain, karena nama yang cocok belum tentu berperilaku sama.

Seluruh halaman dokumentasi memuat bentuk Markdown yang dapat diambil dengan menambahkan akhiran .md pada alamatnya, misalnya halaman manual dasar yang diakhiri .md. Bentuk ini membantu dua kebiasaan kerja, yaitu menyimpan kutipan API ke dalam catatan proyek dan menyalin contoh persis seperti tercetak tanpa format tambahan dari situs. Untuk pencarian biasa, tampilan situs tetap lebih cepat dibaca karena tanda tangan fungsi dan contoh kodenya sudah tersusun dengan penyorotan sintaks.

Ringkasan#

  • Ekstensi Mojo dari penerbit modular-mojotools dipasang dari marketplace VS Code dan menghadirkan penyorotan, pelengkapan, serta diagnostik untuk berkas .mojo.
  • Diagnostik editor dan pesan compiler bersumber dari mesin yang sama, sehingga pesan error terminal menjadi acuan ketika editor diam.
  • Dokumentasi resmi berada di mojolang.org dengan docs.modular.com/mojo sebagai alias yang dialihkan ke sana, dan versinya dicocokkan dengan mojo --version.

Referensi#