#
# Author:   Cristian E. Nuno
# Purpose:  Import worksheets within an Excel workbook as a list of data frames
# Date:     August 10, 2018

ImportXLSX <- function( name.of.file, na.strings = c("", "NA", "n/a", "N/A") ){

  # Input:
  #       1. name.of.file:  the file path to the desired Excel workbook
  #       2. na.strings:    a character vector of strings which are are
  #                         intended
  #
  # Output:
  #       1. A list of data.frames, all of which are named according to their
  #          worksheet name.


  # Build in checks to ensure that users
  # contain the 'openxlsx' package from the CRAN
  if( require( openxlsx ) == FALSE ){
    install.packages( pkgs = "openxlsx" )
  }

  # load necessary package
  require( openxlsx )

  # store the names of the sheets from the
  # workbook specified in name.of.fil
  sheet.data <- names( openxlsx::loadWorkbook( file = name.of.file ) )

  # store each worksheet as its own data frame
  list.df <- lapply( X = sheet.data
                     , FUN = function( i )
                       openxlsx::read.xlsx( xlsxFile = name.of.file
                                            , sheet = i
                                            , na.strings = na.strings ) )

  # name each data frame according to its worksheet name
  names( list.df ) <- sheet.data

  # return list.df to the Global Environment
  return( list.df )

} # end of ImportXLSX() function

# end of script #