mdd_api 0.7.0

Rust API for the Mammal Diversity Database
Documentation 
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

//! Command-line interface argument definitions for the `mdd_api` tooling.
//!
//! Uses `clap` derive macros to expose subcommands for converting raw Mammal
//! Diversity Database (MDD) release assets into JSON, database, or other
//! serialized forms.
//!
//! Subcommands:
//! * `json`  – Parse species + synonym CSVs and export JSON (optionally limit or prefix files).
//! * `db`    – (Planned/placeholder) ingest JSON into a SQLite database.
//! * `toml`  – Parse release metadata TOML plus referenced CSVs (future expansion).
//! * `zip`   – Parse directly from a zipped archive (future/support tooling).
//!
//! Most file path arguments default to relative names to simplify quick starts;
//! override them for production workflows.

use std::path::PathBuf;

use clap::{Args, Parser, Subcommand, crate_authors, crate_description, crate_name, crate_version};

use crate::helper::types::OutputFormat;

/// Top-level CLI dispatcher enumerating supported subcommands.
#[derive(Parser)]
#[command(name = crate_name!(), version = crate_version!(), about = crate_description!(), author = crate_authors!())]
pub enum Cli {
    #[command(name = "unpack", about = "Parse MDD data and export different formats")]
    Unpack(UnpackArgs),
    #[command(
        subcommand,
        name = "filter",
        about = "Filter MDD data by country codes"
    )]
    Filter(FilterSubcommand),
}

#[derive(Subcommand)]
pub enum FilterSubcommand {
    #[command(name = "country", about = "Filter MDD data by country codes")]
    ByCountry(FilterByCountryArgs),
}

#[derive(Args)]
pub struct FilterByCountryArgs {
    #[command(flatten)]
    pub input: CommonInput,
    /// Output file path
    #[command(flatten)]
    pub output: CommonOutput,
    /// Country codes to filter by
    #[arg(
        long,
        short,
        value_delimiter = ',',
        help = "Country codes to filter by"
    )]
    pub country_codes: Vec<String>,
}

/// Arguments for the `zip` subcommand (compressed source processing).
#[derive(Args)]
pub struct UnpackArgs {
    #[command(flatten)]
    pub input: CommonInput,
    /// Override MDD version string for metadata embedding.
    #[arg(long = "mdd", help = "MDD data version", require_equals = true)]
    pub mdd_version: Option<String>,
    /// Override MDD release date (ISO 8601 expected: YYYY-MM-DD).
    #[arg(long = "date", help = "MDD release date")]
    pub release_date: Option<String>,
    #[command(flatten)]
    pub output: CommonOutput,
}

#[derive(Args)]
pub struct CommonOutput {
    /// Output directory for decompressed / processed content.
    #[arg(long, short, default_value = ".", help = "Output directory")]
    pub output: PathBuf,
    /// Output format
    #[arg(
        value_enum,
        long,
        short = 'F',
        default_value = "csv",
        help = "Output file format"
    )]
    pub output_format: OutputFormat,
    /// Limit number of species records to parse.
    #[arg(long = "limit", help = "Limit number of records")]
    pub limit: Option<usize>,
    /// Add a file name prefix to all exported artifacts.
    #[arg(long, help = "Add prefix to output files")]
    pub prefix: Option<String>,
}

#[derive(Args)]
pub struct CommonInput {
    /// Input species CSV file path.
    #[arg(
        long,
        short,
        default_value = "MDD.csv",
        help = "Input MDD species CSV file"
    )]
    pub input: PathBuf,
    /// File format to export (json, db, toml, etc).
    #[arg(long, short, default_value = "zip", help = "Output format")]
    pub format: String,
}