Trait ScannedExcerptSource 

pub trait ScannedExcerptSource:
    Send
    + Sync
    + Debug {
    // Required methods
    fn source_id(&self) -> u64;
    fn extensions(&self) -> &[String];
    fn begin(&self, args: &[String]) -> ScanBeginFuture<'_>;
    fn scan(&self, path: PathBuf, text: String) -> ScanFuture<'_>;

    // Provided methods
    fn view_mode(&self) -> Option<&str> { ... }
    fn roots(&self) -> ScanRootsFuture<'_> { ... }
    fn describe(&self, _args: &[String]) -> ScanDescribeFuture<'_> { ... }
    fn claims(&self, path: &Path) -> bool { ... }
}

An async, off-keystroke-path producer of agenda rows.

Required Methods

fn source_id(&self) -> u64

Stable id of the producing plugin — the teardown key. Two producers with the same id are the same plugin, so a reload replaces rather than duplicates.

fn extensions(&self) -> &[String]

File extensions this source wants offered, lowercased and without the leading dot. Resolved once at registration and cached here, so the walk’s per-file test is a string compare rather than a guest call.

fn begin(&self, args: &[String]) -> ScanBeginFuture<'_>

Drop per-scan state. Called once before the first file of a scan.

An Err drops this source from the scan (its state is unknown, so its rows would be untrustworthy) while every other source carries on.

OA.11a: args is what the VIEW was opened with, passed through uninterpreted. The host routes these; it does not read them. They are how one source serves more than one scan — org’s agenda dispatcher names which custom command to run — and they are deliberately not the provider view’s argument, which is the root override and is host-interpreted because the host does the walk.

Called before Self::roots, so a source that stashes its args here has them for roots, every scan, and the generation key it returns. Empty is the ordinary case: the default scan.

fn scan(&self, path: PathBuf, text: String) -> ScanFuture<'_>

Scan one file. text is the file’s contents, already read by the host — the host must read it anyway to build the source Document, so it reads once and hands the text over.

Provided Methods

fn view_mode(&self) -> Option<&str>

A minor mode this source wants activated on the agenda view.

How a source acts on its own rows. The view’s generic behaviour — jump-to-source, gr — is the host’s, because the host built the view and is the only thing that can re-walk it; but the semantics of a row belong to whoever produced it, and those need chords in a buffer whose major is multibuffer-mode. No activation policy can say “the buffer this provider just built”, so the provider activates it and this is the source naming what.

fn roots(&self) -> ScanRootsFuture<'_>

The paths this source wants scanned — each a FILE or a DIRECTORY (AF.1).

Empty means “no opinion”: the host uses the root it would have used, so a source that does not implement this behaves exactly as before. That is why it has a default and extensions does not — a source with no extensions scans nothing and is a bug worth surfacing, while a source with no roots is the ordinary unconfigured case.

Called PER SCAN, unlike extensions and view_mode, which are facts about the source and are cached at load. This answer comes from user configuration and must follow a :set without a reload.

An Err is logged and treated as empty: a source that cannot say where to look should not be able to make the agenda scan nothing.

fn describe(&self, _args: &[String]) -> ScanDescribeFuture<'_>

What this view IS, in the source’s own words, for its headerline (OA.22).

The host knows only how many rows it composed and how many files it walked; it deliberately does not read args (see Self::begin). So an agenda narrowed to one tag looks exactly like an unfiltered one — and “you have no tasks” is the worst thing this view can say incorrectly.

A short phrase naming the command, the span and any active filters. The caller prefixes its own counts, so this must not repeat them. Empty means “nothing worth saying” and the header keeps its plain form, which is why the default is exactly that: a source with no view state to report implements nothing.

Called ONCE per scan, after begin — off the per-file path.

fn claims(&self, path: &Path) -> bool

True when path’s extension is one this source claimed.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors