chore: release v0.6.0#240
Merged
Merged
Conversation
dosubot
Bot
added
size:M
Contributor
Merge ProtectionsYour pull request matches the following merge protections and will not be merged until they are valid. 🟢 Do not merge outdated PRsWonderful, this rule succeeded.Make sure PRs are within 10 commits of the base branch before merging
|
Contributor
|
Documentation Updates 4 document(s) were updated by changes in this PR: api-referenceView Changes@@ -45,12 +45,10 @@
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()
-};
+// With custom configuration (v0.6.0: use builder methods)
+let config = EvaluationConfig::default()
+ .with_timeout_ms(5000)
+ .with_mime_types(true);
let db = MagicDatabase::with_builtin_rules_and_config(config)?;
// From file
@@ -133,11 +131,10 @@
#### Validation
```rust
-let config = EvaluationConfig {
- max_recursion_depth: 25,
- max_string_length: 16384,
- ..Default::default()
-};
+// v0.6.0: Use builder methods instead of struct literals
+let config = EvaluationConfig::default()
+ .with_max_recursion_depth(25)
+ .with_max_string_length(16384);
// Validate configuration
config.validate()?;
@@ -553,7 +550,19 @@
- **Minimum Rust Version**: 1.85
- **Edition**: 2024
- **License**: Apache-2.0
-- **Current Version**: 0.5.0
+- **Current Version**: 0.6.0
+
+### Breaking Changes in v0.6.0
+
+- `MagicRule` struct now has an additional public field `value_transform`, requiring updates to any code that constructs `MagicRule` instances using struct literal syntax. Prefer using the `MagicRule::new()` constructor and builder methods (`with_children()`, `with_strength_modifier()`, etc.) for forward compatibility.
+- `EvaluationConfig` struct is now marked `#[non_exhaustive]`. Existing struct literals must switch to builder methods (`EvaluationConfig::default().with_max_recursion_depth(n).with_timeout_ms(ms)`) or the provided preset constructors (`::performance()`, `::comprehensive()`).
+- Several public enums (`OffsetSpec`, `LibmagicError`, `IoError`, `Operator`, `TypeReadError`, `ParseError`, `Value`, `TypeKind`, `EvaluationError`) are now marked `#[non_exhaustive]`. Pattern matching on these enums outside the crate must include a wildcard arm (`_ =>`).
+- `OffsetSpec::Indirect` struct variant has three new fields (`base_relative`, `adjustment_op`, `result_relative`). Existing pattern matches and struct literal constructions must be updated.
+- `MimeMapper` now implements `Copy` trait, changing closure capture semantics in non-move closures.
+- `FileBuffer::create_symlink` method removed.
+- `EvaluationContext::increment_recursion_depth` and `::decrement_recursion_depth` methods removed from the public API.
+- `libmagic_rs::parser::grammar` module is no longer public. Several grammar parsing functions previously exported (`parse_offset`, `parse_number`, `parse_magic_rule`, etc.) are now internal only.
+- `evaluate_single_rule` now takes 3 parameters instead of 2.
### Breaking Changes in v0.5.0
API_REFERENCEView Changes@@ -336,6 +336,7 @@
| `typ` | `TypeKind` | Type of data to read |
| `op` | `Operator` | Comparison operator |
| `value` | `Value` | Expected value |
+| `value_transform` | `Option<ValueTransform>` | Optional transformation applied to matched value |
| `message` | `String` | Description message |
| `children` | `Vec<MagicRule>` | Nested rules |
| `level` | `u32` | Indentation level |
@@ -657,3 +658,9 @@
- `MagicDatabase` struct now includes internal fields `root_rules: Arc<[MagicRule]>` and `name_table: Arc<NameTable>` to support meta-type evaluation.
- Printf-style format substitution (`%d`, `%x`, `%s`, etc.) is applied to the `message` field in `MatchResult`. Messages containing literal `%` characters that were previously passed through verbatim will now be interpreted as format specifiers. Escape literal `%` as `%%`.
- `TypeKind::Meta(MetaType)` enum added with variants `Default`, `Clear`, `Name`, `Use`, `Indirect`, `Offset`.
+
+### v0.6.0
+
+**MagicRule struct adds public field**:
+
+- `MagicRule` now has a new public field `value_transform: Option<ValueTransform>`. Existing code that constructs `MagicRule` with struct literals must include this field or use alternative construction patterns (such as the `MagicRule::new()` builder or `Default` trait). Code that only reads or pattern-matches on `MagicRule` without constructing it is unaffected.GETTING_STARTEDView Changes@@ -21,10 +21,12 @@
```toml
[dependencies]
-libmagic-rs = "0.5.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.
+libmagic-rs = "0.6.0"
+```
+
+**Note:** Version 0.6.0 introduces breaking changes. If upgrading from 0.5.x, see the [migration guide](MIGRATION_GUIDE.md) for details on the `MagicRule.value_transform` field addition, `Copy` trait implementation for `MimeMapper`, newly `#[non_exhaustive]` enums (`OffsetSpec`, `LibmagicError`, `IoError`, `Operator`, `TypeReadError`, `ParseError`, `Value`, `TypeKind`, `EvaluationError`) and structs (`EvaluationConfig`), additional fields on `OffsetSpec::Indirect`, and other API changes.
+
+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.
@@ -69,7 +71,7 @@
```toml
[dependencies]
-libmagic-rs = "0.5.0"
+libmagic-rs = "0.6.0"
```
#### Step 3: Write CodemigrationView Changes@@ -576,6 +576,277 @@
**Recommendation:** Avoid relying on enum discriminant values. Use pattern matching or the `std::mem::discriminant` function instead.
+## Migrating from v0.5.x to v0.6.0
+
+Version 0.6.0 introduces multiple breaking changes to the AST, parser API, and evaluator. These changes enable advanced features like indirect offsets, named subroutines, and meta-type directives.
+
+### MagicRule Struct Field Addition
+
+The `MagicRule` struct gained a new `value_transform` field. Code constructing `MagicRule` instances with struct literals must add this field or use the `..Default::default()` syntax to fill in missing fields.
+
+**Before (v0.5.x):**
+
+```rust,ignore
+use libmagic_rs::parser::ast::MagicRule;
+
+let rule = MagicRule {
+ level: 0,
+ offset_spec: OffsetSpec::Direct(0),
+ type_spec: TypeSpec { kind: TypeKind::Byte { signed: false }, operator: Some(Operator::Equal) },
+ value: Value::Uint(0x7f),
+ message: "ELF magic".to_string(),
+ strength_modifier: None,
+ children: vec![],
+};
+```
+
+**After (v0.6.0):**
+
+```rust,ignore
+use libmagic_rs::parser::ast::MagicRule;
+
+let rule = MagicRule {
+ level: 0,
+ offset_spec: OffsetSpec::Direct(0),
+ type_spec: TypeSpec { kind: TypeKind::Byte { signed: false }, operator: Some(Operator::Equal) },
+ value: Value::Uint(0x7f),
+ message: "ELF magic".to_string(),
+ strength_modifier: None,
+ children: vec![],
+ value_transform: None, // New field
+};
+```
+
+**Alternative with default values:**
+
+```rust,ignore
+let rule = MagicRule {
+ level: 0,
+ offset_spec: OffsetSpec::Direct(0),
+ type_spec: TypeSpec { kind: TypeKind::Byte { signed: false }, operator: Some(Operator::Equal) },
+ value: Value::Uint(0x7f),
+ message: "ELF magic".to_string(),
+ ..Default::default() // Fills in missing fields with defaults
+};
+```
+
+### OffsetSpec Enum Changes
+
+Multiple changes to the `OffsetSpec` enum affect pattern matching and construction:
+
+**Marked #[non_exhaustive]:**
+
+The `OffsetSpec` enum is now marked `#[non_exhaustive]`. Exhaustive pattern matches must include a wildcard pattern.
+
+```rust,ignore
+use libmagic_rs::parser::ast::OffsetSpec;
+
+// Before (v0.5.x) - exhaustive match
+match offset_spec {
+ OffsetSpec::Direct(offset) => { /* ... */ }
+ OffsetSpec::Indirect { /* ... */ } => { /* ... */ }
+}
+
+// After (v0.6.0) - wildcard required
+match offset_spec {
+ OffsetSpec::Direct(offset) => { /* ... */ }
+ OffsetSpec::Indirect { /* ... */ } => { /* ... */ }
+ _ => { /* handle future variants */ }
+}
+```
+
+**Indirect Variant Field Additions:**
+
+The `OffsetSpec::Indirect` variant gained three new fields:
+
+- `base_relative: bool` - Whether base offset is relative
+- `adjustment_op: Option<AdjustmentOp>` - Optional offset adjustment
+- `result_relative: bool` - Whether result offset is relative
+
+**Before (v0.5.x):**
+
+```rust,ignore
+let indirect = OffsetSpec::Indirect {
+ base_offset: 4,
+ read_type: TypeKind::Long { endian: Endianness::Big, signed: false },
+};
+```
+
+**After (v0.6.0):**
+
+```rust,ignore
+let indirect = OffsetSpec::Indirect {
+ base_offset: 4,
+ read_type: TypeKind::Long { endian: Endianness::Big, signed: false },
+ base_relative: false,
+ adjustment_op: None,
+ result_relative: false,
+};
+```
+
+### Parser API Changes
+
+The parser API changed to support named subroutines and meta-type directives.
+
+**parse_text_magic_file Return Type:**
+
+The return type changed from `Result<Vec<MagicRule>, ParseError>` to `Result<ParsedMagic, ParseError>`.
+
+**Before (v0.5.x):**
+
+```rust,ignore
+use libmagic_rs::parser::parse_text_magic_file;
+
+let rules = parse_text_magic_file("magic.mgc")?;
+for rule in rules {
+ // Process rule
+}
+```
+
+**After (v0.6.0):**
+
+```rust,ignore
+use libmagic_rs::parser::parse_text_magic_file;
+
+let parsed = parse_text_magic_file("magic.mgc")?;
+for rule in parsed.rules {
+ // Process rule
+}
+// Access name table for named subroutines
+let name_table = parsed.name_table;
+```
+
+**Removed Functions:**
+
+The following parser functions were removed or renamed:
+
+- `libmagic_rs::parser::grammar` module is no longer public
+- Individual parser functions like `parse_offset`, `parse_number` moved to internal grammar module
+- Use high-level `parse_text_magic_file` or `parse_magic_rule` instead
+
+### Evaluator API Changes
+
+**evaluate_single_rule Parameter Count:**
+
+The `evaluate_single_rule` function signature changed from 2 to 3 parameters to accept a `RuleEnvironment`.
+
+**Before (v0.5.x):**
+
+```rust,ignore
+use libmagic_rs::evaluator::evaluate_single_rule;
+
+let result = evaluate_single_rule(&rule, &buffer)?;
+```
+
+**After (v0.6.0):**
+
+```rust,ignore
+use libmagic_rs::evaluator::evaluate_single_rule;
+use libmagic_rs::evaluator::RuleEnvironment;
+
+let env = RuleEnvironment::new(); // Or pass existing environment
+let result = evaluate_single_rule(&rule, &buffer, &env)?;
+```
+
+**EvaluationContext Method Removals:**
+
+The following methods were removed from `EvaluationContext`:
+
+- `increment_recursion_depth` - Recursion tracking moved to internal implementation
+- `decrement_recursion_depth` - Recursion tracking moved to internal implementation
+
+If your code directly managed recursion tracking, use the high-level `evaluate_rules_with_config` API instead.
+
+### EvaluationConfig Struct Changes
+
+The `EvaluationConfig` struct is now marked `#[non_exhaustive]`. Code constructing `EvaluationConfig` with struct literals must use builder methods instead.
+
+**Before (v0.5.x):**
+
+```rust,ignore
+use libmagic_rs::config::EvaluationConfig;
+
+let config = EvaluationConfig {
+ enable_mime_types: true,
+ stop_at_first_match: false,
+ max_string_length: 1024,
+ timeout_ms: None,
+};
+```
+
+**After (v0.6.0):**
+
+```rust,ignore
+use libmagic_rs::config::EvaluationConfig;
+
+let config = EvaluationConfig::default()
+ .with_mime_types(true)
+ .with_stop_at_first_match(false)
+ .with_max_string_length(1024);
+ // .with_timeout_ms(5000) // Optional timeout
+```
+
+Use `EvaluationConfig::performance()` for untrusted input with bounded timeout:
+
+```rust,ignore
+let config = EvaluationConfig::performance(); // Includes timeout, bounded recursion
+```
+
+### Enum #[non_exhaustive] Markers
+
+Multiple enums gained the `#[non_exhaustive]` attribute. Exhaustive matches must add wildcard patterns:
+
+- `LibmagicError`
+- `ParseError`
+- `EvaluationError`
+- `IoError`
+- `TypeReadError`
+- `Operator`
+- `Value`
+- `TypeKind`
+
+**Pattern:**
+
+```rust,ignore
+match error {
+ LibmagicError::ParseError(e) => { /* ... */ }
+ LibmagicError::EvaluationError(e) => { /* ... */ }
+ _ => { /* handle future error variants */ }
+}
+```
+
+### MimeMapper Now Implements Copy
+
+The `MimeMapper` type now implements `Copy`. Non-move closures capture it by reference instead of by value.
+
+**Before (v0.5.x):**
+
+```rust,ignore
+let mapper = MimeMapper::new();
+let closure = move || {
+ // mapper moved into closure
+ mapper.map("text/plain")
+};
+```
+
+**After (v0.6.0):**
+
+```rust,ignore
+let mapper = MimeMapper::new();
+let closure = || {
+ // mapper copied into closure, original still available
+ mapper.map("text/plain")
+};
+```
+
+If move semantics are required, explicitly move the mapper into the closure.
+
+### FileBuffer API Changes
+
+The `FileBuffer::create_symlink` method was removed. Symlink creation is not part of the file buffer abstraction.
+
+If your code created symlinks through `FileBuffer`, use `std::os::unix::fs::symlink` or `std::os::windows::fs::symlink_file` directly.
+
## Getting Help
If you encounter migration issues:How did I do? Any feedback? |
mergify Bot
pushed a commit
that referenced
this pull request
Apr 25, 2026
) Update documentation for #240 Added comprehensive getting started guide with installation, quick start, library usage, CLI examples, and common patterns. Expanded API reference with complete type documentation, error handling, and thread safety information. Added migration guide covering transition from C libmagic and detailed v0.6.0 breaking changes. These updates provide users with clear entry points for learning the library and upgrading between versions. _Generated by [Dosu](https://dosu.dev)_ Co-authored-by: dosubot[bot] <131922026+dosubot[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🤖 New release
libmagic-rs: 0.5.0 -> 0.6.0 (⚠ API breaking changes)⚠
libmagic-rsbreaking changesChangelog
This PR was generated with release-plz.