Beyond File Modes: The Softanza Intent-Based Paradigm

Programming languages have universally adopted the C-style file handling paradigm, forcing developers to think in terms of technical "modes" rather than natural intentions. This article introduces Softanza's intent-based file API, which represents a return to natural, commonsense file interaction. By examining the traditional approach—using Haro as a representative example—we demonstrate how this paradigm shift transforms file programming from a technical puzzle into an intuitive, expressive activity.

The Universal Problem: Mode-Based File Handling

The Traditional Approach

// Haro's current approach - thinking in technical modes
file = fopen("data.txt", "r")      # Read mode - can't write
file = fopen("data.txt", "w")      # Write mode - can't read, truncates
file = fopen("data.txt", "a")      # Append mode - can't read from start
file = fopen("data.txt", "r+")     # Read+write - complex positioning

Haro also provides higher-level functions, but they're still mode-centric:

# Haro's convenience functions
content = read("data.txt")         # Read entire file
write("data.txt", content)         # Overwrite entire file

The Fundamental Limitations

This approach creates several problems:

1. Artificial Restrictions: Why separate reading and writing capabilities?
2. Cognitive Mismatch: Developers think in intentions, not file descriptor modes
3. Error-Prone Patterns: Easy to open in wrong mode or forget to close
4. Complex Workflows: Common tasks require multiple operations

Real-World Example: Conditional Log Entry

Consider adding a log entry only if it doesn't already exist:

# Current established approach - cumbersome and error-prone
if fexists("log.txt")
    content = read("log.txt")
    if not substr(content, "target_entry")
        file = fopen("log.txt", "a")
        fputs(file, "target_entry" + nl)
        fclose(file)
    ok
else
    write("log.txt", "target_entry" + nl)
ok

This requires: 1. Check if file exists (fexists) 2. Read entire file into memory (read) 3. Search through content (substr) 4. Open in append mode (fopen) 5. Write the entry (fputs) 6. Close the file (fclose)

The Softanza Paradigm: Intent-Based File Interaction

The Core Insight

Softanza recognizes that every file interaction naturally includes read capability. Just as opening a physical notebook gives you access to both reading existing content and writing new content, digital file operations should work the same way.

The Natural Mental Model

# Softanza approach - thinking in intentions
FileAppend("log.txt") {
    if not ContainsText("target_entry")
        WriteLogEntry("target_entry")
    ok
	Close()
}

This single, elegant pattern: - Expresses intent clearly (FileAppend) - Use Haro declarative style to work on the returne file object ({ ... }) - Provides natural read access (ContainsText) - Performs write operations seamlessly (WriteLogEntry) - Requires no mode management or complex checks

The Seven Core Intentions

Softanza organizes file operations around natural human intentions:

1. FileInfo() - "I want to get information about this file"
2. FileRead() - "I want to read this file"
3. FileAppend() - "I want to add to the end of this file"
4. FileCreate() - "I want to create a new file"
5. FileOverwrite() - "I want to replace this file's contents"
6. FileModify() - "I want to modify parts of this existing file"
7. FileManage() - "I want to manage this file on the disk"

Each intention provides: - Full read access (the universal capability, where applicable) - Intent-specific write methods (clearly named and purpose-built) - Built-in safety checks (prevent common errors) - Fluent interface (method chaining and declarative style for readability)

The Q Convention: value vs object

Softanza applies one consistent rule across the whole file (and folder) API:

• XxxQ() always returns the live OBJECT — the form you keep working with (dot-notation or a { ... } block).
• The bare Xxx() returns a VALUE whose meaning fits the function: FileInfo() → an info hashlist, FileRead() → the content, FileCreate() / FileOverwrite(file, content) → TRUE/FALSE for success.
• Object-only intents (FileAppend, FileUpdate, FileManage) have no useful scalar value, so the bare name does the same thing as the Q form — both return the object.

Rule of thumb: want the object? add Q. The block examples below therefore use the Q forms for FileInfo/FileRead/FileCreate/FileOverwrite, while FileAppend/FileUpdate/FileManage work the same with or without it.

Practical Comparisons: Traditional vs Softanza

1. Getting Information About Files

Intent: I want to get information about this file

Understanding a file’s state is the foundation of intent-based programming. FileInfo() function, and its underlining stzFileInfo class, provide comprehensive metadata without opening the file:

FileInfoQ("stzFileTest.ring") {
    ? Exists()			#--> TRUE
    ? IsWritable()		#--> TRUE
    ? SizeInBytes()		#--> 140
    ? LastModified()	#--> 18/07/2025 20:28:51
    ? IsExecutable()	#--> FALSE
}

This metadata enables informed decisions about subsequent operations:

# Intelligent intent selection

FileInfoQ("config.txt") {

    if Exists()
    
    	if IsWritable()
            FileUpdateQ("config.txt") {
            	# Make modifications
                ...
                
                Close()
            }
        
    	else
        	? "Configuration file is read-only"
        ok 
        
    else
        FileCreateQ("config.txt") {
        	# Create new configuration
            ...
            
            Close()
        }
    ok
}

This approach simplifies decision-making by providing clear, upfront file information.

2. Reading Files

Intent: I want to read this file

Reading file content is a common task made intuitive with Softanza. FileRead() offers rich querying methods for natural content access:

FileReadQ("data.txt") {
    for cLine in Lines()
        # Process line naturally
    next
	Close()
}

Contrast this with the traditional approach, which requires multiple steps:

if fexists("data.txt")
    content = read("data.txt")
    lines = str2list(content)
    for line in lines
        # Process line
    next
ok

Softanza also supports advanced querying without re-reading the file. This time, we'll use object instantiation and dot notation to demonstrate an alternative to the FileRead() function:

# Rich querying capabilities

oReader = FileReadQ("data.txt")

nTotalLines = oReader.NumberOfLines()
cFirstLine = oReader.FirstLine()
cLastLine = oReader.LastLine()
bContainsKeyword = oReader.ContainsText("important")

oReader.Close()

These methods make content analysis straightforward and efficient.

3. Adding to the End of a File

Intent: I want to add to the end of this file

Appending, especially for logging, is a frequent operation. FileAppend() simplifies adding content with built-in read access:

FileAppendQ("app.log") {
    WriteLogEntryWithTimestamp("Application started")  # Adds timestamp and log entry
    WriteSeparator("=")  # Adds a visual separator
    WriteLogEntry("User authentication successful")  # Adds a plain log entry
    Close()
}

The traditional approach is more cumbersome:

if fexists("app.log")
    file = fopen("app.log", "a")
else
    file = fopen("app.log", "w")
ok
fputs(file, date() + " - Application started" + nl)
fclose(file)

For context-aware logging, Softanza leverages read capabilities:

oLogger = FileAppendQ("app.log")
oLogger {
    if IsEmpty()
        WriteLine("=== Session Started ===")
    ok
    if not ContainsText("Daily backup")
        WriteLogEntryWithTimestamp("Daily backup completed")
    ok
	Close()
}

Note: WriteLogEntryWithTimestamp() combines a timestamp (e.g., current date/time) with the log message for standardized logging.

4. Creating a Configuration File

Intent: I want to create a new file

Creating a new file, such as a configuration file, is streamlined with Softanza. FileCreate() ensures the file doesn’t exist and provides formatted writing:

try
    FileCreateQ("config.ini") {
        WriteHeader("Application Configuration")  # Adds a formatted header
        
        WriteLine("[Database]")
        WriteLine("Host=localhost")
        WriteLine("Port=5432")
        
        WriteBlankLine()  # Adds an empty line for formatting
        
        WriteLine("[Logging]")
        WriteLine("Level=INFO")
        WriteLine("File=app.log")
        
        Close()
    }
catch
    ? "Configuration file already exists. Use FileOverwrite() to replace."
done

The traditional approach requires manual checks:

if fexists("config.ini")
    see "Error: Configuration file already exists" + nl
else
    content = "[Database]" + nl +
              "Host=localhost" + nl +
              "Port=5432" + nl +
              "[Logging]" + nl +
              "Level=INFO" + nl +
              "File=app.log" + nl
    write("config.ini", content)
ok

Softanza’s approach is safer and more expressive, with built-in error handling.

5. Overwriting File Content

Intent: I want to replace this file’s contents

Overwriting a file’s content is intuitive with Softanza. FileOverwriteQ() allows reading original content before replacing it (the bare FileOverwrite(file, content) is the one-shot value form that just returns success):

FileOverwriteQ("data.txt") {
    aOriginalLines = OriginalLines()  # Access original content
    WriteHeader("Updated Data")  # Adds a formatted header
    WriteLine("New content replacing old")
	Close()
}

In contrast, the traditional approach is blunt:

write("data.txt", "New content replacing old")

Softanza’s read access ensures informed overwriting decisions.

6. Modifying Parts of a File

Intent: I want to modify parts of this existing file

Targeted modifications are simplified with FileUpdate(). It supports sophisticated updates with read access to the original state:

FileUpdate("data.txt") {
    aOriginalLines = OriginalLines()  # Access original content
    UpdateLineContaining("version=", "version=2.0")  # Updates matching lines
	Close()
}

The traditional approach is more complex:

if fexists("data.txt")
    content = read("data.txt")
    lines = str2list(content)
    for i = 1 to len(lines)
        if substr(lines[i], "version=")
            lines[i] = "version=2.0"
        ok
    next
    newContent = list2str(lines)
    write("data.txt", newContent)
ok

Advanced modifications are also seamless:

FileUpdate("data.txt") {
    InsertAfterLine(1, "# Updated: " + date())  # Inserts after specific line
    RemoveLinesContaining("deprecated_setting")  # Removes matching lines
    
    aNewLines = oUpdater.Lines()
    nChanges = len(aNewLines) - len(aOriginalLines)
    if nChanges > 0
        InsertLineAtEnd("# " + nChanges + " modifications made")
    ok
    
	Close()
}

This makes precise edits intuitive and maintainable.

7. Managing Files on Disk

Intent: I want to manage this file on the disk

File system operations are streamlined with FileManage(). It handles tasks like copying, renaming, and splitting:

FileManageQ("source.txt") {
    CopyTo("backup/source.txt")  # Copies to a new location
    CopyAs("source_v2.txt")  # Copies with a new name
	Close()
}

The traditional approach requires low-level operations, which Softanza abstracts away:

# Traditional copying (simplified, error handling omitted)
content = read("source.txt")
write("backup/source.txt", content)

Advanced management tasks are equally straightforward:

FileManageQ("source.txt") {
    MoveTo("archive/")  # Moves the file to a new directory
    RenameAs("archived_source.txt")  # Renames the file

    SplitByLines(100)  # Creates source_1.txt, source_2.txt, etc.

    Delete()  # Deletes the file
	Close() # Automatic after Delete()!
}

This simplifies complex file system operations.

Safety and Error Prevention

Traditional Manual Error Handling

Traditional file handling requires explicit error checks, which are error-prone:

if fexists("important.txt")
    see "Error: File already exists" + nl
    return
ok
file = fopen("important.txt", "w")
if file = NULL
    see "Error: Cannot create file" + nl
    return
ok
fputs(file, "Important data")
fclose(file)

Softanza’s Built-in Safety

Softanza automates error handling for clarity and reliability:

try
    FileCreateQ("important.txt") {
        WriteHeader("Important Data")  # Adds a formatted header
        WriteLine("Critical information")
        Close()
    }
catch
    ? "Cannot create important.txt - file already exists."
    ? "Use FileOverwrite() to replace or FileUpdate() to modify."
done

This reduces manual checks and enhances code robustness.

Practical Use Case: Updating a Configuration File

Traditional Approach

Updating a configuration file traditionally involves multiple steps:

func UpdateConfig(filename, setting, value)
    if not fexists(filename)
        see "Error: Configuration file does not exist" + nl
        return
    ok
    content = read(filename)
    lines = str2list(content)
    found = false
    for i = 1 to len(lines)
        if substr(lines[i], setting + "=")
            lines[i] = setting + "=" + value
            found = true
            exit
        ok
    next
    if not found
        add(lines, setting + "=" + value)
    ok
    newContent = list2str(lines)
    write(filename, newContent)

This requires manual file reading, parsing, and rewriting.

Softanza Approach

Softanza simplifies the process with a clear, intent-driven approach:

oConfig = FileUpdate("config.txt")
    if not oConfig.ContainsText(setting + "=")
        oConfig.InsertLineAtEnd(setting + "=" + value)
    ok
oConfig.Close()

The Paradigm Shift

Traditional Question: "What mode do I need and how do I manage file handles?"

Softanza’s Question: "What do I want to accomplish with this file?"

Mental Model Transformation

Technical VS Natural Flow

Traditional approach requires: 1. Choose the right mode 2. Handle file existence checks 3. Manage file handles 4. Remember to close files 5. Deal with positioning and buffering

Softanza enables: 1. Express your intent 2. Use natural read/write methods 3. Trust built-in safety 4. Write expressive, maintainable code

Implementation Foundation: Engine Integration

Softanza’s intent-based file API is built on the Softanza Engine, leveraging its robust file handling system for production-ready applications. Each of the seven intentions is implemented as a dedicated class:

• stzFileInfo: Retrieves metadata (e.g., Exists(), IsWritable(), Size()) without opening the file, enabling informed decisions about file operations.
• stzFileReader: Facilitates content reading with methods like Lines(), FirstLine(), and ContainsText() for efficient querying.
• stzFileAppender: Supports appending content (e.g., WriteLogEntryWithTimestamp(), WriteSeparator()) with read access for context-aware logging.
• stzFileCreater: Creates new files with formatted writing methods (e.g., WriteHeader(), WriteBlankLine()) and checks to prevent overwriting.
• stzFileOverwriter: Replaces file content while allowing access to original content via OriginalLines().
• stzFileModifier: Enables targeted modifications (e.g., UpdateLineMatching(), InsertAfterLine()) with read access to the original state.
• stzFileManager: Handles file system operations (e.g., CopyTo(), MoveTo(), SplitByLines(), ZipAs()) for disk-level management.

This engine foundation delivers: - Battle-tested reliability through the Softanza Engine’s mature file handling system - Comprehensive Unicode support for filenames and content across platforms - Seamless cross-platform behavior, eliminating manual handling of platform-specific details - High-performance operations on large files via efficient buffering - TextStream integration for future cloud-oriented file management

This class-based architecture, combined with the Softanza Engine, prepares Softanza for future extensions like remote file access, network streams, and cloud storage APIs, making it an enterprise-ready file handling system for both local and distributed environments.

Conclusion

The Softanza intent-based file API represents a return to common sense in file operations. By moving beyond the traditional mode-based paradigm, it aligns tools with natural human thinking patterns. Instead of manipulating file handles, developers express what they want to accomplish. The result is code that flows naturally from thought to implementation, making programming an expression of intent rather than a translation of technical constraints.

Citer

Mansour Ayouni. « Beyond File Modes: The Softanza Intent-Based Paradigm ». Softanza narrations, 2025. https://mayouni.github.io/stzsite/fr/narrations/stzfile-api-narration.html

Non exécuté : son code touche aux fichiers, au réseau, à l'horloge ou au hasard. L'article est publié tel qu'il est écrit ; ses blocs sont des illustrations. Le code des articles est du code Haro. Là où un article a été écrit avant que la langue prenne son nom actuel, le nom a été changé et rien d'autre. Genre, domaine et série lus dans le nom du fichier, année tirée du premier commit : dérivés, jusqu'à ce que l'article porte son propre en-tête. Le fichier sur GitHub(s'ouvre dans un nouvel onglet)