Struct Project 

pub struct Project { /* private fields */ }

A reference manager for all data associated with your bioinformatics project.

Projects are the top-level abstraction in refman, allowing you to register, track, download, and manage reference files like FASTA, Genbank, GFA, GFF, GTF and BED files for your bioinformatics work. A Project maintains a registry of datasets, where each dataset has a unique label and can contain references to multiple file types.

The Project struct provides methods to:

• Initialize new reference management projects
• Register new datasets or update existing ones
• Download registered datasets from remote URLs
• Remove datasets from the registry
• Pretty print the current state of registered datasets

Projects can be either local (stored in ./refman.toml) or global (stored in ~/.refman/refman.toml). The registry location can also be customized via the REFMAN_HOME environment variable.

Each dataset in a project is tracked with a unique label and can contain optional URLs pointing to reference files in standard bioinformatics formats (FASTA, Genbank, GFA, GFF, GTF, BED). The registry maintains metadata like when it was last modified and optional title/description fields.

Examples

// Create a new local project
let project = Project::new(
    Some("My Assembly Project".to_string()),
    Some("Reference data for genome assembly".to_string()),
    false
);

The Project struct integrates with other refman types like RefDataset for managing individual reference datasets and RegistryOptions for configuring where and how the registry is stored.

Implementations

impl Project

pub fn datasets(&self) -> &[RefDataset]

Returns a read-only slice of all reference datasets currently registered in the project.

This method provides access to the raw collection of RefDataset entries stored in the project’s registry. Each RefDataset represents a labeled collection of bioinformatics reference files, potentially including FASTA, Genbank, GFA, GFF, GTF and BED formats.

This accessor is useful for:

• Inspecting the currently registered datasets without modifying them
• Iterating over registered datasets to check their properties
• Filtering datasets based on custom criteria
• Accessing individual dataset labels and file URLs

The returned slice allows read-only access to ensure the registry’s integrity is maintained. For mutable access, use datasets_mut() instead. For taking ownership of the datasets, use datasets_owned().

Returns

A read-only slice containing all registered RefDataset entries in the project. Returns an empty slice if no datasets are registered.

pub fn datasets_mut(&mut self) -> &mut [RefDataset]

Returns a mutable slice of all reference datasets registered in the project.

This method provides mutable access to the raw collection of RefDataset entries stored in the project’s registry. Each RefDataset represents a labeled collection of bioinformatics reference files, potentially including FASTA, Genbank, GFA, GFF, GTF and BED formats.

Mutable access allows modifying existing datasets, for example to:

• Update file URLs for existing datasets
• Modify dataset labels or other metadata
• Add or remove file references from datasets
• Reorder datasets within the registry

Use this method with caution as it allows direct mutation of the registry state. For read-only access, use datasets() instead. To take ownership of the datasets, use datasets_owned().

Returns

A mutable slice containing all registered RefDataset entries in the project. Returns an empty slice if no datasets are registered.

pub fn datasets_owned(self) -> Vec<RefDataset>

Takes ownership of all reference datasets registered in the project.

This method provides a way to take ownership of the raw collection of RefDataset entries stored in the project’s registry, consuming the project in the process. Each RefDataset represents a labeled collection of bioinformatics reference files, potentially including FASTA, Genbank, GFA, GFF, GTF and BED formats.

Taking ownership via datasets_owned() allows:

• Moving datasets out of the Project context entirely
• Transferring datasets between Projects
• Performing owned operations on datasets that require ownership
• Converting datasets into other data structures

This is different from datasets() which provides read-only access andatasets_mut() which provides mutable access but keeps ownership within the Project. Using datasets_owned() consumes the Project instance.

Returns

A Vec containing all registered RefDataset entries, transferring ownership from the Project to the caller. Returns an empty Vec if no datasets were registered. The Project instance is consumed in the process.

pub fn get_dataset(&self, label: &str) -> Result<&RefDataset, EntryError>

Returns a reference to a specific dataset from the Project’s registry by its label.

This method provides direct access to individual reference datasets stored in the project’s registry. It takes a label string and returns a reference to the matching RefDataset if one exists. Each dataset in a refman Project has a unique label that identifies it, containing optional references to various bioinformatics file formats (FASTA, Genbank, GFA, GFF, GTF, BED).

The method enforces that:

• The label must exactly match a registered dataset (case-sensitive)
• Only one dataset can have a given label (unique key constraint)
• The dataset must exist in the registry

This is commonly used to:

• Check details of specific registered datasets
• Access dataset file URLs before downloading
• Verify dataset registration status
• Extract dataset metadata

The method complements other Project methods like register() andownload_dataset()() in the dataset management lifecycle. While those methods add and fetch datasets, get_dataset() provides read access to verify and inspect registered data.

Arguments

• label - The unique label identifying the dataset to retrieve

Returns

Returns Ok(&RefDataset) with a reference to the matching dataset if found. Returns EntryError::LabelNotFound if no dataset matches the provided label.

Errors

Can return EntryError::LabelNotFound if the requested dataset label is not registered in the project.

Panics

This method will panic if:

• More than one dataset with the same label exists in the registry (indicates invalid state as labels must be unique)
• The filtered dataset collection contains an unexpected number of matches (should be exactly 1 match for a valid label)

pub fn get_dataset_urls(&self, label: &str) -> Result<Vec<String>, EntryError>

Returns a vector of all registered file URLs for a dataset with the given label.

This method provides access to all file URLs registered for a dataset, combining any valid URLs across the supported bioinformatics file formats (FASTA, Genbank, GFA, GFF, GTF, BED). The URLs can then be used to download reference files, validate dataset completeness, or inspect available file formats.

The method will:

• Verify the dataset exists by the given label
• Extract all non-None URLs registered for that dataset
• Return them as a vector in a consistent order (FASTA, Genbank, etc.)

This complements other dataset access methods by providing URL-specific functionality. While get_dataset() returns the full dataset struct andownload_dataset() handles file fetching, get_dataset_urls() focuses specifically on URL access and validation.

The method is used internally by download_dataset() to determine which files to fetch, but can also be used directly to:

• Preview what files are available before downloading
• Extract URLs for custom download handling
• Verify dataset completeness
• Share dataset URLs

Arguments

• label - The unique label identifying the dataset whose URLs should be retrieved

Returns

Returns Ok(Vec) containing all non-None URLs registered for the dataset. Returns an empty vector if the dataset exists but has no URLs registered. Returns EntryError::LabelNotFound if no dataset matches the provided label.

Errors

Can return EntryError::LabelNotFound if the requested dataset label is not in the registry.

pub fn get_all_urls(&self) -> Result<Vec<String>, EntryError>

Returns a vector of URLs for all reference data across all registered datasets.

This method provides access to all file URLs registered in the project’s datasets, aggregating URLs from each dataset and each supported bioinformatics file format (FASTA, Genbank, GFA, GFF, GTF, BED). It is useful for:

• Getting an overview of all reference data in the project
• Batch downloading all registered files
• Validating URLs across the entire registry
• Sharing/exporting full URL lists

The method processes each dataset sequentially, collecting any non-None URLs into a single vector. URLs are gathered in a consistent order per dataset: FASTA -> Genbank -> GFA -> GFF -> GTF -> BED.

Unlike get_dataset_urls() which operates on a single labeled dataset, this method provides complete URL access across the entire registry. It complements other Project methods like download_dataset() by enabling bulk operations across all reference data.

The method enforces URL validity by checking that:

• No empty URLs are included
• All URLs use either http:// or https:// protocols

Returns

Returns Ok(Vec) containing all valid URLs across all datasets. Returns an empty vector if no URLs are registered.

Errors

Can return EntryError variants if:

• Dataset access fails
• URL validation fails
• Project state is invalid

Panics

This method will panic if:

• Empty URLs are found in datasets (invalid state)
• URLs with invalid protocols are found (must be http/https)

pub fn is_registered(&self, label: &str) -> bool

Checks if a dataset with a given label is registered in the project.

This method searches through the project’s registry to determine if a dataset with the specified label exists. Each dataset in a refman Project must have a unique label that identifies it - this label acts as the primary key for the dataset within the registry.

This method is useful for:

• Validating labels before attempting to register or update datasets
• Checking existence of specific datasets before trying to download them
• General queries about what data is available in the project

The check is case-sensitive - “genome” and “Genome” are considered different labels. Labels must be unique within a project’s registry.

Arguments

• label - The label string to search for in the registry

Returns

Returns true if a dataset with the given label exists in the registry, false otherwise. Note that this only checks for label existence, not whether the dataset has any file URLs registered or if those files are accessible.

pub async fn register(self, new_dataset: RefDataset) -> Result<Self, EntryError>

Registers a new dataset or updates an existing dataset in the Project’s registry.

This is one of the core methods for managing reference data in refman. It takes a RefDataset struct containing a unique label and optional URLs for various bioinformatics file formats (FASTA, Genbank, GFA, GFF, GTF, BED, TAR) and either:

• Adds it as a new dataset if the label doesn’t exist in the registry yet
• Updates an existing dataset with any new URLs provided if the label matches

When updating an existing dataset, only fields that are Some(url) in the new RefDataset will overwrite the existing dataset’s fields. This allows for incremental updates where you can add new file references to a dataset over time without having to re-specify existing URLs.

The registry enforces that dataset labels must be unique - you cannot have two datasets with the same label. This allows the label to act as a primary key for looking up and managing datasets within the project.

Arguments

• new_dataset - A RefDataset struct containing the label and optional file URLs to register or update. The label field is required and must be unique within the registry.

Returns

Returns Ok(Project) with the updated Project if registration succeeds, or an EntryError if there are issues with the dataset registration (e.g. invalid state detected).

Examples

To register a new dataset:

let mut project = Project::new(None, None, false);
let dataset = RefDataset {
    label: "genome".into(),
    fasta: Some("https://example.com/genome.fasta".into()),
    ..Default::default()
};
project = project.register(dataset).unwrap();

The registration process will either add this as a new dataset if “genome” is not yet registered, or update the existing “genome” dataset with the new FASTA URL if it exists.

Errors

This method can return several types of errors:

• EntryError::LabelNotFound if the dataset being registered cannot be found during updates
• EntryError::FinalEntry if registering this dataset would leave the registry empty
• Filesystem errors from reading/writing the registry file
• Serialization errors when encoding/decoding the registry TOML
• Permission errors when accessing registry files
• IO errors if registry files or directories cannot be accessed
• Environment variable errors if REFMAN_HOME is invalid
• Path resolution errors for invalid registry paths

Panics

This method will panic if multiple datasets matching the given label are found in the registry. This should never happen as labels must be unique, but represents an invalid state that requires immediate attention.

pub async fn download_dataset( self, label: Option<&str>, target_dir: PathBuf, ) -> Result<Self>

Downloads a reference dataset from a Project’s registry by label, fetching any registered file URLs into a target directory.

This method implements the core file downloading functionality in refman. Given a dataset label and target directory, it will:

1. Verify the dataset exists in the registry
2. Extract all registered file URLs for that dataset (FASTA, Genbank, GFA, GFF, GTF, BED)
3. Launch concurrent downloads of all files into the target directory
4. Handle any download failures or errors

Downloads happen asynchronously and in parallel for improved performance. The method uses tokio for async runtime and reqwest for HTTP requests. Files are downloaded maintaining their original filenames from the URLs.

Dataset labels must exactly match what is registered (case-sensitive). The target directory will be created if it doesn’t exist. Existing files in the target directory may be overwritten.

This is used to fetch reference data after registering datasets with register(). For example, after registering genome data with FASTA and GFF URLs, this method would concurrently download both files locally.

Arguments

• label - The unique label of the dataset to download, must match what was registered
• target_dir - Directory path where downloaded files should be saved

Returns

Returns Ok(()) if all downloads complete successfully, or an error if:

• The dataset label is not found in the registry
• Any file downloads fail
• The target directory cannot be accessed/created
• Other IO or HTTP errors occur

Errors

This method can return EntryError::LabelNotFound if the dataset is not in the registry, as well as various IO and HTTP errors wrapped in anyhow::Error for failed downloads.

Panics

This method will panic if:

• The progress bar style template is invalid
• Multiple instances simultaneously write to the same shared progress output
• The download futures report an internal thread failure

pub fn update_registry(self, new_datasets: &[RefDataset]) -> Project

pub fn remove(self, label: &str) -> Result<Self, EntryError>

Removes a dataset from the Project’s registry by its label.

This method allows removing individual datasets from a refman Project’s registry while maintaining the integrity of the remaining datasets. It can be used to:

• Remove outdated or no longer needed reference datasets
• Clean up the registry by removing temporary entries
• Manage the project’s dataset collection over time

The method enforces several rules to maintain registry integrity:

• The label must exactly match an existing dataset (case-sensitive)
• The registry must maintain at least one dataset after removal
• Only one dataset can be removed at a time

This complements register() andownload_dataset() in the lifecycle of managing reference data. While those methods add and fetch datasets, remove() allows pruning datasets that are no longer needed.

Arguments

• label - The unique label identifying the dataset to remove from the registry

Returns

Returns Ok(Project) with the updated Project if removal succeeds, or an EntryError in the following cases:

• EntryError::LabelNotFound if no dataset matches the provided label
• EntryError::FinalEntry if removing this dataset would empty the registry

The Project instance is consumed and a new instance is returned to maintain the builder pattern used throughout the API.

Errors

This method can return the following errors:

• EntryError::LabelNotFound if the specified label is not in the registry
• EntryError::FinalEntry if removing this dataset would empty the registry entirely (at least one dataset must always remain)

pub fn prettyprint(self, label: Option<String>)

Pretty prints the currently registered datasets in a tabular format.

This method provides a human-readable view of all reference datasets currently registered in the Project. It prints a formatted table showing each dataset’s label and any registered file URLs for the supported bioinformatics formats (FASTA, Genbank, GFA, GFF, GTF, BED).

The output is formatted as a table with columns for:

• Dataset Label
• FASTA URL (if registered)
• Genbank URL (if registered)
• GFA URL (if registered)
• GFF URL (if registered)
• GTF URL (if registered)
• BED URL (if registered)

Empty cells indicate that no URL is registered for that file format. If the Project has a title set, it will be displayed above the table.

This provides an easy way to:

• View all registered datasets at once
• Check which file formats are available for each dataset
• Verify dataset labels and URLs
• Share the current state of your reference data registry

The method consumes self as it follows the builder pattern used throughout the API. The actual printing is handled through the prettytable crate for consistent formatting.

Outputs

Prints a formatted table to stdout. If the Project has a title, it is printed as a header above the table. Empty values in the table indicate no URL is registered for that format.

Notes

The output is meant for human consumption and formatted for readability. For programmatic access to dataset information, use the datasets() or datasets_owned() methods instead.

Panics

This method will panic if:

• Multiple datasets with the same label exist in the registry when requesting a specific label
• A requested dataset label does not exist when filtering registered datasets
• The prettytable crate encounters an error when printing the output table

Trait Implementations

impl Clone for Project

fn clone(&self) -> Project

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Project

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

Formats the value using the given formatter.

impl Default for Project

fn default() -> Project

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Project

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Project

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.