#' Select Persons by Identifier
#'
#' @description Select one or more persons from a named list by their unique
#'   identifiers, preserving the requested order. All identifiers must be present;
#'   any that are missing raise an error.
#'
#' @param x 'character' vector.
#'   Identifier(s) of the person(s) to select. Must be non-missing and unique, and
#'   each must match a name in `persons`.
#'
#' @param persons 'person' named list.
#'   Information about an arbitrary number of persons, as produced by
#'   [utils::person()]. Each element is named with the identifier that uniquely
#'   identifies that person.
#'
#' @return A 'person' list containing the requested subset of `persons`, in the
#'   order given by `x`.
#'
#' @author J.C. Fisher, U.S. Geological Survey, Idaho Water Science Center
#'
#' @export
#'
#' @keywords internal
#'
#' @examples
#' get_person("jfisher", persons = inlpubs::authors$person)

get_person <- function(x, persons) {
  # check arguments
  checkmate::assert_character(x, any.missing = FALSE, unique = TRUE, .var.name = "x")
  checkmate::assert_class(persons, classes = "person")

  # require that every identifier is present
  missing_id <- !(x %in% names(persons))
  if (any(missing_id)) {
    txt <- x[missing_id] |> sQuote(q = FALSE) |> paste(collapse = ", ")
    stop("Missing entry for person identifier(s): ", txt, call. = FALSE)
  }

  persons[x]
}
