From 92aa8b64638f8bd7ae4e7fb0b77703709c8bc35c Mon Sep 17 00:00:00 2001
From: Rich FitzJohn <r.fitzjohn@imperial.ac.uk>
Date: Tue, 11 Jul 2023 16:48:32 +0100
Subject: [PATCH] New function for reading metadata

---
 NAMESPACE                              |  1 +
 R/outpack_metadata.R                   | 24 ++++++++++++++++++++++++
 man/outpack_metadata.Rd                | 25 +++++++++++++++++++++++++
 tests/testthat/test-outpack-metadata.R | 21 ++++++++++++++++++++-
 4 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 man/outpack_metadata.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 3f6550ec..ff4ac52b 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -31,6 +31,7 @@ export(outpack_log)
 export(outpack_log_debug)
 export(outpack_log_info)
 export(outpack_log_trace)
+export(outpack_metadata)
 export(outpack_metadata_read)
 export(outpack_packet_add_custom)
 export(outpack_packet_cancel)
diff --git a/R/outpack_metadata.R b/R/outpack_metadata.R
index 789c3b0a..ec6532e6 100644
--- a/R/outpack_metadata.R
+++ b/R/outpack_metadata.R
@@ -1,3 +1,27 @@
+##' Read metadata for a particular id. You may want to use
+##' [orderly2::outpack_search] to find an id corresponding to a
+##' particular query.
+##'
+##' @title Read outpack metadata
+##'
+##' @param id The id to fetch metadata for. An error will be thrown if
+##'   this id is not known
+##'
+##' @param The outpack root, typically the path to the root. The
+##'   default value of `NULL` looks for the root from the current
+##'   directory which is typically correct.
+##'
+##' @return A list of metadata. See the outpack schema for details
+##'   (https://github.com/mrc-ide/outpack)
+##'
+##' @export
+outpack_metadata <- function(id, root = NULL) {
+  validate_outpack_id(id)
+  root <- outpack_root_open(root, locate = TRUE)
+  root$metadata(id, full = TRUE)
+}
+
+
 ##' Low-level function for reading metadata and deserialising it. This
 ##' function can be used to directly read a metadata json file without
 ##' reference to a root which contains it. It may be useful in the
diff --git a/man/outpack_metadata.Rd b/man/outpack_metadata.Rd
new file mode 100644
index 00000000..a3713952
--- /dev/null
+++ b/man/outpack_metadata.Rd
@@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/outpack_metadata.R
+\name{outpack_metadata}
+\alias{outpack_metadata}
+\title{Read outpack metadata}
+\usage{
+outpack_metadata(id, root = NULL)
+}
+\arguments{
+\item{id}{The id to fetch metadata for. An error will be thrown if
+this id is not known}
+
+\item{The}{outpack root, typically the path to the root. The
+default value of \code{NULL} looks for the root from the current
+directory which is typically correct.}
+}
+\value{
+A list of metadata. See the outpack schema for details
+(https://github.com/mrc-ide/outpack)
+}
+\description{
+Read metadata for a particular id. You may want to use
+\link{outpack_search} to find an id corresponding to a
+particular query.
+}
diff --git a/tests/testthat/test-outpack-metadata.R b/tests/testthat/test-outpack-metadata.R
index cd6335ba..59dfa7f9 100644
--- a/tests/testthat/test-outpack-metadata.R
+++ b/tests/testthat/test-outpack-metadata.R
@@ -60,9 +60,11 @@ test_that("Validate hashes", {
 test_that("reading metadata via top-level function is same as from root", {
   root <- create_temporary_root(use_file_store = TRUE)
   id <- create_random_packet(root)
+  meta <- root$metadata(id, TRUE)
   expect_identical(
     outpack_metadata_read(file.path(root$path, ".outpack", "metadata", id)),
-    root$metadata(id, TRUE))
+    meta)
+  expect_identical(outpack_metadata(id, root), meta)
 })
 
 
@@ -71,3 +73,20 @@ test_that("Sensible error if metadata file not found", {
     outpack_metadata_read(tempfile()),
     "File does not exist: ")
 })
+
+
+test_that("Sensible error if metadata file not found", {
+  root <- create_temporary_root(use_file_store = TRUE)
+  expect_error(
+    outpack_metadata(1, root),
+    "'id' must be character")
+  expect_error(
+    outpack_metadata(letters, root),
+    "'id' must be a scalar")
+  expect_error(
+    outpack_metadata("some-id", root),
+    "Malformed id 'some-id'")
+  expect_error(
+    outpack_metadata(outpack_id(), root),
+    "id '20230711-154758-232a1b64' not found in index")
+})