goat_cli/
lib.rs

1//! `goat-cli` is a command line interface to query the
2//! [Genomes on a Tree Open API](https://goat.genomehubs.org/api-docs/) using
3//! an asynchronous [`tokio`](<https://docs.rs/tokio/latest/tokio/>) runtime.
4//!
5//! I'm documenting the code here for others, and for future me.
6
7use lazy_static::lazy_static;
8use std::fmt;
9
10/// Like `println!`, but returns the [`std::io::Result`] rather than
11/// panicking, so a closed stdout (e.g. `goat-cli ... | head`) can be
12/// handled gracefully.
13#[macro_export]
14macro_rules! outln {
15    ($($arg:tt)*) => {{
16        use std::io::Write as _;
17        writeln!(std::io::stdout().lock(), $($arg)*)
18    }};
19}
20
21/// The cli itself
22pub mod cli;
23/// Shared HTTP client for all GoaT API requests.
24pub mod client;
25/// Query the GoaT count API.
26pub mod count;
27/// The custom error handling
28pub mod error;
29/// Output formats and tables.
30pub mod output;
31/// Query the GoaT lookup API.
32pub mod lookup;
33/// A module to produce a progress
34/// bar.
35pub mod progress;
36/// Query the GoaT report API.
37pub mod report;
38/// Query the GoaT record API.
39pub mod record;
40/// Query the GoaT search API.
41pub mod search;
42/// Collection of utility functions
43/// used elsewhere.
44pub mod utils;
45
46/// The base URL for GoaT.
47const GOAT_URL_BASE: &str = "https://goat.genomehubs.org/api/";
48/// The current version of the GoaT API.
49const GOAT_API_VERSION: &str = "v2/";
50
51lazy_static! {
52    /// The current GoaT URL.
53    pub static ref GOAT_URL: String = format!("{}{}", GOAT_URL_BASE, GOAT_API_VERSION);
54    /// The taxonomy that `goat-cli` uses.
55    pub static ref TAXONOMY: String = "ncbi".into();
56}
57
58// global size limits on pinging the API
59lazy_static! {
60    /// Upper limit for the CLI arg `--size`.
61    pub static ref UPPER_CLI_SIZE_LIMIT: usize = 50000;
62    /// Upper limit for the number of entries in the file for CLI arg `-f`.
63    pub static ref UPPER_CLI_FILE_LIMIT: usize = 500;
64}
65
66/// The indexes we make searches over in GoaT.
67///
68/// Currently implemented (to some extent) is taxon
69/// and assembly. Others exist, e.g. feature/sample.
70///
71/// Each tuple variant can store their respective
72/// [`std::collections::BTreeMap`] databases.
73#[derive(Clone, Copy, Debug, PartialEq, Eq)]
74pub enum IndexType {
75    /// Taxon search index. The historical main
76    /// functionality of goat-cli went through taxon.
77    Taxon,
78    /// Assembly search index.
79    Assembly,
80}
81
82impl fmt::Display for IndexType {
83    /// Implement [`fmt::Display`] for [`IndexType`] so we can
84    /// use `.to_string()` method.
85    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86        match self {
87            IndexType::Taxon => write!(f, "taxon"),
88            IndexType::Assembly => write!(f, "assembly"),
89        }
90    }
91}
92
93/// The type of result to return in GoaT.
94///
95/// Tax tree is a descendents call to the API,
96/// tax name is a single species, and tax lineage
97/// tracks back up the tree.
98#[derive(Default, Clone, Copy)]
99pub enum TaxType {
100    /// tax_tree() returns a node and all
101    /// of its descendants.
102    #[default]
103    Tree,
104    /// tax_name() returns only the taxon of
105    /// interest.
106    Name,
107    /// tax_lineage() returns all of the nodes
108    /// from a given taxon back to the root of the
109    /// tree.
110    Lineage,
111}
112
113impl fmt::Display for TaxType {
114    /// Implement [`fmt::Display`] for [`TaxType`] so we can
115    /// use `.to_string()` method.
116    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
117        match self {
118            TaxType::Tree => write!(f, "tax_tree"),
119            TaxType::Name => write!(f, "tax_name"),
120            TaxType::Lineage => write!(f, "tax_lineage"),
121        }
122    }
123}