The DIR_LOOP_START command begins a loop of commands over all of the folders within a directory (and optionally its subdirectories) that match one or more filename masks. This is a powerful feature allowing you to do things like easily batch convert a collection of files or perform any other supported operation over a collection of files. You end a loop over the files in a folder using the DIR_LOOP_END command. Note that it is also possible to nest loops.
Built-in Variables
For any commands found within a DIR_LOOP_START...DIR_LOOP_END pair defining a loop, the following special character sequences can be used anywhere (examples of what the values will be based on a current filename of 'C:\path\to\my\data\my_file.dem' are listed):
- %DIR% - full path to current file (value is 'C:\path\to\my\data\')
- %FNAME_W_DIR% - full path and filename of current file (value is 'C:\path\to\my\data\my_file.dem')
- %FNAME% - filename of current file (value is 'my_file.dem')
- %FNAME_WO_EXT% - filename of current file without extension (value is 'my_file')
- %PARENT_DIR% - name of parent directory of file (value is 'data')
- %PARENT_DIRN% - name of some level of parent directory, where 'N' is level. For example, %PARENT_DIR1% value is 'my' and %PARENT_DIR2% is 'to'.
- %RECURSE_FOLDER% - folder recursed into beyond original search folder. So if current filename was 'C:\path\to\my\data\sub\folder\my_file.dem' the value of this would be 'sub\folder\'. Use this to rebuild a directory structure elsewhere when recursing.
For a sample of the DIR_LOOP_START command in use, see the example at the bottom of this reference.
The following parameters are used by the DIR_LOOP_START command.
- DIRECTORY - specifies the directory to search for files in. If you leave this blank, the operation will be based in the current folder.
- FILENAME_MASKS - space-separated list of filename masks to match on. If no value is provided then all files will be used. If you provide ".." as the mask, you will enter the loop once for each folder that is matched, allowing you to perform one operation per folder on an enter directory tree. In addition to individual masks the following special values are also supported:
- COMMON_ALL - a filter with all Commonly Supported Formats
- COMMON_ELEV - a filter with all Commonly Supported Elevation Grid Formats
- COMMON_RASTER - a filter with all Commonly Supported Raster Formats
- COMMON_VECTOR - a filter with all Commonly Supported Vector Formats
- FILENAME_MASKS_EXCLUDE - space-separated list of filename masks to exclude from matching. Any files that match the FILENAME_MASKS but also match a FILENAME_MASKS_EXCLUDE mask will not be looped over.
- RECURSE_DIR - specifies whether the loop operation will search subdirectories of the specified directory as well as the current one. Use RECURSE_DIR=YES to enable. The default value is to NOT search subdirectories.
- LIST_FILENAME - specifies an explicit list of files to iterate over in order. The value can either refer to a previously defined inline DEFINE_TEXT_FILE or a text file on disk. Each line should contain the filename to load.
- INDEX_VAR - specifies the name of a variable to initialize with the current loop index. For example, specify INDEX_VAR="FILE_IDX", then you can use %FILE_IDX% inside the loop. It will have values starting at 0 and incrementing by 1.
DIR_LOOP_END
The DIR_LOOP_END command ends a loop of commands over all of the folders within a directory. See the DIR_LOOP_START command for details.