iwa-inspector/README.md

110 lines
3.1 KiB
Markdown
Raw Normal View History

2023-05-17 01:56:27 +00:00
# iwa-inspector
source for <https://sheetjs.com/tools/iwa-inspector>
`iwa-inspector` is a tool for inspecting iWork archives.
2023-07-26 00:12:12 +00:00
<https://oss.sheetjs.com/notes/iwa/> covers the high-level structure of files.
This inspector performs the top-level extraction of messages and parses using
extracted Protocol Buffer definitions.
2023-07-25 09:19:37 +00:00
## Usage
2023-07-26 00:12:12 +00:00
The sections are separated by a light gray horizontal line and a light gray
vertical line. Panels can be resized by click-dragging the line.
### Selecting a File
The file input element in the top-left corner of the page is limited to the IWA
file types: `.numbers`, `.key`, and `.pages`.
The site automatically fetches a sample file on load.
### Message Table
The message table is shown just below the header bar. The column headers are:
| name | description |
|:----------|:----------------------|
| `id` | Message ID |
| `type` | Numeric Message Type |
| `message` | Absolute Message Type |
| `path` | Location of Message |
The table can be sorted by clicking on the column headers.
### Searching for Messages
The search text box in the top-right corner of the page is a plaintext search
over the parsed messages. Searches will match field names, string values and
UUID fields of message type `.TSP.UUID`.
### Selecting a Message
2023-05-17 01:56:27 +00:00
2023-07-26 00:12:12 +00:00
When a row in the table is selected, the bottom-left panel will display the
Protocol Buffers definition for the message and the bottom-right panel will
display the parsed contents.
### Message Structure
The bottom-right panel shows the following information:
- "Message": parsed information following the message definition
- "Metadata": parsed information from the message metadata
- "Dependents": list of messages that list the current message as a dependency.
2023-05-17 01:56:27 +00:00
2023-07-25 09:19:37 +00:00
Clicking on a message name in the inspector will show the message definition in
the left pane. A "Return" link returns to the base message definition.
2023-05-17 01:56:27 +00:00
Clicking on a `.TSP.Reference` ID will jump to the referenced message.
2023-07-26 00:12:12 +00:00
### Exporting Data
2023-05-17 01:56:27 +00:00
Right-clicking a custom message type will show a context menu with options to
copy the raw byte representation (array of numbers) or parsed object (JSON).
## Development
`make dev` starts the dev server.
`make build` generates the static site.
2023-07-26 00:12:12 +00:00
## Refreshing Protos and Messages
2023-07-25 09:19:37 +00:00
`make deps` requires a SIP-disabled Intel Mac with Keynote + Numbers + Pages.
2023-05-17 01:56:27 +00:00
2023-07-26 00:12:12 +00:00
The last run was on 2023-06-26 against version 13.1
## Protocol Buffer Details
Note that the `message` field is absolute. For example, `TSTArchives.proto`
specifies the `.TST.TileStorage` as follows:
```proto
package TST;
message TileStorage {
message Tile {
required uint32 tileid = 1;
required .TSP.Reference tile = 2;
}
repeated .TST.TileStorage.Tile tiles = 1;
optional uint32 tile_size = 2;
optional bool should_use_wide_rows = 3;
}
```
The protobuf extractor rewrites the message names using the absolute form:
```proto
message .TST.TileStorage {
message Tile {
required uint32 tileid = 1;
required .TSP.Reference tile = 2;
}
repeated .TST.TileStorage.Tile tiles = 1;
optional uint32 tile_size = 2;
optional bool should_use_wide_rows = 3;
}
```