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}