gitignore_template_generator/parser/api.rs
1use std::ffi::OsString;
2
3use crate::ProgramExit;
4pub use crate::parser::impls::ClapArgsParser;
5
6/// Struct to gather cli args parsing result.
7///
8/// Used by [`crate::parser::ArgsParser`] implementations to store
9/// parsing result.
10#[derive(Debug, PartialEq, Default)]
11pub struct Args {
12 /// A non-empty list of gitignore template names.
13 ///
14 /// * Represented by the provided positional arguments, and required
15 /// unless any of `author`, `version` or `help` options are given.
16 /// * This field does not allow commas in any of its field.
17 pub template_names: Vec<String>,
18
19 /// The gitignore template generator service url.
20 ///
21 /// * Optional value represented by the cli option
22 /// [`crate::constant::cli_options::SERVER_URL`] that takes a string
23 /// value, and falling back to
24 /// [`crate::constant::template_manager::BASE_URL`] if not provided
25 /// in cli args.
26 pub server_url: String,
27
28 /// The gitignore template generator service endpoint uri.
29 ///
30 /// * Optional value represented by the cli option
31 /// [`crate::constant::cli_options::GENERATOR_URI`] that takes a string
32 /// value, and falling back to
33 /// [`crate::constant::template_manager::GENERATOR_URI`] if not provided in cli
34 /// args.
35 pub generator_uri: String,
36
37 /// The gitignore template lister service endpoint uri.
38 ///
39 /// * Optional value represented by the cli option
40 /// [`crate::constant::cli_options::LISTER_URI`] that takes a string
41 /// value, and falling back to
42 /// [`crate::constant::template_manager::LISTER_URI`] if not provided in cli
43 /// args.
44 pub lister_uri: String,
45
46 /// The boolean indicator of whether to display help infos or not.
47 ///
48 /// * Optional value represented by the cli option
49 /// [`crate::constant::cli_options::HELP`], and falling back to `false`
50 /// if not provided in cli args.
51 /// * Has precedence over version and author options if multiple are given
52 pub show_help: bool,
53
54 /// The boolean indicator of whether to display version infos or not.
55 ///
56 /// * Optional value represented by the cli option
57 /// [`crate::constant::cli_options::VERSION`], and falling back to
58 /// `false` if not provided in cli args.
59 /// * Has precedence over author option if multiple are given
60 pub show_version: bool,
61
62 /// The boolean indicator of whether to display author infos or not.
63 ///
64 /// * Optional value represented by the cli option
65 /// [`crate::constant::cli_options::AUTHOR`], and falling back to
66 /// `false` if not provided in cli args.
67 pub show_author: bool,
68
69 /// The boolean indicator of whether to display list of available templates
70 /// or not.
71 ///
72 /// * Optional value represented by the cli option
73 /// [`crate::constant::cli_options::LIST`], and falling back to
74 /// `false` if not provided in cli args.
75 pub show_list: bool,
76
77 /// The boolean indicator of whether to enable robust template check or not.
78 ///
79 /// Robust template check allow the script to handle template existence
80 /// check without reaching the generator endpoint.
81 ///
82 /// * Optional value represented by the cli option
83 /// [`crate::constant::cli_options::CHECK`], and falling back to
84 /// `false` if not provided in cli args.
85 pub check_template_names: bool,
86}
87
88impl Args {
89 /// Sets new value for `template_names` field.
90 ///
91 /// It needs to be called on struct instance and effectively mutates it.
92 ///
93 /// # Arguments
94 ///
95 /// * `template_names` - The new value to be assigned to `template_names`
96 /// field.
97 ///
98 /// # Returns
99 ///
100 /// The mutated borrowed instance.
101 pub fn with_template_names(mut self, template_names: Vec<String>) -> Self {
102 self.template_names = template_names;
103 self
104 }
105
106 /// Sets new value for `server_url` field.
107 ///
108 /// It needs to be called on struct instance and effectively mutates it.
109 ///
110 /// # Arguments
111 ///
112 /// * `server_url` - The new value to be assigned to `server_url`
113 /// field.
114 ///
115 /// # Returns
116 ///
117 /// The mutated borrowed instance.
118 pub fn with_server_url(mut self, server_url: &str) -> Self {
119 self.server_url = server_url.to_string();
120 self
121 }
122
123 /// Sets new value for `generator_uri` field.
124 ///
125 /// It needs to be called on struct instance and effectively mutates it.
126 ///
127 /// # Arguments
128 ///
129 /// * `generator_uri` - The new value to be assigned to
130 /// `generator_uri` field.
131 ///
132 /// # Returns
133 ///
134 /// The mutated borrowed instance.
135 pub fn with_generator_uri(mut self, generator_uri: &str) -> Self {
136 self.generator_uri = generator_uri.to_string();
137 self
138 }
139
140 /// Sets new value for `lister_uri` field.
141 ///
142 /// It needs to be called on struct instance and effectively mutates it.
143 ///
144 /// # Arguments
145 ///
146 /// * `lister_uri` - The new value to be assigned to `lister_uri` field.
147 ///
148 /// # Returns
149 ///
150 /// The mutated borrowed instance.
151 pub fn with_lister_uri(mut self, lister_uri: &str) -> Self {
152 self.lister_uri = lister_uri.to_string();
153 self
154 }
155
156 /// Sets new value for `show_list` field.
157 ///
158 /// It needs to be called on struct instance and effectively mutates it.
159 ///
160 /// # Arguments
161 ///
162 /// * `show_list` - The new value to be assigned to `show_list`
163 /// field.
164 ///
165 /// # Returns
166 ///
167 /// The mutated borrowed instance.
168 pub fn with_show_list(mut self, show_list: bool) -> Self {
169 self.show_list = show_list;
170 self
171 }
172
173 /// Sets new value for `check_template_names` field.
174 ///
175 /// It needs to be called on struct instance and effectively mutates it.
176 ///
177 /// # Arguments
178 ///
179 /// * `check_template_names` - The new value to be assigned to
180 /// `check_template_names` field.
181 ///
182 /// # Returns
183 ///
184 /// The mutated borrowed instance.
185 pub fn with_check_template_names(
186 mut self,
187 check_template_names: bool,
188 ) -> Self {
189 self.check_template_names = check_template_names;
190 self
191 }
192}
193
194/// Cli args parser trait to parse CLI args and return them in an [`Args`].
195///
196/// The produced Args instance needs to comply with constraints of each
197/// one of its fields (see fields doc in [`Args`] for more infos).
198pub trait ArgsParser {
199 /// Parses given cli args and return them as an [`Args`] instance.
200 ///
201 /// * First CLI args should be the binary name
202 /// * Rely on [`ArgsParser::try_parse`] method but additionally wrap
203 /// error handling logic
204 ///
205 /// # Arguments
206 ///
207 /// * `args` - The CLI args to be parsed. Typically retrieved from
208 /// [`std::env::args_os`].
209 ///
210 /// # Returns
211 ///
212 /// An owned instance of [`Args`] containing parsing result of given args.
213 fn parse(&self, args: impl IntoIterator<Item = OsString>) -> Args;
214
215 /// Parses given cli args and return them as an [`Args`] instance if no
216 /// error or early exit occurred.
217 ///
218 /// * First CLI args should be the binary name
219 /// * Version, author and help options are considered as early program
220 /// exit
221 /// * Returned Args complies with expected constraints (see fields doc
222 /// in [`Args`] for more infos)
223 ///
224 /// # Arguments
225 ///
226 /// * `args` - The CLI args to be parsed. Typically retrieved from
227 /// [`std::env::args_os`].
228 ///
229 /// # Returns
230 ///
231 /// A result containing an owned instance of [`Args`] if successful parsing,
232 /// or a [`ProgramExit`] if any error or early exit occurred (e.g. version/
233 /// author/help infos printing, invalid cli args...)
234 fn try_parse(
235 &self,
236 args: impl IntoIterator<Item = OsString>,
237 ) -> Result<Args, ProgramExit>;
238}