kaitai-struct-vscode (featuring BETA typescript support)

This is an extension built by Dominick Reba (@fudgepop01) that allows for relative ease of development of ksy files. To find out more about Kaitai Struct and what it can do, head here: [kaitai.io]

If you want to see an overview of what this extension can do, check out [the overview video here]

this is the first extension to utilize the [fudgedit] hex editor. An extension exposing the editor itself will be released at a later date if requested.

Usage

1. open the command palette
2. use the "open hex editor" command
3. in the file explorer, right-click the file you wish to view
4. select "open file as hex"
5. if the file is large, wait a bit for it to load
6. right click the ksy file you wish to visualize
7. choose "compile and examine ksy"
8. wait for it to process and send all the data
9. enjoy your visualization

To generate a new parser from a ksy file in a target language, right click on a ksy file and select "compile to target language". A prompt will appear where you choose the target langugae of choice. Pick the language and a parser will be generated from the ksy.

Pro Tip

Thanks to contributions from BryceBarbara, it is no longer necessary to manually edit the file associations. Thank you Bryce!

Features

regions: highlighting with depth

A region is the name I've given to the different chunks of a file. Depth refers to how many layers are traversed and visualized in the hex viewer. Take the following example ksy:

seq:
  - id: no_subregions
    type: u4
  - id: has_subregions
    type: example_type
types:
  example_type:
    seq:
      - id: first_child
        type: u4
      - id: second_child
        type: u2

When the region depth parameter has a value of 1, only the regions representing the no_subregions and has_subregions will show up. However, with a region depth of 2, the individual components of has_subregions, first_child and second_child, will appear and overlap its parent (has_subregions).

regions: tooltips

When hovering over one of these generated regions, you'll see some data about the underlying region in the form of a tooltip. This tooltip will contain at minumum a name (the id from the ksy) and the size of the region (along with start and end positions in brackets)

Hovering over regions will grey out all other regions to allow the the user to focus on what particular region is being highlighted and distinguish it from the others.

Hovering over a region with a raw value type, such as string or integer will (read: should) additionally display the obtained value in the best way it can.

chunks: focus on what's relevant

If the option is enabled, chunking will automatically take place when a node is clicked in the tree-view. This will force the hex viewer to only render the chunk of the file that's relevant.

tree views

Upon compiling a kaitai struct file, a tree view in the explorer panel will pop up (if enabled). This will be titled KSEXPLORER (Kaitai Struct EXPLORER), and contains a tree view of all of the region names along with their types (or values). This will also give the user a bit more control over the editor.

tree views: navigation

if a tree view's node has children, then a dropdown toggle will appear at the start of the node. Clicking this will expand that region and show the child nodes.

tree views: jumping

By clicking on one of the tree's nodes, the hex editor will jump to the location of that node in the hex, place the cursor at the starting byte of the node, and select the area occupied by the node in the editor. This allows the user to navigate and view regions significantly easier, or focus on particular regions without the color overlay.

Requirements

None! It should all work out of the box!

Release Notes

Version 1.0.0

Bugfixes

• WHOOPS I managed to break instances 8 months ago and never got around to fixing that
  • (in previous versions it only worked with the "eager analysis" box checked)
• Error messages from compilation now properly show the path to the problem

Additions

• kaitai struct compiler is updated once more (with VERY beta typescript support)
• KSExplorer renamed to "Kaitai Struct Explorer"
  • keyboard navigation for this panel improved
• more colors to differentiate between regions with varying levels of saturation depending on depth
• doc comments are shown when hovering over a region

Version 0.9.0

• The commands should work again!
• updated the kaitai struct compiler itself
• fixed major previously-somehow-uncaught bug that prevented commands from actually working (whoops)
• new options
  • "non-display character" is what will be displayed when the character does not have an ASCII equivalent
  • "non-display opacity" is how opaque said character is
  • "go to line" replaced by the significantly more useful "go to offset"
• updated the editor itself
  • makes it compatible with scroll wheels
  • hold Ctrl while scrolling to scroll 10x the normal amount
  • hold Shift while scrolling to scroll 1 line at a time
  • hold Ctrl+Shift while scrolling to scroll 1 page at a time
  • the tooltip text can be selected by clicking on a region. It will immediately warp to the cursor in a selectable state, only unfreezing when the editor is clicked again
• BETA typescript support
  • The compiler for this extension was built with a typescript fork created by @Theaninova
  • (here is the pull request for that feature)

Bugfixes

• unchecking the "chunk selected" option will now immediately display the full view once more
• made commands uh... well, the commands actually work now.

Future Plans:

• find MORE job lol
• MAYBE make doc comments show up in regions
  • I DID IT, WOO

Contributions / Credits:

• StencilJS for the tools that enabled me to build the hex editor
• @Theaninova for the beta typescript compiler
• @BryceBarbara for effectively refactoring an enormous amount of this extension's codebase, effectively making it much more maintainable
• Kaitai Struct (this literally would not exist without it)