Note: if you want to make changes to the project, do not fork this repository kaitai_struct. Instead, choose the component you want to modify in the file tree above and fork that individual component instead.
This is an umbrella repository, containing the components only as submodules to make it easier to check out the entire project. Unless you want to modify this README, it is not the repo where you can make edits.
Kaitai Struct is a declarative language used for describing various binary data structures laid out in files or in memory: i.e. binary file formats, network stream packet formats, etc.
The main idea is that a particular format is described in Kaitai
Struct language only once and then can be compiled with a ksc
into
source files in one of the supported programming languages. These
modules will include a generated code for a parser that can read
described data structure from a file / stream and give access to it in
a nice, easy-to-comprehend API.
Have you ever found yourself writing repetitive, error-prone and hard-to-debug code that reads binary data structures from file / network stream and somehow represents them in memory for easier access?
Kaitai Struct tries to make this job easier — you only have to describe the binary format once and then everybody can use it from their programming languages — cross-language, cross-platform.
Kaitai Struct includes a growing collection of format descriptions, available in formats submodule repository.
Sure. Consider this simple .ksy
format description file that
describes the header of a GIF file (a popular web image format):
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
It declares that GIF files usually have a .gif
extension and use
little-endian integer encoding. The file itself starts with two
blocks: first comes header
and then comes logical_screen
:
87a
or 89a
).image_width
and image_height
are 2-byte unsigned intsflags
, bg_color_index
and pixel_aspect_ratio
take 1-byte
unsigned int eachThis .ksy
file can be compiled it into Gif.cs
/ Gif.java
/
Gif.js
/ Gif.php
/ gif.py
/ gif.rb
and then instantly one can load .gif
file and access, for example, it's width and height.
Gif g = Gif.FromFile("path/to/some.gif");
Console.WriteLine("width = " + g.LogicalScreen.ImageWidth);
Console.WriteLine("height = " + g.LogicalScreen.ImageHeight);
Gif g = Gif.fromFile("path/to/some.gif");
System.out.println("width = " + g.logicalScreen().imageWidth());
System.out.println("height = " + g.logicalScreen().imageHeight());
See JavaScript notes in the documentation for a more complete quick start guide.
var g = new Gif(new KaitaiStream(someArrayBuffer));
console.log("width = " + g.logicalScreen.imageWidth);
console.log("height = " + g.logicalScreen.imageHeight);
local g = Gif:from_file("path/to/some.gif")
print("width = " .. g.logical_screen.image_width)
print("height = " .. g.logical_screen.image_height)
let g = Gif.fromFile("path/to/some.gif")
echo "width = " & $g.logicalScreen.imageWidth
echo "height = " & $g.logicalScreen.imageHeight
$g = Gif::fromFile('path/to/some.gif');
printf("width = %dn", $g->logicalScreen()->imageWidth());
printf("height = %dn", $g->logicalScreen()->imageHeight());
g = Gif.from_file("path/to/some.gif")
print "width = %d" % (g.logical_screen.image_width)
print "height = %d" % (g.logical_screen.image_height)
g = Gif.from_file("path/to/some.gif")
puts "width = #{g.logical_screen.image_width}"
puts "height = #{g.logical_screen.image_height}"
Of course, this example shows only a very limited subset of what Kaitai Struct can do. Please refer to the tutorials and documentation for more insights.
Official Kaitai Struct compiler now supports compiling .ksy
into
source modules for the following languages:
The easiest way to check out the whole Kaitai Struct project is to download the main project repository that already imports all other parts as submodules. Use:
git clone --recursive https://github.com/kaitai-io/kaitai_struct.git
Note the --recursive
option.
Alternatively, one can check out individual subprojects that consitute Kaitai Struct suite. They are:
.ksy
into a parser source code written in a target programming language.ksy
filesTypically, using formats described in KS in your project, involves the following steps:
.ksy
file.ksy
file into target language source file and include
that file in your projectCheck out the tutorial and documentation for more information.