etc_os_release/
lib.rs

1//! A parser and data structures for the `/etc/os-release` file.
2//!
3//! os-release file is used by systemd and other tools to store information about the
4//! operating system distribution.
5//!
6//! The file is formatted as a list of environment-like shell-compatible
7//! variable assignments.
8//!
9//! For more information, see [`os-release(5)`]
10//!
11//! [`os-release(5)`]: https://www.freedesktop.org/software/systemd/man/os-release.html
12//!
13//! # Usage
14//!
15//! Add this to your `Cargo.toml`:
16//!
17//! ```toml
18//! [dependencies]
19//! etc-os-release = "0.1.1"
20//! ```
21//!
22//! # Examples
23//!
24//! Open the os-release file and print the OS name and version:
25//!
26//! ```rust,no_run
27//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
28//! use etc_os_release::OsRelease;
29//!
30//! let os_release = OsRelease::open()?;
31//! println!("{}-{}", os_release.id(), os_release.version_id().unwrap_or_default());
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! Parse a string containing the contents of the os-release file:
37//!
38//! ```rust
39//! use std::str::FromStr;
40//!
41//! use etc_os_release::OsRelease;
42//!
43//! let os_release = OsRelease::from_str(r#"
44//! NAME=Fedora
45//! VERSION="32 (Workstation Edition)"
46//! ID=fedora
47//! VERSION_ID=32
48//! PRETTY_NAME="Fedora 32 (Workstation Edition)"
49//! ANSI_COLOR="0;38;2;60;110;180"
50//! LOGO=fedora-logo-icon
51//! CPE_NAME="cpe:/o:fedoraproject:fedora:32"
52//! HOME_URL="https://fedoraproject.org/"
53//! DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
54//! SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
55//! BUG_REPORT_URL="https://bugzilla.redhat.com/"
56//! REDHAT_BUGZILLA_PRODUCT="Fedora"
57//! REDHAT_BUGZILLA_PRODUCT_VERSION=32
58//! REDHAT_SUPPORT_PRODUCT="Fedora"
59//! REDHAT_SUPPORT_PRODUCT_VERSION=32
60//! PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
61//! VARIANT="Workstation Edition"
62//! VARIANT_ID=workstation
63//! "#).unwrap();
64//!
65//! assert_eq!(os_release.id(), "fedora");
66//! assert_eq!(os_release.version_id(), Some("32"));
67//! ```
68
69#![doc(html_root_url = "https://docs.rs/etc-os-release/0.1.1")]
70#![cfg_attr(docsrs, feature(doc_cfg))]
71#![warn(missing_docs, unreachable_pub)]
72
73use indexmap::IndexMap;
74
75pub use crate::{
76    construct::Error,
77    entry::{OsReleaseEntry, OsReleaseLine},
78};
79
80mod construct;
81mod entry;
82mod fields;
83
84/// The parsed contents of the os-release file.
85///
86/// This structure is a map of the fields in the os-release file.
87///
88/// For more information, see [`os-release(5)`].
89///
90/// [`os-release(5)`]: https://www.freedesktop.org/software/systemd/man/os-release.html
91///
92/// # Notes
93///
94/// If you are using this crate to determine the OS or a specific version of it, use the [`Self::id()`]
95/// and [`Self::version_id()`] methods, possibly with [`Self::id_like()`] as fallback for [`Self::id()`].
96/// When looking for an OS identification string for presentation to the user, use the [`Self::pretty_name()`] method.
97///
98/// Note that operating system vendors may choose not to provide version information, for example to accommodate for rolling releases.
99/// In this case, [`Self::version()`] and [`Self::version_id()`] may be `None`.
100/// Application should not rely on these fields to be set.
101///
102/// # Examples
103///
104/// Open the os-release file and print the OS name and version:
105///
106/// ```rust,no_run
107/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
108/// use etc_os_release::OsRelease;
109///
110/// let os_release = OsRelease::open()?;
111/// println!("{}-{}", os_release.id(), os_release.version_id().unwrap_or_default());
112/// # Ok(())
113/// # }
114/// ```
115///
116/// Parse a string containing the contents of the os-release file:
117///
118/// ```rust
119/// use std::str::FromStr;
120///
121/// use etc_os_release::OsRelease;
122///
123/// let os_release = OsRelease::from_str(r#"
124/// NAME=Fedora
125/// VERSION="32 (Workstation Edition)"
126/// ID=fedora
127/// VERSION_ID=32
128/// PRETTY_NAME="Fedora 32 (Workstation Edition)"
129/// ANSI_COLOR="0;38;2;60;110;180"
130/// LOGO=fedora-logo-icon
131/// CPE_NAME="cpe:/o:fedoraproject:fedora:32"
132/// HOME_URL="https://fedoraproject.org/"
133/// DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
134/// SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
135/// BUG_REPORT_URL="https://bugzilla.redhat.com/"
136/// REDHAT_BUGZILLA_PRODUCT="Fedora"
137/// REDHAT_BUGZILLA_PRODUCT_VERSION=32
138/// REDHAT_SUPPORT_PRODUCT="Fedora"
139/// REDHAT_SUPPORT_PRODUCT_VERSION=32
140/// PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
141/// VARIANT="Workstation Edition"
142/// VARIANT_ID=workstation
143/// "#).unwrap();
144///
145/// assert_eq!(os_release.id(), "fedora");
146/// assert_eq!(os_release.version_id(), Some("32"));
147/// ```
148#[derive(Debug, Clone)]
149pub struct OsRelease {
150    // Use `IndexMap` for reserving insertion order.
151    fields: IndexMap<String, String>,
152}
etc_os_release/lib.rs

etc_os_release/
lib.rs
