devela/sys/env/
namespace.rs

Help
1// devela::sys::env::env
2//
3//! Defines the [`Env`] struct namespace.
4//
5// TOC
6// - Constants
7// - Command line arguments
8// - Environment variables
9// - Paths
10
11#[cfg(all(feature = "std", feature = "unsafe_thread"))]
12use crate::_dep::_std::env::{remove_var, set_var};
13#[allow(deprecated, reason = "WAIT for official undeprecation of home_dir")]
14#[cfg(feature = "std")]
15use crate::{
16    _dep::_std::env::{
17        args, args_os, current_dir, current_exe, home_dir, join_paths, set_current_dir,
18        split_paths, temp_dir, var, var_os, vars, vars_os,
19    },
20    IoResult, IterArgs, IterArgsOs, IterSplitPaths, IterVars, IterVarsOs, JoinPathsError, OsStr,
21    OsString, Path, PathBuf, VarError,
22};
23
24#[doc = crate::TAG_NAMESPACE!()]
25/// A namespaced wrapper for `std::env` functions and constants.
26pub struct Env;
27
28/// # Constants
29/*
30NOTE: The lists of expected values for not(std) configuration flags can be copied from:
31<https://github.com/rust-lang/rust/blob/master/tests/ui/check-cfg/well-known-values.stderr>.
32Afterwards they can be procesed with vim commands similar to:
33s/`//g
34s/, /\r/g
35s/\([a-z0-9_.]\+\)/#[cfg(target_arch = "\1")]\r{ "\1" }/
36s/\([a-z0-9_.]\+\)/target_arch = "\1",/
37*/
38impl Env {
39    #[doc = crate::TAG_MAYBE_STD!()]
40    /// A string describing the architecture of the CPU that is currently in use.
41    ///
42    /// Expected values are:
43    /// `aarch64`, `arm`, `arm64ec`, `avr`, `bpf`, `csky`, `hexagon`, `loongarch64`, `m68k`, `mips`, `mips32r6`, `mips64`, `mips64r6`, `msp430`, `nvptx64`, `powerpc`, `powerpc64`, `riscv32`, `riscv64`, `s390x`, `sparc`, `sparc64`, `unknown`, `wasm32`, `wasm64`, `x86`, `x86_64`, and `xtensa`.
44    #[rustfmt::skip]
45    pub const ARCH: &'static str = {
46        #[cfg(feature = "std")]
47        { ::std::env::consts::ARCH }
48        #[cfg(not(feature = "std"))]
49        { // 28 arches:
50            #[cfg(target_arch = "aarch64")]
51            { "aarch64" }
52            #[cfg(target_arch = "amdgpu")]
53            { "amdgpu" }
54            #[cfg(target_arch = "arm")]
55            { "arm" }
56            #[cfg(target_arch = "arm64ec")]
57            { "arm64ec" }
58            #[cfg(target_arch = "avr")]
59            { "avr" }
60            #[cfg(target_arch = "bpf")]
61            { "bpf" }
62            #[cfg(target_arch = "csky")]
63            { "csky" }
64            #[cfg(target_arch = "hexagon")]
65            { "hexagon" }
66            #[cfg(target_arch = "loongarch64")]
67            { "loongarch64" }
68            #[cfg(target_arch = "m68k")]
69            { "m68k" }
70            #[cfg(target_arch = "mips")]
71            { "mips" }
72            #[cfg(target_arch = "mips32r6")]
73            { "mips32r6" }
74            #[cfg(target_arch = "mips64")]
75            { "mips64" }
76            #[cfg(target_arch = "mips64r6")]
77            { "mips64r6" }
78            #[cfg(target_arch = "msp430")]
79            { "msp430" }
80            #[cfg(target_arch = "nvptx64")]
81            { "nvptx64" }
82            #[cfg(target_arch = "powerpc")]
83            { "powerpc" }
84            #[cfg(target_arch = "powerpc64")]
85            { "powerpc64" }
86            #[cfg(target_arch = "riscv32")]
87            { "riscv32" }
88            #[cfg(target_arch = "riscv64")]
89            { "riscv64" }
90            #[cfg(target_arch = "s390x")]
91            { "s390x" }
92            #[cfg(target_arch = "sparc")]
93            { "sparc" }
94            #[cfg(target_arch = "sparc64")]
95            { "sparc64" }
96            #[cfg(target_arch = "wasm32")]
97            { "wasm32" }
98            #[cfg(target_arch = "wasm64")]
99            { "wasm64" }
100            #[cfg(target_arch = "x86")]
101            { "x86" }
102            #[cfg(target_arch = "x86_64")]
103            { "x86_64" }
104            #[cfg(target_arch = "xtensa")]
105            { "xtensa" }
106            #[cfg(not(any(
107                target_arch = "aarch64",
108                target_arch = "amdgpu",
109                target_arch = "arm",
110                target_arch = "arm64ec",
111                target_arch = "avr",
112                target_arch = "bpf",
113                target_arch = "csky",
114                target_arch = "hexagon",
115                target_arch = "loongarch64",
116                target_arch = "m68k",
117                target_arch = "mips",
118                target_arch = "mips32r6",
119                target_arch = "mips64",
120                target_arch = "mips64r6",
121                target_arch = "msp430",
122                target_arch = "nvptx64",
123                target_arch = "powerpc",
124                target_arch = "powerpc64",
125                target_arch = "riscv32",
126                target_arch = "riscv64",
127                target_arch = "s390x",
128                target_arch = "sparc",
129                target_arch = "sparc64",
130                target_arch = "wasm32",
131                target_arch = "wasm64",
132                target_arch = "x86",
133                target_arch = "x86_64",
134                target_arch = "xtensa",
135            )))]
136            { "unknown" }
137        }
138    };
139
140    #[doc = crate::TAG_MAYBE_STD!()]
141    /// The family of the operating system.
142    ///
143    /// The expected values are: `unix`, `unknown`, `wasm` and `windows`.
144    #[rustfmt::skip]
145    pub const FAMILY: &'static str = {
146        #[cfg(feature = "std")]
147        { ::std::env::consts::FAMILY }
148        #[cfg(not(feature = "std"))]
149        {
150            #[cfg(target_family = "unix")]
151            { "unix" }
152            #[cfg(target_family = "wasm")]
153            { "wasm" }
154            #[cfg(target_family = "windows")]
155            { "windows" }
156            #[cfg(not(any(
157                target_family = "unix",
158                target_family = "wasm",
159                target_family = "windows",
160            )))]
161            { "unknown" }
162        }
163    };
164
165    /// A string describing the vendor of the CPU that is currently in use.
166    ///
167    /// Expected values are:
168    ///  `amd`, `apple`, `espressif`, `fortanix`, `ibm`, `kmc`, `mti`, `nintendo`, `nvidia`, `openwrt`, `pc`, `risc0`, `sony`, `sun`, `unikraft`, `unknown`, `uwp`, `win7`, and `wrs`.
169    #[rustfmt::skip]
170    pub const VENDOR: &'static str = { // 18 vendors
171        #[cfg(target_vendor = "amd")]
172        { "amd" }
173        #[cfg(target_vendor = "apple")]
174        { "apple" }
175        #[cfg(target_vendor = "espressif")]
176        { "espressif" }
177        #[cfg(target_vendor = "fortanix")]
178        { "fortanix" }
179        #[cfg(target_vendor = "ibm")]
180        { "ibm" }
181        #[cfg(target_vendor = "kmc")]
182        { "kmc" }
183        #[cfg(target_vendor = "mti")]
184        { "mti" }
185        #[cfg(target_vendor = "nintendo")]
186        { "nintendo" }
187        #[cfg(target_vendor = "nvidia")]
188        { "nvidia" }
189        #[cfg(target_vendor = "openwrt")]
190        { "openwrt" }
191        #[cfg(target_vendor = "pc")]
192        { "pc" }
193        #[cfg(target_vendor = "risc0")]
194        { "risc0" }
195        #[cfg(target_vendor = "sony")]
196        { "sony" }
197        #[cfg(target_vendor = "sun")]
198        { "sun" }
199        #[cfg(target_vendor = "unikraft")]
200        { "unikraft" }
201        #[cfg(target_vendor = "uwp")]
202        { "uwp" }
203        #[cfg(target_vendor = "win7")]
204        { "win7" }
205        #[cfg(target_vendor = "wrs")]
206        { "wrs" }
207        #[cfg(not(any(
208            target_vendor = "amd",
209            target_vendor = "apple",
210            target_vendor = "espressif",
211            target_vendor = "fortanix",
212            target_vendor = "ibm",
213            target_vendor = "kmc",
214            target_vendor = "mti",
215            target_vendor = "nintendo",
216            target_vendor = "nvidia",
217            target_vendor = "openwrt",
218            target_vendor = "pc",
219            target_vendor = "risc0",
220            target_vendor = "sony",
221            target_vendor = "sun",
222            target_vendor = "unikraft",
223            target_vendor = "uwp",
224            target_vendor = "win7",
225            target_vendor = "wrs",
226        )))]
227        { "unknown" }
228    };
229
230    #[doc = crate::TAG_MAYBE_STD!()]
231    /// A string describing the specific operating system in use.
232    ///
233    /// The expected values are:
234    /// `aix`, `android`, `cuda`, `cygwin`, `dragonfly`, `emscripten`, `espidf`, `freebsd`, `fuchsia`, `haiku`, `hermit`, `horizon`, `hurd`, `illumos`, `ios`, `l4re`, `linux`, `macos`, `netbsd`, `none`, `nto`, `nuttx`, `openbsd`, `psp`, `psx`, `redox`, `rtems`, `solaris`, `solid_asp3`, `teeos`, `trusty`, `tvos`, `uefi`, `unknown`, `visionos`, `vita`, `vxworks`, `wasi`, `watchos`, `windows`, `xous`, and `zkvm`.
235    #[rustfmt::skip]
236    pub const OS: &'static str = {
237        #[cfg(feature = "std")]
238        { ::std::env::consts::OS }
239        #[cfg(not(feature = "std"))]
240        { // 42 oses:
241            #[cfg(target_os = "aix")]
242            { "aix" }
243            #[cfg(target_os = "amdhsa")]
244            { "amdhsa" }
245            #[cfg(target_os = "android")]
246            { "android" }
247            #[cfg(target_os = "cuda")]
248            { "cuda" }
249            #[cfg(target_os = "cygwin")]
250            { "cygwin" }
251            #[cfg(target_os = "dragonfly")]
252            { "dragonfly" }
253            #[cfg(target_os = "emscripten")]
254            { "emscripten" }
255            #[cfg(target_os = "espidf")]
256            { "espidf" }
257            #[cfg(target_os = "freebsd")]
258            { "freebsd" }
259            #[cfg(target_os = "fuchsia")]
260            { "fuchsia" }
261            #[cfg(target_os = "haiku")]
262            { "haiku" }
263            #[cfg(target_os = "hermit")]
264            { "hermit" }
265            #[cfg(target_os = "horizon")]
266            { "horizon" }
267            #[cfg(target_os = "hurd")]
268            { "hurd" }
269            #[cfg(target_os = "illumos")]
270            { "illumos" }
271            #[cfg(target_os = "ios")]
272            { "ios" }
273            #[cfg(target_os = "l4re")]
274            { "l4re" }
275            #[cfg(target_os = "linux")]
276            { "linux" }
277            #[cfg(target_os = "macos")]
278            { "macos" }
279            #[cfg(target_os = "netbsd")]
280            { "netbsd" }
281            #[cfg(target_os = "none")]
282            { "none" }
283            #[cfg(target_os = "nto")]
284            { "nto" }
285            #[cfg(target_os = "nuttx")]
286            { "nuttx" }
287            #[cfg(target_os = "openbsd")]
288            { "openbsd" }
289            #[cfg(target_os = "psp")]
290            { "psp" }
291            #[cfg(target_os = "psx")]
292            { "psx" }
293            #[cfg(target_os = "redox")]
294            { "redox" }
295            #[cfg(target_os = "rtems")]
296            { "rtems" }
297            #[cfg(target_os = "solaris")]
298            { "solaris" }
299            #[cfg(target_os = "solid_asp3")]
300            { "solid_asp3" }
301            #[cfg(target_os = "teeos")]
302            { "teeos" }
303            #[cfg(target_os = "trusty")]
304            { "trusty" }
305            #[cfg(target_os = "tvos")]
306            { "tvos" }
307            #[cfg(target_os = "uefi")]
308            { "uefi" }
309            #[cfg(target_os = "visionos")]
310            { "visionos" }
311            #[cfg(target_os = "vita")]
312            { "vita" }
313            #[cfg(target_os = "vxworks")]
314            { "vxworks" }
315            #[cfg(target_os = "wasi")]
316            { "wasi" }
317            #[cfg(target_os = "watchos")]
318            { "watchos" }
319            #[cfg(target_os = "windows")]
320            { "windows" }
321            #[cfg(target_os = "xous")]
322            { "xous" }
323            #[cfg(target_os = "zkvm")]
324            { "zkvm" }
325            #[cfg(not(any(
326                target_os = "aix",
327                target_os = "amdhsa",
328                target_os = "android",
329                target_os = "cuda",
330                target_os = "cygwin",
331                target_os = "dragonfly",
332                target_os = "emscripten",
333                target_os = "espidf",
334                target_os = "freebsd",
335                target_os = "fuchsia",
336                target_os = "haiku",
337                target_os = "hermit",
338                target_os = "horizon",
339                target_os = "hurd",
340                target_os = "illumos",
341                target_os = "ios",
342                target_os = "l4re",
343                target_os = "linux",
344                target_os = "macos",
345                target_os = "netbsd",
346                target_os = "none",
347                target_os = "nto",
348                target_os = "nuttx",
349                target_os = "openbsd",
350                target_os = "psp",
351                target_os = "psx",
352                target_os = "redox",
353                target_os = "rtems",
354                target_os = "solaris",
355                target_os = "solid_asp3",
356                target_os = "teeos",
357                target_os = "trusty",
358                target_os = "tvos",
359                target_os = "uefi",
360                target_os = "visionos",
361                target_os = "vita",
362                target_os = "vxworks",
363                target_os = "wasi",
364                target_os = "watchos",
365                target_os = "windows",
366                target_os = "xous",
367                target_os = "zkvm",
368            )))]
369            { "unknown" }
370        }
371    };
372
373    /// Specifies the file extension used for shared libraries on this platform
374    /// that goes after the dot.
375    ///
376    /// Some possible values:
377    /// - `so`
378    /// - `dylib`
379    /// - `dll`
380    #[cfg(feature = "std")]
381    #[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
382    pub const DLL_EXTENSION: &'static str = ::std::env::consts::DLL_EXTENSION;
383
384    /// Specifies the filename prefix used for shared libraries on this platform.
385    ///
386    /// Some possible values:
387    /// - `lib`
388    /// - `` (an empty string)
389    #[cfg(feature = "std")]
390    #[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
391    pub const DLL_PREFIX: &'static str = ::std::env::consts::DLL_PREFIX;
392
393    /// Specifies the filename suffix used for shared libraries on this platform.
394    ///
395    /// Some possible values:
396    /// - `.so`
397    /// - `.dylib`
398    /// - `.dll`
399    #[cfg(feature = "std")]
400    #[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
401    pub const DLL_SUFFIX: &'static str = ::std::env::consts::DLL_SUFFIX;
402
403    /// Specifies the file extension, if any, used for executable binaries on this platform.
404    ///
405    /// Some possible values:
406    /// - `exe`
407    /// - `` (an empty string)
408    #[cfg(feature = "std")]
409    #[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
410    pub const EXE_EXTENSION: &'static str = ::std::env::consts::EXE_EXTENSION;
411
412    /// Specifies the filename suffix used for executable binaries on this platform.
413    ///
414    /// Some possible values:
415    /// - `.exe`
416    /// - `.nexe`
417    /// - `.pexe`
418    /// - `` (an empty string)
419    #[cfg(feature = "std")]
420    #[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
421    pub const EXE_SUFFIX: &'static str = ::std::env::consts::EXE_SUFFIX;
422}
423
424/// # Command line arguments
425#[cfg(feature = "std")]
426#[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
427impl Env {
428    /// Returns the arguments that this program was started with.
429    ///
430    /// See [args].
431    pub fn args() -> IterArgs {
432        args()
433    }
434
435    /// See [args_os].
436    pub fn args_os() -> IterArgsOs {
437        args_os()
438    }
439}
440
441/// # Environment variables
442#[cfg(feature = "std")]
443#[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
444impl Env {
445    /// Fetches the environment variable key from the current process.
446    ///
447    /// See [var].
448    pub fn var<K: AsRef<OsStr>>(key: K) -> Result<String, VarError> {
449        var(key)
450    }
451
452    /// Returns an iterator of (variable, value) pairs of strings,
453    /// for all the environment variables of the current process.
454    ///
455    /// See [vars].
456    pub fn vars() -> IterVars {
457        vars()
458    }
459
460    /// Fetches the environment variable key from the current process.
461    ///
462    /// See [var_os].
463    pub fn var_os<K: AsRef<OsStr>>(key: K) -> Option<OsString> {
464        var_os(key)
465    }
466
467    /// Returns an iterator of (variable, value) pairs of OS strings,
468    /// for all the environment variables of the current process.
469    ///
470    /// See [vars_os].
471    pub fn vars_os() -> IterVarsOs {
472        vars_os()
473    }
474
475    /// Removes the environment variable `key` from the environment
476    /// of the currently running process.
477    ///
478    /// # Safety
479    /// See [remove_var].
480    #[cfg(all(not(feature = "safe_sys"), feature = "unsafe_thread"))]
481    #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_thread")))]
482    pub unsafe fn remove_var<K: AsRef<OsStr>>(key: K) {
483        unsafe { remove_var(key) }
484    }
485
486    /// Sets the environment variable `key` to the value `value`
487    /// for the currently running process.
488    ///
489    /// # Safety
490    /// See [set_var].
491    #[cfg(all(not(feature = "safe_sys"), feature = "unsafe_thread"))]
492    #[cfg_attr(nightly_doc, doc(cfg(feature = "unsafe_thread")))]
493    pub unsafe fn set_var<K: AsRef<OsStr>, V: AsRef<OsStr>>(key: K, value: V) {
494        unsafe { set_var(key, value) }
495    }
496}
497
498/// # Paths
499#[cfg(feature = "std")]
500#[cfg_attr(nightly_doc, doc(cfg(feature = "std")))]
501impl Env {
502    /// Returns the full filesystem path of the current running executable.
503    ///
504    /// See [current_exe].
505    pub fn current_exe() -> IoResult<PathBuf> {
506        current_exe()
507    }
508
509    /// Returns the current working directory.
510    ///
511    /// See [current_dir].
512    pub fn current_dir() -> IoResult<PathBuf> {
513        current_dir()
514    }
515
516    /// Changes the current working directory to the specified path.
517    ///
518    /// See [set_current_dir].
519    pub fn set_current_dir<P: AsRef<Path>>(path: P) -> IoResult<()> {
520        set_current_dir(path)
521    }
522
523    /// Returns the path of the current user’s home directory if known.
524    ///
525    /// See [home_dir].
526    #[allow(deprecated, reason = "WAIT for official undeprecation")]
527    pub fn home_dir() -> Option<PathBuf> {
528        home_dir()
529    }
530
531    /// Returns the path of a temporary directory.
532    ///
533    /// See [temp_dir].
534    pub fn temp_dir() -> PathBuf {
535        temp_dir()
536    }
537
538    /// Joins a collection of [Path]s appropriately for the `PATH` environment variable.
539    ///
540    /// See [join_paths].
541    pub fn join_paths<I, T>(paths: I) -> Result<OsString, JoinPathsError>
542    where
543        I: IntoIterator<Item = T>,
544        T: AsRef<OsStr>,
545    {
546        join_paths(paths)
547    }
548
549    /// Parses input according to platform conventions for the `PATH` environment variable.
550    ///
551    /// See [split_paths].
552    pub fn split_paths<T: AsRef<OsStr> + ?Sized>(unparsed: &T) -> IterSplitPaths<'_> {
553        split_paths(unparsed)
554    }
555}
devela/sys/env/namespace.rs

devela/sys/env/
namespace.rs
