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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
//! # content_scan
//!
//! A pluggable, hierarchical content-scanning framework.
//!
//! `content_scan` provides the building blocks for walking arbitrary
//! content (files, buffers, nested archives, embedded resources, etc.),
//! identifying its type, analyzing it, and recursively extracting inner
//! content. It is intentionally transport-agnostic: the caller supplies
//! anything that implements [`Content`] and the [`Scanner`] takes care of
//! dispatch, recursion, filtering, and result aggregation.
//!
//! ## Concepts
//!
//! - **[`ContentType`]** – a user-defined enum (typically derived with
//! `#[derive(ContentType)]`) that enumerates the content kinds your
//! application understands.
//! - **[`Content`]** – a trait describing a byte-addressable piece of
//! content with a [`ContentPath`] and a size. Use [`BufferContent`]
//! for in-memory data, [`FileContent`] for a file on disk,
//! [`FolderContent`] for a directory, or implement it for your own
//! sources.
//! - **[`ContentPath`]** – the path (or synthetic address) of a piece
//! of content. UTF-8 strings and real OS paths, including non-UTF-8
//! names, are both representable; use [`ContentPath::as_path`] to
//! open a file and [`ContentPath::as_printable_string`] to display
//! it.
//! - **[`ContentIdentifier`]** – classifies a piece of content into a
//! `ContentType` (via magic bytes, file name, or extension) and
//! validates the guess.
//! - **[`ContentAnalyzer`]** – inspects content and records information
//! into the [`Context`] (global or per-object variable maps, plus
//! a flat list of [`Finding`]s via [`Context::add_finding`]). An
//! analyzer can also queue extra extraction with
//! [`Context::request_extract`]. Every analyzer implements
//! [`Dependencies`] (typically via `#[derive(Dependencies)]`) so
//! debug builds can check that required analyzers are registered
//! with a lower priority. Findings may carry typed
//! [`FindingMetadata`]; the default is [`NoMetadata`].
//! - **[`ContentExtractor`]** – produces child [`Content`] items from a
//! parent (e.g. entries of an archive). `create_session` receives an
//! [`OwnedContentPtr`] to the parent and an [`ExtractionContext`]
//! naming the region to look at, and returns an [`ExtractionSession`].
//! The session then yields children via `advance` / `extract`.
//! Extracted children are scanned recursively up to a configurable
//! depth. Put per-session state on the session object, not on the
//! extractor — one extractor instance is shared and sessions may
//! nest. [`FolderExtractor`] is a ready-made implementation that
//! walks a directory.
//! - **[`Filter`]** – optional inclusion/exclusion rules applied before
//! any plugin runs on a piece of content.
//! - **[`Scanner`] / [`ScannerBuilder`]** – wires all plugins together
//! and drives a scan. The scan produces a [`ScanResult`] that can be
//! navigated as a tree of [`ScanContentHandle`]s, and whose
//! [`findings`](ScanResult::findings) iterate every recorded
//! [`Finding`]. Use [`ScannerBuilder::with_metadata`] when findings
//! need a custom [`FindingMetadata`] type.
//!
//! ## Example
//!
//! ```ignore
//! use content_scan::*;
//!
//! #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, ContentType)]
//! #[repr(u16)]
//! enum MyTypes { Text }
//!
//! struct TextId;
//! impl ContentIdentifier<MyTypes> for TextId {
//! fn identify_method(&self) -> Option<IdentifyMethod> {
//! Some(IdentifyMethod::Extension("txt"))
//! }
//! fn validate(&self, _: &mut dyn Content<MyTypes>) -> bool { true }
//! }
//!
//! let mut scanner = ScannerBuilder::<MyTypes>::new()
//! .add_identifier(MyTypes::Text, TextId)
//! .build();
//!
//! let mut content = BufferContent::<MyTypes>::new(b"hello", "hello.txt");
//! let result = scanner.scan(&mut content, true);
//! assert_eq!(result.objects_scanned(), 1);
//! ```
//!
//! ## Scanning a directory
//!
//! ```ignore
//! use content_scan::*;
//!
//! # #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, ContentType)]
//! # #[repr(u16)]
//! # enum MyTypes { Text, Folder }
//! let mut scanner = ScannerBuilder::<MyTypes>::new()
//! .add_extractor(MyTypes::Folder, FolderExtractor::<MyTypes>::new(true, false))
//! .build();
//!
//! let mut root = FolderContent::<MyTypes>::with_content_type("./src", MyTypes::Folder);
//! // `false`: the root folder itself is not tested against the filter
//! let result = scanner.scan(&mut root, false);
//! ```
pub use *;
pub use *;
pub use *;
pub use *;
use BufferArena;
use ContentPtr;
use ExtractionRequest;
use ExtractionRequestMetadata;
use *;
use *;
use Object;
pub use *;
pub use ;
pub use Context;
pub use ScanContentHandle;
pub use ScanResult;
pub use ExtractRequestBuilder;
pub use ExtractionContext;
pub use *;
pub use Scanner;
pub use ScannerBuilder;
pub use *;