Perkakas pengembang

Selain kompilator, distribusi Nim menyertakan perkakas pendukung yang dipakai setiap hari selama kode ditulis. Topik ini membahas tiga di antaranya, yaitu nimsuggest sebagai backend pertanyaan untuk editor, nimpretty sebagai penata gaya kode, dan nim doc sebagai pembuat dokumentasi HTML dari komentar dokumen. Modul penghitung kata pada topik unittest dan testament menjadi bahan ketiga perkakas tersebut, ditambah satu berkas sengaja berantakan untuk latihan penataan gaya.

nimsuggest sebagai backend editor#

nimsuggest adalah program server yang menjawab pertanyaan tentang kode Nim, dan editor memakainya untuk melengkapi nama, melompat ke definisi, serta menampilkan daftar simbol. Pertanyaannya dikirim lewat masukan standar dalam bentuk perintah dan posisi berformat berkas:baris:kolom, lalu jawabannya dikembalikan satu baris per simbol dengan kolom yang dipisahkan tab. Berikut modul yang dijadikan contoh, yang memuat komentar dokumen berawalan dua tanda pagar pada setiap procnya.

proc jumlahKata*(teks: string): int =
  ## Menghitung banyak kata yang dipisahkan spasi, tab, atau baris baru.
  result = 0
  var dalamKata = false
  for c in teks:
    if c in {' ', '\t', '\n'}:
      dalamKata = false
    elif not dalamKata:
      dalamKata = true
      inc result

proc kataTerpanjang*(teks: string): string =
  ## Mengembalikan kata pertama yang paling panjang.
  ## Memunculkan ValueError bila teks tidak memuat satu kata pun.
  var
    terpanjang = ""
    kataSaatIni = ""
  for c in teks & " ":
    if c in {' ', '\t', '\n'}:
      if kataSaatIni.len > terpanjang.len:
        terpanjang = kataSaatIni
      kataSaatIni = ""
    else:
      kataSaatIni.add(c)
  if terpanjang.len == 0:
    raise newException(ValueError, "teks tidak memuat kata")
  return terpanjang

Perintah outline meminta daftar seluruh simbol pada berkas. Permintaan ditulis lewat printf agar nimsuggest menerima perintahnya, lalu berhenti setelah perintah quit. Jawaban mentahnya juga memuat baris pembuka berisi daftar perintah yang tersedia, sehingga contoh ini menyaring baris yang diawali outline saja.

# minta daftar simbol pada modul lewat nimsuggest
printf 'outline %s:1:1\nquit\n' "$PWD/penghitung.nim" | nimsuggest penghitung.nim | grep ^outline

outline	skVar	penghitung.jumlahKata.dalamKata	bool	/home/kal/my-project/content/nim/pengujian-pengemasan/perkakas-pengembang/penghitung.nim	4	6	""	100
outline	skProc	penghitung.jumlahKata	proc (teks: string): int{.noSideEffect, gcsafe, raises: <inferred> [].}	/home/kal/my-project/content/nim/pengujian-pengemasan/perkakas-pengembang/penghitung.nim	1	5	"Menghitung banyak kata yang dipisahkan spasi, tab, atau baris baru."	100
outline	skVar	penghitung.kataTerpanjang.terpanjang	string	/home/kal/my-project/content/nim/pengujian-pengemasan/perkakas-pengembang/penghitung.nim	16	4	""	100
outline	skVar	penghitung.kataTerpanjang.kataSaatIni	string	/home/kal/my-project/content/nim/pengujian-pengemasan/perkakas-pengembang/penghitung.nim	17	4	""	100
outline	skProc	penghitung.kataTerpanjang	proc (teks: string): string{.noSideEffect, gcsafe, raises: <inferred> [ref ValueError].}	/home/kal/my-project/content/nim/pengujian-pengemasan/perkakas-pengembang/penghitung.nim	12	5	"Mengembalikan kata pertama yang paling panjang.\x0AMemunculkan ValueError bila teks tidak memuat satu kata pun."	100

Setiap jawaban memuat jenis simbolnya, nama lengkapnya, tanda tangan proc, letak berkas beserta baris dan kolomnya, sampai teks komentar dokumennya. Inilah data yang dirangkai editor menjadi panel struktur berkas dan gelembung dokumentasi saat kursor berhenti di atas nama proc. Perintah lain melayani kebutuhan yang berbeda, sebagaimana dirangkum tabel berikut.

Format posisi menyediakan satu kemudahan lagi untuk pekerjaan sehari-hari, yaitu berkas sementara yang ditulis setelah titik koma pada pola file.nim[;dirtyfile.nim]:line:col sebagaimana terlihat pada baris bantuan nimsuggest. Berkas sementara itu memuat isi buffer editor yang belum disimpan, sehingga pelengkapan dan pemeriksaan tetap akurat untuk suntingan terbaru sebelum berkasnya disimpan. Berkas aslinya tetap dirujuk pada bagian pertama pola, sehingga konteks proyek dari berkas lain tidak hilang.

Menata gaya dengan nimpretty#

nimpretty menata ulang kode sumber mengikuti gaya resmi Nim, seperti indentasi dua spasi dan jarak antara token deklarasi. Secara bawaan ia menimpa berkas masukannya, sehingga berkas contoh berikut sengaja ditata ke berkas lain dengan opsi –out agar versi aslinya dapat dibandingkan. Opsi lain yang berguna adalah –maxLineLen untuk menetapkan panjang baris maksimum hasil penataan, serta –indent untuk mengubah lebar indentasi, yang nilainya dapat ditautkan ke angka tertentu atau dilepas ke mode pengenalan otomatis melalui –indent:0.

import    strutils
proc sapa(nama:string):string=
  let bersih=strip(nama)
  result="Halo, "&bersih&"!"
echo    sapa(  "Citra" )

# tata berkas ke berkas baru, lalu bandingkan dengan asalnya
nimpretty --out:sapa_rapi.nim sapa_berantakan.nim
diff -u --label asal --label rapi sapa_berantakan.nim sapa_rapi.nim

--- asal
+++ rapi
@@ -1,5 +1,5 @@
-import    strutils
-proc sapa(nama:string):string=
-  let bersih=strip(nama)
-  result="Halo, "&bersih&"!"
-echo    sapa(  "Citra" )
+import strutils
+proc sapa(nama: string): string =
+  let bersih = strip(nama)
+  result = "Halo, "&bersih&"!"
+echo sapa("Citra")

Perbandingan di atas menunjukkan dua macam perubahan, yaitu spasi berlebih yang dihapus dan tanda baca deklarasi yang diberi jarak, seperti nama:string menjadi nama: string. Penulisan operator penggabung string pada contoh ini dibiarkan apa adanya, karena nimpretty menata struktur dan indentasi tanpa menafsirkan gaya pemakaian operator pada setiap konteks. Hasil penataan yang deterministik membuat berkas yang sudah rapi tidak berubah lagi bila ditata ulang, sehingga perintah ini aman dijadikan bagian dari rutinitas sebelum commit.

Membuat dokumentasi dengan nim doc#

Perintah nim doc mengompilasi berkas Nim sekaligus menghasilkan dokumentasi HTML dari komentar dokumen dan tanda tangan simbolnya. Komentar dokumen ditulis dengan dua tanda pagar ## di atas deklarasi, berbeda dari komentar biasa yang berawalan satu tanda pagar dan tidak dibaca pembuat dokumentasi. Opsi –outdir menentukan folder penyimpanan hasilnya.

# buat dokumentasi HTML dari komentar dokumen modul
nim doc --verbosity:0 --outdir:nimcache/doc penghitung.nim
# pastikan berkas hasilnya benar-benar ada
test -f nimcache/doc/penghitung.html && echo "dokumentasi dibuat: nimcache/doc/penghitung.html"

dokumentasi dibuat: nimcache/doc/penghitung.html

Dokumen yang dihasilkan berjudul penghitung sesuai nama modulnya, memuat tanda tangan kedua proc beserta teks komentar dokumennya, dan dapat dibuka langsung di browser. Format lain tersedia bila diperlukan, misalnya jsondoc yang menghasilkan data dokumentasi berformat JSON untuk diolah perkakas lain, sebagaimana dijelaskan panduan docgen resmi. Kebiasaan yang sehat adalah menulis komentar dokumen pada proc publik sejak awal, karena teks yang sama melayani pembaca kode dan pengguna pustaka tanpa kerja ganda.

Kesalahan umum#

Kesalahan pertama berupa menjalankan nimpretty tanpa opsi –out lalu kehilangan bentuk asli berkasnya. Perilaku bawaannya memang menimpa berkas masukan, sehingga perbandingan sebelum dan sesudah tidak mungkin lagi tanpa kontrol versi. Jalankan nimpretty pada berkas yang sudah tersimpan di repositori git, atau arahkan hasilnya ke berkas lain dengan –out terlebih dahulu.

Kesalahan kedua berupa mengirim permintaan nimsuggest dengan jalur berkas relatif. Permintaan seperti outline penghitung.nim:1:1 tidak menghasilkan jawaban dan tidak memunculkan pesan kesalahan apa pun, sementara permintaan dengan jalur absolut seperti pada contoh $PWD dijawab lengkap. Gunakan jalur absolut pada setiap permintaan, misalnya dengan membentuknya dari variabel $PWD.

Kesalahan ketiga berupa menulis komentar biasa dengan satu tanda pagar lalu mengharapkannya muncul di dokumentasi. Hanya komentar dokumen berawalan dua tanda pagar ## di atas deklarasi yang dibaca nim doc, sedangkan komentar biasa diperuntukkan bagi pembaca kode sumbernya. Pindahkan teks yang ditujukan bagi pengguna pustaka ke komentar dokumen agar tampil pada halaman HTML hasil nim doc.

Ringkasan#

• nimsuggest menjawab pertanyaan editor berupa pelengkapan, definisi, pemakaian, pemeriksaan, dan daftar simbol, dengan jawaban satu baris per simbol yang kolomnya dipisahkan tab.
• Permintaan nimsuggest memakai jalur absolut dan posisi berformat berkas:baris:kolom, sedangkan jalur relatif diabaikan tanpa pesan.
• nimpretty menata gaya kode sesuai gaya resmi, menimpa berkas masukan secara bawaan, dan menyimpan ke berkas lain dengan opsi –out.
• nim doc menghasilkan dokumentasi HTML dari komentar dokumen ## beserta tanda tangan simbol, dengan format JSON tersedia melalui jsondoc.

Referensi#

• Nim IDE Integration Guide — nim-lang.org — Protokol pertanyaan nimsuggest, perintahnya, dan format jawaban satu barisnya.
• Nim DocGen Tools Guide — nim-lang.org — Perintah nim doc, aturan komentar dokumen, dan format keluaran HTML serta JSON.
• Tools available with Nim — nim-lang.org — Deskripsi nimpretty sebagai penata gaya kode beserta perkakas bawaan lainnya.