1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
shellexpand, a library for shell-like expansion in strings
==========================================================
[![Build Status][actions]](https://gitlab.com/ijackson/rust-shellexpand/-/pipelines)
[![crates.io][crates]](https://crates.io/crates/shellexpand)
[![docs][docs]](https://docs.rs/shellexpand)
[actions]: https://img.shields.io/gitlab/pipeline-status/ijackson/rust-shellexpand?branch=main&style=flat-square
[crates]: https://img.shields.io/crates/v/shellexpand.svg?style=flat-square
[docs]: https://img.shields.io/badge/docs-latest%20release-6495ed.svg?style=flat-square
[Documentation](https://docs.rs/shellexpand/)
shellexpand is a single dependency library which allows one to perform shell-like expansions in strings,
that is, to expand variables like `$A` or `${B}` into their values inside some context and to expand
`~` in the beginning of a string into the home directory (again, inside some context).
This crate provides generic functions which accept arbitrary contexts as well as default, system-based
functions which perform expansions using the system-wide context (represented by functions from `std::env`
module and [dirs](https://crates.io/crates/dirs) crate).
---
### Alternatives to this crate:
* [`expanduser`](https://docs.rs/expanduser/latest/expanduser/):
Tilde substitution only.
Supports `~user` which this crate currently does not
(although we hope to).
* [`envsubst`](https://docs.rs/envsubst/latest/envsubst/):
Does not do offer tildeexpansion.
Only supports certain concrete types
(eg `HashMap` for variable map).
* [`expand_str`](https://crates.io/crates/expand_str):
Uses `%..%` syntax.
Does not offer tilde expansion.
Variable lookups can only be infallible.
* [`tilde_expand`](https://crates.io/crates/tilde-expand):
Only does tilde expansion, on bytes (`[u8]`).
## Usage
Just add a dependency in your `Cargo.toml`:
```toml
[dependencies]
shellexpand = "3.0"
```
See the crate documentation (a link is present in the beginning of this readme) for more information
and examples.
### Cargo features
Functional features:
* `tilde` (on by default): support for tilde expansion (home directory).
* `path` (in `full`): support for operations on `Path`s. (MSRV: 1.51)
Metafeatures:
* `full`: all reasonable (non-experimental, non-hazardous) functionality.
(Currently equivalent to `full-msrv-1.51`.)
* `base-0` (on by default): basic functionality.
You must enable this feature.
* `full-msrv-1.51`: all reasonable functionality compatible with Rust 1.51.
(currently: `base-0`, `tilde`, `paths`).
* `full-msrv-1.31`: all reasonable functionality compatible with Rust 1.31.
(currently: `base-0`, `tilde`).
At the time of writing there is no experimental or hazardous functionality;
if we introduce any it will be feature gated and not enabled by default nor part of `full*`.
Requiring `base-0` allows us to split existing functionality into a new optional feature,
without a semver break.
We will try to avoid MSRV increases for existing functionality;
increasing the MSRV for `full` will be minor version bump.
## Changelog
### Version 3.1.0 - 2023-03-24
Added:
* cargo features `full-msrv-1.31` and `full-msrv-1.51`
Fixed:
* Explicitly declared MSRV 1.51 for `paths` feature.
* Fixed build (without `paths` feature) with MSRV (1.31)
Improved:
* MSRV tested.
* Update to `dirs` 5. (Allow use of dirs 4 too, since it's fine.)
* Update `Cargo.lock.exaple`
### Version 3.0.0 - 2022-12-01
Breaking changes:
* `tilde_with_context` and `full_with_context` now expect home directories as `str`, not `Path`.
If you want to deal in Path, use the `path` feature and module.
* You must select at least one cargo feature.
The `base-0` feature is equivalent to the features available in shellexpand 2.x.
Significant changes:
* Use Rust 2018, bumping MSRV to 1.31.0.
* New `path` module, and corresponding cargo feature.
### Version 2.1.2
Minor changes:
* "Un-forked": now released as `shellexpand` on crates.io.
* List alternatives to this crate.
* Switch back to dirs from dirs-next.
* Improve linking in docs and fix broken links and badges.
* Apply some proposals from `cargo fix`.
### Version 2.1.1
* Fix tilde expanding on Windows with Windows style (backslash) paths.
Addresses <https://github.com/netvl/shellexpand/pull/13>.
* Forked as `shellexpand-fork` on crates.io.
### Version 2.1.0
* Switched to `dirs-next` instead of the obsolete `dirs` as the underlying dependency used to resolve the home directory
* Switched to GitHub Actions instead of Travis CI for building the project.
### Version 2.0.0
* Added support for default values in variable expansion (i.e. `${ANSWER:-42}`)
* Breaking changes (minimum Rust version is now 1.30.0):
+ Using `dyn` for trait objects to fix deprecation warning
+ Switched to using `source()` instead of `cause()` in the `Error` implementation, and
therefore added a `'static` bound for the generic error parameter `E`
### Version 1.1.1
* Bump `dirs` dependency to 2.0.
### Version 1.1.0
* Changed use of deprecated `std::env::home_dir` to the [dirs](https://crates.io/crates/dirs)::home_dir function
### Version 1.0.0
* Fixed typos and minor incompletenesses in the documentation
* Changed `home_dir` argument type for tilde expansion functions to `FnOnce` instead `FnMut`
* Changed `LookupError::name` field name to `var_name`
### Version 0.1.0
* Initial release
## License
This program is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed
as above, without any additional terms or conditions.
|
