# -------------------------------------------------------------------------------------------------------------------------  #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #           File Name              :  camelSplit.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                                                                                     #
  #                                                                                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #   CamelCaseSplit     ( string, flat=FALSE )                                                                                #
  #   camelSplit         ( x, alsoSplit=c(" ", "_", "-", "."), isolate=c("%"), dontUseNames.of.data.frame=FALSE )              #
  #                                                                                                                            #
  #                                                                                                                            #
  #                                                     <END FUNCS>                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  # -------------------------------------------------------------------------------------------------------------------------  #

## IMPORTANT TEST CASE:   x <-  "TheAmericanADLLeague"


### TODO:  Consider deprecating this function
CamelCaseSplit <- function(string,  flat=FALSE) { 
### OLDER FUNCTION, NOT SURE IF IT WORKS

  warning("use camelSplit() instead of CamelCaseSplit() ")

  splat <- strsplit(string, "(?<!^)(?=[A-Z])", perl=TRUE)
  
  if (flat)
    return(unlist(splat, recursive=FALSE)) 
  return(splat)

  # This does not work: 
  # http://stackoverflow.com/questions/7593969/regex-to-split-camelcase-or-titlecase-advanced
  #   strsplit(string, "(?<!(^|[A-Z]))(?=[A-Z])|(?<!^)(?=[A-Z][a-z])", fixed=TRUE)
}



camelSplit <- function(x, alsoSplit=c(" ", "_", "-", "."), isolate=c("%"), dontUseNames.of.data.frame=FALSE) {
## Splits a camelCase string into words, also splitting on any value in 'alsoSplit'
## If x has length == 1, returns a vector of length equal to the number of words found
## If x has length >  1, returns a list of vectors
## If x has length == 0, returns x
##
## isolate :: each string in isolate is considered a standalone word and will be split as such

  if (!length(alsoSplit))
    stop("alsoSplit must have length at least one")
  if (!length(x)) {
    warning ("x has no length")
    return(x)
  }
  if (!dontUseNames.of.data.frame && is.data.frame(x))
    x <- names(x)

  isolate <- setdiff(isolate, "")
  if (length(isolate)) {
    if (!is.character(isolate))
      stop ("isolate should be a character vector or NULL")
    pat.iso <- sprintf("(.)?%s(.)?", regOr(isolate, escape=TRUE))
    repl.iso  <- sprintf("\\1%s\\2%1$s\\3", alsoSplit[[1]])
    x <- gsub(pat.iso, repl.iso, x)
    x <- gsub(pat.iso, repl.iso, x)
  }

  pat.gsub  <- "([a-z])([A-Z])"
  repl.gsub <- sprintf("\\1%s\\2", alsoSplit[[1]])
  pat.split <- regOr(alsoSplit, escape=TRUE)
  ret <- lapply(
              strsplit(gsub(pat.gsub, repl.gsub, x), pat.split)
              , function(x) x[x != ""])

  if (length(x) == 1)
    return (ret[[1]])
  return(Ret)
}