Skip to content

merge queue: embarking main (6397007) and #241 together #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mergify wants to merge 2 commits into from
Closed

merge queue: embarking main (6397007) and #241 together #243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37abcb0
docs: expand getting started guide and add migration documentation
dosubot[bot] Apr 25, 2026
9c4b44d
Merge of #241
mergify[bot] Apr 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 63 additions & 31 deletions docs/API_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,11 +70,9 @@ let result = db.evaluate_file("sample.bin")?;
println!("Type: {}", result.description);

// With custom configuration
let config = EvaluationConfig {
timeout_ms: Some(5000),
enable_mime_types: true,
..Default::default()
};
let config = EvaluationConfig::default()
.with_timeout_ms(Some(5000))
.with_mime_types(true);
let db = MagicDatabase::with_builtin_rules_and_config(config)?;

// From file
Expand Down Expand Up @@ -123,14 +121,14 @@ let config = EvaluationConfig::comprehensive();
// - timeout_ms: Some(30000)
```

#### Validation
#### Builder Methods

`EvaluationConfig` is `#[non_exhaustive]` (as of v0.6.0); use builder-style setters:

```rust
let config = EvaluationConfig {
max_recursion_depth: 25,
max_string_length: 16384,
..Default::default()
};
let config = EvaluationConfig::default()
.with_max_recursion_depth(25)
.with_max_string_length(16384);

// Validate configuration
config.validate()?;
Expand Down Expand Up @@ -340,6 +338,7 @@ use libmagic_rs::MagicRule;
| `children` | `Vec<MagicRule>` | Nested rules |
| `level` | `u32` | Indentation level |
| `strength_modifier` | `Option<StrengthModifier>` | Optional strength modifier from `!:strength` directive |
| `value_transform` | `Option<ValueTransform>` | Optional value transformation (v0.6.0) |

#### OffsetSpec

Expand All @@ -349,12 +348,14 @@ Offset specification for locating data.
use libmagic_rs::OffsetSpec;
```

| Variant | Description |
| ------------------------------------------------------------ | ------------------------------- |
| `Absolute(i64)` | Absolute offset from file start |
| `Indirect { base_offset, pointer_type, adjustment, endian }` | Indirect through pointer |
| `Relative(i64)` | Relative to previous match |
| `FromEnd(i64)` | Offset from end of file |
| Variant | Description |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
| `Absolute(i64)` | Absolute offset from file start |
| `Indirect { base_offset, pointer_type, adjustment, endian, base_relative, adjustment_op, result_relative }` | Indirect through pointer |
| `Relative(i64)` | Relative to previous match |
| `FromEnd(i64)` | Offset from end of file |

**v0.6.0 Changes:** The `Indirect` variant added three fields: `base_relative: bool`, `adjustment_op: Option<AdjustmentOp>`, and `result_relative: bool` to support advanced indirect offset resolution.

#### TypeKind

Expand Down Expand Up @@ -505,19 +506,19 @@ use libmagic_rs::EvaluationContext;

#### Methods

| Method | Description |
| ------------------------------ | ---------------------------------- |
| `new(config)` | Create new context |
| `current_offset()` | Get current position |
| `set_current_offset(offset)` | Set current position |
| `recursion_depth()` | Get recursion depth |
| `increment_recursion_depth()` | Increment depth (with limit check) |
| `decrement_recursion_depth()` | Decrement depth |
| Method | Description |
| ----------------------------- | ---------------------------------- |
| `new(config)` | Create new context |
| `current_offset()` | Get current position |
| `set_current_offset(offset)` | Set current position |
| `recursion_depth()` | Get recursion depth |
| `should_stop_at_first_match()` | Check stop behavior |
| `max_string_length()` | Get max string length |
| `enable_mime_types()` | Check MIME type setting |
| `timeout_ms()` | Get timeout value |
| `reset()` | Reset to initial state |
| `max_string_length()` | Get max string length |
| `enable_mime_types()` | Check MIME type setting |
| `timeout_ms()` | Get timeout value |
| `reset()` | Reset to initial state |

**v0.6.0 Changes:** The `increment_recursion_depth()` and `decrement_recursion_depth()` methods were removed.

### MatchResult (Evaluator)

Expand Down Expand Up @@ -633,9 +634,9 @@ Currently, libmagic-rs does not have optional feature flags. All functionality i

## Thread Safety

- `MagicDatabase` is **not** `Send` or `Sync` by default due to internal state
- `MagicDatabase` implements `Send + Sync` as of v0.6.0 and can be shared across threads
- `EvaluationConfig` is `Send + Sync` (plain data)
- For multi-threaded use, create separate `MagicDatabase` instances per thread or use appropriate synchronization
- For optimal performance in multi-threaded scenarios, consider cloning the database or using `Arc<MagicDatabase>`

---

Expand All @@ -649,6 +650,37 @@ Currently, libmagic-rs does not have optional feature flags. All functionality i

## Breaking Changes

### v0.6.0

**EvaluationConfig is now #[non_exhaustive]**:

- Struct literal construction (`EvaluationConfig { field: value, .. }`) is no longer supported outside the crate
- Use builder-style setters: `EvaluationConfig::default().with_max_recursion_depth(25).with_timeout_ms(Some(5000))`
- Available setters: `with_max_recursion_depth()`, `with_max_string_length()`, `with_stop_at_first_match()`, `with_mime_types()`, `with_timeout_ms()`

**MagicRule gains value_transform field**:

- The `MagicRule` struct has a new `value_transform: Option<ValueTransform>` field
- Existing code constructing `MagicRule` with struct literals must add this field

**OffsetSpec::Indirect gains new fields**:

- The `Indirect` variant added: `base_relative: bool`, `adjustment_op: Option<AdjustmentOp>`, `result_relative: bool`
- Existing pattern matches on `Indirect` must account for these fields or use wildcard patterns

**Multiple enums marked #[non_exhaustive]**:

- `OffsetSpec`, `LibmagicError`, `IoError`, `Operator`, `TypeReadError`, `ParseError`, `Value`, `TypeKind`, `EvaluationError`
- External match arms on these enums must include a wildcard pattern (`_ =>`)

**EvaluationContext method removals**:

- `increment_recursion_depth()` and `decrement_recursion_depth()` removed (internal recursion tracking changed)

**MagicDatabase now implements Send + Sync**:

- `MagicDatabase` can now be shared across threads safely

### v0.5.0

**Meta-type directives and format substitution** (PR #230):
Expand Down
30 changes: 13 additions & 17 deletions docs/GETTING_STARTED.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,12 @@ Add libmagic-rs to your `Cargo.toml`:

```toml
[dependencies]
libmagic-rs = "0.5.0"
libmagic-rs = "0.6.0"
```

**Note:** Version 0.5.0 introduces breaking changes. If upgrading from 0.4.x, the `RuleMatch` struct has a new `type_kind` field that must be included in struct literals, the `Value` enum no longer derives the `Eq` trait (affecting comparison operations), and the `TypeKind` enum gained two new variants (`Float`, `Double`) for floating-point types with endian variants, causing the `TypeKind::String` variant discriminant to change from 4 to 6. Exhaustive pattern matching on `TypeKind` and struct literals for `RuleMatch` require updates.
**Note:** Version 0.6.0 introduces breaking changes. `EvaluationConfig` is now `#[non_exhaustive]` and cannot be constructed with struct literals. Use builder methods (`with_timeout_ms`, `with_max_recursion_depth`, `with_max_string_length`, `with_stop_at_first_match`, `with_mime_types`) or `..Default::default()` syntax. `MagicRule` gained a `value_transform` field. Several enums (`OffsetSpec`, `LibmagicError`, `IoError`, `Operator`, `TypeReadError`, `ParseError`, `Value`, `TypeKind`, `EvaluationError`) are now `#[non_exhaustive]` and require a wildcard `_` in pattern matching. `parse_text_magic_file` returns `ParsedMagic { rules, name_table }` instead of `Vec<MagicRule>`. Many parser grammar functions moved from public to internal API. `evaluate_single_rule` signature changed. `MimeMapper` now implements `Copy`.

Version 0.5.0 introduces breaking changes. If upgrading from 0.4.x, the `RuleMatch` struct has a new `type_kind` field that must be included in struct literals, the `Value` enum no longer derives the `Eq` trait (affecting comparison operations), and the `TypeKind` enum gained two new variants (`Float`, `Double`) for floating-point types with endian variants, causing the `TypeKind::String` variant discriminant to change from 4 to 6. Exhaustive pattern matching on `TypeKind` and struct literals for `RuleMatch` require updates.

Version 0.4.0 introduces breaking changes. If upgrading from 0.3.x, the `Operator` enum gained three new variants (`BitwiseXor`, `BitwiseNot`, `AnyValue`) for bitwise and any-value operations. Exhaustive pattern matching on `Operator` requires updates.

Expand Down Expand Up @@ -69,7 +71,7 @@ Edit `Cargo.toml`:

```toml
[dependencies]
libmagic-rs = "0.5.0"
libmagic-rs = "0.6.0"
```

#### Step 3: Write Code
Expand Down Expand Up @@ -141,12 +143,10 @@ let db = MagicDatabase::load_from_file("/usr/share/file/magic")?;
```rust
use libmagic_rs::{MagicDatabase, EvaluationConfig};

let config = EvaluationConfig {
timeout_ms: Some(5000), // 5 second timeout
enable_mime_types: true, // Get MIME types
max_string_length: 16384, // Larger string buffer
..Default::default()
};
let config = EvaluationConfig::default()
.with_timeout_ms(Some(5000)) // 5 second timeout
.with_mime_types(true) // Get MIME types
.with_max_string_length(16384); // Larger string buffer

let db = MagicDatabase::with_builtin_rules_and_config(config)?;
```
Expand Down Expand Up @@ -351,10 +351,8 @@ fn is_image(path: &str) -> bool {
use libmagic_rs::{MagicDatabase, EvaluationConfig};

fn validate_upload(data: &[u8], allowed_types: &[&str]) -> Result<bool, String> {
let config = EvaluationConfig {
timeout_ms: Some(1000), // Short timeout for uploads
..Default::default()
};
let config = EvaluationConfig::default()
.with_timeout_ms(Some(1000)); // Short timeout for uploads

let db = MagicDatabase::with_builtin_rules_and_config(config)
.map_err(|e| e.to_string())?;
Expand Down Expand Up @@ -421,10 +419,8 @@ struct FileInfo {
}

fn get_file_info(path: &str) -> Result<FileInfo, String> {
let config = libmagic_rs::EvaluationConfig {
enable_mime_types: true,
..Default::default()
};
let config = libmagic_rs::EvaluationConfig::default()
.with_mime_types(true);

let db = MagicDatabase::with_builtin_rules_and_config(config)
.map_err(|e| e.to_string())?;
Expand Down
Loading
Loading