--[[
- @file file.lua
- API for handling file uploads and server file management.
]]

--[[
- Finds all files that match a given mask in a given directory.
- Directories and files beginning with a period are excluded; this
- prevents hidden files and directories (such as SVN working directories)
- from being scanned.
-
- @param dir
-   String, The base directory for the scan, without trailing slash.
- @param mask
-   String, The regular expression of the files to find.
- @param nomask
-   Table, files/directories to ignore.
- @param callback
-   String, The callback function to call for each match.
- @param recurse
-   Boolean, When TRUE, the directory scan will recurse the entire tree
-   starting at the provided directory.
- @param key
-   String, The key to be used for the returned table of files. Possible
-   values are "filename", for the path starting with dir,
-   "basename", for the basename of the file, and "name" for the name
-   of the file without an extension.
- @param min_depth
-   Number, Minimum depth of directories to return files from.
- @param depth
-   Current depth of recursion. This parameter is only used internally and
-   should not be passed.
- @return
-   Table, (keyed on the provided key) of objects with "path", "basename", and
-   "name" members corresponding to the matching files.
]]
function ajato_file_scan_directory(dir, mask, nomask, callback, recurse, key, min_depth, depth)
  nomask        = nomask or ajato_map_assoc({'.', '..', 'CVS', '.bzr'})
  recurse       = recurse or true
  key           = key or 'filename'
  depth         = depth or 0
  min_depth     = min_depth or 1
  local files   = {}
  local current_dir = lfs.attributes(dir)

  if hv(current_dir) and current_dir['mode'] == 'directory' then
    for file in lfs.dir(dir) do
      if not nomask[file] then
        current_dir = lfs.attributes(dir ..'/'.. file)
        if hv(current_dir) and current_dir['mode'] == 'directory' and recurse then
          files = ajato_tables_merge(files, ajato_file_scan_directory(dir ..'/'.. file,
            mask, nomask, callback, recurse, key, min_depth, depth + 1), true)
        elseif depth >= min_depth and hv(string.find(file, mask)) then
          local filename = dir ..'/'
          local name = string.gsub(file, '/(%w+)%.%w+^', '%1')
          files[key] = {}
          files[key]['path']     = filename
          files[key]['file']     = name
          if hv(callback) then
            _G[filename]()
          end
        end
      end
    end
  end

  return files
end