## 1. Project Overview & Quickstart (kaitai-io/kaitai_struct)

## File: README.md

# Kaitai Struct

[](https://gitter.im/kaitai_struct/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

> [!NOTE]
> If you want to make changes to the project, do **not** fork this `kaitai_struct` repository. 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.

## What is Kaitai Struct?

Kaitai Struct (KS) is a declarative language used to describe 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 (`.ksy` file) only once and then can be compiled with
`kaitai-struct-compiler` (or `ksc` for short) into source files in one
of the supported programming languages. These modules will include
generated code for a parser that can read the described data structure
from a file or stream and provide access to it in a nice,
easy-to-comprehend API.

## What is it used for?

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](https://github.com/kaitai-io/kaitai_struct_formats)
submodule repository.

## Using KS in your project

Typically, using formats described in KS in your project involves the
following steps:

* Describe the format — i.e. create a `.ksy` file
* Use a visualizer to debug the format and ensure that it parses data
  properly (official visualizers are [Web IDE](https://ide.kaitai.io/)
  and the console visualizer
  [ksv](https://github.com/kaitai-io/kaitai_struct_visualizer))
* Compile the `.ksy` file into a target language source file and include
  that file in your project
* Add the KS runtime library for your particular language to your
  project (don't worry, it's small and it's there mostly to ensure
  readability of generated code)
* Use the generated class(es) to parse your binary file or stream and
  access its components

To see an example, a list of supported languages, download instructions
and licensing information, visit https://kaitai.io/.

---

## File: runtime/README.md

# Developers' memo for runtimes

All runtimes should include at least the following methods in
`KaitaiStream` class (or its equivalent). It's heavily preferred to
maintain exactly this order of declarations and group headers.

## Stream positioning

* `eof?`
* `seek(n)`
* `pos`
* `size`

## Integer numbers

### Signed

* `read_s1`

#### Big-endian

* `read_s2be`
* `read_s4be`
* `read_s8be`

#### Little-endian

* `read_s2le`
* `read_s4le`
* `read_s8le`

### Unsigned

* `read_u1`

#### Big-endian

* `read_u2be`
* `read_u4be`
* `read_u8be`

#### Little-endian

* `read_u2le`
* `read_u4le`
* `read_u8le`

## Floating point numbers

### Big-endian

* `read_f4be`
* `read_f8be`

### Little-endian

* `read_f4le`
* `read_f8le`

## Unaligned bit values

* `align_to_byte()`
* `read_bits_int(n)`
* `read_bits_array(n)`

## Byte arrays

* `read_bytes(n)`
* `read_bytes_full`
* `read_bytes_term(String encoding, int term, boolean include_term, boolean consumeTerm, boolean eosError)`
* `ensure_fixed_contents(expected)`
* static `bytes_strip_right(bytes, pad_byte)`
* static `bytes_terminate(bytes, term, include_term)`
* static `bytes_to_str(bytes, encoding)`

## Byte array processing

* `process_xor(data, key)`
  * `process_xor_one(data, key)`
  * `process_xor_many(data, key)`
* `process_rotate_left(data, amount, group_size)`
* `process_zlib(data)`

## Misc runtime operations

* static `mod(a, b)`

## 2. Official Technical Reference & Guides (kaitai-io/kaitai-io.github.io)

# [kaitai.io](https://kaitai.io/) - Kaitai Project homepage

Kaitai Struct homepage at [kaitai.io](https://kaitai.io/) is a static site generated by [Jekyll](https://jekyllrb.com/) and hosted on GitHub Pages.

Jekyll generates static output `.html` files from source Markdown (`.md`) pages and a few `.html` [layouts](https://jekyllrb.com/docs/step-by-step/04-layouts/) (_templates_) from folder [`_layouts/`](./_layouts/).

The Markdown dialect used is [kramdown](https://kramdown.gettalong.org/index.html). Here's the syntax [quick reference guide](https://kramdown.gettalong.org/quickref.html).

The site uses [Bootstrap v3.3.6](https://getbootstrap.com/docs/3.3/) to simplify CSS coding and to ensure the decent appearance and design of the page.

Jekyll configuration is present in file [`_config.yml`](./_config.yml). Possible configuration options can be found [in the Jekyll docs](https://jekyllrb.com/docs/configuration/).

## Local testing

### Installing Jekyll

You need to have [Jekyll](https://jekyllrb.com/) installed on your machine to be able to build the generated site locally. Run `jekyll --version` to find out. If you don't have it, try running:

```bash
gem install jekyll
```

If this fails, follow the [Jekyll installation guide](https://jekyllrb.com/docs/installation/) for your OS.

### Installing Jekyll plugins

The site uses these plugins (see `plugins` key in [`_config.yml`](./_config.yml)):

- [`jekyll-redirect-from`](https://github.com/jekyll/jekyll-redirect-from)

Install them using:

```bash
gem install jekyll-redirect-from
```

### Jekyll commands

To build the site and place the generated files into the `_site/` folder, run:

```bash
jekyll build
```

For local development, however, using `jekyll build` is inconvenient because it only runs once, so you would have to run it manually after each change to the source files. Much more useful command is:

```bash
jekyll serve
```

It builds the site, launches a local server at http://127.0.0.1:4000/, watches the source files and rebuilds the site every time they are changed. This makes local development much easier.