{"id":13642917,"url":"https://github.com/kaitai-io/kaitai_struct","last_synced_at":"2025-05-13T21:11:20.595Z","repository":{"id":37493265,"uuid":"52159512","full_name":"kaitai-io/kaitai_struct","owner":"kaitai-io","description":"Kaitai Struct: declarative language to generate binary data parsers in C++ / C# / Go / Java / JavaScript / Lua / Nim / Perl / PHP / Python / Ruby","archived":false,"fork":false,"pushed_at":"2025-04-19T21:59:14.000Z","size":310,"stargazers_count":4153,"open_issues_count":502,"forks_count":198,"subscribers_count":95,"default_branch":"master","last_synced_at":"2025-04-28T17:06:44.645Z","etag":null,"topics":["c-plus-plus","cpp","csharp","declarative-language","file-format","go","golang","graphviz","java","javascript","lua","nim","perl","php","protocol-analyser","python","reverse-engineering","ruby"],"latest_commit_sha":null,"homepage":"https://kaitai.io","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaitai-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-02-20T15:17:00.000Z","updated_at":"2025-04-28T13:06:21.000Z","dependencies_parsed_at":"2023-10-16T14:29:05.950Z","dependency_job_id":"fa2f4163-58d7-42b0-a061-88dd73e499a8","html_url":"https://github.com/kaitai-io/kaitai_struct","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitai-io%2Fkaitai_struct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitai-io%2Fkaitai_struct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitai-io%2Fkaitai_struct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaitai-io%2Fkaitai_struct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaitai-io","download_url":"https://codeload.github.com/kaitai-io/kaitai_struct/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254029003,"owners_count":22002283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","cpp","csharp","declarative-language","file-format","go","golang","graphviz","java","javascript","lua","nim","perl","php","protocol-analyser","python","reverse-engineering","ruby"],"created_at":"2024-08-02T01:01:38.045Z","updated_at":"2025-05-13T21:11:14.699Z","avatar_url":"https://github.com/kaitai-io.png","language":"Shell","funding_links":[],"categories":["Tools","Structure definition","Shell","c-plus-plus","Repositories"],"sub_categories":["Binary files examination and editing"],"readme":"# Kaitai Struct\n\n[![Join the chat at https://gitter.im/kaitai_struct/Lobby](https://badges.gitter.im/kaitai_struct/Lobby.svg)](https://gitter.im/kaitai_struct/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n\u003e **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.\n\u003e\n\u003e 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.\n\n## What is Kaitai Struct?\n\nKaitai Struct is a declarative language used for describing various\nbinary data structures laid out in files or in memory: i.e. binary\nfile formats, network stream packet formats, etc.\n\nThe main idea is that a particular format is described in Kaitai\nStruct language only once and then can be compiled with a `ksc` into\nsource files in one of the supported programming languages. These\nmodules will include a generated code for a parser that can read\ndescribed data structure from a file / stream and give access to it in\na nice, easy-to-comprehend API.\n\n## What it's used for?\n\nHave you ever found yourself writing repetitive, error-prone and\nhard-to-debug code that reads binary data structures from file /\nnetwork stream and somehow represents them in memory for easier\naccess?\n\nKaitai Struct tries to make this job easier — you only have to\ndescribe the binary format once and then everybody can use it from their\nprogramming languages — cross-language, cross-platform.\n\nKaitai Struct includes a growing collection of format descriptions,\navailable in\n[formats](https://github.com/kaitai-io/kaitai_struct_formats)\nsubmodule repository.\n\n## Can you give me a quick example?\n\nSure. Consider this simple `.ksy` format description file that\ndescribes the header of a GIF file (a popular web image format):\n\n```yaml\nmeta:\n  id: gif\n  file-extension: gif\n  endian: le\nseq:\n  - id: header\n    type: header\n  - id: logical_screen\n    type: logical_screen\ntypes:\n  header:\n    seq:\n      - id: magic\n        contents: 'GIF'\n      - id: version\n        size: 3\n  logical_screen:\n    seq:\n      - id: image_width\n        type: u2\n      - id: image_height\n        type: u2\n      - id: flags\n        type: u1\n      - id: bg_color_index\n        type: u1\n      - id: pixel_aspect_ratio\n        type: u1\n```\n\nIt declares that GIF files usually have a `.gif` extension and use\nlittle-endian integer encoding. The file itself starts with two\nblocks: first comes `header` and then comes `logical_screen`:\n\n* \"Header\" consists of \"magic\" string of 3 bytes (\"GIF\") that\n  identifies that it's a GIF file starting and then there are 3 more\n  bytes that identify format version (`87a` or `89a`).\n* \"Logical screen descriptor\" is a block of integers:\n  * `image_width` and `image_height` are 2-byte unsigned ints\n  * `flags`, `bg_color_index` and `pixel_aspect_ratio` take 1-byte\n    unsigned int each\n\nThis `.ksy` file can be compiled it into `Gif.cs` / `Gif.java` /\n`Gif.js` / `Gif.php` / `gif.py` / `gif.rb` and then instantly one can load .gif\nfile and access, for example, it's width and height.\n\n### In C\\#\n\n```cs\nGif g = Gif.FromFile(\"path/to/some.gif\");\nConsole.WriteLine(\"width = \" + g.LogicalScreen.ImageWidth);\nConsole.WriteLine(\"height = \" + g.LogicalScreen.ImageHeight);\n```\n\n### In Java\n\n```java\nGif g = Gif.fromFile(\"path/to/some.gif\");\nSystem.out.println(\"width = \" + g.logicalScreen().imageWidth());\nSystem.out.println(\"height = \" + g.logicalScreen().imageHeight());\n```\n\n### In JavaScript\n\nSee [JavaScript notes in the documentation](http://doc.kaitai.io/lang_javascript.html) for a more complete quick start guide.\n\n```javascript\nvar g = new Gif(new KaitaiStream(someArrayBuffer));\nconsole.log(\"width = \" + g.logicalScreen.imageWidth);\nconsole.log(\"height = \" + g.logicalScreen.imageHeight);\n```\n\n### In Lua\n\n```lua\nlocal g = Gif:from_file(\"path/to/some.gif\")\nprint(\"width = \" .. g.logical_screen.image_width)\nprint(\"height = \" .. g.logical_screen.image_height)\n```\n\n### In Nim\n```nim\nlet g = Gif.fromFile(\"path/to/some.gif\")\necho \"width = \" \u0026 $g.logicalScreen.imageWidth\necho \"height = \" \u0026 $g.logicalScreen.imageHeight\n```\n\n### In PHP\n\n```php\n$g = Gif::fromFile('path/to/some.gif');\nprintf(\"width = %d\\n\", $g-\u003elogicalScreen()-\u003eimageWidth());\nprintf(\"height = %d\\n\", $g-\u003elogicalScreen()-\u003eimageHeight());\n```\n\n### In Python\n\n```python\ng = Gif.from_file(\"path/to/some.gif\")\nprint \"width = %d\" % (g.logical_screen.image_width)\nprint \"height = %d\" % (g.logical_screen.image_height)\n```\n\n### In Ruby\n\n```ruby\ng = Gif.from_file(\"path/to/some.gif\")\nputs \"width = #{g.logical_screen.image_width}\"\nputs \"height = #{g.logical_screen.image_height}\"\n```\n\nOf course, this example shows only a very limited subset of what Kaitai\nStruct can do. Please refer to the tutorials and documentation for\nmore insights.\n\n## Supported languages\n\nOfficial Kaitai Struct [compiler] now supports compiling `.ksy` into\nsource modules for the following languages:\n\n* C#\n* Java\n* JavaScript\n* Lua\n* Nim\n* PHP\n* Python\n* Ruby\n\n## Downloading and installing\n\nThe easiest way to check out the whole Kaitai Struct project is to\ndownload the main project repository that already imports all other parts\nas submodules. Use:\n\n    git clone --recursive https://github.com/kaitai-io/kaitai_struct.git\n\nNote the `--recursive` option.\n\nAlternatively, one can check out individual subprojects that\nconsitute Kaitai Struct suite. They are:\n\n* [kaitai_struct_compiler](https://github.com/kaitai-io/kaitai_struct_compiler) — compiler that translates `.ksy` into a parser source code written in a target programming language\n* [kaitai_struct_tests](https://github.com/kaitai-io/kaitai_struct_tests) — tests \u0026 specs to ensure that compiler work as planned\n* Runtime libraries\n  * [kaitai_struct_cpp_stl_runtime](https://github.com/kaitai-io/kaitai_struct_cpp_stl_runtime) — for C++/STL\n  * [kaitai_struct_csharp_runtime](https://github.com/kaitai-io/kaitai_struct_csharp_runtime) — for C#\n  * [kaitai_struct_java_runtime](https://github.com/kaitai-io/kaitai_struct_java_runtime) — for Java\n  * [kaitai_struct_javascript_runtime](https://github.com/kaitai-io/kaitai_struct_javascript_runtime) — for JavaScript\n  * [kaitai_struct_nim_runtime](https://github.com/kaitai-io/kaitai_struct_nim_runtime) — for Nim\n  * [kaitai_struct_lua_runtime](https://github.com/kaitai-io/kaitai_struct_lua_runtime) — for Lua\n  * [kaitai_struct_python_runtime](https://github.com/kaitai-io/kaitai_struct_python_runtime) — for Python\n  * [kaitai_struct_ruby_runtime](https://github.com/kaitai-io/kaitai_struct_ruby_runtime) — for Ruby\n  * [kaitai_struct_swift_runtime](https://github.com/kaitai-io/kaitai_struct_swift_runtime) — for Swift\n* [kaitai_struct_formats](https://github.com/kaitai-io/kaitai_struct_formats)\n  — library of widely used formats and binary structures described as\n  `.ksy` files\n\n## Using KS in your project\n\nTypically, using formats described in KS in your project, involves the\nfollowing steps:\n\n* Describe the format — i.e. create a `.ksy` file\n* Compile `.ksy` file into target language source file and include\n  that file in your project\n* Add KS runtime library for your particular language into your\n  project (don't worry, it's small and it's there mostly to ensure\n  readability of generated code)\n* Use generated class(es) to parse your binary file / stream and\n  access its components\n\nCheck out the tutorial and documentation for more information.\n\n## Licensing\n\n* [Compiler] — GPLv3+\n* Runtime libraries — MIT or Apache v2 (=\u003e you can include generated\n  code even into proprietary applications) — see individual libraries\n  for details\n\n[compiler]: https://github.com/kaitai-io/kaitai_struct_compiler\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaitai-io%2Fkaitai_struct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaitai-io%2Fkaitai_struct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaitai-io%2Fkaitai_struct/lists"}