kaitai_struct

Struktur Kaitai

Catatan: jika Anda ingin membuat perubahan pada proyek, jangan fork repositori ini kaitai_struct . Sebagai gantinya, pilih komponen yang ingin Anda modifikasi pada pohon file di atas dan bagi masing-masing komponen tersebut .

Ini adalah repositori payung, yang berisi komponen hanya sebagai submodul untuk memudahkan pemeriksaan keseluruhan proyek. Kecuali Anda ingin memodifikasi README ini, ini bukanlah repo tempat Anda dapat melakukan pengeditan.

Apa itu Struktur Kaitai?

Kaitai Struct adalah bahasa deklaratif yang digunakan untuk menggambarkan berbagai struktur data biner yang diletakkan dalam file atau memori: yaitu format file biner, format paket aliran jaringan, dll.

Ide utamanya adalah bahwa format tertentu dijelaskan dalam bahasa Kaitai Struct hanya sekali dan kemudian dapat dikompilasi dengan ksc menjadi file sumber dalam salah satu bahasa pemrograman yang didukung. Modul-modul ini akan menyertakan kode yang dihasilkan untuk parser yang dapat membaca struktur data yang dijelaskan dari file/aliran dan memberikan akses ke sana dalam API yang bagus dan mudah dipahami.

Untuk apa itu digunakan?

Pernahkah Anda mendapati diri Anda menulis kode berulang, rawan kesalahan, dan sulit di-debug yang membaca struktur data biner dari aliran file/jaringan dan entah bagaimana merepresentasikannya dalam memori untuk akses yang lebih mudah?

Kaitai Struct mencoba membuat pekerjaan ini lebih mudah — Anda hanya perlu mendeskripsikan format biner satu kali dan kemudian semua orang dapat menggunakannya dari bahasa pemrograman mereka — lintas bahasa, lintas platform.

Kaitai Struct mencakup koleksi deskripsi format yang terus bertambah, tersedia dalam repositori submodul format.

Bisakah Anda memberi saya contoh singkat?

Tentu. Pertimbangkan file deskripsi format .ksy sederhana ini yang menjelaskan header file GIF (format gambar web populer):

 meta :
  id : gif
  file-extension : gif
  endian : le
seq :
  - id : header
    type : header
  - id : logical_screen
    type : logical_screen
types :
  header :
    seq :
      - id : magic
        contents : ' GIF '
      - id : version
        size : 3
  logical_screen :
    seq :
      - id : image_width
        type : u2
      - id : image_height
        type : u2
      - id : flags
        type : u1
      - id : bg_color_index
        type : u1
      - id : pixel_aspect_ratio
        type : u1

Ini menyatakan bahwa file GIF biasanya memiliki ekstensi .gif dan menggunakan pengkodean integer little-endian. File itu sendiri dimulai dengan dua blok: pertama muncul header dan kemudian muncul logical_screen :

• "Header" terdiri dari string "ajaib" sebanyak 3 byte ("GIF") yang mengidentifikasi bahwa itu adalah file GIF yang dimulai dan kemudian ada 3 byte lagi yang mengidentifikasi versi format ( 87a atau 89a ).
• "Deskriptor layar logis" adalah blok bilangan bulat:
  • image_width dan image_height adalah int 2-byte yang tidak ditandatangani
  • flags , bg_color_index dan pixel_aspect_ratio masing-masing membutuhkan 1-byte unsigned int

File .ksy ini dapat dikompilasi menjadi Gif.cs / Gif.java / Gif.js / Gif.php / gif.py / gif.rb dan kemudian secara instan seseorang dapat memuat file .gif dan mengaksesnya, misalnya lebar dan tinggi.

Di C#

 Gif g = Gif . FromFile ( "path/to/some.gif" ) ;
Console . WriteLine ( "width = " + g . LogicalScreen . ImageWidth ) ;
Console . WriteLine ( "height = " + g . LogicalScreen . ImageHeight ) ;

Di Jawa

 Gif g = Gif . fromFile ( "path/to/some.gif" );
System . out . println ( "width = " + g . logicalScreen (). imageWidth ());
System . out . println ( "height = " + g . logicalScreen (). imageHeight ());

Dalam JavaScript

Lihat catatan JavaScript di dokumentasi untuk panduan memulai cepat yang lebih lengkap.

 var g = new Gif ( new KaitaiStream ( someArrayBuffer ) ) ;
console . log ( "width = " + g . logicalScreen . imageWidth ) ;
console . log ( "height = " + g . logicalScreen . imageHeight ) ;

Di Lua

 local g = Gif : from_file ( " path/to/some.gif " )
print ( " width = " .. g . logical_screen . image_width )
print ( " height = " .. g . logical_screen . image_height )

Di Nim

 let g = Gif . fromFile ( " path/to/some.gif " )
echo " width = " & $ g.logicalScreen.imageWidth
echo " height = " & $ g.logicalScreen.imageHeight

Dalam PHP

logicalScreen()->imageWidth()); printf("height = %dn", $g->logicalScreen()->imageHeight());">

 $ g = Gif:: fromFile ( ' path/to/some.gif ' );
printf ( " width = %d n" , $ g -> logicalScreen ()-> imageWidth ());
printf ( " height = %d n" , $ g -> logicalScreen ()-> imageHeight ());

Dengan Python

 g = Gif . from_file ( "path/to/some.gif" )
print "width = %d" % ( g . logical_screen . image_width )
print "height = %d" % ( g . logical_screen . image_height )

Di Ruby

 g = Gif . from_file ( "path/to/some.gif" )
puts "width = #{ g . logical_screen . image_width } "
puts "height = #{ g . logical_screen . image_height } "

Tentu saja, contoh ini hanya menunjukkan sebagian kecil dari apa yang dapat dilakukan Kaitai Struct. Silakan merujuk ke tutorial dan dokumentasi untuk wawasan lebih lanjut.

Bahasa yang didukung

Kompiler Resmi Kaitai Struct sekarang mendukung kompilasi .ksy ke dalam modul sumber untuk bahasa berikut:

• C#
• Jawa
• JavaScript
• Lua
• Nim
• PHP
• ular piton
• Rubi

Mengunduh dan menginstal

Cara termudah untuk memeriksa keseluruhan proyek Kaitai Struct adalah dengan mengunduh repositori proyek utama yang sudah mengimpor semua bagian lain sebagai submodul. Menggunakan:

 git clone --recursive https://github.com/kaitai-io/kaitai_struct.git

Perhatikan opsi --recursive .

Sebagai alternatif, seseorang dapat memeriksa masing-masing subproyek yang merupakan rangkaian Kaitai Struct. Mereka adalah:

• kaitai_struct_compiler — kompiler yang menerjemahkan .ksy menjadi kode sumber parser yang ditulis dalam bahasa pemrograman target
• kaitai_struct_tests — tes & spesifikasi untuk memastikan bahwa kompiler berfungsi sesuai rencana
• Perpustakaan waktu proses
  • kaitai_struct_cpp_stl_runtime — untuk C++/STL
  • kaitai_struct_csharp_runtime — untuk C#
  • kaitai_struct_java_runtime — untuk Java
  • kaitai_struct_javascript_runtime — untuk JavaScript
  • kaitai_struct_nim_runtime — untuk Nim
  • kaitai_struct_lua_runtime — untuk Lua
  • kaitai_struct_python_runtime — untuk Python
  • kaitai_struct_ruby_runtime — untuk Ruby
  • kaitai_struct_swift_runtime — untuk Swift
• kaitai_struct_formats — pustaka format dan struktur biner yang banyak digunakan yang digambarkan sebagai file .ksy

Menggunakan KS dalam proyek Anda

Biasanya, menggunakan format yang dijelaskan dalam KS di proyek Anda, melibatkan langkah-langkah berikut:

• Jelaskan formatnya — yaitu membuat file .ksy
• Kompilasi file .ksy ke dalam file sumber bahasa target dan sertakan file tersebut dalam proyek Anda
• Tambahkan pustaka runtime KS untuk bahasa khusus Anda ke dalam proyek Anda (jangan khawatir, ukurannya kecil dan sebagian besar ada di sana untuk memastikan keterbacaan kode yang dihasilkan)
• Gunakan kelas yang dihasilkan untuk mengurai file/aliran biner Anda dan mengakses komponennya

Lihat tutorial dan dokumentasi untuk informasi lebih lanjut.

Perizinan

• Kompiler — GPLv3+
• Pustaka runtime — MIT atau Apache v2 (=> Anda dapat memasukkan kode yang dihasilkan bahkan ke dalam aplikasi berpemilik) — lihat masing-masing pustaka untuk detailnya