Read-Below function

1. What does it do?

It finds all the files and subdirectories below a specified directory. By default, it returns these files and subdirectories as a block. It is worth trying with FTP too.

2. Why is it useful?

2.1 Directory comparisons

It returns relative paths to the files and directories - relative to the path specified. This allows comparisons between two similar directories using REBOL's built-in Exclude and Intersect functions. Example:

    sources: read-below %sources/
    targets: read-below %local-site/
    new-files: exclude sources targets

Going further, we might want to pre-create directories found in one directory tree and not the other. For this define a helper function:

    remove-files: func [
        {Strips block of files (missing trailing slash).}
        block [block!]
    ][remove-each file block [#"/" <> last file]]

Then using the code above - it is easy:

    repeat new-dir remove-files copy new-files [
        make-dir join %local-site/ new-dir
    ]

Note that REBOL's Make-dir function has a /deep refinement. However, sometimes it is useful to create each level directly.

2.2 Control functionality

Read-below has a /Foreach refinement that will evaluate a block you specify for each file or directory as it is processed. This allows more custom incremental processing. This would be useful when FTP is slow for example.

For example:

    ftp-site: ftp://user:pass@somwhere.com/
    read-below/foreach ftp-site filename [
        ?? filename
    ]

Note that Read-below will not return a block of files when using the /Foreach refinement - your evaluation code should collect them as needed. Instead, when /Foreach is used, Read-below will normally return True. Alternatively the value specified by any Break/return will be returned.

   read-below/foreach %sources/ file [
       ...
       if current-depth > 3 [break/return result]
       ...
   ]

3. The slash ("/")

The convention used by the Read-below function is that any filename with a trailing slash is considered to be a directory. Doing this avoids the extra disk accesses or network requests peformed by REBOL's dir? function.

Read-below will throw an error if the initial file path is missing a trailing slash.

4. Notes

Some versions of REBOL contain a FTP scheme definition which does not always work. Check with the REBOL mailing list if you are having problems with FTP as there is now updated schemes to try.

5. About the script author

Brett Handley started programming REBOL early 2000 and maintains a site of REBOL information and scripts at:

http://www.codeconscious.com/rebol/