FILEINFO$() and FINDFILE$() File Related Functions

FILEINFO$ Function Documentation

FILEINFO$ Function

The FILEINFO$ function parses a file specification and returns either a full file specification or specific file specification fields.

Syntax

FILEINFO$(str_expr1 [, str_expr2 [, str_expr3]])

Parameters

str_expr1 - The file specification to be parsed. If no file specification is given, the device and directory you are currently running from are returned.
str_expr2 - A list of field names, separated by commas, which are to be returned. The field names are:
- CONTENTS - File contents
- DEVICE - Drive name
- DIRECTORY - Directory name
- NAME - File name
- TYPE - Type or extension name
- LOCATION - Device and directory names
- BACKUP_DATE - Last file backup date
- CREATION_DATE - Date file was created
- EXPIRATION_DATE - File expiration date
- REVISION_DATE - Date file was last modified
- REVISION - The number of times a given file has been revised (given that the underlying OS supports this)
- SIZE - The size of the file in bytes
- ALL or "" - Full file specification
str_expr3 - The default file specification. This parameter is optional.

Examples

Basic Usage of FILEINFO$

Note: In Sheerpower, when specifying file paths, the '@' symbol at the beginning of a path refers to the directory of the currently running program. This makes it easy to reference files relative to your program's location, enhancing portability and simplifying path management.


    print fileinfo$('x.y', 'ALL') 
    print fileinfo$('', 'ALL') 
    print fileinfo$('@config.ini', 'ALL')  // Relative to program directory

    end

Output:


    c:\Sheerpower\x.y 
    c:\Sheerpower 
    (The '@' example will output the full path to config.ini in your program's directory)

Using Default File Specification


    x$ = 'Sheerpower:samples\client' 
    print fileinfo$(x$, 'ALL', '.ars') 
    end

Output:


    c:\Sheerpower\samples\client.ars

Various Field Names


    print fileinfo$('Sheerpower:samples\client', 'all', '.ars') 
    print fileinfo$('Sheerpower:samples\client', 'location') 
    print fileinfo$('Sheerpower:samples\client', 'location, name') 
    print fileinfo$('Sheerpower:samples\client.ars') 
    end

Output:


    c:\Sheerpower\samples\client.ars 
    c:\Sheerpower\samples\ 
    c:\Sheerpower\samples\client 
    c:\Sheerpower\samples\client.ars

FILEINFO$ Contents Option

The CONTENTS option of FILEINFO$ returns the entire contents of the file 'some_file.xxx' into all_of_file$. If the file cannot be found, then it returns a null string. A zero-length file will also return a null string.

FORMAT


    all_of_file$ = fileinfo$('some_file.xxx', 'contents')

Using FILEINFO$ to Retrieve File Contents


    all_of_file$ = fileinfo$('Sheerpower:Sheerpower.ini', 'contents') 
    print all_of_file$ 
    
    end

Output:


    [license] 
    LicenseKey=xxx-xxx-xxx-xxx
    Username=non-commercial 
    EmailAddress=non-commercial

Copy a File with FILEINFO$ CONTENTS


    sourcefile$ = 'source.xxx' 
    destfile$   = 'destination.xxx' 
    contents$   = fileinfo$(sourcefile$, 'contents') 
    open file dest_ch: name destfile$, access output, unformatted
    print #dest_ch: contents$ 
    close #dest_ch 
    end

FILEINFO$ CONTENTS efficiently handles files of any size. Thanks to Sheerpower's string management, repeated file operations reuse memory buffers, and identical file contents are automatically shared via String IDs - making file caching and batch processing extremely efficient.

FINDFILE$ — Locating Files by Name or Pattern

The FINDFILE$ function searches for files that match a given name or pattern and returns the full file specification of the first match found.

If no matching file exists, the function returns a null string ('').

FINDFILE$(str_expr [, int_expr])

Parameters

str_expr — The file name or search pattern. This can be a full path or a partial specification using wildcards (e.g., *.spsrc).
int_expr (optional) — The index of the match to return when multiple files are found. Defaults to 1 (the first match).
result — The complete file specification of the file found, or '' if no match exists.

Problem: Many languages require complex directory APIs or external libraries just to locate files matching a pattern.

Solution: FINDFILE$ provides a simple, built-in way to search for files using familiar wildcard patterns.

Efficiency: File lookup is handled internally by the runtime, avoiding manual directory traversal and reducing code complexity.

Takeaway: File discovery is a one-line operation in Sheerpower, making common tasks both simple and reliable.

Basic Example — Find First Matching File

print findfile$('sheerpower:\samples\*.spsrc')

Example output:

c:\sheerpower\samples\cdplayer.spsrc

Listing All Matching Files

Use the optional index parameter to iterate through all matches.

do line input 'File specification': spec$ if _exit then exit do for i = 1 to 9999 file$ = findfile$(spec$, i) if file$ = '' then exit for print file$ next i loop end

Example input:

sheerpower:samples\client.*

Example output:

c:\sheerpower\samples\client.ars c:\sheerpower\samples\client.def c:\sheerpower\samples\client.fdl c:\sheerpower\samples\client.str

Processing Files Found

You can combine FINDFILE$ with other functions such as FILEINFO$ to process each file.

// Tell the length of each file by reading its contents my_path$ = 'c:\sheerpower\*.*' for idx = 1 to 19999 my_file$ = findfile$(my_path$, idx) if my_file$ = '' then exit for contents$ = fileinfo$(my_file$, 'contents') print my_file$; ', length '; len(contents$) next idx end

Nested FINDFILE$ Calls

FINDFILE$ calls can be nested, provided the inner call uses only the file specification (no index parameter).

// Example concept (inner call returns a file name) result$ = findfile$(findfile$('c:\data\*.txt'))

Problem: File-processing pipelines often require multiple lookup steps, which can become verbose and error-prone.

Solution: Nested FINDFILE$ calls allow composing file searches directly in expressions.

Efficiency: Reduces intermediate variables and keeps file-selection logic compact and readable.

Takeaway: File discovery can be composed just like string or numeric expressions.

(Show/Hide Sheerpower FINDFILE$ Takeaways)

Hide Description

a$ b$ x y

Enter or modify the code below, and then click on RUN

Looking for the full power of Sheerpower?
Check out the Sheerpower website. Free to download. Free to use.