Why I Built stzNatural: A Journey from Haro's NaturalLib to Softanza's Natural System

By Mansour Ayouni, Creator of Softanza library

I tried to build my vision on top of it. But I kept hitting a wall: NaturalLib is designed for commands, not narratives.

I didn't want to trigger isolated actions.\ I wanted to transform one object through a sequence of natural steps—like a human would describe a task.

I needed natural code that constructs a complete computational model in memory before executing anything, so I could apply all the gymnastics required by natural language semantics (deferred execution) before turning human words into Haro code.

So I built stzNatural from scratch. Not to replace NaturalLib—but to explore a different path: focused, object-centric natural programming.

This made Softanza's stzNatural different by design from Haro's NaturalLib on several fundamental aspects.

The Molecular Design Principle

stzNatural operates on a simple but powerful rule:

Each natural block works on exactly one Softanza object.

This means:

• You create one object (Create a string…),
• Then apply any of its methods (Uppercase, Box, Replace, etc.),
• Using pronouns (it, this) that always refer to that object,
• And modifiers (@box … box@) that refine actions in context.

This isn't restrictive—it's liberating:

• No ambiguity about scope,
• No need for complex state management,
• Maximum performance (only one object in memory),
• Full method fluency (every verb = real method).

In contrast, Haro's standard NaturalLib treats each phrase as a standalone command with no shared context. You can't say "box it" because there is no "it."

String-Based Natural Code: 10X Performance Leap

The Strategic Decision:

Initially, stzNatural used Haro's brace syntax ({ }) with dynamic attribute evaluation to capture natural statements. This worked, but came with significant costs:

• Required underscored keywords (the_, and_, is_) to avoid Haro reserved words
• Relied on Haro's braceExprEval() reflection mechanism
• Limited natural code to runtime-only evaluation
• Couldn't store, version, or manipulate natural code as data

The Breakthrough:

I refactored the entire system to accept natural code as plain strings:

# Old approach (brace-based)
Naturally() {
    Create a string with "hello"
    Uppercase it
    Show it
}

# New approach (string-based)
Naturally("
    Create a string with 'hello'
    Uppercase it
    Show it
")

Performance Impact: 10X faster by:

• Eliminating Haro's braceExprEval() overhead
• Using the Softanza Engine's optimized native string backend via stzString
• Direct string tokenization vs dynamic attribute evaluation
• No reflection during token capture

Strategic Advantages:

Natural code became a first-class data type:

• Storable: Save to .natural files
• Versionable: Git-friendly plain text
• Searchable: Use grep, regex, IDE tools
• Manipulable: Full stzString and stzRegex power with full punctuation freedom
• Sharable: Exchange natural code across systems
• IDE-friendly: Syntax highlighting, linting possible

No More Keyword Workarounds:

The string-based approach eliminated all underscore hacks:

# Before: and_ the_ is_
# After:  and the is   (work naturally)

Deferred Execution: Thinking Before Acting

Haro's NaturalLib executes commands as they appear.\ stzNatural captures the entire block first, stores it internally, then compiles it into efficient Haro code only when ready.

Why? Because humans plan before they act.

"@Box the string—but make the box@ rounded."

This requires remembering an action, then refining it later.\ Only possible with deferred compilation.

The string-based approach makes this even more powerful—we can preprocess, validate, and optimize the entire natural code before a single Haro instruction executes.

Vocabulary Freedom, with Focused Computable Keywords

In stzNatural, only words defined in the semantic dictionary are interpreted. All others become literals—no pre-nullification needed. A pragmatic design choice that makes a huge performance difference.

The ignored_words list (e.g., "a", "with", "containing") exists only to enable natural phrasing around structural boundaries—like Create a string or Replace X with Y.

This lets you write fluently without compromising parsing integrity.

Data-Driven, Config-Only Multilingualism

Haro's NaturalLib: duplicate command files per language.\ stzNatural: one semantic core, many linguistic skins, unique implementation code.

English "uppercase", Hausa Latin "maida", and Hausa Ajami "ميّدَ" all map to the same METHOD_UPPERCASE. The implementation engine doesn't care about translated semantics—only METHOD_UPPERCASE is processed.

Add a language? Just add a data block (at devtime or runtime). No files to manage, no loads to worry about, no if/thens inside the implementation code.

# English
Naturally("Create string with 'hello' Uppercase it")

# Hausa (Latin)
NaturallyIn("hausa", "Yi rubutu dauke 'hello' Maida shi")

# Hausa (Ajami)
NaturallyIn("hausa-ajami", "يي رُوْبُتُ ɗوكي 'hello' مَيْدَ شي")

All produce identical Haro code. The string-based approach makes this even cleaner—language definitions are just data structures, and natural code flows as readable text in any script system.

Developer Experience: Introspection & Debugging

o1 = Naturally("
    Create string with 'test.data'
    Replace '.' with '_'
    Uppercase it
")

? o1.Result()
#--> TEST_DATA

? o1.Code()
#--> oStr = StzStringQ("test.data")
#    oStr.Replace(".", "_")
#    oStr.Uppercase()
#    @result = oStr.Content()

? o1.NaturalCode()
#--> (returns the original natural code string)

o1.EnableDebug()
? o1.DebugLog()  # Full execution trace

String-based natural code adds NaturalCode() accessor—you can inspect, modify, or regenerate the natural source at any time.

Conclusion

stzNatural enables:

• Fluent, stateful chains on one object,
• Deferred modifiers via @...@,
• Multilingual expression (English, Hausa, Arabic, and beyond),
• Full devtime introspection (.Code(), .Result(), .NaturalCode(), .DebugLog()),
• 10X performance boost through string-based architecture,
• Natural code as first-class data (storable, versionable, manipulable),
• And native Haro code execution speed.

The shift from brace-based to string-based natural code wasn't just a refactoring—it was a strategic leap that removed artificial constraints, unlocked massive performance gains, and transformed natural code into a true data medium.

Related reading

• "Code Meets Cells": The Spreadsheet Metaphor in Softanza's stzTable
• **Natural Language Programming, Reimagined: The stzNatural Class in Softanza**
• Softanza: Bridging Minds and Code - A Humanistic Approach to Programming

Cite

Mansour Ayouni. "Why I Built `stzNatural`: A Journey from Haro's NaturalLib to Softanza's Natural System". Softanza narrations, 2025. https://mayouni.github.io/stzsite/en/narrations/stznatural-vs-ring-naturallib.html

Run in Haro's name on 2026-10-08 20:43 inside the library at commit 4a184e6f0, block after block in one process: 0 of 4 blocks kept their promise; the others are illustrations. The code of the articles is Haro code. Where an article was written before the language took its present name, the name was changed and nothing else. Genre, area and series read from the file's name, the year from its first commit: derived, until the article carries its own header. The file on GitHub(opens in a new tab)