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. It may also be an http:// or https:// address: see Reading a Web Address below.
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, and it never raises an exception for a file it cannot reach. A zero-length file also returns a null string, so to tell the two apart, test _integer right after the call: it is 1 when the file was read and 0 when it could not be. The SIZE and date items set _integer the same way.

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

Reading a Web Address

The file specification may be an http:// or https:// address. The page or file is fetched the same way OPEN FILE reads a URL, with the same 10-second default timeout, and comes back as one string. The SIZE item works on an address too. A page that cannot be fetched, a 404 for instance, returns a null string with _integer 0, exactly like a missing file.

page$ = fileinfo$('https://example.com/', 'contents') print 'fetched '; len(page$); ' bytes, _integer ='; _integer print 'size item: '; fileinfo$('https://example.com/', 'size') missing$ = fileinfo$('https://example.com/no-such-page', 'contents') print 'missing page: '; len(missing$); ' bytes, _integer ='; _integer

Output:

fetched 559 bytes, _integer = 1 size item: 559 missing page: 0 bytes, _integer = 0

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

When the goal is only a copy, the COPY FILE statement does it in one line, keeps the file's revision date, and streams the bytes instead of holding the whole file in memory: copy file sourcefile$ to destfile$. See Working with Files, Console Output, URLs, and Data.

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)

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

FILEINFO$ Function Documentation

FILEINFO$ Function

Syntax

Parameters

Examples

Basic Usage of FILEINFO$

Using Default File Specification

Various Field Names

FILEINFO$ Contents Option

FORMAT

Using FILEINFO$ to Retrieve File Contents

Reading a Web Address

Copy a File with FILEINFO$ CONTENTS

FINDFILE$ — Locating Files by Name or Pattern

Parameters

Basic Example — Find First Matching File

Listing All Matching Files

Processing Files Found

Nested FINDFILE$ Calls

Sheerpower FINDFILE$ Takeaways

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