function files=cosmo_dir(varargin)
% list files recursively in a directory
%
% files=cosmo_dir([directory][,file_pattern])
%
% Inputs:
% directory optional parent directory to look for files. If omitted
% the current directory is used.
% file_pattern optional pattern to match file names. The wildcards '*'
% (zero or more of any character) and '?' (any single
% character) can be used. If omitted, '*' is used, meaning
% that all files are listed. A file pattern may be
% prefixed by a directory.
% Output:
% files Px1 struct (if P files were found in the directory or
% recursively in any (sub^X)-directorie) with fields
% .name, .date, .bytes, .isdir, .datenum. Unlike the
% built-in 'dir' function, .name contains the path and
% filename.
%
% Notes:
% - the output is similar to built-in 'dir', except that .name contains
% the path of the files as well.
% - to list files in a directory but not those in its subdirectories, use
% the built-in 'dir' function.
% - this function does not return '.' (current directory) or '..' (parent
% directory.
%
% Examples:
% % list recursively all files in the current directory
% d=cosmo_dir();
%
% % Assuming that the directory 'my_dir' exists, list recursively all
% % files the directory contains
% d=cosmo_dir('my_dir');
%
% % Assuming that the directory 'my_file' does not exist, return
% % either a struct with a single entry (if a file named 'my_file'
% % exists), or an emtpy struct (if no such file exists)
% d=cosmo_dir('my_file');%
%
% % list recursively all files in the current directory for which the name
% % ends with '.jpg'
% d=cosmo_dir('*.jpg')
%
% % list recursively all files in the directory 'my_dir' with extension
% % '.jpg'
% d=cosmo_dir('my_dir', '*.jpg')
%
% % as above but with a single argument; list recursively all files in
% % the directory 'my_dir' with extension '.jpg'
% d=cosmo_dir('my_dir/*.jpg')
%
% % list recursively all files in my_dir that are two characters long,
% % followed by the extension '.jpg'
% d=cosmo_dir('my_dir', '??.jpg')
%
% % list recursively all files in my_dir that start with 'a', followed by
% % any character, followed by 'b', followed by any number of characters,
% % followed by '.jpg'
% d=cosmo_dir('my_dir', 'a?b*.jpg')
%
% See also: dir
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
