Skip to main content

env_reader/
reader.rs

1//! Reading a whole configuration, collecting every problem on the way.
2
3use std::collections::BTreeMap;
4use std::str::FromStr;
5
6use crate::error::{Error, Errors};
7use crate::secret::Secret;
8use crate::value::{parse_bool, parse_bool_lenient, parse_csv, present};
9
10/// What an unparseable integer is reported as.
11const A_WHOLE_NUMBER: &str = "a whole number";
12
13/// Reads a configuration from variables, accumulating problems rather than
14/// stopping at the first.
15///
16/// A reader is built once, asked for every value the program needs, and
17/// then [`finish`](Reader::finish)ed. Each getter returns a usable value
18/// even when it failed — a required string that was missing comes back
19/// empty — so a caller can read the whole configuration in one straight run
20/// of statements without `?` after every line. `finish` is what decides
21/// whether any of it was valid.
22///
23/// That shape is the point: a program with four missing variables reports
24/// all four, once, instead of over four restarts.
25///
26/// # Examples
27///
28/// ```
29/// use env_reader::Reader;
30///
31/// #[derive(Debug)]
32/// struct Config {
33///     service_name: String,
34///     port: u16,
35///     upstreams: Vec<String>,
36/// }
37///
38/// let mut reader = Reader::from_pairs([
39///     ("SERVICE_NAME", "orders"),
40///     ("PORT", "8443"),
41///     ("UPSTREAMS", "a.internal, b.internal"),
42/// ]);
43///
44/// let config = Config {
45///     service_name: reader.required_string("SERVICE_NAME"),
46///     port: reader.integer_or("PORT", 8080),
47///     upstreams: reader.list("UPSTREAMS"),
48/// };
49/// reader.finish()?;
50///
51/// assert_eq!(config.port, 8443);
52/// assert_eq!(config.upstreams, ["a.internal", "b.internal"]);
53/// # Ok::<(), env_reader::Errors>(())
54/// ```
55#[derive(Debug, Clone)]
56pub struct Reader {
57    /// The variables this reader sees.
58    source: BTreeMap<String, String>,
59    /// Problems found so far, in the order they were found.
60    errors: Vec<Error>,
61}
62
63impl Reader {
64    /// A reader over the process environment.
65    ///
66    /// The only constructor that touches the environment, so every other
67    /// path is testable without mutating global state — which
68    /// [`std::env::set_var`] is `unsafe` for good reason.
69    #[must_use]
70    pub fn from_env() -> Self {
71        Self::from_pairs(std::env::vars())
72    }
73
74    /// A reader over an explicit set of variables, for tests and for
75    /// configuration that arrives from somewhere other than the
76    /// environment.
77    ///
78    /// # Examples
79    ///
80    /// ```
81    /// use env_reader::Reader;
82    ///
83    /// let mut reader = Reader::from_pairs([("PORT", "9000")]);
84    /// assert_eq!(reader.integer_or::<u16>("PORT", 8080), 9000);
85    /// ```
86    pub fn from_pairs<K, V, I>(pairs: I) -> Self
87    where
88        I: IntoIterator<Item = (K, V)>,
89        K: Into<String>,
90        V: Into<String>,
91    {
92        Self {
93            source: pairs
94                .into_iter()
95                .map(|(key, value)| (key.into(), value.into()))
96                .collect(),
97            errors: Vec::new(),
98        }
99    }
100
101    // -- reading ----------------------------------------------------------
102
103    /// The raw value of a variable, trimmed, or `None` when absent or
104    /// blank.
105    ///
106    /// # Examples
107    ///
108    /// ```
109    /// use env_reader::Reader;
110    ///
111    /// let reader = Reader::from_pairs([("A", " x "), ("B", "  ")]);
112    /// assert_eq!(reader.raw("A"), Some("x"));
113    /// assert_eq!(reader.raw("B"), None);
114    /// assert_eq!(reader.raw("C"), None);
115    /// ```
116    #[must_use]
117    pub fn raw(&self, name: &str) -> Option<&str> {
118        present(self.source.get(name).map(String::as_str))
119    }
120
121    /// Whether a variable is set to something non-blank.
122    ///
123    /// # Examples
124    ///
125    /// ```
126    /// use env_reader::Reader;
127    ///
128    /// let reader = Reader::from_pairs([("A", "x"), ("B", " ")]);
129    /// assert!(reader.is_set("A"));
130    /// assert!(!reader.is_set("B"), "blank is absent");
131    /// assert!(!reader.is_set("C"));
132    /// ```
133    #[must_use]
134    pub fn is_set(&self, name: &str) -> bool {
135        self.raw(name).is_some()
136    }
137
138    /// A variable that must be set.
139    ///
140    /// Records [`Error::Missing`] and returns an empty string when it is
141    /// not, so reading can continue and every other problem is found too.
142    ///
143    /// # Examples
144    ///
145    /// ```
146    /// use env_reader::Reader;
147    ///
148    /// let mut reader = Reader::from_pairs([("SERVICE_NAME", "orders")]);
149    /// assert_eq!(reader.required_string("SERVICE_NAME"), "orders");
150    /// assert_eq!(reader.required_string("REGION"), "");
151    /// assert_eq!(reader.finish().unwrap_err().len(), 1);
152    /// ```
153    pub fn required_string(&mut self, name: &str) -> String {
154        if let Some(value) = self.raw(name) {
155            value.to_string()
156        } else {
157            self.errors.push(Error::missing(name));
158            String::new()
159        }
160    }
161
162    /// A variable that need not be set.
163    ///
164    /// # Examples
165    ///
166    /// ```
167    /// use env_reader::Reader;
168    ///
169    /// let reader = Reader::from_pairs([("REGION", "eu-west-2")]);
170    /// assert_eq!(reader.optional_string("REGION").as_deref(), Some("eu-west-2"));
171    /// assert_eq!(reader.optional_string("ZONE"), None);
172    /// ```
173    #[must_use]
174    pub fn optional_string(&self, name: &str) -> Option<String> {
175        self.raw(name).map(str::to_string)
176    }
177
178    /// An optional variable with a fallback.
179    ///
180    /// # Examples
181    ///
182    /// ```
183    /// use env_reader::Reader;
184    ///
185    /// let reader = Reader::from_pairs([("HOST", "0.0.0.0")]);
186    /// assert_eq!(reader.string_or("HOST", "127.0.0.1"), "0.0.0.0");
187    /// assert_eq!(reader.string_or("BIND", "127.0.0.1"), "127.0.0.1");
188    /// ```
189    #[must_use]
190    pub fn string_or(&self, name: &str, default: &str) -> String {
191        self.raw(name).unwrap_or(default).to_string()
192    }
193
194    // -- secrets ----------------------------------------------------------
195
196    /// A secret that must be set.
197    ///
198    /// # Examples
199    ///
200    /// ```
201    /// use env_reader::Reader;
202    ///
203    /// let mut reader = Reader::from_pairs([("DB_PASSWORD", "hunter2")]);
204    /// let password = reader.required_secret("DB_PASSWORD");
205    /// assert_eq!(format!("{password:?}"), "<redacted>");
206    /// ```
207    pub fn required_secret(&mut self, name: &str) -> Secret {
208        Secret::new(self.required_string(name))
209    }
210
211    /// A secret that need not be set.
212    ///
213    /// # Examples
214    ///
215    /// ```
216    /// use env_reader::Reader;
217    ///
218    /// let reader = Reader::from_pairs([("API_KEY", "  ")]);
219    /// assert!(reader.optional_secret("API_KEY").is_none());
220    /// ```
221    #[must_use]
222    pub fn optional_secret(&self, name: &str) -> Option<Secret> {
223        self.raw(name).map(Secret::new)
224    }
225
226    // -- integers ---------------------------------------------------------
227
228    /// An integer that must be set.
229    ///
230    /// # Examples
231    ///
232    /// ```
233    /// use env_reader::Reader;
234    ///
235    /// let mut reader = Reader::from_pairs([("PORT", "8443")]);
236    /// assert_eq!(reader.required_integer::<u16>("PORT"), 8443);
237    /// ```
238    pub fn required_integer<T>(&mut self, name: &str) -> T
239    where
240        T: FromStr + Default,
241    {
242        self.required_parse(name, A_WHOLE_NUMBER).unwrap_or_default()
243    }
244
245    /// An integer that need not be set.
246    ///
247    /// A blank value is absent, not a parse failure.
248    ///
249    /// # Examples
250    ///
251    /// ```
252    /// use env_reader::Reader;
253    ///
254    /// let mut reader = Reader::from_pairs([("A", "30"), ("B", "  ")]);
255    /// assert_eq!(reader.optional_integer::<u64>("A"), Some(30));
256    /// assert_eq!(reader.optional_integer::<u64>("B"), None);
257    /// assert!(reader.finish().is_ok());
258    /// ```
259    pub fn optional_integer<T>(&mut self, name: &str) -> Option<T>
260    where
261        T: FromStr,
262    {
263        self.optional_parse(name, A_WHOLE_NUMBER)
264    }
265
266    /// An integer with a fallback.
267    ///
268    /// An unparseable value is a recorded error, **not** a silent fallback
269    /// to the default: a program quietly running on a default nobody chose
270    /// is harder to diagnose than one that will not start.
271    ///
272    /// # Examples
273    ///
274    /// ```
275    /// use env_reader::Reader;
276    ///
277    /// let mut reader = Reader::from_pairs([("PORT", "8443"), ("OTHER", "two")]);
278    /// assert_eq!(reader.integer_or::<u16>("PORT", 8080), 8443);
279    /// assert_eq!(reader.integer_or::<u16>("MISSING", 8080), 8080);
280    /// assert_eq!(reader.integer_or::<u16>("OTHER", 8080), 8080);
281    /// // The absent one is fine; the unparseable one is not.
282    /// assert_eq!(reader.finish().unwrap_err().len(), 1);
283    /// ```
284    pub fn integer_or<T>(&mut self, name: &str, default: T) -> T
285    where
286        T: FromStr,
287    {
288        self.parse_or(name, A_WHOLE_NUMBER, default)
289    }
290
291    /// An optional integer that, when present, must be greater than zero.
292    ///
293    /// For the "absent means unlimited" shape, where a configured zero is a
294    /// mistake rather than a request for an infinite wait.
295    ///
296    /// # Examples
297    ///
298    /// ```
299    /// use env_reader::Reader;
300    ///
301    /// let mut reader = Reader::from_pairs([("A", "30"), ("B", "0")]);
302    /// assert_eq!(reader.optional_positive_integer::<u32>("A"), Some(30));
303    /// assert_eq!(reader.optional_positive_integer::<u32>("B"), None);
304    /// assert_eq!(reader.optional_positive_integer::<u32>("C"), None);
305    /// // Only B is a problem; C was simply absent.
306    /// assert_eq!(reader.finish().unwrap_err().len(), 1);
307    /// ```
308    pub fn optional_positive_integer<T>(&mut self, name: &str) -> Option<T>
309    where
310        T: FromStr + PartialOrd + Default,
311    {
312        let raw = self.raw(name)?.to_string();
313        let parsed: T = self.parse(name, &raw, A_WHOLE_NUMBER)?;
314
315        if parsed > T::default() {
316            Some(parsed)
317        } else {
318            self.errors.push(Error::invalid(
319                name,
320                "a positive integer when provided",
321                raw,
322            ));
323            None
324        }
325    }
326
327    // -- anything with a `FromStr` ----------------------------------------
328
329    /// Any [`FromStr`] value that must be set.
330    ///
331    /// `expected` is the noun phrase the error message uses: `a socket
332    /// address`, `an RFC 3339 timestamp`, `a log level`. It is the whole
333    /// difference between a message somebody can act on and one they
334    /// cannot, so it is required rather than derived from the type name.
335    ///
336    /// Returns `None` on either failure, having recorded it.
337    ///
338    /// # Examples
339    ///
340    /// ```
341    /// use std::net::IpAddr;
342    /// use env_reader::Reader;
343    ///
344    /// let mut reader = Reader::from_pairs([("BIND", "10.0.0.1"), ("PEER", "not-an-ip")]);
345    ///
346    /// assert_eq!(
347    ///     reader.required_parse::<IpAddr>("BIND", "an IP address"),
348    ///     Some("10.0.0.1".parse().unwrap())
349    /// );
350    /// assert_eq!(reader.required_parse::<IpAddr>("PEER", "an IP address"), None);
351    ///
352    /// let errors = reader.finish().unwrap_err();
353    /// assert!(errors.to_string().contains("PEER must be an IP address"));
354    /// ```
355    pub fn required_parse<T>(&mut self, name: &str, expected: &str) -> Option<T>
356    where
357        T: FromStr,
358    {
359        match self.raw(name) {
360            None => {
361                self.errors.push(Error::missing(name));
362                None
363            }
364            Some(value) => {
365                let value = value.to_string();
366                self.parse(name, &value, expected)
367            }
368        }
369    }
370
371    /// Any [`FromStr`] value that need not be set.
372    ///
373    /// Absent is `None` with no error; present-but-unparseable is `None`
374    /// with one.
375    ///
376    /// # Examples
377    ///
378    /// ```
379    /// use std::path::PathBuf;
380    /// use env_reader::Reader;
381    ///
382    /// let mut reader = Reader::from_pairs([("CA_BUNDLE", "/etc/ca.pem")]);
383    /// assert_eq!(
384    ///     reader.optional_parse::<PathBuf>("CA_BUNDLE", "a path"),
385    ///     Some(PathBuf::from("/etc/ca.pem"))
386    /// );
387    /// assert_eq!(reader.optional_parse::<PathBuf>("OTHER", "a path"), None);
388    /// assert!(reader.finish().is_ok());
389    /// ```
390    pub fn optional_parse<T>(&mut self, name: &str, expected: &str) -> Option<T>
391    where
392        T: FromStr,
393    {
394        let value = self.raw(name)?.to_string();
395        self.parse(name, &value, expected)
396    }
397
398    /// Any [`FromStr`] value with a fallback.
399    ///
400    /// As with [`Reader::integer_or`], an unparseable value is a recorded
401    /// error rather than a silent fallback.
402    ///
403    /// # Examples
404    ///
405    /// ```
406    /// use std::net::IpAddr;
407    /// use env_reader::Reader;
408    ///
409    /// let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
410    /// let bind: IpAddr = reader.parse_or("BIND", "an IP address", "127.0.0.1".parse().unwrap());
411    ///
412    /// assert_eq!(bind.to_string(), "127.0.0.1");
413    /// assert!(reader.finish().is_ok());
414    /// ```
415    pub fn parse_or<T>(&mut self, name: &str, expected: &str, default: T) -> T
416    where
417        T: FromStr,
418    {
419        match self.raw(name) {
420            None => default,
421            Some(value) => {
422                let value = value.to_string();
423                self.parse(name, &value, expected).unwrap_or(default)
424            }
425        }
426    }
427
428    // -- booleans ---------------------------------------------------------
429
430    /// A boolean with a fallback, read strictly by [`crate::parse_bool`].
431    ///
432    /// A value that is neither a true spelling nor a false one is a
433    /// recorded error, not a silent fallback.
434    ///
435    /// # Examples
436    ///
437    /// ```
438    /// use env_reader::Reader;
439    ///
440    /// let mut reader = Reader::from_pairs([("TRACING", "off"), ("CACHE", "maybe")]);
441    /// assert!(!reader.bool_or("TRACING", true));
442    /// assert!(reader.bool_or("METRICS", true), "absent takes the default");
443    /// assert!(reader.bool_or("CACHE", true), "unparseable takes it too, but records");
444    ///
445    /// let errors = reader.finish().unwrap_err();
446    /// assert_eq!(errors.len(), 1);
447    /// assert!(errors.to_string().contains("CACHE"));
448    /// ```
449    pub fn bool_or(&mut self, name: &str, default: bool) -> bool {
450        let Some(raw) = self.raw(name) else {
451            return default;
452        };
453        let raw = raw.to_string();
454
455        if let Some(parsed) = parse_bool(Some(&raw)) {
456            parsed
457        } else {
458            self.errors.push(Error::invalid(
459                name,
460                "true, 1, yes, on, false, 0, no or off",
461                raw,
462            ));
463            default
464        }
465    }
466
467    /// A boolean with a fallback, read leniently by
468    /// [`crate::parse_bool_lenient`]: anything not false-ish is true.
469    ///
470    /// Never records an error, because there is no value it cannot read.
471    /// See [`crate::parse_bool_lenient`] for when that is what you want and
472    /// when it is not.
473    ///
474    /// # Examples
475    ///
476    /// ```
477    /// use env_reader::Reader;
478    ///
479    /// let reader = Reader::from_pairs([("LEGACY_FLAG", "disabled")]);
480    /// assert!(reader.lenient_bool_or("LEGACY_FLAG", false), "not a false spelling");
481    /// ```
482    #[must_use]
483    pub fn lenient_bool_or(&self, name: &str, default: bool) -> bool {
484        parse_bool_lenient(self.raw(name)).unwrap_or(default)
485    }
486
487    // -- lists ------------------------------------------------------------
488
489    /// A comma-separated list, possibly empty.
490    ///
491    /// # Examples
492    ///
493    /// ```
494    /// use env_reader::Reader;
495    ///
496    /// let reader = Reader::from_pairs([("UPSTREAMS", "a, b")]);
497    /// assert_eq!(reader.list("UPSTREAMS"), ["a", "b"]);
498    /// assert!(reader.list("ABSENT").is_empty());
499    /// ```
500    #[must_use]
501    pub fn list(&self, name: &str) -> Vec<String> {
502        parse_csv(self.raw(name))
503    }
504
505    /// A comma-separated list that must be set and must have an element.
506    ///
507    /// # Examples
508    ///
509    /// ```
510    /// use env_reader::Reader;
511    ///
512    /// let mut reader = Reader::from_pairs([("BAD", " , ")]);
513    /// assert!(reader.required_list("ABSENT").is_empty());
514    /// assert!(reader.required_list("BAD").is_empty());
515    /// // One missing, one set to nothing but separators.
516    /// assert_eq!(reader.finish().unwrap_err().len(), 2);
517    /// ```
518    pub fn required_list(&mut self, name: &str) -> Vec<String> {
519        let Some(value) = self.raw(name) else {
520            self.errors.push(Error::missing(name));
521            return Vec::new();
522        };
523        let value = value.to_string();
524        let parsed = parse_csv(Some(&value));
525
526        if parsed.is_empty() {
527            self.errors.push(Error::invalid(
528                name,
529                "a comma-separated list with at least one value",
530                value,
531            ));
532        }
533        parsed
534    }
535
536    /// A comma-separated list, falling back to a default list when the
537    /// variable is absent.
538    ///
539    /// A variable set to only separators is a recorded error rather than an
540    /// empty list, because it means someone meant to configure something.
541    ///
542    /// # Examples
543    ///
544    /// ```
545    /// use env_reader::Reader;
546    ///
547    /// let mut reader = Reader::from_pairs([("BAD", " , ")]);
548    /// assert_eq!(reader.list_or("METHODS", "GET,HEAD"), ["GET", "HEAD"]);
549    /// assert!(reader.list_or("BAD", "x").is_empty());
550    /// assert_eq!(reader.finish().unwrap_err().len(), 1);
551    /// ```
552    pub fn list_or(&mut self, name: &str, default: &str) -> Vec<String> {
553        match self.raw(name) {
554            None => parse_csv(Some(default)),
555            Some(value) => {
556                let value = value.to_string();
557                let parsed = parse_csv(Some(&value));
558                if parsed.is_empty() {
559                    self.errors.push(Error::invalid(
560                        name,
561                        "a comma-separated list with at least one value",
562                        value,
563                    ));
564                }
565                parsed
566            }
567        }
568    }
569
570    // -- fixed sets -------------------------------------------------------
571
572    /// A value that must be set and must be one of a fixed set.
573    ///
574    /// # Examples
575    ///
576    /// ```
577    /// use env_reader::Reader;
578    ///
579    /// const LEVELS: &[&str] = &["trace", "debug", "info", "warn", "error"];
580    ///
581    /// let mut reader = Reader::from_pairs([("LOG_LEVEL", "verbose")]);
582    /// assert_eq!(reader.required_one_of("LOG_LEVEL", LEVELS), None);
583    ///
584    /// let errors = reader.finish().unwrap_err();
585    /// assert!(errors.to_string().contains("one of trace, debug, info, warn, error"));
586    /// ```
587    pub fn required_one_of(&mut self, name: &str, accepted: &[&str]) -> Option<String> {
588        if self.raw(name).is_none() {
589            self.errors.push(Error::missing(name));
590            return None;
591        }
592        self.optional_one_of(name, accepted)
593    }
594
595    /// A value that, when set, must be one of a fixed set.
596    ///
597    /// # Examples
598    ///
599    /// ```
600    /// use env_reader::Reader;
601    ///
602    /// const LEVELS: &[&str] = &["trace", "debug", "info", "warn", "error"];
603    ///
604    /// let mut reader = Reader::from_pairs([("LOG_LEVEL", "debug")]);
605    /// assert_eq!(reader.optional_one_of("LOG_LEVEL", LEVELS).as_deref(), Some("debug"));
606    /// assert_eq!(reader.optional_one_of("OTHER", LEVELS), None);
607    /// assert!(reader.finish().is_ok());
608    /// ```
609    pub fn optional_one_of(&mut self, name: &str, accepted: &[&str]) -> Option<String> {
610        let value = self.raw(name)?.to_string();
611
612        if accepted.contains(&value.as_str()) {
613            Some(value)
614        } else {
615            self.errors.push(Error::invalid(
616                name,
617                format!("one of {}", accepted.join(", ")),
618                value,
619            ));
620            None
621        }
622    }
623
624    // -- UUIDs ------------------------------------------------------------
625
626    /// A required UUID.
627    ///
628    /// Returns [`uuid::Uuid::nil`] and records a problem when the variable
629    /// is absent or unparseable, so reading continues like every other
630    /// getter here.
631    ///
632    /// # Examples
633    ///
634    /// ```
635    /// use env_reader::Reader;
636    ///
637    /// let mut reader = Reader::from_pairs([
638    ///     ("BATCH_ID", "00000000-0000-0000-0000-000000000001"),
639    /// ]);
640    /// assert_eq!(
641    ///     reader.required_uuid("BATCH_ID").to_string(),
642    ///     "00000000-0000-0000-0000-000000000001"
643    /// );
644    /// ```
645    #[cfg(feature = "uuid")]
646    pub fn required_uuid(&mut self, name: &str) -> uuid::Uuid {
647        self.required_parse(name, "a UUID")
648            .unwrap_or_else(uuid::Uuid::nil)
649    }
650
651    /// An optional UUID.
652    #[cfg(feature = "uuid")]
653    pub fn optional_uuid(&mut self, name: &str) -> Option<uuid::Uuid> {
654        self.optional_parse(name, "a UUID")
655    }
656
657    // -- problems the caller finds ----------------------------------------
658
659    /// Record that one variable held a value this crate cannot check.
660    ///
661    /// [`optional_one_of`](Reader::optional_one_of) covers a fixed set of
662    /// accepted strings, and [`optional_parse`](Reader::optional_parse)
663    /// covers anything with a [`FromStr`]. This is for what neither can: a
664    /// value that has to be resolved against something outside this crate,
665    /// where only the caller knows what "valid" means. The problem joins
666    /// the others, so a program that rejects a value here still reports
667    /// every *other* problem in the same breath.
668    ///
669    /// # Examples
670    ///
671    /// ```
672    /// use env_reader::Reader;
673    ///
674    /// let mut reader = Reader::from_pairs([("TENANT", "unknown-tenant")]);
675    ///
676    /// if let Some(value) = reader.optional_string("TENANT") {
677    ///     if !["alpha", "beta"].contains(&value.as_str()) {
678    ///         reader.invalid("TENANT", "a tenant this build knows about", value);
679    ///     }
680    /// }
681    ///
682    /// let errors = reader.finish().unwrap_err();
683    /// assert!(errors.to_string().contains("a tenant this build knows about"));
684    /// ```
685    pub fn invalid(
686        &mut self,
687        name: impl Into<String>,
688        expected: impl Into<String>,
689        got: impl Into<String>,
690    ) {
691        self.errors.push(Error::invalid(name, expected, got));
692    }
693
694    /// Record a conflict between variables that are individually fine.
695    ///
696    /// # Examples
697    ///
698    /// ```
699    /// use env_reader::Reader;
700    ///
701    /// let mut reader = Reader::from_pairs([("QUEUE_NAME", "q"), ("TOPIC_NAME", "t")]);
702    /// if reader.is_set("QUEUE_NAME") && reader.is_set("TOPIC_NAME") {
703    ///     reader.conflict("Cannot specify both QUEUE_NAME and TOPIC_NAME.");
704    /// }
705    /// assert!(reader.finish().is_err());
706    /// ```
707    pub fn conflict(&mut self, message: impl Into<String>) {
708        self.errors.push(Error::conflict(message));
709    }
710
711    // -- finishing --------------------------------------------------------
712
713    /// Whether anything has gone wrong so far.
714    ///
715    /// Lets a caller skip a cross-field check that would only produce noise
716    /// on top of an already-broken configuration.
717    ///
718    /// # Examples
719    ///
720    /// ```
721    /// use env_reader::Reader;
722    ///
723    /// let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
724    /// assert!(!reader.has_errors());
725    /// let _ = reader.required_string("SERVICE_NAME");
726    /// assert!(reader.has_errors());
727    /// ```
728    #[must_use]
729    pub fn has_errors(&self) -> bool {
730        !self.errors.is_empty()
731    }
732
733    /// How many problems have been found so far.
734    #[must_use]
735    pub fn error_count(&self) -> usize {
736        self.errors.len()
737    }
738
739    /// Finish reading.
740    ///
741    /// # Errors
742    ///
743    /// Returns every problem found, in the order it was found, when there
744    /// was at least one.
745    ///
746    /// # Examples
747    ///
748    /// ```
749    /// use env_reader::Reader;
750    ///
751    /// let mut reader = Reader::from_pairs([("SERVICE_NAME", "orders")]);
752    /// let _ = reader.required_string("SERVICE_NAME");
753    /// assert!(reader.finish().is_ok());
754    /// ```
755    pub fn finish(self) -> Result<(), Errors> {
756        if self.errors.is_empty() {
757            Ok(())
758        } else {
759            Err(Errors::new(self.errors))
760        }
761    }
762
763    /// Finish reading, returning `value` when nothing went wrong.
764    ///
765    /// The shape that lets a `Config` be built and validated in one
766    /// expression, so a caller cannot forget the `finish`.
767    ///
768    /// # Errors
769    ///
770    /// Returns every problem found, as [`Reader::finish`].
771    ///
772    /// # Examples
773    ///
774    /// ```
775    /// use env_reader::{Errors, Reader};
776    ///
777    /// #[derive(Debug)]
778    /// struct Config {
779    ///     port: u16,
780    /// }
781    ///
782    /// fn load() -> Result<Config, Errors> {
783    ///     let mut reader = Reader::from_pairs([("PORT", "8443")]);
784    ///     let config = Config {
785    ///         port: reader.integer_or("PORT", 8080),
786    ///     };
787    ///     reader.finish_with(config)
788    /// }
789    ///
790    /// assert_eq!(load()?.port, 8443);
791    /// # Ok::<(), Errors>(())
792    /// ```
793    pub fn finish_with<T>(self, value: T) -> Result<T, Errors> {
794        self.finish().map(|()| value)
795    }
796
797    /// Parse a value, recording a problem and returning `None` when it does
798    /// not parse.
799    fn parse<T: FromStr>(&mut self, name: &str, value: &str, expected: &str) -> Option<T> {
800        if let Ok(parsed) = value.parse::<T>() {
801            Some(parsed)
802        } else {
803            self.errors.push(Error::invalid(name, expected, value));
804            None
805        }
806    }
807}
808
809#[cfg(test)]
810mod tests {
811    use super::*;
812
813    #[test]
814    fn every_problem_is_reported_at_once() {
815        // The reason this crate is shaped the way it is.
816        let mut reader = Reader::from_pairs([("PORT", "two")]);
817        let _ = reader.required_string("SERVICE_NAME");
818        let _ = reader.required_string("REGION");
819        let _: u16 = reader.integer_or("PORT", 8080);
820
821        let errors = reader.finish().unwrap_err();
822        assert_eq!(errors.len(), 3);
823        assert_eq!(errors.to_string().lines().count(), 3);
824    }
825
826    #[test]
827    fn problems_come_back_in_the_order_they_were_found() {
828        let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
829        let _ = reader.required_string("FIRST");
830        let _ = reader.required_string("SECOND");
831
832        let errors = reader.finish().unwrap_err();
833        let names: Vec<_> = errors.iter().filter_map(Error::name).collect();
834        assert_eq!(names, ["FIRST", "SECOND"]);
835    }
836
837    #[test]
838    fn a_blank_integer_is_absent_rather_than_a_parse_failure() {
839        // The trap: `int("")` in the language this pattern usually comes
840        // from raises, so a blank variable becomes a crash rather than a
841        // default.
842        let mut reader = Reader::from_pairs([("A", "  ")]);
843        assert_eq!(reader.optional_integer::<u32>("A"), None);
844        assert_eq!(reader.integer_or::<u32>("A", 7), 7);
845        assert!(reader.finish().is_ok());
846    }
847
848    #[test]
849    fn an_unparseable_value_does_not_silently_take_the_default() {
850        // A program quietly running on a default nobody chose is harder to
851        // diagnose than one that will not start.
852        let mut reader = Reader::from_pairs([("PORT", "eighty")]);
853        assert_eq!(reader.integer_or::<u16>("PORT", 8080), 8080);
854        assert!(reader.has_errors());
855    }
856
857    #[test]
858    fn a_failed_getter_still_returns_something_usable() {
859        // What lets a caller read a whole configuration without `?` after
860        // every line.
861        let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
862        assert_eq!(reader.required_string("A"), "");
863        assert_eq!(reader.required_integer::<u16>("B"), 0);
864        assert!(reader.required_list("C").is_empty());
865        assert_eq!(reader.error_count(), 3);
866    }
867
868    #[test]
869    fn any_from_str_type_can_be_read() {
870        use std::net::{IpAddr, SocketAddr};
871        use std::path::PathBuf;
872
873        let mut reader = Reader::from_pairs([
874            ("BIND", "10.0.0.1"),
875            ("PEER", "10.0.0.2:9000"),
876            ("BUNDLE", "/etc/ca.pem"),
877        ]);
878
879        assert_eq!(
880            reader.required_parse::<IpAddr>("BIND", "an IP address"),
881            Some("10.0.0.1".parse().unwrap())
882        );
883        assert_eq!(
884            reader.required_parse::<SocketAddr>("PEER", "a socket address"),
885            Some("10.0.0.2:9000".parse().unwrap())
886        );
887        assert_eq!(
888            reader.optional_parse::<PathBuf>("BUNDLE", "a path"),
889            Some(PathBuf::from("/etc/ca.pem"))
890        );
891        assert!(reader.finish().is_ok());
892    }
893
894    #[test]
895    fn the_expected_phrase_reaches_the_message() {
896        // The whole difference between a message somebody can act on and
897        // one they cannot.
898        use std::net::IpAddr;
899
900        let mut reader = Reader::from_pairs([("BIND", "localhost")]);
901        assert_eq!(reader.required_parse::<IpAddr>("BIND", "an IP address"), None);
902
903        let errors = reader.finish().unwrap_err();
904        assert_eq!(
905            errors.to_string(),
906            r#"invalid configuration: BIND must be an IP address, got "localhost""#
907        );
908    }
909
910    #[test]
911    fn a_strict_boolean_records_what_it_cannot_read() {
912        let mut reader = Reader::from_pairs([("A", "on"), ("B", "disabled")]);
913        assert!(reader.bool_or("A", false));
914        assert!(reader.bool_or("B", true), "the default, having recorded");
915        assert!(reader.bool_or("C", true), "absent takes the default silently");
916
917        let errors = reader.finish().unwrap_err();
918        assert_eq!(errors.len(), 1);
919        assert_eq!(errors.iter().next().and_then(Error::name), Some("B"));
920    }
921
922    #[test]
923    fn a_lenient_boolean_records_nothing() {
924        let mut reader = Reader::from_pairs([("B", "disabled")]);
925        assert!(reader.lenient_bool_or("B", false));
926        assert!(!reader.lenient_bool_or("C", false));
927        let _ = reader.bool_or("ABSENT", true);
928        assert!(reader.finish().is_ok());
929    }
930
931    #[test]
932    fn a_positive_integer_rejects_zero_but_not_absence() {
933        let mut reader = Reader::from_pairs([("A", "0")]);
934        assert_eq!(reader.optional_positive_integer::<u32>("A"), None);
935        assert_eq!(reader.optional_positive_integer::<u32>("ABSENT"), None);
936        assert_eq!(reader.error_count(), 1, "only the configured zero");
937    }
938
939    #[test]
940    fn a_fixed_set_lists_what_it_accepted() {
941        const LEVELS: &[&str] = &["info", "warn"];
942
943        let mut reader = Reader::from_pairs([("L", "verbose")]);
944        assert_eq!(reader.optional_one_of("L", LEVELS), None);
945        assert_eq!(reader.required_one_of("M", LEVELS), None);
946
947        let text = reader.finish().unwrap_err().to_string();
948        assert!(text.contains("one of info, warn"), "{text}");
949        assert!(text.contains("missing required configuration: M"), "{text}");
950    }
951
952    #[test]
953    fn a_required_fixed_set_reports_missing_once_not_twice() {
954        // The trap in delegating to the optional form: an absent variable
955        // must not be both "missing" and "not one of".
956        const LEVELS: &[&str] = &["info"];
957
958        let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
959        assert_eq!(reader.required_one_of("L", LEVELS), None);
960        assert_eq!(reader.error_count(), 1);
961    }
962
963    #[test]
964    fn a_list_of_only_separators_is_a_problem_not_an_empty_list() {
965        // It means someone meant to configure something.
966        let mut reader = Reader::from_pairs([("A", " , ")]);
967        assert!(reader.list_or("A", "x").is_empty());
968        assert!(reader.list("A").is_empty(), "the plain reader has no opinion");
969        assert_eq!(reader.error_count(), 1);
970    }
971
972    #[test]
973    fn finish_with_carries_a_value_through() {
974        let mut reader = Reader::from_pairs([("PORT", "8443")]);
975        let port = reader.integer_or::<u16>("PORT", 8080);
976        assert_eq!(reader.finish_with(port).unwrap(), 8443);
977
978        let mut reader = Reader::from_pairs([] as [(&str, &str); 0]);
979        let _ = reader.required_string("A");
980        assert!(reader.finish_with(1).is_err());
981    }
982
983    #[test]
984    fn blank_is_absent_everywhere_it_matters() {
985        let mut reader = Reader::from_pairs([
986            ("S", "   "),
987            ("I", "\t"),
988            ("B", " "),
989            ("L", ""),
990            ("K", "  "),
991        ]);
992
993        assert_eq!(reader.optional_string("S"), None);
994        assert_eq!(reader.optional_integer::<u32>("I"), None);
995        assert!(!reader.lenient_bool_or("B", false));
996        assert!(reader.list("L").is_empty());
997        assert!(reader.optional_secret("K").is_none());
998        assert!(!reader.is_set("S"));
999        assert!(reader.finish().is_ok(), "none of that is a problem");
1000    }
1001
1002    #[test]
1003    fn a_reader_can_come_from_the_process_environment() {
1004        // Constructing it is the whole assertion: this is the one path that
1005        // touches global state, and it must not panic on whatever is there.
1006        let reader = Reader::from_env();
1007        assert!(!reader.has_errors());
1008    }
1009
1010    #[cfg(feature = "uuid")]
1011    #[test]
1012    fn a_uuid_is_read_and_a_bad_one_is_recorded() {
1013        let mut reader = Reader::from_pairs([
1014            ("GOOD", "00000000-0000-0000-0000-000000000001"),
1015            ("BAD", "not-a-uuid"),
1016        ]);
1017
1018        assert_eq!(
1019            reader.required_uuid("GOOD").to_string(),
1020            "00000000-0000-0000-0000-000000000001"
1021        );
1022        assert!(reader.required_uuid("BAD").is_nil());
1023        assert!(reader.optional_uuid("ABSENT").is_none());
1024
1025        let text = reader.finish().unwrap_err().to_string();
1026        assert!(text.contains("BAD must be a UUID"), "{text}");
1027    }
1028}