Working with Files, Console Output, URLs, and Data

A single United I/O Pattern

Working with text files, console output, and URL data is handled through the same simple text-based I/O model.

This tutorial walks you through the full lifecycle of a file: creating it, writing to it, and reading it back. Along the way, it also highlights Sheerpower's efficient text I/O features.

1. The File Handle: Your Connection to a File

Before you can work with a file, you must first open it. The OPEN statement establishes a connection and gives you a file handle—a nickname you will use to refer to that file.

Output to a File

The print statement outputs data to any open file that permits writing.

2. File Access Modes

When you open a file, you must tell Sheerpower how you want to use it. This is called the access mode.

• output: Creates a new, empty file for writing. If the file already exists, it will be overwritten.
• input: Opens an existing file for reading only. This is the default open mode.
• update: Opens an existing file for both reading and writing.
• shared: Opens the file so multiple processes can access it at the same time. Writes are automatically flushed to disk quickly enough for other readers to see new data almost immediately, but not so frequently that they create an I/O bottleneck. This makes shared ideal for log files that are being watched as a program runs.

ACCESS OUTPUT Creates Missing Directories

When a file is opened with access output, Sheerpower automatically creates any missing directories in the output path. This means you do not need to manually create the directory tree before writing the file.

For example:

If the logs, errors, or today directories do not already exist, Sheerpower creates them automatically before opening the output file.

3. The Lifecycle of a File: A Practical Example

Let's walk through the full process of creating a simple settings file.

Step 1: Write to the File

We'll OPEN a new file for output and use PRINT # to write lines of text into it.

Writing to Multiple Files at Once

Sheerpower simplifies a common task: writing the exact same information to multiple places simultaneously. Instead of writing separate PRINT statements for each destination, you can list all the file handles in a single, efficient command.

Practical Example: Logging to the Console and a File

A frequent use case is logging an event to both the user's screen (the console) and a permanent log file. Sheerpower makes this trivial.

When you run this code, the message INFO: System backup completed successfully. will appear on your screen and will be added to the end of the activity.log file.

Outputting to Text Windows

Sometimes a program needs to display information in a separate pop-up window — for example, a running event log, diagnostic trace, or real-time message stream. In Sheerpower, you can do this easily by opening a textwindow instead of a disk file.

A textwindow behaves like any other output channel, except that its contents appear in a new on-screen text window. This makes it useful for rare or important messages that you want to keep visible while the program continues running.

To create one, use the OPEN statement with a name beginning with "textwindow://". The text immediately following textwindow:// becomes the window title. Optional parameters, such as the window width, may be added after a ?.

Example: Creating a Simple Event Log Text Window

// Opens a text window titled "My EventLog" with a width of 120 columns
open file event_ch:
  name "textwindow://My EventLog?width=120",
  access output

print #event_ch: "I just opened the event logging text window"
print #event_ch: "Logging continues as the program runs..."

Once opened, the text window stays active until closed by the program or by the user. You can write to it just like any other file handle — using PRINT #.

Step 2: Closing Files

After completing your work with a file, it's good practice to close it explicitly using the CLOSE statement. This ensures that all data written to the file is properly saved to disk and that system resources are released immediately.

Although Sheerpower automatically closes any open files when the program ends, closing them manually is more professional — especially for longer-running programs, web services, or applications that open multiple files over time. It prevents file locks, buffering delays, and potential conflicts with other processes trying to access the same files.

You can close one or more file handles at once by listing them after CLOSE, separated by commas. You can also use CLOSE ALL to close every open file in one command.

Example: Closing one or more files

Deleting Files with KILL

Sheerpower provides the KILL statement for deleting files. The basic form deletes the specified file:

If the file does not exist, the normal KILL statement raises an exception. This is useful when the missing file should be treated as a meaningful error.

When deleting a file that may or may not exist, use KILL CONDITIONAL:. This form attempts to delete the file, but does not raise an exception if the file is not found.

Step 3: Read from the File

Now we can reopen the file for `input` to read the data back. We use a DO/LOOP and the line input statement to read the file one line at a time until we reach the end.

4. Smart File Paths and High Performance

Logical Names: Centralized Path Management

When your project spans multiple directories, Sheerpower provides a simple way to keep paths organized: logical names. These are aliases that map to full directory paths, keeping your file operations clean and making path changes trivial.

Setting Up a Logical — They Survive Reboots

Using the Logical

5. Playing It Safe: Handling Errors

What happens if you try to open a file for input that does not exist? By default, the program stops with an error. To prevent this, you can wrap the operation in a WHEN EXCEPTION IN block to catch the error and handle it gracefully.

Sheerpower includes a comprehensive error handling facility. For a detailed discussion, see Exception Handling.

6. Files and URLs: One Unified Concept

Unlike languages that require a separate library for HTTP access, Sheerpower lets you open URLs using the same file commands you use for local text files. This unified design means a program can read from a web resource just as easily as it reads from a file on disk.

Why It Matters

By treating URLs as standard text files, Sheerpower removes the need for specialized HTTP or REST libraries. File and network I/O share the same syntax and behavior, simplifying code, reducing dependencies, and making it easier to build programs that blend local and web-based data seamlessly.

7. Using the data:// In-Memory File Feature

Sheerpower supports in-memory file channels using the data:// scheme. These behave like ordinary files but store their data entirely in memory. This makes them ideal for temporary output, formatted data generation, or CGI responses that don't require disk access.

Explanation

• open file data_ch: name 'data://'
  Creates a memory-only file channel.
• print #data_ch:
  Writes data to the virtual file, just like a disk file.
• ask #data_ch: data mydata$
  Reads all data currently stored in the memory file into the string mydata$.
• close #data_ch
  Closes the virtual file and releases its memory.

Clearing In-Memory Data

To reset the contents of a data:// channel without closing and reopening it, use the SET statement:

This clears all accumulated data in the memory buffer, making the virtual file empty again and ready for reuse.