refactor: change `tauri::api::open` `with` argument to an enum [TRI-022] (#19)

.changes/shell-open-with-refactor.md

@@ -0,0 +1,5 @@
+---
+"tauri": patch
+---
+
+The `tauri::api::shell::open`'s `with` argument is now an enum value instead of any string.

core/tauri/src/api/error.rs

@@ -83,6 +83,9 @@ pub enum Error {
   /// Shell error.
   #[error("shell error: {0}")]
   Shell(String),
+  /// Unknown program name.
+  #[error("unknown program name: {0}")]
+  UnknownProgramName(String),
 }
 
 #[cfg(feature = "cli")]

core/tauri/src/api/shell.rs

@@ -4,11 +4,95 @@
 
 //! Types and functions related to shell.
 
+use std::str::FromStr;
+
+/// Program to use on the [`open`] call.
+pub enum Program {
+  /// Use the `open` program.
+  Open,
+  /// Use the `start` program.
+  Start,
+  /// Use the `xdg-open` program.
+  XdgOpen,
+  /// Use the `gio` program.
+  Gio,
+  /// Use the `gnome-open` program.
+  GnomeOpen,
+  /// Use the `kde-open` program.
+  KdeOpen,
+  /// Use the `wslview` program.
+  WslView,
+  /// Use the `Firefox` program.
+  Firefox,
+  /// Use the `Google Chrome` program.
+  Chrome,
+  /// Use the `Chromium` program.
+  Chromium,
+  /// Use the `Safari` program.
+  Safari,
+}
+
+impl FromStr for Program {
+  type Err = super::Error;
+
+  fn from_str(s: &str) -> Result<Self, Self::Err> {
+    let p = match s.to_lowercase().as_str() {
+      "open" => Self::Open,
+      "start" => Self::Start,
+      "xdg-open" => Self::XdgOpen,
+      "gio" => Self::Gio,
+      "gnome-open" => Self::GnomeOpen,
+      "kde-open" => Self::KdeOpen,
+      "wslview" => Self::WslView,
+      "firefox" => Self::Firefox,
+      "chrome" | "google chrome" => Self::Chrome,
+      "chromium" => Self::Chromium,
+      "safari" => Self::Safari,
+      _ => return Err(super::Error::UnknownProgramName(s.to_string())),
+    };
+    Ok(p)
+  }
+}
+
+impl Program {
+  fn name(self) -> &'static str {
+    match self {
+      Self::Open => "open",
+      Self::Start => "start",
+      Self::XdgOpen => "xdg-open",
+      Self::Gio => "gio",
+      Self::GnomeOpen => "gnome-open",
+      Self::KdeOpen => "kde-open",
+      Self::WslView => "wslview",
+
+      #[cfg(target_os = "macos")]
+      Self::Firefox => "Firefox",
+      #[cfg(not(target_os = "macos"))]
+      Self::Firefox => "firefox",
+
+      #[cfg(target_os = "macos")]
+      Self::Chrome => "Google Chrome",
+      #[cfg(not(target_os = "macos"))]
+      Self::Chrome => "google-chrome",
+
+      #[cfg(target_os = "macos")]
+      Self::Chromium => "Chromium",
+      #[cfg(not(target_os = "macos"))]
+      Self::Chromium => "chromium",
+
+      #[cfg(target_os = "macos")]
+      Self::Safari => "Safari",
+      #[cfg(not(target_os = "macos"))]
+      Self::Safari => "safari",
+    }
+  }
+}
+
 /// Opens path or URL with program specified in `with`, or system default if `None`.
-pub fn open(path: String, with: Option<String>) -> crate::api::Result<()> {
+pub fn open(path: String, with: Option<Program>) -> crate::api::Result<()> {
   {
     let exit_status = if let Some(with) = with {
-      open::with(&path, &with)
+      open::with(&path, with.name())
     } else {
       open::that(&path)
     };

core/tauri/src/endpoints/shell.rs

@@ -158,7 +158,15 @@ impl Cmd {
       }
       Self::Open { path, with } => {
         #[cfg(shell_open)]
-        match crate::api::shell::open(path, with) {
+        match crate::api::shell::open(
+          path,
+          if let Some(w) = with {
+            use std::str::FromStr;
+            Some(crate::api::shell::Program::from_str(&w)?)
+          } else {
+            None
+          },
+        ) {
           Ok(_) => Ok(().into()),
           Err(err) => Err(crate::Error::FailedToExecuteApi(err)),
         }

tooling/api/src/shell.ts

@@ -341,6 +341,10 @@ type CommandEvent =
 /**
  * Opens a path or URL with the system's default app,
  * or the one specified with `openWith`.
+ *
+ * The `openWith` value must be one of `firefox`, `google chrome`, `chromium` `safari`,
+ * `open`, `start`, `xdg-open`, `gio`, gnome-open`, `kde-open` or `wslview`.
+ *
  * @example
  * ```typescript
  * // opens the given URL on the default browser: