Naftah Programming Language : Let's write programs in Tunisian/Arabic, like living in Naftah

نفطه: لغة برمجة، لنكتب برامج باللغة العربية وكأننا نعيش في نفطه

🌟 Motivation: Why I Created Naftah

As a Tunisian and an Arabic speaker passionate about programming, I was always searching for a programming language that uses Tunisian/Arabic naturally — not just in keywords, but in structure, logic, and support for dialects, including my own Tunisian dialect. I wanted something that makes programming feel familiar, intuitive, and accessible, especially for those of us who don’t speak English fluently.

But after years of searching, I found that no existing Tunisian/Arabic programming language truly met those needs. Most were limited, overly simplistic, or not designed with real-world learning and development in mind. None of them made me feel like I could write code the way I speak and think in Tunisian/Arabic.

What pushed me even more was seeing how many people around me — students, kids, and even adults — struggle to learn programming not because it’s too hard, but because of the language barrier. Most programming resources, documentation, and languages are in English. And for many, especially young kids, this makes it almost impossible to start.

You shouldn’t have to learn a foreign language just to learn how to think logically or create something with code.

That’s why I created Naftah — a modern, expressive, and educational programming language written entirely in Arabic, with built-in support for dialects, including Tunisian Arabic. Naftah allows people to write code in a way that feels close to how they speak, think, and understand the world around them.

I built Naftah using the best ideas and syntax patterns from popular programming languages, blending them with the richness of the Arabic languageand the diversity of dialects. My goal is to make programming accessible to everyone, regardless of their level of English.

Naftah is not just a language. It’s an invitation to learn, explore, and build — in our own words.

---

بصفتي تونسيًّا ناطقًا باللغة العربية ومحبًا لعلم البرمجة، لطالما كنت أبحث عن لغة برمجة تعتمد اللغة العربية بشكل طبيعي — ليس فقط في الكلمات المفتاحية، بل في البنية والأسلوب، وتدعم حتى اللهجات المحكية، بما في ذلك اللهجة التونسية التي أعبّر بها يوميًا.

كنت أريد لغة تجعل البرمجة أقرب للفهم، وأسهل للتعلّم، وأكثر ألفة، خصوصًا لأولئك الذين لا يُجيدون الإنجليزية بطلاقة. لكن بعد سنوات من البحث، لم أجد لغة برمجة عربية تلبي هذه الحاجة بجدّية. معظم ما وُجد إما بسيط للغاية، أو غير عملي، أو لا يدعم التعليم بشكل فعّال، ولم أشعر يومًا أن بإمكاني "كتابة كود" كما أفكر وأتحدث باللغة العربية.

ما دفعني أكثر هو الواقع المؤلم الذي أراه حولي: أشخاص كثيرون — طلاب، أطفال، حتى بالغون — يعانون في تعلّم البرمجة، ليس لصعوبتها ذاتها، بل بسبب حاجز اللغة. معظم المصادر والمفاهيم البرمجية مكتوبة بالإنجليزية، وهذا يجعل التعلّم أشبه بالمستحيل بالنسبة للأطفال أو من ليست لديهم خلفية لغوية قوية.

لا ينبغي أن يكون تعلّم البرمجة مرهونًا بإتقان لغة أجنبية.

لذلك قررت إنشاء "نفطه" — لغة برمجة حديثة، معبّرة، وتعليميّة، مكتوبة بالكامل باللغة العربية، وتدعم اللهجات أيضًا، بما في ذلك اللهجة التونسية. تهدف "نفطه" إلى تمكين الجميع من كتابة الكود كما يتحدثون ويفكرون ويفهمون.

لقد بنيت "نفطه" اعتمادًا على خبرتي في البرمجة، وأخذت من لغات البرمجة العالمية أفضل المفاهيم، والبنى، وأنماط الكتابة، ثم صغتها بالعربية، بأسلوب يجعل التعلّم والتطوير أكثر قربًا وسلاسة.

نفطه ليست مجرد لغة، بل هي دعوة مفتوحة للتعلّم، والاكتشاف، والإبداع — بلغتنا، وعلى طريقتنا.

---

⚙️ Why Build Naftah on Top of Java (JVM)?

One of the most important decisions in designing a new programming language is choosing the right foundation. For Naftah, that foundation is the Java Virtual Machine (JVM) — and that choice was very intentional.

The JVM is one of the most mature, stable, and high-performance platforms in the world of software development. By building Naftah on top of the JVM, we gain access to decades of engineering, optimization, and innovation, while making sure Naftah remains:

• 🔒 Secure
• ⚡ Fast
• 🌍 Cross-platform
• 🔌 Easily integrated with existing tools and libraries

🚀 Benefits of the JVM for Naftah

✅ Massive Ecosystem

Java has one of the largest and most battle-tested ecosystems out there. By using the JVM, Naftah can interact with thousands of existing Java libraries, APIs,...

🛠️ Performance & Optimization

The JVM is highly optimized for performance, thanks to JIT (Just-In-Time) compilation, garbage collection, and decades of improvements.

Naftah code runs with the speed and efficiency of Java code, making it suitable not just for education, but also for real-world applications.

🔗 Full Interoperability with Java

Naftah is fully interoperable with the Java ecosystem, making it an ideal gateway language for Tunisian/Arabic speakers entering the world of modern software development.

✅ What This Means:

• You can Java classes and use them inside your Naftah code in arabic (via transliteration).
• You can build hybrid applications — with parts written in Naftah, others in Java or Kotlin...
• You can write Java extension libraries and expose them as Naftah functions via a powerful, annotation-based system.

---

🧩 Write Java, Use It in Naftah — Seamlessly

Thanks to Naftah's plugin discovery system based on reflection, you can:

• Write Java classes using Arabic method names (or dialects).
• Annotate them using @NaftahFn and @NaftahFnProvider.
• Naftah will automatically detect, register, and expose those methods as native Naftah functions.

🔠 You can even transliterate Java code to feel like Arabic

Want to write Java that looks like Naftah code? You can do that too:

@NaftahFn(
		name = "إجمع",
		description = "يجمع رقمين",
		usage = "إجمع(أ ، ب)",
		parameterTypes = {int.class, int.class},
		returnType = int.class
)
public static int sum(int a, int b) {
	return a + b;
}

This code:

• Is pure Java
• Can be compiled with any Java build tool (Maven, Gradle, etc.)
• And becomes immediately usable inside a Naftah script:

إطبع("مجموع ١ و ٢ هو: " + إلى_نص(إجمع(1، 2)))

---

🚀 Why This Matters

• You can start programming in Tunisian/Arabic, then gradually shift to more advanced Java/Kotlin/Groovy systems.
• You gain access to the entire JVM ecosystem: libraries, frameworks, tools.
• You don’t have to choose between expressiveness and power — with Naftah, you get both.

Whether you're teaching children, building local apps, or writing serious libraries — Naftah gives you a voice in your language, and the power of the Java world behind it.

🌐 Portability

The JVM is cross-platform by design: Code written in Naftah runs on Windows, macOS, Linux, and even on mobile devices via JVM-compatible platforms.

This means developers can build once and run anywhere.

🧠 Why Not Build a New VM From Scratch?

Building a virtual machine from scratch is possible, but it takes years of effort, and the result may lack performance, stability, or community adoption.

By standing on the shoulders of a giant like the JVM, Naftah gets:

• A reliable runtime
• Compatibility with modern systems
• Tools that developers already know and trust
• Time to focus on what matters: a great Tunisian/Arabic programming experience

We didn’t want to reinvent the wheel — we wanted to drive it in our direction.

---

🧩 Java/Kotlin/Groovy Interoperability

Naftah allows full access to Java libraries:

• After running init, all Java classes in lib/ become usable.
• You can use transliterated Arabic method names to call them.
• Java extensions can be written once and reused inside Naftah without recompilation.

This makes Naftah a gateway language — start in Arabic, scale into Java as needed.

---

🚀 Running Naftah: Scripts, REPL, Initialization and Manual

Naftah comes with cross-platform CLI tools that allow you to run scripts, start an interactive shell, or initialize the system to work with existing Java/Kotlin/Groovy libraries.

---

🔧 Prerequisites

• Java 17 or higher (ensure JAVA_HOME is set correctly)

• Naftah distribution folder with:

  • lib/ – containing core and optional .jar files
  • Shell/BAT scripts: naftah.sh, naftah-repl.sh, naftah-init.sh, etc.

---

🗂️ Available Scripts

Script Name	Description
naftah.sh / .bat	Default entry point (runs a script by default)
naftah-repl.sh / .bat	Starts REPL (interactive shell)
naftah-init.sh / .bat	Initializes Java classpath libraries
naftah-man.sh / .bat	Naftah language manual

🖥️ Use .bat files on Windows and .sh scripts on Linux/macOS.

---

✅ 1. Run a Naftah Script

To execute a .naftah file:

Linux / macOS

./naftah-shell.sh run hello.naftah

Or directly (default subcommand is run):

./naftah.sh hello.naftah

Windows

naftah-shell.bat run hello.naftah

Or simply:

naftah.bat hello.naftah

---

💬 2. Start the Interactive Shell (REPL)

The REPL allows you to experiment with Naftah code line-by-line in a terminal.

Linux / macOS

./naftah-repl.sh

Or:

./naftah-shell.sh shell

Windows

naftah-repl.bat

Or:

naftah.bat shell

Features:

• Multi-line code support
• Auto history and arrow key navigation
• Live feedback with Arabic-style syntax

---

⚙️ 3. Initialize Java Libraries for Use in Naftah

The init command processes all .jar files inside the lib/ folder and adds them to Naftah's reflection system. This enables:

• Using Java/Kotlin/Groovy classes inside .naftah scripts.
• Interacting with them via Arabic transliterated syntax.
• Seamless interop without additional build steps.

Linux / macOS

./naftah-init.sh

Or:

./naftah.sh init

Windows

naftah-init.bat

Or:

naftah.bat init

🔍 By default, init scans all .jar files under lib/ and builds type metadata for use in Naftah scripts.

---

📚 4. Use the Naftah Manual (Dynamic CLI Help)

The man command launches Naftah's interactive manual system, which supports exploring all built-in commands, functions, and Java interop metadata — in both Arabic and English.

It behaves like a smart REPL-based help system, not just a static manual:

🔍 Features:

• ⌨️ Type usage / مساعدة to view all supported commands
• 📁 Use list / المواضيع to browse available help topics
• 📚 Type any topic name to open its Markdown-based guide
• 🏷️ Type any Java class name (fully-qualified) to view its Arabic-qualified alias
• 📦 Explore Java interop using:
  • classes / الأصناف — All known classes
  • accessible-classes / الأصناف-المتاحة — Public classes only
  • instantiable-classes / الأصناف-القابلة-للتهيئة — Instantiable classes
• ⚙️ View runtime and built-in functions using:
  • builtin-functions / الدوال-المدمجة
  • jvm-functions / دوال-جافا
• ❌ Type exit / خروج to quit the manual session at any time

---

Linux / macOS

./naftah-man.sh

Or:

./naftah.sh man

Windows

naftah-man.bat

Or:

naftah.bat man

💡 You can use this command as a lightweight alternative to browsing the docs online — it’s fully terminal-friendly and supports Arabic output with pagination.

---

🧪 Example Workflow

1. Add your Java/Kotlin/Groovy .jar files under lib/
2. Run naftah-init to scan and index classes
3. Start REPL or run a .naftah file that uses those classes

# Add your JAR
cp mylib.jar lib/

# Initialize classpath
./naftah-init.sh

# Run a script
./naftah.sh myscript.naftah

# Start REPL
./naftah-repl.sh

---

📄 CLI Usage Summary

Available Subcommands:

Command	Purpose
run	Runs a .naftah script or inline code
shell	Starts interactive REPL
init	Scans Java/Kotlin/Groovy .jars under lib/
man	launches Naftah's interactive manual system

Global Options:

Option	Description
-e "<script>"	Run inline Naftah code (instead of providing a filename)
-cp, --classpath <path>	Add custom entries to the Java classpath
-D <key=value>	Define system properties, available via System.getProperty(...)
--scan-classpath (-scp)	Enable reuse of Java types from classpath in your Naftah script
--force-scan-classpath	Force classpath re-scan even if already initialized
--enable-cache=M,I	Enable performance caches: M for multiline strings, I for interpolation
--number_formatting	Use Tunisian/Arabic-style number formatting (e.g., decimal separator)
--arabic_indic	Use Arabic-Indic digit shapes (٠١٢٣٤٥٦٧٨٩)
-d, --debug	Enable debug mode (prints stack traces)
-c, --encoding <charset>	Specify character encoding (e.g., UTF-8, windows-1256)
--vector	Enable experimental Vector API optimizations (JDK incubator)
-h, --help	Show help message and exit
-v, --version	Show version and exit

---

🧠 Examples

# Run a Naftah script file
naftah run myscript.naftah

# Run Naftah inline code
naftah run -e "اطبع(\"السلام عليكم\")"

# Start interactive shell
naftah shell

# Initialize classpath types for reuse
naftah init -cp lib/my.jar --scan-classpath

# Use Arabic-Indic numerals
naftah run script.naftah --arabic_indic

# Enable both caches (multiline + interpolation)
naftah run script.naftah --enable-cache=M,I

---

📚 Naftah Language Documentation

Looking to learn the Naftah programming language?

🚀 Visit the full Language Reference Guide for syntax, types, control flow, functions, and more:

👉 docs

Or explore by topic:

Topic	Description
📘 Keywords	Introduction to reserved words and special identifiers used in Naftah language.
📙 Primitives And Variables	Explanation of basic data types: numbers, strings, booleans; Arabic digits usage; constants (ثابت) vs variables (متغير); typing and assignment rules.
📕 Collections	Detailed overview of data structures like lists, tuples, sets, and associative arrays with examples and element-wise operations.
📒 Expressions	How to write and evaluate expressions, including arithmetic, logical, and bitwise operations.
📘 Radix Numbers	How to define numbers in different numeral systems (from base 2 to 36) using the '' syntax; includes Arabic and Ascii digit support with examples.
📙 Objects	Defining and working with structured data using key-value fields; includes nested objects and multiple field-access syntaxes.
📕 Control Flow	Overview of conditionals (if, else), loops (while, for), and pattern matching; control statements like stop, تابع, and return.
📘 Functions	Defining named and anonymous functions; parameter passing, default values, return types, and function composition in Naftah.
📙 Java Interop	Using Java classes and methods within Naftah code; how to call, instantiate, and work with Java objects seamlessly.
📒 Concurrency	Working with asynchronous functions, tasks, scopes, channels, and actors in Naftah; how to write concurrent and parallel code safely and efficiently.
📒 Temporal	Working with dates, times, durations, and periods; support for multiple chronologies (ISO, Hijrah), time zones and offsets, and precise conversions between them.

---

You can also run naftah shell and start experimenting right away.

---

🤝 Contributing

We welcome contributions of all kinds! Please see our Contributing Guidelines for details.

By participating, you agree to follow our Code of Conduct.

---

💸 Support This Project

This project is actively maintained and developed. If you find it useful or want to support ongoing development, you can sponsor or donate through any of the platforms below:

Your support helps improve the tools, documentation, and the language itself.

Thank you 🙌