feat: add semver_matches utility function

Cargo.toml

@@ -33,6 +33,7 @@ libc = "0.2.0"
 log = "0.4.4"
 num_cpus = "1.15.0"
 regex = "1.5.4"
+semver = "1.0.20"
 serde = { version = "1.0.130", features = ["derive", "rc"] }
 serde_json = "1.0.68"
 sha2 = "0.10"

README.md

@@ -1241,6 +1241,10 @@ These functions can fail, for example if a path does not have an extension, whic
 - `sha256_file(path)` - Return the SHA-256 hash of the file at `path` as a hexadecimal string.
 - `uuid()` - Return a randomly generated UUID.
 
+#### Semantic Versions
+
+- `semver_matches(version, requirement)`<sup>master</sup> - Check whether a [semantic `version`](https://semver.org), e.g., `"0.1.0"` matches a `requirement`, e.g., `">=0.1.0"`, returning `"true"` if so and `"false"` otherwise.
+
 ### Recipe Attributes
 
 Recipes may be annotated with attributes that change their behavior.

src/function.rs

@@ -4,6 +4,7 @@ use {
     ToKebabCase, ToLowerCamelCase, ToShoutyKebabCase, ToShoutySnakeCase, ToSnakeCase, ToTitleCase,
     ToUpperCamelCase,
   },
+  semver::{Version, VersionReq},
   Function::*,
 };
 
@@ -46,6 +47,7 @@ pub(crate) fn get(name: &str) -> Option<Function> {
     "quote" => Unary(quote),
     "replace" => Ternary(replace),
     "replace_regex" => Ternary(replace_regex),
+    "semver_matches" => Binary(semver_matches),
     "sha256" => Unary(sha256),
     "sha256_file" => Unary(sha256_file),
     "shoutykebabcase" => Unary(shoutykebabcase),
@@ -411,3 +413,23 @@ fn without_extension(_context: &FunctionContext, path: &str) -> Result<String, S
 
   Ok(parent.join(file_stem).to_string())
 }
+
+/// Check whether a string processes properly as semver (e.x. "0.1.0")
+/// and matches a given semver requirement (e.x. ">=0.1.0")
+fn semver_matches(
+  _context: &FunctionContext,
+  version: &str,
+  requirement: &str,
+) -> Result<String, String> {
+  Ok(
+    requirement
+      .parse::<VersionReq>()
+      .map_err(|err| format!("invalid semver requirement: {err}"))?
+      .matches(
+        &version
+          .parse::<Version>()
+          .map_err(|err| format!("invalid semver version: {err}"))?,
+      )
+      .to_string(),
+  )
+}

tests/functions.rs

@@ -412,6 +412,21 @@ test! {
     stderr: "echo Bar\n",
 }
 
+#[test]
+fn semver_matches() {
+  Test::new()
+    .justfile(
+      "
+      foo:
+        echo {{ semver_matches('0.1.0', '>=0.1.0') }}
+        echo {{ semver_matches('0.1.0', '=0.0.1') }}
+    ",
+    )
+    .stdout("true\nfalse\n")
+    .stderr("echo true\necho false\n")
+    .run();
+}
+
 fn assert_eval_eq(expression: &str, result: &str) {
   Test::new()
     .justfile(format!("x := {expression}"))

tests/test.rs

@@ -39,6 +39,7 @@ pub(crate) struct Output {
   pub(crate) tempdir: TempDir,
 }
 
+#[must_use]
 pub(crate) struct Test {
   pub(crate) args: Vec<String>,
   pub(crate) current_dir: PathBuf,