kaitai_struct

Estrutura Kaitai

Nota: se você quiser fazer alterações no projeto, não bifurque este repositório kaitai_struct . Em vez disso, escolha o componente que deseja modificar na árvore de arquivos acima e bifurque esse componente individual.

Este é um repositório guarda-chuva, contendo os componentes apenas como submódulos para facilitar o check-out de todo o projeto. A menos que você queira modificar este README, não é o repositório onde você pode fazer edições.

O que é estrutura Kaitai?

Kaitai Struct é uma linguagem declarativa usada para descrever várias estruturas de dados binários dispostas em arquivos ou na memória: ou seja, formatos de arquivos binários, formatos de pacotes de fluxo de rede, etc.

A ideia principal é que um formato específico seja descrito na linguagem Kaitai Struct apenas uma vez e então possa ser compilado com um ksc em arquivos de origem em uma das linguagens de programação suportadas. Esses módulos incluirão um código gerado para um analisador que pode ler a estrutura de dados descrita de um arquivo/stream e dar acesso a ela em uma API agradável e fácil de compreender.

Para que serve?

Você já se viu escrevendo código repetitivo, sujeito a erros e difícil de depurar, que lê estruturas de dados binários de fluxo de arquivo/rede e de alguma forma os representa na memória para facilitar o acesso?

Kaitai Struct tenta tornar esse trabalho mais fácil - você só precisa descrever o formato binário uma vez e então todos poderão usá-lo em suas linguagens de programação - entre linguagens e plataformas.

Kaitai Struct inclui uma coleção crescente de descrições de formato, disponíveis no repositório de submódulos de formatos.

Você pode me dar um exemplo rápido?

Claro. Considere este arquivo de descrição de formato .ksy simples que descreve o cabeçalho de um arquivo GIF (um formato popular de imagem da web):

 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

Ele declara que os arquivos GIF geralmente têm uma extensão .gif e usam codificação inteira little-endian. O arquivo em si começa com dois blocos: primeiro vem header e depois vem logical_screen :

• "Cabeçalho" consiste em uma string "mágica" de 3 bytes ("GIF") que identifica que se trata de um arquivo GIF começando e depois há mais 3 bytes que identificam a versão do formato ( 87a ou 89a ).
• "Descritor de tela lógica" é um bloco de números inteiros:
  • image_width e image_height são inteiros não assinados de 2 bytes
  • flags , bg_color_index e pixel_aspect_ratio levam 1 byte unsigned int cada

Este arquivo .ksy pode ser compilado em Gif.cs / Gif.java / Gif.js / Gif.php / gif.py / gif.rb e então instantaneamente pode-se carregar o arquivo .gif e acessar, por exemplo, sua largura e altura.

Em C#

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

Em Java

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

Em JavaScript

Consulte as notas sobre JavaScript na documentação para obter um guia de início rápido mais completo.

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

Na Lua

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

Em Nim

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

Em 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 ());

Em 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 )

Em rubi

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

É claro que este exemplo mostra apenas um subconjunto muito limitado do que o Kaitai Struct pode fazer. Consulte os tutoriais e a documentação para obter mais informações.

Idiomas suportados

O compilador oficial Kaitai Struct agora suporta a compilação .ksy em módulos de origem para os seguintes idiomas:

• C#
• Java
• JavaScript
• Lua
• Nim
• PHP
• Pitão
• Rubi

Baixando e instalando

A maneira mais fácil de verificar todo o projeto Kaitai Struct é baixar o repositório principal do projeto que já importa todas as outras partes como submódulos. Usar:

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

Observe a opção --recursive .

Alternativamente, pode-se verificar subprojetos individuais que constituem o pacote Kaitai Struct. Eles são:

• kaitai_struct_compiler — compilador que traduz .ksy em um código-fonte do analisador escrito em uma linguagem de programação alvo
• kaitai_struct_tests — testes e especificações para garantir que o compilador funcione conforme planejado
• Bibliotecas de tempo de execução
  • kaitai_struct_cpp_stl_runtime — para C++/STL
  • kaitai_struct_csharp_runtime — para C#
  • kaitai_struct_java_runtime — para Java
  • kaitai_struct_javascript_runtime — para JavaScript
  • kaitai_struct_nim_runtime — para Nim
  • kaitai_struct_lua_runtime — para Lua
  • kaitai_struct_python_runtime — para Python
  • kaitai_struct_ruby_runtime — para Ruby
  • kaitai_struct_swift_runtime — para Swift
• kaitai_struct_formats — biblioteca de formatos amplamente usados ​​e estruturas binárias descritas como arquivos .ksy

Usando KS em seu projeto

Normalmente, usar os formatos descritos no KS em seu projeto envolve as seguintes etapas:

• Descreva o formato – ou seja, crie um arquivo .ksy
• Compile o arquivo .ksy no arquivo de origem do idioma de destino e inclua esse arquivo em seu projeto
• Adicione a biblioteca de tempo de execução KS para sua linguagem específica em seu projeto (não se preocupe, ela é pequena e existe principalmente para garantir a legibilidade do código gerado)
• Use classes geradas para analisar seu arquivo/fluxo binário e acessar seus componentes

Confira o tutorial e a documentação para obter mais informações.

Licenciamento

• Compilador – GPLv3+
• Bibliotecas de tempo de execução — MIT ou Apache v2 (=> você pode incluir código gerado até mesmo em aplicativos proprietários) — consulte bibliotecas individuais para obter detalhes