**Natural Language Programming, Reimagined: The stzNatural Class in Softanza**

“Make a string with ‘hello Niger’ inside. Uppercase it, spacify it, and box it—rounded. Then show the result.”
— Not pseudocode. Not an LLM prompt. Real, executable Haro code.

No NLP. No neural nets. No hallucinations. Just clean, deterministic, data-driven code that reads like human instruction—and executes like machine logic.

🌍 A Vision: Natural Orientation in Code

At the heart of Softanza lies a design philosophy called natural orientation: software should feel intuitive, expressive, and accessible—not just to engineers, but to domain experts, educators, and multilingual communities.

stzNatural embodies this vision by enabling developers to write executable natural-language commands directly inside Haro programs. But unlike toy DSLs or brittle macro systems, stzNatural is:

• Multilingual by design (English, Hausa Latin, Hausa Ajami—and infinitely extensible),
• Data-driven (language rules are pure configuration, not hardcoded logic),
• Debuggable and transparent (you can inspect the generated Haro code at any time),
• And above all—fast (as fast as caling a bunch of method on a Haro object).

Let’s explore how it works—and why it matters.

Core Architecture: Separation of Concerns, Perfected

stzNatural rests on three cleanly separated pillars:

1. Language Definitions ($aLanguageDefinitions)

A pure data structure mapping words in any language to semantic identifiers:

[:natural = "uppercase", :semantic = "METHOD_UPPERCASE"],
[:natural = "maiɗa",    :semantic = "METHOD_UPPERCASE"],   // Hausa (Latin)
[:natural = "ميّرد",     :semantic = "METHOD_UPPERCASE"]    // Hausa (Ajami)

Add Swahili? Arabic? Just append a new block. No recompilation needed.

2. Semantic Operations ($aSemanticOperations)

Language-agnostic definitions of what each semantic ID does:

[
  :semantic_id = "METHOD_BOX",
  :stz_signature = "@var.Box()",
  :supports_modifiers = 1,
  :modifiers = [
    [:semantic_id = "MODIFIER_ROUNDED", :stz_method = "BoxXT", :stz_param = ":Rounded = 1"]
  ]
]

This decouples meaning from implementation—enabling rich behaviors like modifiers.

3. Execution Engine (stzNaturalEngine)

The runtime that: - Tokenizes input, - Filters ignored words (“the”, “and”, “please”), - Resolves semantics, - Generates and evaluates Haro code.

All while supporting debug mode, literal protection, and deferred references.

✨ Feature Walkthrough: By Example

1. Basic Object Creation & Transformation

Naturally() {
  Create a string with "softanza" inside
  Uppercase it
  Display the result
}
#--> SOFTANZA

3. Action Application: Natural Verbs as Methods

Once an object exists, you apply actions using intuitive verbs. Here are examples from the stzString domain:

Nt = Naturally() {
    Create a stzString with "  Sample Data  "
    
    Trim it
    Uppercase it
    Show it
}
#--> SAMPLE DATA

? Nt.Code()
#-->
oStr = StzStringQ("  Sample Data  ")
oStr.Trim()
oStr.Uppercase()
? oStr.Content()

Important: These string operations are not "features" of the natural programming system itself. They're examples of how any Haro object with any methods can be naturally expressed. The system dynamically maps natural verbs to actual method calls.

4. Chained Operations with Natural Connectors

Naturally() {
  Make a string containing "haro language"
  Uppercase it and_ spacify it
  Show it
}
#--> H A R O   L A N G U A G E

Words like and_, then_, plus are ignored—they exist only for fluency.

5. Parameterized Methods

Naturally() {
  Create a string with "old text old"
  Replace "old" with "new"
  Display it
}
#--> new text new

The system intelligently treats tokens after replace as literals, even if they match known keywords.

6. Modifiers via Deferred Reference (@...@)

This is where stzNatural shines:

o1 = Naturally()
o1 {
  Create a string with "Softanza ♥ Haro"
  @box it
  The box@ should be rounded
  Display the final result
}
#-->
╭─────────────────╮
│ Softanza ♥ Haro │
╰─────────────────╯

The @box ... the box@ pattern creates a deferred reference, allowing natural phrasing like “the box should be rounded”—a construct impossible in most DSLs.

Generated code:

? o1.Code()
#-->
'
oStr = StzStringQ("boxed text")
oStr.BoxXT([:Rounded = 1])
? oStr.Content()
'

💡 Note: box and frame are aliases. So are replace, substitute, change, and swap.

7. Multilingual Execution

English:

Hausa (Latin script):

Hausa (Ajami/Arabic script):

All produce identical output—and identical internal Haro code.

This isn’t just localization—it’s linguistic inclusion in programming.

Pragmatic Safeguards

stzNatural avoids common pitfalls:

• Ignored words (like "it", "the") are stripped—so you can’t accidentally use them as values.
• Unknown words default to literals—making the system forgiving.
• Empty or nothing values are handled gracefully.
• Debug mode lets you trace every token and generated line.

Example of misuse:

Naturally() { Create a string with "it" }  // "it" is ignored!
// → Creates empty string: StzStringQ("")

🌱 Extensibility: Add Any Language, Any Operation

Want to support French?

[
  :code = "fr",
  :ignored_words = ["le", "la", "et", "avec"],
  :semantic_mappings = [
    [:natural = "créer", :semantic = "CREATE_OBJECT"],
    [:natural = "chaîne", :semantic = "OBJECT_STRING"],
    [:natural = "afficher", :semantic = "OUTPUT_DISPLAY"]
  ]
]

Need a new method like encrypt? 1. Add to $aSemanticOperations:

[:semantic_id = "METHOD_ENCRYPT", :stz_signature = "@var.Encrypt()"]

1. Map natural words in any language:

[:natural = "encrypt", :semantic = "METHOD_ENCRYPT"],
[:natural = "chiffrer", :semantic = "METHOD_ENCRYPT"]

Done. No engine changes. No recompilation.

Why This Matters

In an era where “AI coding assistants” generate fragile, opaque, and often incorrect code, stzNatural proves that clarity, control, and expressiveness can coexist—without sacrificing performance or determinism.

It enables: - Teaching programming in local languages, - Domain-specific scripting for non-programmers (e.g., “format this report, box the title, and email it”), - Readable automation that stakeholders can audit and understand.

And it does so within the Haro language itself—no external servers, no black boxes.

Conclusion: Natural, But Not Naive

stzNatural is not about mimicking human conversation. It’s about leveraging natural language as a structured interface to deterministic computation.

By separating vocabulary, semantics, and execution, Softanza provides more than a class—it provides a blueprint for inclusive, maintainable, and joyful programming.

Natural programming shouldn’t require magic.
With stzNatural, it just requires Haro—and a little poetry.

Related reading

• Why I Built stzNatural: A Journey from Haro's NaturalLib to Softanza's Natural System
• Softanza: Bridging Minds and Code - A Humanistic Approach to Programming

Cite

Mansour Ayouni. "**Natural Language Programming, Reimagined: The `stzNatural` Class in Softanza**". Softanza narrations, 2025. https://mayouni.github.io/stzsite/en/narrations/stznatural-narration.html

Run in Haro's name on 2026-10-08 20:58 inside the library at commit 4a184e6f0, block after block in one process: 0 of 12 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)