honzo-chunks 0.1.0

Honzo ebook chunk types, validation, and analysis
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

# Honzo

[![CI](https://github.com/Nisoku/Honzo/actions/workflows/lint.yml/badge.svg)](https://github.com/Nisoku/Honzo/actions/workflows/lint.yml)
[![npm version](https://img.shields.io/npm/v/@nisoku/honzo.svg)](https://www.npmjs.com/package/@nisoku/honzo)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

---

The "ideal" ebook format.

Honzo is a binary ebook format designed for simplicity, performance, and portability.

## Features

| Feature                      | Description                                                                 |
|------------------------------|-----------------------------------------------------------------------------|
| **Zero-copy parsing**        | Read without allocating: embeddable on bare metal                           |
| **Pull-based streaming**     | Decompress chapters on demand, never hold the whole book in memory          |
| **Per-chunk compression**    | lz4, selected per chapter via TOC flag                                      |
| **Separately editable tail** | META is last: edit title, tags, revision without touching DATA              |
| **Portable annotations**     | org.nisoku.anno in EXTRA: highlights, bookmarks, notes travel with the file |
| **Search index**             | SIDX chunk with inverted term index (MessagePack)                           |
| **Encryption envelope**      | org.nisoku.drm for AES-256-CBC content protection                           |
| **Multi-language metadata**  | Titles and descriptions localized per BCP 47 language tag                   |

## Quick Start

### Rust

```rust
use honzo_std::{HonzoParser, HonzoStream, Builder};

// Zero-copy parse
let data = std::fs::read("book.hzo").unwrap();
let p = HonzoParser::new(&data, 1).unwrap();
println!("{} chunks", p.head().chunk_count);
for entry in p.toc_entries() {
    println!("  {} - {:?}", entry.chunk_id, std::str::from_utf8(&entry.chunk_type));
}

// Streaming read
let file = std::fs::File::open("book.hzo").unwrap();
let mut stream = HonzoStream::open(file, 1).unwrap();
for chapter in stream.chapters() {
    let text = chapter.unwrap();
    println!("Chapter: {} bytes", text.len());
}

// Build
let hzo = Builder::new()
    .add_chunk(*b"CHAP", b"Hello, world!", Compression::None,
               MarkupType::Markdown, CoverType::Front, None, None, None)
    .finalize()
    .unwrap();
```

### TypeScript

```typescript
import { createReader, buildHonzo } from '@nisoku/honzo';

const response = await fetch('book.hzo');
const buf = new Uint8Array(await response.arrayBuffer());
const reader = await createReader(buf);
console.log(reader.chunkCount, reader.layoutMode);

const meta = reader.getMeta();
console.log(meta.title?.en);
```

### C

```c
#include "honzo.h"

HonzoHandle* handle = HonzoHandle_parse(data, data_len, 1);
uint32_t count = HonzoHandle_chunk_count(handle);
```

## Repository Layout

```txt
Honzo/
  Cargo.toml                # Rust workspace root
  Build/
    crates/
      honzo-core/           # no_std wire-format + parser
      honzo-chunks/         # chunk semantics (SIDX, COVT, extras)
      honzo-io/             # builder/reader/stream + compression (std)
      honzo-convert/        # epub/mobi/pdf import
      honzo-c/              # C FFI bindings (Diplomat)
      honzo-wasm/           # wasm-pack target
      honzo-cli/            # CLI binary
    adapters/typescript/    # npm @nisoku/honzo
  Demo/                     # Vite web demo
  Docs/                     # Documentation site
  Tests/
    fixtures/                # Sample .hzo files
    corpus/                 # Edge case files
    tests/                  # Rust integration tests
  honzo.ksy                 # Kaitai Struct spec
```

## Documentation

- [Getting Started](https://nisoku.github.io/Honzo/getting-started/quickstart/)
- [Format Specification](honzo.ksy)
- [API Reference](https://nisoku.github.io/Honzo/api/)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

Apache License 2.0. See [LICENSE](LICENSE).