From a847f7ea846de474f54d4009b38876bfeecca5d7 Mon Sep 17 00:00:00 2001
From: LTLA <infinite.monkeys.with.keyboards@gmail.com>
Date: Wed, 2 Oct 2024 13:53:23 -0700
Subject: [PATCH] Added utility to unpack a Gobbler path to its
 project/asset/version details.

---
 DESCRIPTION                      |  4 ++--
 NAMESPACE                        |  1 +
 R/unpackPath.R                   | 27 +++++++++++++++++++++++++++
 man/unpackPath.Rd                | 27 +++++++++++++++++++++++++++
 tests/testthat/test-unpackPath.R | 12 ++++++++++++
 5 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 R/unpackPath.R
 create mode 100644 man/unpackPath.Rd
 create mode 100644 tests/testthat/test-unpackPath.R

diff --git a/DESCRIPTION b/DESCRIPTION
index 717e844..1872a04 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: gobbler
-Version: 0.3.8
-Date: 2024-09-18
+Version: 0.3.9
+Date: 2024-10-02
 Title: Interface to the gobbler service
 Description:
     Friendly interface to the gobbler service.
diff --git a/NAMESPACE b/NAMESPACE
index 592b906..eeaf41d 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -25,6 +25,7 @@ export(serviceInfo)
 export(setPermissions)
 export(startGobbler)
 export(stopGobbler)
+export(unpackPath)
 export(uploadDirectory)
 export(versionPath)
 import(httr2)
diff --git a/R/unpackPath.R b/R/unpackPath.R
new file mode 100644
index 0000000..a029615
--- /dev/null
+++ b/R/unpackPath.R
@@ -0,0 +1,27 @@
+#' Unpack a path to its project-asset-version combination
+#'
+#' Unpack a Gobbler path to its combination of project, asset, version, and (optionally) path,
+#' for easier use in the various \pkg{gobbler} functions.
+#'
+#' @param path String containing a relative path within the Gobbler registry. 
+#'
+#' @return List containing \code{project}, \code{asset}, \code{version} and \code{path}.
+#' All are strings, except for \code{path}, which may be \code{NULL}.
+#'
+#' @author Aaron Lun
+#'
+#' @examples
+#' unpackPath("project/asset/version/path")
+#' unpackPath("project/asset/version")
+#'
+#' @export
+unpackPath <- function(path) {
+    components <- strsplit(path, "/")[[1]]
+    stopifnot(length(components) >= 3L)
+    if (length(components) == 3L || components[4] == "") {
+        path <- NULL
+    } else {
+        path <- paste(tail(components, -3), collapse="/")
+    }
+    list(project=components[1], asset=components[2], version=components[3], path=path)
+}
diff --git a/man/unpackPath.Rd b/man/unpackPath.Rd
new file mode 100644
index 0000000..83ad80f
--- /dev/null
+++ b/man/unpackPath.Rd
@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/unpackPath.R
+\name{unpackPath}
+\alias{unpackPath}
+\title{Unpack a path to its project-asset-version combination}
+\usage{
+unpackPath(path)
+}
+\arguments{
+\item{path}{String containing a relative path within the Gobbler registry.}
+}
+\value{
+List containing \code{project}, \code{asset}, \code{version} and \code{path}.
+All are strings, except for \code{path}, which may be \code{NULL}.
+}
+\description{
+Unpack a Gobbler path to its combination of project, asset, version, and (optionally) path,
+for easier use in the various \pkg{gobbler} functions.
+}
+\examples{
+unpackPath("project/asset/version/path")
+unpackPath("project/asset/version")
+
+}
+\author{
+Aaron Lun
+}
diff --git a/tests/testthat/test-unpackPath.R b/tests/testthat/test-unpackPath.R
new file mode 100644
index 0000000..47cc9a4
--- /dev/null
+++ b/tests/testthat/test-unpackPath.R
@@ -0,0 +1,12 @@
+# library(gobbler); library(testthat); source("test-unpackPath.R")
+
+test_that("unpackPath works as expected", {
+    out <- unpackPath("project/asset/version/path")
+    expect_identical(out, list(project="project", asset="asset", version="version", path="path"))
+
+    out <- unpackPath("project/asset/version")
+    expect_identical(out, list(project="project", asset="asset", version="version", path=NULL))
+
+    out <- unpackPath("project/asset/version/")
+    expect_identical(out, list(project="project", asset="asset", version="version", path=NULL))
+})