Core types and abstractions for working with BIDS datasets.

This crate provides the foundational building blocks used by all other bids-* crates:

• [Entity] and [EntityValue] — BIDS entity definitions (subject, session, task, run, …) with regex-based extraction from file paths and typed value coercion.
• [BidsFile] — Representation of a single file in a BIDS dataset, with automatic file type detection, entity extraction, suffix/extension parsing, and companion file lookup.
• [BidsMetadata] — Ordered key-value metadata dictionary backed by IndexMap, supporting typed access (get_f64, get_str, get_array, …) and deserialization into arbitrary structs.
• [DatasetDescription] — Typed representation of dataset_description.json with validation, derivative detection, and legacy field migration.
• [Config] — Layout configuration defining entity patterns and path templates, loadable from built-in configs (bids, derivatives) or custom JSON files.
• [PaddedInt] — Zero-padded integer type that preserves formatting (e.g., "02") while comparing numerically.
• [BidsError] — Comprehensive error enum covering I/O, JSON, validation, entity, filter, database, and path-building errors.

BIDS Entities

BIDS filenames encode metadata as key-value pairs separated by underscores:

sub-01_ses-02_task-rest_run-01_bold.nii.gz
^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^^^ ^^^^
subject session  task     run   suffix

The [mod@entities] module defines the canonical entity ordering and provides functions to parse entities from paths, sort them, and coerce values to the correct types (string, padded integer, float, boolean).

Example

use bids_core::{BidsFile, Config, DatasetDescription};

// Parse entities from a filename
let config = Config::bids();
let entities = bids_core::entities::parse_file_entities(
    "sub-01/eeg/sub-01_task-rest_eeg.edf",
    &config.entities,
);
assert_eq!(entities.get("subject").unwrap().as_str_lossy(), "01");
assert_eq!(entities.get("task").unwrap().as_str_lossy(), "rest");