# -------------------------------------------------------------------------------------------------------------------------  #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #           File Name              :  fileSelfDescription.r                                                                             #
  #           Last Updated Funclist  :  19 Feb 2015, 12:52 PM (Thursday)                                                       #
  #                                                                                                                            #
  #           Author Name            :  Rick Saporta                                                                           #
  #           Author Email           :  RickSaporta@gmail.com                                                                  #
  #           Author URL             :  www.github.com/rsaporta                                                                #
  #                                                                                                                            #
  #           Packages Called        :  NA                                                                                     #
  #           Packages Used via NS   :  NA                                                                                     #
  #                                                                                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #   fileSelfDescription           ( ... )                                                                                               #
  #   getFileDescr       ( fileName )                                                                                          #
  #                                                                                                                            #
  #                                                                                                                            #
  #                                                     <END FUNCS>                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  # -------------------------------------------------------------------------------------------------------------------------  #



## fileSelfDescription() is meant to grab a description of what is inside an *.R file
##                       much like pythons '''lepsum description ... ''' 
## fileInfo() is meant to be a cleaner (and data.table) output version of file.info
fileInfo <- function(files, unexpand=TRUE) {
## gets file informaiton from system (disk) and cleans the output. Returns a DT
  ret <- file.info(files) %>% as.data.table(keep=TRUE) %>% setnames("rn", "file")
  if (unexpand)
    ret[, file := path.unexpand(file) %>% gsub("~rsaporta", "~", .)]
  return(ret)
}


fileSelfDescription <- function(..., .DESCR="Like python's  ''' for the top of a file") {
### The purpose of this function is similar to python's  `'''info info info'''`  at the top of a document
### In other words, it should be placed at the top of the document to describe the file
### So far (as of 2015-Dec), I have only used it in "Acc_vs_Anal"
### Not sure if this is the best use

  ## This will genearlly also deal with non-character inputs
  ret <- paste(unlist(list(...)), collapse="\n")
  classAppend_(ret, "fileSelfDescription")
  return(ret)
}


# removed Dec 2015 ##      ## This was an older version I had.  
# removed Dec 2015 ##      getFileDescr <- function(fileName) {
# removed Dec 2015 ##      # if you place 
# removed Dec 2015 ##        capture.output(source(fileName, local=TRUE, echo=FALSE, verbose=FALSE, print.eval=FALSE))
# removed Dec 2015 ##        if (!exists(".description"))
# removed Dec 2015 ##          return("NO DESCRIPTION AVAILABLE.\nPlease include an object   .description <- '...'  in the file.")
# removed Dec 2015 ##        return(.description)
# removed Dec 2015 ##      }

getFileDate <- function(..., DEPRECATED="Use fileDate() instead") {
  stop ("getFileDate() is deprecated.  Use fileDate()")
}

fileDate <- function(files, use=c("ctime", "atime", "mtime")) {
  use <- match.arg(use)
  DT.info <- fileInfo(files)
  if (use %in% names(DT.info))
    return(DT.info[[use]])
  ## ELSE
  warning("internal error in function getFileDate():  DT.info, which is the output of fileInfo(), did not have a column named", use)
  return(as.POSIXct(rep(NA, length(files))))
}