Popup YouTube Video
Sheerpower Logo

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

    

        


      

      
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.