Struct Library 

pub struct Library {
    pub metadata: LibraryMetadata,
    pub mtime: MtimeIndex,
    pub tags: Tags,
    pub saved_filters: Vec<SavedFilter>,
    pub skipped: Vec<(PathBuf, String)>,
    /* private fields */
}

An Eagle library loaded into memory (item payload files stay on disk).

Fields

metadata: LibraryMetadata

metadata.json.

mtime: MtimeIndex

mtime.json.

tags: Tags

tags.json.

saved_filters: Vec<SavedFilter>

saved-filters.json, in menu order.

skipped: Vec<(PathBuf, String)>

Item folders whose metadata.json couldn’t be read or parsed (for example zeroed by a sync tool), with the reason. They are left out and never written to.

Implementations

impl Library

pub fn run_steps(&mut self, ids: &[String], steps: &[Step]) -> Result<RunReport>

Runs steps in order on the items ids: each step on every item before the next step. Items in the Trash are left alone. A step that changes nothing is no error; a folder that no longer exists is skipped and reported; a write error stops the run there. AI steps do nothing here; Library::run_steps_with applies their results.

pub fn run_steps_with( &mut self, ids: &[String], steps: &[Step], outputs: &HashMap<(usize, String), StepOutput>, ) -> Result<RunReport>

Runs steps in order on ids as Library::run_steps does, with each AI step taking its results from outputs, keyed by the step’s index and the item’s id. An item with no result for an AI step is left as it is by that step.

impl Library

pub fn finish_add( &mut self, plan: &AddPlan, copied: &[String], ) -> Result<AddReport>

The second half of Add to Other Library, on the other library: adds the plan’s folder, smart folder or tag group (saving metadata.json only then), and registers the items copy_items copied, in memory and in mtime.json. With a folder, a copied item’s folders keep only ids this library has once the tree is merged. A copied item that can’t be read is left on disk and counted out.

impl Library

pub fn set_folder_auto_tags( &mut self, id: &str, tags: &[String], ) -> Result<usize>

Sets folder id’s auto-tags (its tags key) and, as Eagle’s auto-tag dialog does when the list changed, appends the folder’s new tags to every item in the folder or in any folder below it (trashed items included). Tags taken off the folder stay on the items. Duplicates in tags are dropped, keeping the first. Only tags changes in metadata.json; the folder’s modificationTime and any cached extendTags are left alone. Returns how many items changed.

impl Library

pub fn backup_metadata(&self) -> Result<Option<PathBuf>>

Copies metadata.json into backup/ as Eagle does and returns the new backup’s path. Returns None without writing when the file on disk is damaged (doesn’t parse or has no applicationVersion) or the newest backup has the same size. Backups beyond the newest MAX_BACKUP_COUNT are deleted.

pub fn backups(&self) -> Result<Vec<PathBuf>>

Backup files in backup/, newest first (by name, as Eagle sorts).

pub fn restore_metadata_from_backup( &mut self, path: impl AsRef<Path>, ) -> Result<()>

Replaces metadata.json with the backup at path and reloads the folder tree from it. The current file is first kept as backup/metadata.json.damaged-<ms>. Fails, changing nothing, if the backup doesn’t parse as a library metadata.json.

pub fn open_or_restore( path: impl AsRef<Path>, ) -> Result<(Library, Option<PathBuf>)>

Opens the library like Library::open, but if metadata.json can’t be read or parsed, restores it from the newest usable backup first, as Eagle does on launch. Returns the backup used, if any.

pub fn open_or_restore_with_progress( path: impl AsRef<Path>, progress: &dyn Fn(usize, usize), ) -> Result<(Library, Option<PathBuf>)>

Library::open_or_restore with Library::open_with_progress’s progress calls.

impl Library

pub fn update_item(&mut self, item: Item) -> Result<()>

Saves item over the stored item with the same id.

pub fn add_comment(&mut self, item_id: &str, comment: Comment) -> Result<String>

Adds a comment to an item and returns its id. A missing id or lastModified is filled in. Timed notes (duration) are kept sorted by time, a new one after any at the same time; region notes are appended. The item is saved like any other edit.

pub fn update_comment(&mut self, item_id: &str, comment: Comment) -> Result<()>

Replaces the comment with comment.id on an item (text, region or time). Eagle leaves the comment’s lastModified alone on edits, so whatever comment carries is written.

pub fn delete_comment(&mut self, item_id: &str, comment_id: &str) -> Result<()>

Removes a comment from an item. Eagle keeps an empty comments: [].

pub fn set_trashed(&mut self, ids: &[String], trashed: bool) -> Result<()>

Moves items to the trash (isDeleted plus deletedTime) or restores them.

pub fn delete_permanently(&mut self, ids: &[String]) -> Result<()>

Deletes items for good, as Eagle’s permanent delete does: the whole .info folder is removed and the id leaves mtime.json.

pub fn empty_trash(&mut self) -> Result<usize>

Permanently deletes everything in the trash and returns how many items went.

pub fn rename_tag(&mut self, from: &str, to: &str) -> Result<usize>

Renames a tag on every item, merging it into to where an item has both. Tag history, starred tags, tag groups, folders’ auto-tags and smart-folder tag rules follow, as in Eagle. Returns how many items changed.

pub fn delete_tag(&mut self, tag: &str) -> Result<usize>

Removes a tag from every item, the history, starred tags, groups and folders’ auto-tags.

pub fn set_tag_starred(&mut self, tag: &str, starred: bool) -> Result<()>

Stars or unstars a tag (most recent first, as Eagle keeps them).

pub fn record_tag_use(&mut self, tags: &[String]) -> Result<()>

Records tags as just used: moved to the front of historyTags, which is capped at 120, then writes tags.json.

impl Library

Tag groups, kept in tagsGroups of the library metadata.json. Group edits only rewrite that file; items are untouched unless a delete asks for its tags to go too.

pub fn create_tag_group( &mut self, name: &str, tags: &[String], color: Option<&str>, ) -> Result<String>

Adds a tag group at the end of the list and returns its id. Tags are kept in the given order without duplicates; like Eagle’s “create group from tags”, they are not taken out of other groups.

pub fn rename_tag_group(&mut self, id: &str, name: &str) -> Result<()>

Renames a tag group (cut to 1024 characters, as Eagle does).

pub fn set_tag_group_tags(&mut self, id: &str, tags: &[String]) -> Result<()>

Replaces a group’s tags (order kept, duplicates dropped). Other groups are left alone.

pub fn add_tags_to_group(&mut self, id: &str, tags: &[String]) -> Result<()>

Adds tags to the end of a group. As in Eagle’s tag manager, a tag moves: it leaves any other group it was in.

pub fn remove_tags_from_group( &mut self, id: &str, tags: &[String], ) -> Result<()>

Takes tags out of a group; the tags stay on their items.

pub fn set_tag_group_color( &mut self, id: &str, color: Option<&str>, ) -> Result<()>

Sets a group’s colour (one of ICON_COLORS) or removes it.

pub fn set_tag_group_description( &mut self, id: &str, description: &str, ) -> Result<()>

Sets a group’s description, the text under its name in the tag manager. Eagle keeps the key once set: clearing the box writes "" rather than removing it, and the key goes after color.

pub fn delete_tag_group(&mut self, id: &str, remove_tags: bool) -> Result<()>

Deletes a group. With remove_tags, its tags are also deleted from every item, the tag history and starred tags, as Eagle offers.

pub fn reorder_tag_group(&mut self, id: &str, index: usize) -> Result<()>

Moves a group to index in the list (after it has left its old place; past the end appends), as dragging in the tag manager does.

impl Library

Saved filters in saved-filters.json. Entries have no id, so they are addressed by position, as Eagle’s menu does. Each edit rewrites the file (compact, no trailing newline) and leaves metadata.json alone.

pub fn create_saved_filter(&mut self, name: &str, rule: Value) -> Result<usize>

Appends a saved filter and returns its position. rule is the rule object (see SavedFilter::rule_from_filter).

pub fn rename_saved_filter(&mut self, index: usize, name: &str) -> Result<()>

Renames the saved filter at index; Eagle ignores empty names.

pub fn update_saved_filter(&mut self, index: usize, rule: Value) -> Result<()>

Replaces the rules of the saved filter at index.

pub fn delete_saved_filter(&mut self, index: usize) -> Result<()>

Deletes the saved filter at index.

pub fn reorder_saved_filter(&mut self, index: usize, to: usize) -> Result<()>

Moves the saved filter at index to position to (past the end appends), as dragging in Eagle’s menu does.

impl Library

pub fn create_folder( &mut self, parent: Option<&str>, name: &str, ) -> Result<String>

Creates a folder at the end of parent’s children (or at the root) and returns its id. A subfolder takes its parent’s icon and colour, as Eagle’s new-subfolder command does.

pub fn rename_folder(&mut self, id: &str, name: &str) -> Result<()>

Renames a folder. Eagle leaves its modificationTime alone. A cached pinyin (which Eagle itself strips before writing) would now be stale, so it goes.

pub fn set_folder_order( &mut self, id: &str, order: Option<FolderOrder>, increase: bool, ) -> Result<()>

Sets a folder’s own sort, or clears it with None (both orderBy and sortIncrease go). Eagle leaves modificationTime alone.

pub fn set_folder_icon( &mut self, id: &str, icon: Option<&str>, color: Option<&str>, ) -> Result<()>

Sets a folder’s icon and icon colour; None removes the key (the default icon or colour). Pass the current value to keep one. The colour must be one of ICON_COLORS.

pub fn set_folder_cover(&mut self, id: &str, item: Option<&str>) -> Result<()>

Sets the item shown as a folder’s cover, or removes coverId.

pub fn set_folder_description( &mut self, id: &str, description: &str, ) -> Result<()>

Sets a folder’s description.

pub fn set_folder_password( &mut self, id: &str, password: Option<(&str, &str)>, ) -> Result<()>

Locks a folder with (password, hint), or unlocks it with None. Eagle stores btoa(password), which only accepts characters up to U+00FF, so other passwords are refused here as Eagle cannot set them either. Unlocking writes "" for both keys, as Eagle’s save does.

pub fn verify_folder_password(&self, id: &str, password: &str) -> bool

Whether password opens the folder. An unlocked or unknown folder never matches.

pub fn delete_folder(&mut self, id: &str) -> Result<()>

Deletes a folder and its subfolders, moving items left in no folder to the trash (see Library::delete_folders).

pub fn delete_folders( &mut self, ids: &[String], trash_items: bool, ) -> Result<()>

Deletes folders with their subfolders, and unpins them from Quick Access. Items that were in them lose those folder ids. With trash_items (Eagle’s “move the items to the trash too”, on by default), an item left in no folder goes to the trash, without a deletedTime as Eagle does; an item still in another folder stays. Without it every item stays. An id inside another deleted folder goes with it; an unknown id is refused before anything changes.

pub fn duplicate_folder(&mut self, id: &str) -> Result<String>

Duplicates a folder with its subfolders, right after it, as Eagle’s Duplicate does, and returns the copy’s id. The copies keep the names, description, auto-tags, icon, colour, cover and item sort; each gets a new id and a new modificationTime, and loses its password. No items are put in the copies.

pub fn rename_folders(&mut self, names: &[(String, String)]) -> Result<()>

Renames several folders, (id, new name) each, in one save, as Eagle’s batch rename does. Like Library::rename_folder it leaves modificationTime alone and drops a stale pinyin. An unknown id is refused before anything changes.

pub fn restyle_folders( &mut self, ids: &[String], icon: Option<Option<&str>>, color: Option<Option<&str>>, ) -> Result<()>

Gives several folders the same icon and/or colour in one save, as Eagle’s commands for selected folders do. None leaves that key as each folder has it; Some(None) removes it.

pub fn set_folders_order( &mut self, ids: &[String], order: Option<FolderOrder>, ) -> Result<()>

Gives several folders the same item sort in one save, as Eagle’s menu for selected folders does: None removes orderBy and sortIncrease; a key keeps each folder’s direction, ascending when it had none.

pub fn set_folders_increase( &mut self, ids: &[String], increase: bool, ) -> Result<()>

Sets the sort direction of several folders in one save.

pub fn move_folders( &mut self, ids: &[String], target: &str, place: FolderPlace, ) -> Result<()>

Moves several folders above, into or below target in one save, as Eagle’s Move Folder dialog does. They keep their order in the tree (top to bottom); above and below they become the target’s siblings in that order, into it they follow its last child. A folder whose parent moves too stays inside it. Moving onto one of the moved folders, or into a moved folder’s descendant, is refused, and nothing changes on any error.

pub fn move_folders_to_top(&mut self, ids: &[String]) -> Result<()>

Moves several folders to the end of the top level in one save, keeping their tree order. A folder whose parent is among them stays inside it.

pub fn move_folder(&mut self, id: &str, parent: Option<&str>) -> Result<()>

Moves a folder under parent (or to the root), at the end of its new siblings as Eagle appends. Moving a folder into itself or one of its descendants is refused.

pub fn reorder_folder( &mut self, id: &str, new_parent: Option<&str>, index: usize, ) -> Result<()>

Moves a folder under new_parent (or to the root) at position index among its new siblings, counted after it has left its old place; an index past the end appends. Use it with the same parent to reorder siblings. Moving a folder into itself or one of its descendants is refused, and nothing changes on any error.

pub fn sort_subfolders( &mut self, parent: Option<&str>, sort: SubfolderSort, ) -> Result<()>

Sorts parent’s subfolders (or the root folders) by name, as the folder menu’s “Sort By” commands do, and saves the reordered tree. With all_levels, every folder below is sorted too. Names compare case-insensitively with numbers by value; descending is the ascending list reversed. Eagle stores no flag: only children (or the root list) changes order.

pub fn add_quick_access(&mut self, kind: &str, id: &str) -> Result<()>

Pins a folder ("folder") or smart folder ("smartFolder") to Quick Access, at the end as Eagle does.

pub fn place_quick_access( &mut self, kind: &str, id: &str, target: &str, below: bool, ) -> Result<()>

Pins id (a "folder" or "smartFolder") to Quick Access just above target, or just below it when below, as Eagle does when an entry or a folder is dropped on a pinned row. An id already pinned is moved. A target that isn’t pinned appends; dropping on itself does nothing.

pub fn remove_quick_access(&mut self, id: &str) -> Result<()>

Unpins an id from Quick Access.

pub fn save_metadata(&mut self) -> Result<()>

Writes the library metadata.json, stamping its modificationTime. An open transaction records the metadata as last saved; in batched mode the write waits for Library::flush.

impl Library

pub fn set_font_language(&mut self, id: &str, lang: &str) -> Result<()>

Sets the language of a font item’s specimen, as Eagle’s “change language” does: fontMetas.preferLng becomes lang (one of fontmeta::SAMPLE_LANGUAGES) and the specimen thumbnail and its palette are drawn again in that language.

impl Library

pub fn create_folders(&mut self, folders: &[NewFolder]) -> Result<()>

Creates the folders of a Plan and writes metadata.json once. Each parent must exist already or come earlier in folders. As in Eagle, the new folders take no icon from their parent. Nothing is changed when a parent is missing.

impl Library

pub fn open(path: impl AsRef<Path>) -> Result<Library>

Loads the library at path. Items are sorted by id.

pub fn open_with_progress( path: impl AsRef<Path>, progress: &dyn Fn(usize, usize), ) -> Result<Library>

Library::open, calling progress(read, total) as item folders are read (first with 0 once the folder list is known), for a loading screen.

pub fn create(path: impl AsRef<Path>) -> Result<Library>

Creates an empty library at path (normally ending in .library) with the files Eagle expects, and opens it. Refuses a folder that already exists.

pub fn root(&self) -> &Path

The library’s root folder.

pub fn items(&self) -> &[Item]

All items (including trashed ones), sorted by id.

pub fn item(&self, id: &str) -> Option<&Item>

Looks up an item by id.

pub fn items_mut(&mut self) -> &mut Vec<Item>

Mutable access to the items, for edits before Library::save_to.

pub fn all_folders(&self) -> Vec<&Folder>

Every folder in the tree, depth first.

pub fn folder_ids(&self) -> HashSet<&str>

Ids of all folders in the tree.

pub fn info_dir(&self, item: &Item) -> PathBuf

Info directory of item in this library.

pub fn save_to(&self, dest: impl AsRef<Path>) -> Result<()>

Writes the library to dest (created if needed), copying each item’s files and any other root entries (backup/, Icon, …) unchanged, and regenerating the JSON files from the in-memory model.

impl Library

pub fn take_conflict(&mut self) -> bool

Whether a metadata.json write was refused since the last call because the file on disk changed under falcon (or a newer Eagle wrote it). The app then reloads the library from disk, as Eagle does; any caller of the library (the HTTP API included) can trip it.

impl Library

pub fn move_items_manually( &mut self, folder: &str, moved: &[String], before: Option<&str>, ) -> Result<()>

Moves moved items, as one block in their current manual order, to just before before (or to the end with None) in folder’s manual order, as dragging in Eagle’s grid does. New order values sit between the neighbours; if two other items share a value, all values are first nudged apart. Changed items are saved with Library::update_item, and a folder not yet sorted by hand is switched to an ascending manual sort.

The order is worked out over all untrashed items in the folder (Eagle uses the items currently shown). Moving into an otherwise empty folder changes nothing, as Eagle has no neighbour to place against.

impl Library

pub fn merge_duplicates(&mut self, merges: &[Merge]) -> Result<MergeReport>

Applies merges: each kept item takes its merge’s values, and the others move to the Trash. Items that are gone, already trashed, or kept by some merge are never trashed, so a mistake can’t lose the copy meant to stay.

impl Library

pub fn finish_merge( &mut self, plan: &MergePlan, copied: &[String], ) -> Result<MergeReport>

Merges the plan’s folders, smart folders and tag groups into this library (saving metadata.json), and registers the item folders copied by copy_items in memory and mtime.json. Copied items that can’t be read are left on disk and counted out.

impl Library

pub fn refresh_palette(&mut self, id: &str) -> Result<bool>

Recomputes an item’s palette (Eagle’s “Refresh Palette”) with the same median cut as import, from refresh_source. Only palettes changes, in place, so the item’s key order stays the same. Audio is skipped, as Eagle’s analyser skips it; the result is then false.

impl Library

pub fn clear_invalid( &mut self, scan: &InvalidScan, discard: impl FnMut(&Path) -> Result<()>, ) -> Result<Cleared>

Applies scan: moves its broken items to the Trash (one undoable step when a transaction is open), forgets items whose folder has gone, and hands each orphaned folder still there to discard.

impl Library

pub fn smart_folders(&self) -> Vec<SmartFolder>

The library’s smart folders, top level first.

pub fn smart_folder_items(&self, id: &str) -> Vec<&Item>

Ids of live items in the smart folder id.

pub fn create_smart_folder( &mut self, name: &str, conditions: Vec<Value>, ) -> Result<String>

Adds a top-level smart folder at the end and returns its id.

pub fn create_smart_folder_in( &mut self, parent: Option<&str>, name: &str, conditions: Vec<Value>, ) -> Result<String>

Adds a smart folder at the end of parent’s children (or at the top level) and returns its id. A top-level entry takes the shape Eagle’s save rebuilds top-level entries into (id, name, description, modificationTime, conditions, children). Eagle writes nested entries as its dialog built them, with the parent’s id added (id, name, conditions, modificationTime, children, parent).

pub fn create_smart_folder_group( &mut self, parent: Option<&str>, name: &str, ) -> Result<String>

Adds a smart folder group (no conditions, the grid icon) at the end of parent’s children or of the top level, and returns its id. Eagle’s command only makes top-level groups, which its save writes as id, icon, name, description, modificationTime, conditions, children. A nested group keeps the key order of Eagle’s new group object with parent added, as a group dragged into another smart folder would be written.

pub fn update_smart_folder( &mut self, id: &str, name: &str, conditions: Vec<Value>, ) -> Result<()>

Replaces a smart folder’s name and conditions (at any depth) and stamps its modificationTime, as Eagle’s edit dialog does.

pub fn rename_smart_folder(&mut self, id: &str, name: &str) -> Result<()>

Renames a smart folder (at any depth) in place, as Eagle’s sidebar rename does: only name changes (cut to 1024 characters), and modificationTime is left alone.

pub fn delete_smart_folder(&mut self, id: &str) -> Result<()>

Removes a smart folder (at any depth) with its children.

pub fn move_smart_folder( &mut self, id: &str, parent: Option<&str>, index: usize, ) -> Result<()>

Moves a smart folder under parent (or to the top level) at position index among its new siblings, counted after it has left its old place; past the end appends. A nested entry gets parent set to its parent’s id and a top-level one loses it, as Eagle’s drag does. Moving into itself or a descendant is refused. Children keep narrowing their new ancestors when evaluated.

pub fn set_smart_folder_description( &mut self, id: &str, description: &str, ) -> Result<()>

Sets a smart folder’s description (at any depth). An existing description is replaced where it is; a missing one goes right after name. modificationTime is left alone, as Eagle leaves it.

pub fn set_smart_folder_icon( &mut self, id: &str, icon: Option<&str>, color: Option<&str>, ) -> Result<()>

Sets a smart folder’s icon and colour; None removes the key. Pass the current value to keep one. A new key goes where Eagle’s save puts it on a top-level entry (right after id), or at the end of a nested one. modificationTime is left alone.

pub fn set_smart_folder_order( &mut self, id: &str, order: Option<FolderOrder>, increase: bool, ) -> Result<()>

Sets a smart folder’s own sort, or clears it (orderBy and sortIncrease both go).

pub fn duplicate_smart_folder(&mut self, id: &str) -> Result<String>

Duplicates a smart folder with its children, as Eagle’s Duplicate does, and returns the copy’s id. The copy is a deep copy of the entry (same name, rules, icon and sort, same modificationTime) placed just before the original, with new ids throughout; nested copies point their parent at their new parent.

impl Library

pub fn take_external_metadata(&mut self, metadata: LibraryMetadata) -> bool

Takes metadata read from disk if it is newer than what falcon last read or wrote (its modificationTime is later), as Eagle does; returns whether it did. A newer folder tree replaces the one in memory, including edits still waiting in batched mode, and becomes the base later writes are checked against.

pub fn sync_items(&mut self, index: &MtimeIndex) -> ItemSync

Brings the items in memory up to date with index, the mtime.json just read from disk: items it lists that falcon doesn’t hold are read and added, items with a later stamp are read again, and when its all count differs from the number of items held, images/ is listed to drop items whose folder is gone and add folders the index missed. Items that can’t be read yet (a sync still copying them) are left for the next poll. Nothing is written.

pub fn rebuild_mtime(&mut self) -> Result<()>

Rebuilds mtime.json from the items in memory, as Eagle’s Empty Cache and Reload does after reading the library again: one entry per item with a lastModified, in id order, then all (the item count, as falcon always writes it).

pub fn discard_pending_writes(&mut self)

Drops every write batched mode is holding back, for a library whose folder is gone: writing them would fail, or put files where the library used to be.

impl Library

pub fn add_tags_to_items( &mut self, ids: &[String], tags: &[String], ) -> Result<usize>

Adds tags to items, as Eagle’s picker does: each tag (cleaned with clean) is appended to the items that lack it, then moved to the front of historyTags. Returns how many items changed.

pub fn remove_tags_from_items( &mut self, ids: &[String], tags: &[String], ) -> Result<usize>

Takes tags off items, as Eagle’s picker and the × on a tag chip do. A tag that no item outside the Trash has any more also leaves historyTags. Returns how many items changed.

pub fn paste_tags(&mut self, ids: &[String], tags: &[String]) -> Result<usize>

Eagle’s Paste Tags: appends the copied tags each item lacks, in order, leaving the history alone. Returns how many items changed.

pub fn clear_tags(&mut self, ids: &[String]) -> Result<usize>

Eagle’s Clear Tags: empties the items’ tags, leaving the history alone. Returns how many items had tags.

impl Library

Notes and links on several items at once, as Eagle’s inspector edits them when more than one item is selected.

pub fn set_notes(&mut self, ids: &[String], note: &str) -> Result<usize>

Sets the note (annotation) of every item, cut to 20480 characters. Returns how many items changed.

pub fn set_urls(&mut self, ids: &[String], url: &str) -> Result<usize>

Sets the source URL of every item. Returns how many items changed.

impl Library

The tag manager’s commands on several tags at once.

pub fn merge_tags(&mut self, tags: &[String], into: &str) -> Result<usize>

Eagle’s Merge Tags: renames each of tags to into everywhere (Library::rename_tag: items, history, starred tags and groups), so items keep one copy. Returns how many items changed.

pub fn delete_tags(&mut self, tags: &[String]) -> Result<usize>

Deletes several tags (Library::delete_tag). Returns how many items changed.

pub fn star_tags(&mut self, tags: &[String], starred: bool) -> Result<()>

Stars several tags, the first one ending up first (Eagle’s addStarredTags), or unstars them.

pub fn add_tags_to_group_too(&mut self, id: &str, tags: &[String]) -> Result<()>

Eagle’s Add to Group: files tags in a group as well, leaving them in their other groups (where Library::add_tags_to_group moves them).

pub fn clear_tag_history(&mut self) -> Result<()>

Empties historyTags (Eagle’s Clear Tag History).

impl Library

pub fn save_text(&mut self, id: &str, text: &str) -> Result<()>

Replaces the text of the .txt item id with text and refreshes its size and mtime. Empty text is refused, as in Eagle. The save is not recorded in an open undo transaction: the text has its own undo in the editor, and reverting only the metadata would leave it describing a file it no longer matches.

impl Library

pub fn begin_transaction(&mut self, label: impl Into<String>)

Starts recording edits. An already open transaction is ended and dropped first, so a transaction never spans more than one caller’s unit of work.

pub fn set_transaction_label(&mut self, label: impl Into<String>)

Renames the open transaction (the app names it once it knows what the frame did).

pub fn end_transaction(&mut self) -> Option<Transaction>

Stops recording and returns what was recorded, or None when nothing changed.

pub fn revert(&mut self, tx: Transaction) -> Result<Transaction>

Puts back the state tx recorded and returns the inverse transaction (reverting that redoes tx). Items are saved through Library::update_item, so renamed files get their old names back and lastModified moves forward, as with any edit (Eagle’s own undo also saves the item anew). Items tx created go to the trash; their files stay. Metadata, tags and saved filters are restored and written (metadata gets a fresh modificationTime). Items deleted for good since are skipped. A transaction open around the call is set aside meanwhile, so the revert is not recorded in it.

pub fn write_mode(&self) -> WriteMode

The current write mode.

pub fn set_write_mode(&mut self, mode: WriteMode) -> Result<()>

Switches between immediate and batched writes. Leaving batched mode flushes what is pending.

pub fn has_pending_writes(&self) -> bool

True when batched writes are waiting for Library::flush.

pub fn flush(&mut self) -> Result<FlushReport>

Writes everything batched mode held back: each dirty item once, then mtime.json, metadata.json, tags.json and saved-filters.json once each. It takes no backup; FlushReport::wants_backup tells the caller when to (see Library::backup_metadata). On an error the pending set is kept, so the next flush tries again.

impl Library

pub fn import_file( &mut self, path: impl AsRef<Path>, opts: &ImportOptions, ) -> Result<String>

Imports one file and returns the new item’s id.

The original is copied into images/<ID>.info/ with its mtime kept, a thumbnail and palette are produced where the format is supported, and the item’s metadata.json and the library’s mtime.json are written. Formats falcon cannot decode import with no thumbnail and no palette.

pub fn check_folders(&self, path: &Path, opts: &ImportOptions) -> Result<()>

Fails if opts names folders this library doesn’t have.

pub fn commit_import(&mut self, staged: Staged) -> Result<String>

Moves a staged import into images/<ID>.info/, stamps its times and writes its metadata.json and mtime.json.

impl Library

pub fn duplicate_item(&mut self, id: &str) -> Result<String>

Eagle’s Duplicate (⌘D): copies the item’s whole .info folder to a new id and writes its metadata.json with only the id changed, so the copy keeps the name, tags, folders, dates and everything else. Returns the new id.

pub fn set_pinned( &mut self, ids: &[String], folders: &[String], pin: bool, now: u64, ) -> Result<usize>

Pins the items to the top of folders (Eagle’s Pin to Top), or unpins them. Only the folders each item is in are touched. A pin is stamped now - n for the nth item, so they keep their order at the top; unpinning the last folder removes the pinned key. Returns how many items changed.

pub fn set_palette_marked( &mut self, id: &str, index: usize, marked: bool, ) -> Result<()>

Marks or unmarks palette entry index as the item’s primary colour (Eagle’s “Set as Primary Color”). Like Eagle, unmarking writes marked: false rather than dropping the key.

pub fn set_extension(&mut self, id: &str, ext: &str) -> Result<()>

Eagle’s Change Extension: renames the original to the new extension (checked with check_extension) and stores it. The file’s bytes, the thumbnail and everything else stay. Refused when a file of that name is already in the .info folder.

pub fn replace_original(&mut self, id: &str, src: &Path) -> Result<()>

Eagle’s Replace with File: the item keeps its id, name and everything it was given, but its original becomes a copy of src with src’s extension (lower case, unknown when it has none). Size, dates and dimensions are read again and the thumbnail and palette redrawn, except that a custom thumbnail is kept.

impl Library

pub fn duplicate_candidates( &self, size: u64, ext: &str, ) -> Vec<(String, PathBuf)>

Items, not in the Trash, that a new file of size bytes with extension ext could duplicate, with their originals’ paths. Empty for extensions that aren’t checked. Cheap: no file is read.

pub fn use_existing_for_import( &mut self, existing: &str, folders: &[String], ) -> Result<()>

Eagle’s “Use existing file”: instead of importing a duplicate, the existing item joins each of folders it isn’t in yet, taking that folder’s auto-tags (see crate::autotag), and its modificationTime becomes the import time, so it sorts with the new items. Other tags and notes of the would-be import are not carried over, as in Eagle.

impl Library

pub fn set_video_thumbnail( &mut self, id: &str, frame: &RgbaImage, at: f64, ) -> Result<()>

Makes the video frame shown at at seconds the item’s thumbnail, as Eagle’s “Set Current Frame as Thumbnail” does: Eagle regenerates the video thumbnail from that time, so the frame is written per video_thumbnail_jpeg to <name>_thumbnail.png, the palette is computed from it and thumbnailAt records the time (Eagle keeps it and draws later thumbnails from there). The item is not marked as a custom thumbnail and keeps its size.

pub fn set_frame_thumbnail(&mut self, id: &str, frame: &RgbaImage) -> Result<()>

Makes a frame of an animated item its thumbnail, as Eagle’s GIF player does: the frame is scaled per frame_thumbnail_size, written as a PNG to <name>_thumbnail.png, and the palette is computed from it. Nothing else changes: the item keeps its size and is not marked as a custom thumbnail, so Refresh Thumbnail draws the first frame again.

pub fn set_page_thumbnail( &mut self, id: &str, page: &PageThumbnail, width: u32, height: u32, ) -> Result<bool>

Saves a page screenshot as a bookmark’s thumbnail, through the normal thumbnail path: <name>_thumbnail.png is written to a temporary sibling and renamed into place, width and height become the page’s size, the palette is set and noThumbnail and removeThumbnail are cleared. Size, URL, times and tags are untouched, and the item is not marked as a custom thumbnail. Returns false, writing nothing, when the item is gone or has a custom thumbnail.

pub fn set_custom_thumbnail(&mut self, id: &str, image: &Path) -> Result<()>

Makes the image at image the item’s thumbnail, as Eagle’s “Custom Thumbnail” does: the file is copied byte for byte to <name>_thumbnail.png (not resized or re-encoded), width and height become the picture’s size, the palette is computed from it, noThumbnail and noPreview are removed and customThumbnail: true is set. Refuses files over 10 MB, pictures falcon can’t decode, and items whose format is its own thumbnail.

pub fn reset_custom_thumbnail(&mut self, id: &str) -> Result<bool>

Drops a custom thumbnail and draws the item’s own again (Eagle’s “Reset Thumbnail”). Returns false when the item had none.

pub fn refresh_thumbnail(&mut self, id: &str) -> Result<bool>

Redraws an item’s thumbnail from its original and recomputes the palette (Eagle’s “Refresh Thumbnail”). Size, birth time and mtime are read from the file again. As in Eagle, an item with a custom thumbnail is left alone; the result is then false.

impl Library

pub fn rotate_item(&mut self, id: &str, quarter_turns: i32) -> Result<()>

Turns an item’s original by quarter_turns × 90° clockwise (negative turns go anticlockwise). JPEGs only get a new EXIF orientation, so their pixels are untouched; PNG, WebP and BMP are re-encoded. Animated PNG and WebP are refused, as Eagle refuses APNG.

pub fn flip_item(&mut self, id: &str, flip: Flip) -> Result<()>

Mirrors an item’s original as shown (EXIF orientation applied). Like rotating, a JPEG only gets a new EXIF orientation and keeps its pixels; PNG, WebP and BMP are drawn mirrored and re-encoded. The item is refreshed (size, dimensions, thumbnail, palette) and the open undo transaction marked irreversible. Animated PNG and WebP are refused.

pub fn crop_item(&mut self, id: &str, rect: PixelRect) -> Result<()>

Crops an item’s original to rect, in displayed pixels (the part outside the image is ignored), and saves it under the same name. A JPEG is encoded at quality 100 without its EXIF block, as a canvas export does, so its orientation is baked into the pixels.

pub fn crop_item_as_new(&mut self, id: &str, rect: PixelRect) -> Result<String>

Eagle’s crop “Save As”: the cropped picture becomes a new item and the original is left alone. The new item has the original’s name, tags, folders, source URL and rating, and its date added is just after the original’s so the two sit together. Returns its id; a crop of the whole picture still makes a copy.

impl Library

pub fn convert_webp( &mut self, id: &str, format: Format, discard: impl FnOnce(&Path) -> Result<()>, ) -> Result<Converted>

Converts WebP item id to format (see the module docs). discard receives the old WebP once the item is saved.

Trait Implementations

impl Clone for Library

fn clone(&self) -> Library

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Library

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Library

A batched library flushes what is pending when dropped, so nothing is lost when the app closes it. Errors can’t be reported here; call Library::flush first to see them. (A clone shares the pending set at the time of cloning, so drop clones of a batched library before the original makes further edits, or flush first.)

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.