# OVERVIEW ====================================================================
# AUTHOR: Brad West
# CREATED ON: 2018-06-19
# ---
# DESCRIPTION: Script for defining a function for generating a default header.
#   The motivation is to create a consistent header that can be used to
#   scripts within a project or package. Easy access to the script's purpose,
#   author, and its date of creation. Also can be used for creating a skeleton
#   template.
# ---

# FUNCTIONS ===================================================================

#' R Script Header
#'
#' Generate a formatted header for R scripts with a description, author, and
#' date fields. Can specify the appropriate line width and pass additional
#' fields which will server to break the script into sections. Motivation is
#' to create a reproducible header for consistently documenting scripts within
#' a project or package.
#'
#' @param description character vector length 1; A verbose description of the
#'   script
#' @param auth character vector length 1; author
#' @param date character vector length 1 or coercible to; the created date for
#'   the script, defaults to current date
#' @param width numeric vector length 1; line width in characters
#' @param sections character vector length n; additional sections to add to the
#'   script
#'
#' @return A vector of the lines of the header, invisibly
#'
#' @examples
#' header("A very simple script", sections = c("IMPORT", "VARS" "FUNCTIONS", "ANALYSIS"))
header <- function(description = "",
                   auth = "Brad West",
                   date = Sys.Date(),
                   width = 80,
                   sections = NULL) {

  # split description on spaces
  s <- function(x, n) {

    sst <- strsplit(x, '(?=\\s)', perl = T)[[1]]
    chars <- nchar(sst)
    rows <- c()
    row <- c()
    total <- 0

    for (i in 1:length(chars)) {
      if (total + chars[i] < n) {
        row <- paste0(row, sst[i])
        total <- total + chars[i]
      } else {
        rows <- c(rows, row)
        total <- 0
        row <- c()
      }
    }

    rows <- c(rows, row)

    trimws(rows)

  }

  overview <- "# OVERVIEW "
  spaces <- stringr::str_locate_all(description, "\\s")[[1]][, 1]
  spaces_idx <- which(spaces < (width - nchar("# DESCRIPTION: ") + 1))
  last_space <- max(spaces[spaces_idx])

  descrip <- c(paste0("# DESCRIPTION: ", substring(description, 1, last_space)))

  rest_of_string <- substring(description, last_space + 1)
  indent <- "#   "
  remaining_width <- width - nchar(indent)
  string_split <- s(rest_of_string, remaining_width)

  descrip <- c(descrip, paste0(indent, string_split))

  more_sections <- vapply(sections, function(x) {
    c(paste0("# ", x, " ",
             paste0(rep("=", width - nchar(x) - 4), collapse = "")),
      "", "")
  }, FUN.VALUE = character(3), USE.NAMES = F)

  # build header
  out <- c(
    paste0(overview, paste0(rep("=", width - 1 - nchar(overview)), collapse = "")),
    paste0("# AUTHOR: ", auth),
    paste0("# CREATED ON: ", date),
    "# ---",
    descrip,
    "# ---",
    "",
    more_sections
  )

  cat(out, sep = "\n")

  invisible(out)

}