This built-in predicate retrieves the next file from a specified directory. The name of the directory may contain wildcard characters like ? and *. The directory to scan is the first argument. The second argument is matched with the next file in the directory. After all files have been matched with the second argument the predicate fails. The third argument is a list for specifying search options; the possible options are:
see also: app_dir/1 base64_decode_file/2 base64_encode_file/2 compress_file/2 copy_file/2 current_dir/1 decompress_file/1 decompress_file/2 decrypt_file/3 delete_file/1 encrypt_file/3 exists_dir/1 exists_file/1 info_file/2 make_dir/1 md5_file/2 next_file/2 next_dir/2 remove_dir/1 rename_file/2 set_current_dir/1 split_fn/2 unlink_file/1 wipe_file/1
| Examples | |
| next_file('c:\\documents\\*.tdt', File, [directory, hidden]). | All the subdirectories and hidden files in the directory 'c:\documents\' are included in the set of files returned by next_file/3. If the specified directory does not contain any files, directories or hidden files or files with the extension 'tdt' then the predicate fails. |
| next_file('c:\\documents\\*.*', File, []). | The name of each file in the folder 'c:\documents\' is matched with the argument File. |
| next_file('c:\\documents\\*.*', 'c:\\documents\\mydoc.txt', [include_path]). | If the name of the first file in the folder 'c:\documents\' is 'mydoc.txt' then this predicate is exited, else it fails. Because of the option 'include_path' the complete filepath is included in the name of the file found. |
| Exceptions | |
| The first argument is an empty variable | an instantiation_error exception is thrown |
| The first argument Directory is not an atom enclosed by single or double quotes | A type_error(atom_singlequotes, Directory) exception is thrown |
| The second argument Filename is neither a variable nor an atom enclosed by single or double quotes | A type_error(atom_singlequotes, Filename) exception is thrown |
| The third argument is an empty variable | an instantiation_error exception is thrown |
| The third argument SearchOptions is not a list | A type_error(list, SearchOptions) exception is thrown |
| SearchOptions is list with an element E which is a variable | an instantiation_error exception is thrown |
| an element E of the options list is neither a variable nor a valid option | a domain_error(next_file_option, E) exception is thrown |